CatalogLock v0.3.0 — Complete Protocol-Surface & Trust-Context Locking

CatalogLock v0.3.0 — Complete Protocol-Surface & Trust-Context Locking

Stable identity is not stable capability. Stable capability is not stable implementation.

v0.3.0 expands CatalogLock from live MCP tool drift detection into a contextual protocol-surface and trust-evidence gate.

Highlights

• ARD v0.91-first resolution at /.well-known/ard.json, predecessor fallback kept explicit, and HTML rel="ard" support.
• Lockfile v3 fingerprints the ARD base context, resolution source, authority/trust posture and contextual MCP surfaces.
• MCP 2026-07-28 server/discover, tools, prompts, resources and resource templates are locked for every concrete Streamable HTTP remote and configured client profile.
• Authenticated/contextual profiles inject secrets from environment variables without persisting secret values.
• Optional prompts/get, resources/read and custom read-only extension probes lock content where operators choose to inspect it. tools/call is forbidden.
• Modern MCP JSON-RPC identity, resultType, cache metadata, pagination and Mcp-Name/Mcp-Method transport rules are validated.
• Invalid x-mcp-header tools are excluded while valid tools remain inspectable.
• Trust evidence now has explicit absent, present-unverified, unsupported, verified and invalid states.
• Byte-accurate SHA-256 attestation/provenance verification, canonical JWS verification, JWKS/did:web resolution and pluggable trust verifiers.
• Endpoint drift, discovery/capability drift, primitive additions/mutations, private-to-public cache widening and read-only probe drift receive explicit classifications.
• Release hygiene gates prevent node_modules, .test-dist, .release, secret files and other staging artifacts from entering the published tree/package.

Verification

The release is gated by the full local suite, clean Node 20/22/24 installs, typecheck/build, npm audit, package/tree leak inspection, official ARD v0.91 conformance and positive MCP 2026-07-28 interoperability against the current official TypeScript SDK source pinned to an immutable upstream commit, plus an explicit compatibility-boundary check against the npm-published SDK 2.0.0, before publication.

• Protocol-version rejections returned as JSON-RPC errors with id:null are now surfaced accurately instead of being misclassified as response-ID mismatches.

CatalogLock v0.2.0 — Live MCP Tool-Surface Locking

🔒 CatalogLock v0.2.0

Live MCP Tool-Surface Locking

Stable identity is not stable capability. CatalogLock now locks both.

---

CatalogLock v0.2.0 directly addresses a dangerous agentic-supply-chain failure mode: an MCP server can keep the same publisher, identity, Server Card and endpoint while its runtime executable tool surface changes underneath the client.

A newly appearing delete_*, transfer_*, admin_* or any other tool is no longer invisible just because the discovery metadata stayed stable.

✨ What changed

• Resolves current application/mcp-server-card+json ARD resources.
• Follows public Streamable HTTP MCP remotes through the same SSRF/DNS-pinning boundary used by catalog resolution.
• Calls live MCP tools/list using protocol revision 2026-07-28.
• Canonicalizes and SHA-256 hashes every complete tool definition.
• Separately hashes inputSchema and outputSchema when present.
• Produces deterministic lockfile v2 with MCP Server Card, endpoint and tool-surface state.
• Flags new MCP tools as CRITICAL drift.
• Flags changed MCP tool definitions/schemas as CRITICAL drift.
• Flags MCP endpoint changes as CRITICAL drift.
• Flags Server Card semantic changes independently.
• Handles paginated tools/list safely with page/tool ceilings and cursor-loop protection.
• Parses both direct JSON and SSE-delivered JSON-RPC list results.
• Detects required-auth Server Cards without persisting credentials.
• Adds requireMcpInspection for environments that must fail closed when a surface cannot be inspected.
• Updates the self-contained HTML report with live MCP surface/tool visibility.
• Updates GitHub Action outputs with mcp-surfaces and mcp-tools.
• Tracks the current ARD v0.91 proposal published 26 August 2026.

🎯 The exact drift case

Reviewed state:

get_invoice
search_invoices

Later, with the same server identity and endpoint:

get_invoice
search_invoices
delete_invoice

CatalogLock now reports:

[CRITICAL] mcp-tool-added:
New executable MCP tool appeared: delete_invoice on urn:air:example.com:mcp:billing

That is the core v0.2.0 change.

🛡️ Security properties

Live MCP inspection does not weaken CatalogLock's network boundary. Server Card URLs and MCP endpoints are subject to the same HTTPS policy, port allowlist, DNS resolution, public-IP rejection and pinned socket lookup as catalog retrieval.

POST redirects are only followed for HTTP 307/308 so an MCP request cannot silently mutate into a GET during redirect handling.

CatalogLock still does not execute tools, infer that a tool implementation matches its schema, or treat a clean scan as authorization to invoke a resource.

🧪 Verification

The release candidate passed 54/54 tests plus production TypeScript build and CLI smoke tests before publication.

Coverage includes:

• exact same-identity/new-tool drift regression
• tool-schema mutation
• Server Card semantic drift
• deterministic tool ordering and hashing
• pagination and cursor-loop handling
• duplicate tool rejection
• JSON and SSE tools/list responses
• authenticated Server Card handling
• catalog → Server Card → tools/list → lockfile end-to-end flow
• IPv4/IPv6 private-address rejection
• nested catalog bounds
• publisher/source and trust-identity checks
• deterministic lockfiles
• policy, catalog, resource and authority drift

