Skip to content

Latest commit

 

History

History
129 lines (105 loc) · 5.5 KB

LOCK.md

File metadata and controls

129 lines (105 loc) · 5.5 KB

Lock spec

The file you commit is the same check that runs in CI and on the wire.

If the tool the model can see is not the tool you approved, the call does not happen.

This is the digest other tools implement. It is not a second lock format. .mcp-pin.lock is JSON, version 2, no hostname, no env values.

Tool digest

SHA-256, hex, of the UTF-8 bytes of the RFC 8785 (JCS) canonical form of body.

sha256(jcs(body))

JCS is what makes "same object, same digest, any language" a specification rather than a hope. It pins the number formatting and key ordering that two hand-matched implementations will always eventually disagree about:

case JCS writes
1.0 1 — an integral float loses its decimal
-0.0 0
1e16 10000000000000000 — full decimals below 1e21
1e21 1e+21 — exponent notation at and above it
1e-7 1e-7 — full decimals down to 1e-6
a lone surrogate escaped as \udXXX, rather than refused
keys sorted by UTF-16 code unit, not by code point

Two consequences worth stating outright:

  • A key mixing BMP and astral characters sorts differently under UTF-16 than under code point. In {"": 1, "😀": 2} the emoji comes first.
  • An integer that cannot survive a double round-trip — 9007199254740993 — is hashed as the nearest double, 9007199254740992, which is what JavaScript's JSON.parse makes of it, so both sides agree. Two integers that round to the same double therefore hash alike. Only an integer beyond the largest double is refused. Large integral values are written as ECMAScript writes them: 2**60 is 1152921504606847000, not its exact digits.

body is:

key rule
name string; missing becomes ""
title string; missing becomes ""
description string; missing becomes ""
input_schema object; missing becomes {}. Wire name inputSchema is accepted.
annotations object; missing becomes {}
output_schema object; omitted when missing or {}. Wire name outputSchema is accepted.
icons array; omitted when missing or empty

Omitted keys are load-bearing. Writing output_schema: {} into every hash would rug-pull every existing lockfile on upgrade.

Key order in the input object does not change the digest. tests/golden/tools/04-schema-key-order-a.json and 05-schema-key-order-b.json are the same hex.

1 and 1.0 are now the same digest, which is the point of the change: a Pydantic or FastMCP server emitting "minimum": 0.0 used to hash differently in Python and in JavaScript, so the Claude Code plugin hook reported drift on tools that had been approved correctly.

Vectors

tests/golden/tools/ — twelve objects, ten cases (one pair is key order). A checker that disagrees with any file is wrong.

tests/golden/jcs_vectors.json — the canonicalization contract itself, read by tests/test_digest_parity.py and by js/heldfast-check/test.js. Both languages assert the same strings from the same file, so the two implementations cannot drift apart again without a test going red.

python -c "from heldfast.digest import tool_digest; ..."
node js/heldfast-check/bin.js --golden tests/golden/tools

File

{
  "version": 2,
  "generated": "2026-09-21T00:00:00Z",
  "servers": {
    "claude-code:files": {
      "name": "files",
      "command_line": "npx -y @scope/[email protected]",
      "tools": {
        "read_file": {
          "fingerprint": "<64 hex>",
          "description_preview": "Read a file from disk."
        }
      }
    }
  },
  "skills": {}
}
  • Version newer than the tool understands is refused (T-LOCK-FUTURE).

  • A version 1 lock is reported, not silently re-read. Its fingerprints came from the pre-JCS digest, and this tool cannot tell which of them the change affected. scan says the lock needs re-approving instead of comparing against it, and heldfast-check returns T-LOCK-STALE-DIGEST. Run heldfast approve to re-record it.

    In practice most digests do not change: all twelve golden vectors hash to the same hex under both algorithms, because ordinary tool objects contain none of the constructs JCS pins down. A digest moves only if the object holds an integral float (1.0, the common one), a value like 1e16, a -0.0, or keys mixing BMP with astral characters. The version bump is there because nothing can tell you which locks those are without rehashing them, and quietly reporting a changed algorithm as a rug pull is the failure this whole change exists to prevent.

  • Hostname does not belong in a portable lock.

  • Env values do not belong in a portable lock. The launch command is pinned (T-LAUNCH); logs redact env.

  • Credentials do not belong in it either. A launch line or URL that carries one -- a --token argument, a user:password@ or ?api_key= URL, often from a user-level config that was never meant for a repository -- is written redacted, and launch_sha256 (SHA-256 of the JSON array [command_line, url] of the real values) is recorded beside it. The launch pin and MCPA016 compare that digest, so a changed launch is still caught; a changed credential is reported as one, without its value. A lock with no launch_sha256 compares command_line as written, as before.

  • heldfast check / heldfast-check verify the file without launching anything.

  • Missing file is MCPA014. Drifted tool is MCPA015.

Python: heldfast.digest.tool_digest. JavaScript: js/heldfast-check. Claude Code: plugin/heldfast.