Repository navigation
Releases
SurfacePin 1.6.1
No change to the CLI, library or Action behavior, the lockfile format or any digest. Besides documentation and tests, the only code changes are the version string and the wording of five error messages (two lockfile version errors, the unknown canonicalization error and two canonical JSON errors).
- The
surfacepin-jcs-v2format is frozen. SPEC.md now opens with a format freeze and compatibility promise: for the same input, every future release computes the same jcs-v2 bytes, digests and roots; any future format need ships as a new, separately named profile;surfacepin-jcs-v1andsurfacepin-jcs-v2lockfiles stay verifiable; an unknown profile is always rejected. README links to it. - Golden fixtures lock the format.
testdata/golden/jcs-v2/holds the byte-exact canonical output, lockfiles and SHA-256 hashes for two representative surfaces, plus value-level encoding vectors. A new test fails if any byte changes. - SPEC.md now states the string rules exactly, including two existing behaviors that differ from RFC 8785: a repeated member name keeps its last value, and an unpaired surrogate is hashed as U+FFFD; RFC 8785 rejects both.
- SPEC.md now says plainly that
surfacepin-jcs-v1already changed meaning once, in 1.4: lockfiles written by 1.0–1.3 for tools withannotationsoroutputSchemareport drift until re-locked. That is unchanged. - A real lockfile v2, written by the published SurfacePin 1.2.0, is now a test fixture, and the roots of the existing jcs-v1 fixtures are pinned in a test.
- SPEC.md: the instructions string may come from
initializeorserver/discover; where it comes from is transport, not format. Unknown lockfile fields never affect pass/fail; new sections arrive only with a new profile. - Error messages: a non-numeric lockfile
versionand an unknowncanonicalizationare shown quoted (got "3",unsupported canonicalization: "surfacepin-jcs-v2 "), and canonical JSON errors name both profiles. - README: Quick start says Node 22+, matching
engines. - SPEC.md wording: plain language in place of internal shorthand.
SurfacePin 1.6.0
Existing lockfiles keep verifying exactly as in 1.5. Re-lock to get the new pins.
- Titles are pinned. New locks record canonicalization
surfacepin-jcs-v2, which also hashestitleon tools, resources, prompts and prompt arguments, and toolannotations.title. Clients showtitleto people in approval prompts, so under 1.5 a title swap passed verify. Locks that recordsurfacepin-jcs-v1are still verified with v1 rules;verifyprints a one-line re-lock note for them. - New
instructionssurface.--surface …,instructionspins theinstructionstext from the server'sinitializereply. Many clients pass it to the model. verify --jsonprints the sameDiffResultasdiff --json, with the same exit codes.verifyanddiffdefault to the surfaces stored in the lockfile, so--surfaceno longer has to be repeated in CI.- Fix: the
--stdioserver now inherits the caller's environment. Before, it got only HOME/PATH/USER-style variables, so a server that reads an API key or feature flag could expose a different surface than in the user's client. --clean-envand--env-allow NAME[,NAME…]for--stdio(Action inputsclean-env,env-allow) keep CI secrets away from the server when it does not need them.surfacepin --help/-hprint the usage on stdout and exit0. Running with no arguments is still a usage error (stderr, exit2).- Fix: names and field paths containing control characters are printed JSON-quoted, so a server-chosen name can't forge report lines.
- Fix: a server that repeats a list cursor, or returns more than 10,000 pages, is an error instead of a loop until the timeout.
- Action: on drift it writes the diff to the job summary and puts an error annotation on the lockfile. It turns off workflow commands while server text is printed, no longer glob-expands
server-args, installs withnpm ci --include=devfrom the tag (soNODE_ENV=productionjobs build), uses Node 22 by default (node-versioninput; it applies to later steps in your job too), pinsactions/setup-nodeby commit, and drops the unpinnednpm install -gfallback. Pin@v1.6.0. - The MCP client identifies itself with the package version (it said 1.2.0).
surfacepin --versionwas added. The npm package no longer ships compiled tests, andnpm packalways builds a freshdist(prepack). Node 22 or later. - Docs: README rewritten (quickstart, CI, comparison with mcp-scan, limits and threat model). Internal planning and status files removed. A stderr tip added on main after 1.5.0 (never released) is gone.
v1.5.0
Five-minute lock path.
Action@v1 can lock from multi-surface dumps and from a live MCP server (command/stdio). Pre-commit hook included. Pass/fail is still digest equality on surfacepin.lock.json (unchanged name, lockfile v3).
npm: npm i surfacepin@1.5.0
Pin Action@v1.4.0 (or older) if you need the previous hasher behavior.
v1.4.0
Lockfile Spec v1.4. Exact-hash now includes tool annotations
(drop title) and outputSchema. Pass/fail is still digest equality.
Re-lock if your tools already had annotations or outputSchema:
surfacepin lock <file.json> -o surfacepin.lock.json
Action@v1 now serves this hasher. Pin @v1.3.0 to stay on 1.3.