Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
# Changelog

## 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-v2` format 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-v1` and `surfacepin-jcs-v2` lockfiles 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-v1` already changed meaning once, in 1.4: lockfiles written by 1.0–1.3 for tools with `annotations` or `outputSchema` report 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 `initialize` or `server/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 `version` and an unknown `canonicalization` are 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.

## 1.6.0

Existing lockfiles keep verifying exactly as in 1.5. Re-lock to get the new pins.
Expand Down
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ They overlap on change detection and complement each other. SurfacePin keeps the

## Five-minute quickstart

Node 20+. This uses the stub server that ships in the repo, so nothing is fetched beyond npm packages.
Node 22+. This uses the stub server that ships in the repo, so nothing is fetched beyond npm packages.

```bash
git clone https://github.com/yellowgram/surfacepin.git
Expand Down Expand Up @@ -145,6 +145,10 @@ const live = await verifyStdio({ command: "node", args: ["server.mjs"], lockfile
- Re-locking writes `surfacepin-jcs-v2`, which also pins titles (including prompt argument titles) (and instructions, if you add `--surface …,instructions`). Review the diff first.
- A jcs-v2 lockfile needs SurfacePin 1.6 or later. Move the Action pin to `@v1.6.0` in the same commit; an older verifier rejects the lockfile with exit 2 rather than passing it.

## Format stability

The lockfile format SurfacePin writes, canonicalization `surfacepin-jcs-v2` in lockfile v3, is frozen. For the same surface, every future release computes the same bytes and digests, so a lockfile that passes today keeps passing. If the format ever needs to change, the change ships as a new, separately named profile; `surfacepin-jcs-v2` itself never changes. Older `surfacepin-jcs-v1` lockfiles stay verifiable. Byte-exact golden fixtures in `testdata/golden/jcs-v2/` fail CI on any drift. The full promise is in [SPEC.md §0](./SPEC.md#0-format-freeze-and-compatibility-promise).

## Limits and threat model

SurfacePin proves that the surface a server **declares** is byte-for-byte what you reviewed. It does not prove that the surface is safe or that the server behaves as declared.
Expand Down
78 changes: 61 additions & 17 deletions SPEC.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "surfacepin",
"version": "1.6.0",
"version": "1.6.1",
"description": "Lock exact hashes of what an MCP server shows a model (tools, resources, prompts, titles, initialize instructions) and fail CI on silent drift. Offline files or live --stdio; field-level diff.",
"license": "MIT",
"author": {
Expand Down
8 changes: 4 additions & 4 deletions src/canonicalize.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/**
* surfacepin-jcs-v1 — RFC 8785 JCS-compatible deterministic JSON encoding.
* See SPEC.md §3.
* SurfacePin canonical JSON (shared by surfacepin-jcs-v1 and surfacepin-jcs-v2): RFC 8785
* JCS-compatible deterministic JSON encoding. See SPEC.md §3.
*/

function isPlainObject(value: unknown): value is Record<string, unknown> {
Expand Down Expand Up @@ -57,7 +57,7 @@ function escapeString(s: string): string {
*/
function serializeNumber(n: number): string {
if (!Number.isFinite(n)) {
throw new Error(`non-finite number not allowed in surfacepin-jcs-v1: ${n}`);
throw new Error(`non-finite number not allowed in surfacepin canonical JSON (jcs-v1 and jcs-v2): ${n}`);
}
// JSON.stringify uses the ES ToString number rules JCS relies on.
return JSON.stringify(n);
Expand Down Expand Up @@ -100,7 +100,7 @@ export function canonicalize(value: unknown): string {
return `{${parts.join(",")}}`;
}

throw new Error(`unsupported JSON type in surfacepin-jcs-v1: ${t}`);
throw new Error(`unsupported JSON type in surfacepin canonical JSON (jcs-v1 and jcs-v2): ${t}`);
}

/** UTF-8 bytes of the canonical form. */
Expand Down
2 changes: 1 addition & 1 deletion src/test/contributor-path.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ describe("action/verify.sh", () => {
]);
});

it("clean-env and env-allow reach the CLI in stdio mode and are refused in file mode (SP-4)", () => {
it("clean-env and env-allow reach the CLI in stdio mode and are refused in file mode", () => {
const dir = mkdtempSync(join(tmpdir(), "surfacepin-argv-"));
const fake = join(dir, "fake-cli.js");
const out = join(dir, "argv.json");
Expand Down
55 changes: 55 additions & 0 deletions src/test/error-messages.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
/** Wording of lockfile format and canonical JSON errors (outside the frozen format; exit codes unchanged). */
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { describe, it } from "node:test";
import { fileURLToPath } from "node:url";
import { canonicalize } from "../canonicalize.js";
import { parseLockfile } from "../verify.js";

const testdata = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "testdata");
const read = (f: string): unknown => JSON.parse(readFileSync(join(testdata, f), "utf8"));

describe("format error messages", () => {
it("a non-numeric lockfile version is shown quoted", () => {
const v3 = read("titles.v3.lock.json") as Record<string, unknown>;
assert.throws(
() => parseLockfile({ ...v3, version: "3" }),
(e: Error) => e.message === 'canonicalization surfacepin-jcs-v2 requires lockfile version 3 (got "3")',
);
const v1 = read("basic.lock.json") as Record<string, unknown>;
assert.throws(
() => parseLockfile({ ...v1, version: "1" }),
(e: Error) => e.message === 'unsupported lockfile version: "1"',
);
assert.throws(
() => parseLockfile({ ...v1, version: 4 }),
(e: Error) => e.message === "unsupported lockfile version: 4",
);
});

it("an unknown canonicalization is shown quoted", () => {
const v3 = read("titles.v3.lock.json") as Record<string, unknown>;
assert.throws(
() => parseLockfile({ ...v3, canonicalization: "surfacepin-jcs-v2 " }),
(e: Error) => e.message === 'unsupported canonicalization: "surfacepin-jcs-v2 "',
);
const { canonicalization: _omit, ...missing } = v3;
void _omit;
assert.throws(
() => parseLockfile(missing),
(e: Error) => e.message === "unsupported canonicalization: undefined",
);
});

it("canonical JSON errors name both profiles", () => {
assert.throws(
() => canonicalize(Number.NaN),
(e: Error) => e.message === "non-finite number not allowed in surfacepin canonical JSON (jcs-v1 and jcs-v2): NaN",
);
assert.throws(
() => canonicalize(1n),
(e: Error) => e.message === "unsupported JSON type in surfacepin canonical JSON (jcs-v1 and jcs-v2): bigint",
);
});
});
119 changes: 119 additions & 0 deletions src/test/frozen-lockfiles.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
/**
* Lockfiles that existing users already have committed. Their roots and file hashes are
* pinned here so that verification of existing pins can never change unnoticed, even if
* the fixture files are regenerated (SPEC.md §0 promise 3).
*/
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { describe, it } from "node:test";
import { fileURLToPath } from "node:url";
import { verify } from "../api.js";
import { computeSurface } from "../lock.js";
import { parseLockfile } from "../verify.js";
import type { SurfaceKind } from "../types.js";

const here = dirname(fileURLToPath(import.meta.url));
const repo = join(here, "..", "..");
const testdata = join(repo, "testdata");
const cli = join(repo, "dist", "cli.js");
const sha256 = (b: Buffer): string => createHash("sha256").update(b).digest("hex");
const read = (f: string): unknown => JSON.parse(readFileSync(join(testdata, f), "utf8"));

const FROZEN_V1: ReadonlyArray<{
lockfile: string;
surface: string;
kinds: SurfaceKind[];
version: 1 | 2 | 3;
root: string;
fileSha256: string;
writtenBy: string;
}> = [
{
lockfile: "basic.lock.json",
surface: "basic.tools.json",
kinds: ["tools"],
version: 1,
root: "eca572b549d73a6db0c8c2a44f865982c67aaf291f4c57d80dfd6031af62c2f2",
fileSha256: "5be933eb2511bddb6ae886e9caeb8d221ef991de4fd3fbd609db00d2cbcf9baa",
writtenBy: "lockfile v1 (tools only)",
},
{
lockfile: "basic.v2.lock.json",
surface: "basic.surface.json",
kinds: ["tools", "resources", "prompts"],
version: 2,
root: "21e88a5125e9d687ef27d1fbe4e3259c20a0fd6b0b8a0300d5cc3d5fbb371317",
fileSha256: "ee66a0831ee75a75821ecf25d432ea6c341518c7e543e23c9eb4e9699a6278f3",
writtenBy: "published surfacepin@1.2.0 (lockfile v2)",
},
{
lockfile: "basic.v3.lock.json",
surface: "basic.tools.json",
kinds: ["tools"],
version: 3,
root: "efaec0b9f37bd16446eefaea05f562075df0506da99f1ce3204e26e6c4de70bb",
fileSha256: "217e7832eae2a6a714afc32cd3ca4b6f080cd8e3e279a8f3af787e8300f67a38",
writtenBy: "lockfile v3, jcs-v1, tools only",
},
{
lockfile: "annotations-output.v3.lock.json",
surface: "annotations-output.tools.json",
kinds: ["tools"],
version: 3,
root: "eb3d367190d9d62f77225e211b90da7090ad11152b541190a35dda25b637dcfa",
fileSha256: "666c5e4b7d148425fc4230830c549110eb9a44aed342a1d730739547e8f63d5f",
writtenBy: "lockfile v3, jcs-v1, annotations and outputSchema",
},
];

describe("existing surfacepin-jcs-v1 lockfiles keep verifying", () => {
for (const f of FROZEN_V1) {
describe(`${f.lockfile}: ${f.writtenBy}`, () => {
it("file bytes, version, profile and root are the pinned values", () => {
assert.equal(sha256(readFileSync(join(testdata, f.lockfile))), f.fileSha256);
let lock: ReturnType<typeof parseLockfile> | undefined;
assert.doesNotThrow(() => {
lock = parseLockfile(read(f.lockfile));
}, `${f.lockfile} must stay readable`);
assert.equal(lock?.version, f.version);
assert.equal(lock?.canonicalization, "surfacepin-jcs-v1");
assert.equal(lock?.root, f.root);
});

it("recomputing the surface with jcs-v1 gives the pinned root", () => {
const computed = computeSurface(read(f.surface), f.kinds, "surfacepin-jcs-v1");
// Lockfile v1's root is the tools section root; v2 and v3 use the overall root.
assert.equal(f.version === 1 ? computed.tools?.root : computed.root, f.root);
});

it("verifies through the library", () => {
let ok: boolean | undefined;
assert.doesNotThrow(() => {
ok = verify(read(f.surface), read(f.lockfile)).ok;
}, `${f.lockfile} must stay verifiable`);
assert.equal(ok, true);
});

it("verifies through the CLI (exit 0)", () => {
const r = spawnSync(
process.execPath,
[cli, "verify", join(testdata, f.surface), join(testdata, f.lockfile)],
{ encoding: "utf8" },
);
assert.equal(r.status, 0, r.stdout + r.stderr);
assert.match(r.stdout, /OK: surface matches lockfile/);
});
});
}

it("the real lockfile v2 still fails on drift", () => {
const doc = read("basic.surface.json") as { prompts: Array<{ description?: string }> };
const changed = structuredClone(doc);
changed.prompts[0].description = `${changed.prompts[0].description ?? ""}.`;
assert.equal(verify(changed, read("basic.v2.lock.json")).ok, false);
});
});

Loading
Loading