🚀 Usage

cataloglock scan example.com
cataloglock lock example.com --output cataloglock.lock.json
cataloglock verify example.com --lock cataloglock.lock.json

Live MCP inspection is enabled by default for public, unauthenticated Streamable HTTP Server Cards.

To require complete MCP inspection:

{
  "requireMcpInspection": true
}

To explicitly disable live MCP inspection:

cataloglock lock example.com --no-mcp-tools

📦 Release artifacts

This release includes:

• CatalogLock-v0.2.0.zip
• cataloglock-0.2.0.tgz
• CatalogLock-v0.2.0.sha256

---

The open agentic web needs more than identity pinning. It needs capability pinning.

⭐ Star the repository if you want agent discovery and runtime capability drift to become reviewable infrastructure.

CatalogLock

🔒 CatalogLock v0.1.0

First public release

ARD / ai-catalog security · recursive resolution · SSRF resistance · trust graph · deterministic lockfile · blast-radius diff · SARIF · GitHub Action

---

CatalogLock is a pre-connect security gate for Agentic Resource Discovery (ARD) catalogs. It resolves remote catalog graphs under strict network controls, validates publisher and trust authority, freezes reviewed state into a deterministic lockfile, and makes later drift explicit before an agent connects to newly discovered capabilities.

retrieval ≠ trust and discovery ≠ authorization

✨ Highlights

• Canonical ARD discovery via /.well-known/ai-catalog.json
• Compatibility probe for early /.well-known/ard.json deployments
• Recursive catalog resolution with explicit depth/catalog limits
• SSRF resistance across IPv4/IPv6, private, loopback, link-local, CGNAT, reserved and documentation ranges
• DNS validation plus pinned socket lookup to reduce rebinding risk
• Redirect-by-redirect URL/DNS/IP revalidation
• Publisher/source authority validation for urn:air: identifiers
• HTTPS, SPIFFE and did:web trust-identity alignment checks
• Host-level trust identity validation
• Cross-catalog identifier collision detection
• Deterministic SHA-256 lockfiles with policy and graph fingerprints
• Full-entry semantic hashing
• Policy, root, catalog, resource and authority drift detection
• Blast-radius reporting with severity classification
• JSON, self-contained HTML and SARIF 2.1.0 output
• Ready-to-use GitHub Action
• Zero runtime npm dependencies

🛡️ Security posture

CatalogLock treats catalog metadata as untrusted input.

It does not silently promote strings such as SOC2-Type2, HIPAA or GDPR into verified compliance claims. It records signature presence but does not claim cryptographic verification where verification has not actually occurred. Passing CatalogLock is not equivalent to authorizing the discovered MCP server, A2A agent or API.

The resolver is fail-closed around unsafe network destinations and enforces bounded graph traversal.

🧪 Verification

The release candidate passed 44/44 regression tests before publication, including coverage for:

• IPv4/IPv6 private-address rejection
• canonical ARD discovery behavior
• schema and URL/data validation
• publisher/source mismatches
• host trust identity mismatches
• cross-catalog identifier collisions
• deterministic lockfile generation
• authority drift
• policy drift
• catalog body drift
• semantic entry drift

The source release was also compiled against genuine Node 24 type definitions, and the packaged CLI/action wrappers were smoke-tested.

🚀 Quick start

npm ci
npm run build

node dist/cli.cjs scan example.com
node dist/cli.cjs lock example.com --output cataloglock.lock.json

Then compare reviewed state later:

node dist/cli.cjs lock example.com --output cataloglock.next.json
node dist/cli.cjs diff cataloglock.lock.json cataloglock.next.json

⚙️ GitHub Action

Use the published semver release tag:

name: Catalog security
on: [push, pull_request]

jobs:
  cataloglock:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: BryanFiFife/CatalogLock@v0.1.0
        with:
          target: example.com
          fail-on: error
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: cataloglock.sarif

📦 Release artifacts

Attach these three files to the GitHub Release:

• CatalogLock-v0.1.0.zip
• cataloglock-0.1.0.tgz
• CatalogLock-v0.1.0.sha256

SHA-256

893f24ceaa03b740a510bd2a2fcc8a354fb065ed525ca798ca9a5cfc8a2081c0  CatalogLock-v0.1.0.zip
4fa5a74afcc4fd16fef2af01e9b710327746fc5664e9a809829d9ccf5d7afc20  cataloglock-0.1.0.tgz

📌 Release target

Published tag: v0.1.0

Recommended target commit:

de13eb613044b2589880f2d579cc9818ffe00bc4

This commit contains the verified v0.1.0 implementation plus the final README/CI metadata fixes. No application-source changes were made after the 44/44 test gate.

🗺️ Next

Planned work includes cryptographic verification for supported JWS/DID Web trust manifests, richer redirect-chain telemetry, public-suffix-aware authority policy, signed lockfiles/transparency anchoring, fleet-scale registry ingestion and enterprise policy packs.

---

The open agentic web needs a lockfile.

⭐ If CatalogLock is useful to you, star the repository and help make agent discovery reviewable infrastructure instead of blind runtime trust.