diff --git a/CHANGELOG.md b/CHANGELOG.md index e04a0b2..6da7f2b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index ed1ac02..8d4879d 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. diff --git a/SPEC.md b/SPEC.md index be22065..e9234ad 100644 --- a/SPEC.md +++ b/SPEC.md @@ -3,13 +3,38 @@ Canonical specification for SurfacePin surface locking. CLI and Action are reference clients of this document. -**Status:** Lockfile Spec v1.6 (2026-10-19) -**Scope:** MCP `tools/list`, `resources/list`, and `prompts/list` surfaces, and the server's `initialize.instructions`. +**Status:** Frozen as of 2026-10-20 (published in SurfacePin 1.6.1). The frozen format, canonicalization profile `surfacepin-jcs-v2` in lockfile v3, is exactly what SurfacePin 1.6.0 writes. See §0. +**Scope:** MCP `tools/list`, `resources/list`, and `prompts/list` surfaces, and the server's instructions (`initialize` or `server/discover`). **Wire formats:** lockfile **v1** (tools digests), **v2** (multi-surface digests), **v3** (multi-surface + embedded hashed payloads for structured field-diff). **Not in wire format:** signed lockfiles, semantic/embedding drift, LLM-assisted diff. --- +## 0. Format freeze and compatibility promise + +`surfacepin-jcs-v2` is **frozen**. Its format will not change. + +"The format" means everything that decides the bytes SurfacePin hashes and the digests it compares, for a lockfile that records `"canonicalization": "surfacepin-jcs-v2"`: + +- which input fields are hashed, ignored or rejected, and the defaults for absent fields (§2); +- the canonical byte encoding (§3.1); +- the item digests, section roots and overall root, including their fixed prefix lines (§3.2); +- the lockfile v3 fields and their meaning (§4.3), and the profile id string `surfacepin-jcs-v2` itself. + +What SurfacePin promises: + +1. **A pin keeps its meaning.** For the same input, every future SurfacePin release computes exactly the same jcs-v2 bytes, digests and roots as 1.6.0. A jcs-v2 lockfile that passes today keeps passing, and one that fails keeps failing. +2. **No silent changes.** Any future need (a newly hashed field, a new surface kind, a different default, a fix to the encoding) ships as a new, separately named profile such as `surfacepin-jcs-v3`, and, if the lockfile shape changes, a new lockfile `version`. It is never made by changing what `surfacepin-jcs-v2` means. +3. **Existing pins are never dropped.** Verifiers keep verifying every profile and lockfile version they verify today: `surfacepin-jcs-v1` (lockfile v1, v2 and v3) and `surfacepin-jcs-v2` (lockfile v3). Each lockfile is always recomputed with the profile it records. `surfacepin-jcs-v1` means the rules of SurfacePin 1.4 and later (annotations and `outputSchema` hashed). Lockfiles written by 1.0–1.3 for tools that carry `annotations` or `outputSchema` have reported drift since 1.4 (§9) and still do; re-lock them. +4. **Unknown means reject.** A verifier that does not know a lockfile's profile rejects it (exit 2). It never falls back to another profile and never passes the lockfile. +5. **New profiles are opt-in for existing pins.** A new profile can become the default for newly written locks only in a release whose CHANGELOG entry and §9 migration notes say so. Existing lockfiles keep the profile they record until you re-lock. + +If the reference implementation is ever found to differ from this document for jcs-v2, the frozen behavior captured by the golden fixtures (§11) is the format. This document is corrected to describe it, and any change in behavior ships as a new profile. + +Not part of the frozen format, and free to improve: the explanatory field-diff paths and labels (§6), report wording, stderr notes and other CLI messages. None of them affect pass/fail. File formatting of a lockfile is not hashed (§4.3), although the bytes the reference CLI writes are also pinned by the golden fixtures. Where the instructions string is fetched from (a legacy `initialize` result or a `server/discover` result) is transport, not format; the hashed descriptor `{ "name": "instructions", "text": … }` is the same. + +--- + ## 1. Goals 1. **Exact hash** — pass/fail is deterministic byte comparison of digests. @@ -27,7 +52,7 @@ CLI and Action are reference clients of this document. | `tools` | `tools/list` | `name` | `name`, `title`, `description`, `inputSchema`, `annotations` (including `annotations.title`), `outputSchema` | | `resources` | `resources/list` | `uri` | `uri`, `name`, `title`, `description`, `mimeType` | | `prompts` | `prompts/list` | `name` | `name`, `title`, `description`, `arguments` (each argument's `name`, `description`, `required`, and in jcs-v2 its `title`; see §2.4) | -| `instructions` | `initialize` result | `"instructions"` | `text` | +| `instructions` | `initialize` (or `server/discover`) result | `"instructions"` | `text` | Under `surfacepin-jcs-v1` (locks written by 1.5 and earlier) no `title` is hashed and the `instructions` kind does not exist. See §3.0. @@ -35,7 +60,7 @@ Under `surfacepin-jcs-v1` (locks written by 1.5 and earlier) no `title` is hashe Aligned to MCP schema revision **2026-07-28** as a documentation reference only (not a runtime fetch). -Profile ids: `"surfacepin-jcs-v2"` (written since 1.6.0) and `"surfacepin-jcs-v1"` (still verified). See §3.0. +Profile ids: `"surfacepin-jcs-v2"` (written since 1.6.0, frozen; see §0) and `"surfacepin-jcs-v1"` (still verified). See §3.0. ### 2.1 Input shapes @@ -46,7 +71,7 @@ SurfacePin accepts a combined document: "tools": [ /* Tool */ ], "resources": [ /* Resource */ ], "prompts": [ /* Prompt */ ], - "instructions": "" + "instructions": "" } ``` @@ -60,8 +85,8 @@ Selected list kinds with a missing key are treated as an **empty array**. A miss | Field | Required | Notes | |-------|----------|-------| | `name` | yes | Non-empty string. Primary identity. | -| `description` | no | If absent, treated as `""` (1.3 coercion unchanged). | -| `inputSchema` | no | If absent, treated as `{}`. Must be a JSON object when present (1.3 coercion unchanged). | +| `description` | no | If absent, treated as `""`. | +| `inputSchema` | no | If absent, treated as `{}`. Must be a JSON object when present. | | `title` | no | jcs-v2 only. String → hashed as `title`. Absent or `null` → omit key. Non-string → usage error (exit 2). jcs-v1 ignores it. | | `annotations` | no | Source: `tool.annotations`. Keep all keys including unknown; jcs-v1 drops `title` here. If absent or non-object → omit `annotations` key entirely. If empty after any drop → omit key. **Do not** materialize MCP defaults into hashed fields. | | `outputSchema` | no | Absent or `null` → omit key. Empty object `{}` → include as empty object. Present non-object → usage error (exit 2). **Do not** coerce absent → `{}` (absent ≠ `{}`). | @@ -149,7 +174,7 @@ Under jcs-v2 a descriptor with a title also carries `"title": ""` (tools ### 2.5 Instructions (jcs-v2 only) -The `instructions` string from the server's `initialize` result. Many clients pass it to the model, so it steers tool use the way a description does. +The server's `instructions` string (from the `initialize` result, or from `server/discover` in newer MCP revisions; see §0). Many clients pass it to the model, so it steers tool use the way a description does. - Non-empty text → one entry `{ "name": "instructions", "text": "" }`. - Absent, `null` or `""` → no entry (empty section). Text appearing later is `ADDED instructions`; text disappearing is `REMOVED instructions`. @@ -166,17 +191,17 @@ The lockfile's `canonicalization` field names the profile. Both profiles use the | | `surfacepin-jcs-v1` | `surfacepin-jcs-v2` | |---|---|---| -| Written by | 1.0 – 1.5 | 1.6.0 and later (default) | +| Written by | 1.0 – 1.5 (rules as of 1.4; see §9 1.3 → 1.4) | 1.6.0 and later (default) | | `title` on tools, resources, prompts and prompt arguments | ignored | hashed | | tool `annotations.title` | dropped | hashed | | `instructions` kind | not available | available | | Lockfile versions | v1, v2, v3 | v3 only | -A verifier MUST recompute with the profile recorded in the lockfile. A jcs-v1 lock therefore keeps passing or failing exactly as it did under 1.5. For a surface with no titles and no instructions, both profiles give identical digests and roots; only the recorded id differs. +A verifier MUST recompute with the profile recorded in the lockfile. A jcs-v1 lock therefore keeps passing or failing exactly as it did under 1.4 and 1.5. For a surface with no titles and no instructions, both profiles give identical digests and roots; only the recorded id differs. Why titles: MCP clients show `title` to people in place of `name`, including in approval and confirmation prompts. Under jcs-v1, renaming a tool's title from "Export" to "Read-only export (safe)" passed verify. -This is an **RFC 8785 JCS-compatible** deterministic JSON encoding for the JSON data model subset used by SurfacePin (objects, arrays, strings, numbers, booleans, null). Implementation uses Node’s `JSON.parse` / ECMAScript number model. +This is an **RFC 8785 JCS-compatible** deterministic JSON encoding for the JSON data model subset used by SurfacePin (objects, arrays, strings, numbers, booleans, null), with two documented differences: duplicate member names (§3.1 rule 9) and unpaired surrogates (§3.1 rule 5). Implementation uses Node’s `JSON.parse` / ECMAScript number model. ### 3.1 Rules @@ -184,10 +209,11 @@ This is an **RFC 8785 JCS-compatible** deterministic JSON encoding for the JSON 2. **Whitespace:** None (no spaces, tabs, newlines between tokens). 3. **Objects:** Keys sorted by UTF-16 code unit lexicographic order (ECMAScript default string comparison: `(a < b ? -1 : a > b ? 1 : 0)`). 4. **Arrays:** Preserve order. Recursively canonicalize elements. -5. **Strings:** JSON string encoding per ECMA-404 / RFC 8259. +5. **Strings:** JSON string encoding per ECMA-404 / RFC 8259, as RFC 8785 specifies it: `"` and `\` are escaped; U+0008, U+0009, U+000A, U+000C and U+000D are written `\b`, `\t`, `\n`, `\f`, `\r`; other code points below U+0020 are written `\u00xx` (lowercase hex); everything else, including `/`, U+007F, U+2028 and U+2029, is written as-is in UTF-8. An unpaired UTF-16 surrogate (possible in JSON input such as `"\ud800"`) is written as the UTF-8 bytes of U+FFFD (`EF BF BD`), so it hashes the same as a literal U+FFFD. RFC 8785 would reject such a string instead; jcs-v2 keeps this behavior because it is frozen. 6. **Booleans / null:** `true`, `false`, `null`. 7. **Numbers:** ECMAScript `Number` serialization via `JSON.stringify` rules for finite numbers. `NaN` / `±Infinity` are **not allowed**. 8. **No `undefined`:** omit object members that would be undefined. +9. **Duplicate member names:** input JSON is parsed with ECMAScript `JSON.parse`. When an object repeats a member name, the last value is kept and earlier ones are ignored, before normalization and hashing. RFC 8785 (via I-JSON) would reject such input; jcs-v2 keeps this behavior because it is frozen. MCP clients built on `JSON.parse` show the model the same last value. Canonical bytes = UTF-8 encoding of `canonicalize(descriptor)`. @@ -356,7 +382,7 @@ Same section/root digest rules as v2. Each entry includes `surface`: the **exact | `tools` / `resources` / `prompts` / `instructions` | Optional; at least one required. `instructions` requires jcs-v2. | | `entries[].surface` | Required when writing v3; exact hashed descriptor. | -Unknown top-level fields: **ignored** (forward compatible). +Unknown top-level fields are ignored and never affect pass/fail. A new surface kind or section ships only under a new profile (§0), which older verifiers reject. Missing required fields: **usage / format error**. Lockfiles **should** use 2-space indent + trailing newline. File formatting is **not** hashed. @@ -437,7 +463,7 @@ JSON field changes carry a `kinds` **array** of taxonomy labels. Human lines pri Known-hint transitions **not** in that list → `COMPATIBLE` (still a digest change). Examples: `readOnlyHint` `false → true` / `absent → true`; `destructiveHint` `true → false`; `idempotentHint` `false → true`; `openWorldHint` `true → false`. -Explicit value equal to an MCP default then omitted still changes the digest and stays `HINT_FLIP` this cut when the transition is in the list above (do not special-case default-equivalent omit as `COMPATIBLE`). +An explicit value equal to the MCP default that is later omitted still changes the digest, and is labelled `HINT_FLIP` when the transition is in the list above. Omitting a default-equivalent value is not treated as `COMPATIBLE`. #### outputSchema @@ -516,12 +542,12 @@ Streamable HTTP / SSE live fetch is not required for lockfile conformance. ### 1.5 → 1.6 - Existing lockfiles verify exactly as before: they record `surfacepin-jcs-v1`, and verify uses that profile. The CLI prints a one-line stderr note suggesting a re-lock. -- New locks record `surfacepin-jcs-v2`. Re-lock (after reviewing the surface) to pin titles, and add `--surface …,instructions` to pin `initialize.instructions`. +- New locks record `surfacepin-jcs-v2`. Re-lock (after reviewing the surface) to pin titles, and add `--surface …,instructions` to pin the server's instructions. - A jcs-v2 lock needs a 1.6+ verifier. Bump the Action pin in the same commit as the re-lock; an older verifier fails it with exit 2. ### 1.3 → 1.4 -- Old lockfiles (v1 / v2 / v3) still verify. +- Old lockfiles (v1 / v2 / v3) are still read. Tools with neither annotations nor `outputSchema` keep the same digests; tools with either report drift until re-locked. - Digests **change** when a tool had kept annotation keys or `outputSchema`. - Digests stay **stable** when a tool had neither and only `title` / `icons` / `_meta` changed or were present. - **Re-lock after upgrading to ≥1.4** so embedded surfaces and digests include annotations / outputSchema. @@ -537,4 +563,22 @@ Streamable HTTP / SSE live fetch is not required for lockfile conformance. ## 11. Conformance -Golden vectors under `testdata/` are normative for digests: `basic.*`, `empty.*` and `annotations-output.*` for jcs-v1, and `titles.surface.json` → `titles.v3.lock.json` for jcs-v2. Implementations MUST match those digests for the given inputs. Structured field-diff classification rules in §6 are normative for the reference CLI’s explanatory output. +Golden vectors under [`testdata/`](https://github.com/yellowgram/surfacepin/tree/v1.6.1/testdata) (in the GitHub repository; not shipped in the npm package) are normative for digests: `basic.*`, `empty.*` and `annotations-output.*` for jcs-v1, including `basic.v2.lock.json`, a lockfile v2 written by the published SurfacePin 1.2.0 (root `21e88a5125e9d687ef27d1fbe4e3259c20a0fd6b0b8a0300d5cc3d5fbb371317`); and `titles.surface.json` → `titles.v3.lock.json` and everything under `testdata/golden/jcs-v2/` for jcs-v2. Implementations MUST match those digests for the given inputs. Structured field-diff classification rules in §6 are normative for the reference CLI’s explanatory output. + +### 11.1 jcs-v2 golden fixtures (frozen) + +[`testdata/golden/jcs-v2/`](https://github.com/yellowgram/surfacepin/tree/v1.6.1/testdata/golden/jcs-v2) (in the GitHub repository) holds the byte-exact jcs-v2 output of SurfacePin 1.6.0 for two representative surfaces, and `golden.json` lists the SHA-256 of every input surface, canonical `.jcs` file and lockfile. The test [`src/test/golden-jcs-v2.test.ts`](https://github.com/yellowgram/surfacepin/blob/v1.6.1/src/test/golden-jcs-v2.test.ts) recomputes all of it, also pins the SHA-256 of `golden.json` itself, and fails on any difference. The fixtures are never regenerated to make a change pass (§0). + +- `full.surface.json`: all four surface kinds. Tools with and without `title`, `annotations` (including `annotations.title` and an unknown key), `outputSchema` (including `{}`), ignored `icons` / `_meta`, absent `description` / `inputSchema`, string escapes, non-ASCII keys in UTF-16 order, and number forms. Resources and prompts with and without `title`, prompt arguments with a `title` and with defaults, and multi-line instructions. +- `tools-only.surface.json`: the default `surfacepin lock` selection (tools only). +- `*.jcs`: canonical bytes of each embedded descriptor, exactly as hashed (no trailing newline). +- `*.lock.json`: the lockfile the reference CLI writes for the surface. +- `golden.json` `values`: value-level vectors (JSON text in, canonical bytes out), including a repeated member name and an unpaired surrogate. + +| Case | Value | SHA-256 | +|------|-------|---------| +| `full` | overall `root` | `07dee637abb8eb13c64d4ef779a0e2037a6fe3cf3217dee1a85dda7dc5fb6945` | +| `full` | `full.lock.json` file | `5d91442e365b85887bb4970b6ced45e412dd488439270bb86c047078f145fb02` | +| `tools-only` | overall `root` | `092658bdcbfb2d55d67e71d84ded776cc6aca42d88ca8b9f8c36e53cae7e2188` | +| `tools-only` | `tools-only.lock.json` file | `7a2c9c10b697c93e5c7803a5e77d0bba62becaaf58179bc23005989ff2a7eb84` | +| all | `golden.json` file | `6b5d735b828cce234bb47b8dcb2f80ff51b3feb32ac683dd253ad149524d2ab2` | diff --git a/package-lock.json b/package-lock.json index aaba4ea..43bda7f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "surfacepin", - "version": "1.6.0", + "version": "1.6.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "surfacepin", - "version": "1.6.0", + "version": "1.6.1", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "^1.30.1", diff --git a/package.json b/package.json index f9ebade..66db1a5 100644 --- a/package.json +++ b/package.json @@ -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": { diff --git a/src/canonicalize.ts b/src/canonicalize.ts index 8452e16..5adafcb 100644 --- a/src/canonicalize.ts +++ b/src/canonicalize.ts @@ -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 { @@ -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); @@ -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. */ diff --git a/src/test/contributor-path.test.ts b/src/test/contributor-path.test.ts index 132c2c1..66e6baf 100644 --- a/src/test/contributor-path.test.ts +++ b/src/test/contributor-path.test.ts @@ -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"); diff --git a/src/test/error-messages.test.ts b/src/test/error-messages.test.ts new file mode 100644 index 0000000..2d3f73c --- /dev/null +++ b/src/test/error-messages.test.ts @@ -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; + 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; + 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; + 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", + ); + }); +}); diff --git a/src/test/frozen-lockfiles.test.ts b/src/test/frozen-lockfiles.test.ts new file mode 100644 index 0000000..7dc3901 --- /dev/null +++ b/src/test/frozen-lockfiles.test.ts @@ -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 | 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); + }); +}); + diff --git a/src/test/golden-jcs-v2.test.ts b/src/test/golden-jcs-v2.test.ts new file mode 100644 index 0000000..481bf36 --- /dev/null +++ b/src/test/golden-jcs-v2.test.ts @@ -0,0 +1,264 @@ +/** + * Format lock for surfacepin-jcs-v2 (frozen; see SPEC.md "Format freeze and compatibility promise"). + * + * The files under testdata/golden/jcs-v2/ were produced once by SurfacePin 1.6.0 and are + * compared byte for byte. If any of these tests fails, the jcs-v2 output changed. Do not + * regenerate the fixtures to make it pass: jcs-v2 is frozen, and a format change ships as a + * new, separately named profile instead. + */ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { describe, it } from "node:test"; +import { fileURLToPath } from "node:url"; +import { pin, verify } from "../api.js"; +import { canonicalize, canonicalizeToBytes } from "../canonicalize.js"; +import { + instructionsDigest, + promptDigest, + resourceDigest, + toolDigest, +} from "../hash.js"; +import { computeSurface, serializeLockfile } 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 dir = join(repo, "testdata", "golden", "jcs-v2"); +const cli = join(repo, "dist", "cli.js"); + +const sha256 = (b: Buffer | string): string => createHash("sha256").update(b).digest("hex"); +const bytes = (f: string): Buffer => readFileSync(join(dir, f)); +const json = (f: string): unknown => JSON.parse(bytes(f).toString("utf8")); + +interface GoldenEntry { + kind: SurfaceKind; + id: string; + canonical: string; + sha256: string; +} +interface GoldenCase { + name: string; + surface: string; + surfaceSha256: string; + kinds: SurfaceKind[]; + lockfile: string; + lockfileSha256: string; + root: string; + sections: Partial>; + entries: GoldenEntry[]; +} +interface GoldenValue { + input: string; + canonicalHex: string; + sha256: string; +} +const golden = json("golden.json") as { + canonicalization: string; + cases: GoldenCase[]; + values: GoldenValue[]; +}; + +/** + * Pinned here as well as in golden.json and SPEC.md §11, so editing the fixture files alone + * cannot make a format change pass. + */ +const FROZEN = { + full: { + root: "07dee637abb8eb13c64d4ef779a0e2037a6fe3cf3217dee1a85dda7dc5fb6945", + lockfileSha256: "5d91442e365b85887bb4970b6ced45e412dd488439270bb86c047078f145fb02", + surfaceSha256: "c1981ad81f1c61f6ea92330e39611356341b55fb355881cdf3a2eca2fc7f61eb", + }, + "tools-only": { + root: "092658bdcbfb2d55d67e71d84ded776cc6aca42d88ca8b9f8c36e53cae7e2188", + lockfileSha256: "7a2c9c10b697c93e5c7803a5e77d0bba62becaaf58179bc23005989ff2a7eb84", + surfaceSha256: "b63c255c876e5b25b3d8493f9ac91e9d3161bffe59253c4972b7d023f950a153", + }, +} as const; + +/** SHA-256 of golden.json itself, so no listed hash or value vector can change unnoticed. */ +const GOLDEN_JSON_SHA256 = "6b5d735b828cce234bb47b8dcb2f80ff51b3feb32ac683dd253ad149524d2ab2"; + +const caseByName = (n: string): GoldenCase => { + const c = golden.cases.find((x) => x.name === n); + assert.ok(c, `golden case ${n}`); + return c; +}; + +describe("surfacepin-jcs-v2 format lock (golden fixtures)", () => { + it("golden.json is byte-identical to the frozen manifest", () => { + assert.equal(sha256(bytes("golden.json")), GOLDEN_JSON_SHA256); + }); + + it("covers the frozen profile and both representative surfaces", () => { + assert.equal(golden.canonicalization, "surfacepin-jcs-v2"); + assert.deepEqual( + golden.cases.map((c) => c.name), + Object.keys(FROZEN), + ); + // Every surface kind and a non-trivial number of entries are exercised. + const full = caseByName("full"); + assert.deepEqual(full.kinds, ["tools", "resources", "prompts", "instructions"]); + assert.equal(full.entries.length, 9); + assert.equal(caseByName("tools-only").entries.length, 2); + }); + + for (const name of Object.keys(FROZEN) as Array) { + describe(`case ${name}`, () => { + const c = caseByName(name); + const doc = json(c.surface); + + it("root and lockfile hash match the values pinned in this test", () => { + assert.equal(c.root, FROZEN[name].root); + assert.equal(c.lockfileSha256, FROZEN[name].lockfileSha256); + assert.equal(sha256(bytes(c.lockfile)), FROZEN[name].lockfileSha256); + assert.equal(c.surfaceSha256, FROZEN[name].surfaceSha256); + assert.equal(sha256(bytes(c.surface)), FROZEN[name].surfaceSha256); + }); + + it("lock output is byte-identical to the golden lockfile", () => { + const computed = computeSurface(doc, c.kinds, "surfacepin-jcs-v2"); + const text = serializeLockfile(computed.lockfile); + assert.equal(text, bytes(c.lockfile).toString("utf8")); + assert.equal(sha256(Buffer.from(text, "utf8")), c.lockfileSha256); + assert.equal(computed.root, c.root); + for (const kind of c.kinds) { + assert.equal(computed[kind]?.root, c.sections[kind], `${kind} section root`); + } + }); + + it("the default pin() writes jcs-v2 and the same bytes", () => { + const r = pin(doc, { surfaces: c.kinds }); + assert.equal(r.lockfile.canonicalization, "surfacepin-jcs-v2"); + assert.ok(r.text === bytes(c.lockfile).toString("utf8"), "pin() text differs from golden"); + assert.equal(r.root, c.root); + }); + + it("each entry's canonical bytes and digest match the golden files", () => { + const computed = computeSurface(doc, c.kinds, "surfacepin-jcs-v2"); + const seen: GoldenEntry[] = []; + for (const kind of c.kinds) { + const section = computed[kind]; + assert.ok(section, kind); + section.entries.forEach((e, i) => { + const g = c.entries.find((x) => x.canonical === `${c.name}.${kind}.${i}.jcs`); + assert.ok(g, `golden entry ${kind}[${i}]`); + seen.push(g); + const id = "uri" in e ? e.uri : e.name; + assert.equal(id, g.id, `${kind}[${i}] id/order`); + const want = bytes(g.canonical); + const got = canonicalizeToBytes(e.surface); + assert.ok(got.equals(want), `${g.canonical}: canonical bytes differ\n got ${got}\nwant ${want}`); + assert.equal(sha256(want), g.sha256, `${g.canonical} sha256`); + assert.equal(e.digest, g.sha256, `${g.canonical} digest`); + }); + // The digest functions hash exactly these bytes. + const descriptors = section.descriptors as unknown[]; + descriptors.forEach((d, i) => { + const g = c.entries.find((x) => x.canonical === `${c.name}.${kind}.${i}.jcs`)!; + const digest = + kind === "tools" + ? toolDigest(d as Parameters[0]) + : kind === "resources" + ? resourceDigest(d as Parameters[0]) + : kind === "prompts" + ? promptDigest(d as Parameters[0]) + : instructionsDigest(d as Parameters[0]); + assert.equal(digest, g.sha256, `${kind}[${i}] digest function`); + }); + } + assert.equal(seen.length, c.entries.length, "no extra or missing golden entries"); + }); + + it("the golden lockfile parses and verifies against its surface", () => { + const lock = json(c.lockfile); + const parsed = parseLockfile(lock); + assert.equal(parsed.canonicalization, "surfacepin-jcs-v2"); + assert.equal(parsed.version, 3); + assert.equal(verify(doc, lock).ok, true); + }); + + it("the CLI lock command writes the golden bytes", () => { + const out = join(mkdtempSync(join(tmpdir(), "sp-golden-")), "lock.json"); + const surfaceFlag = c.kinds.length === 1 && c.kinds[0] === "tools" ? [] : ["--surface", c.kinds.join(",")]; + const r = spawnSync(process.execPath, [cli, "lock", join(dir, c.surface), ...surfaceFlag, "-o", out], { + encoding: "utf8", + }); + assert.equal(r.status, 0, r.stderr); + assert.ok(readFileSync(out).equals(bytes(c.lockfile)), "CLI lock output differs from golden"); + const v = spawnSync(process.execPath, [cli, "verify", join(dir, c.surface), join(dir, c.lockfile)], { + encoding: "utf8", + }); + assert.equal(v.status, 0, v.stdout + v.stderr); + }); + }); + } + + it("value-level canonical bytes match the golden vectors", () => { + assert.equal(golden.values.length, 10); + for (const v of golden.values) { + const got = canonicalizeToBytes(JSON.parse(v.input)); + assert.equal(got.toString("hex"), v.canonicalHex, v.input); + assert.equal(sha256(got), v.sha256, v.input); + } + }); + + it("documented encoding rules hold (UTF-16 key order, number and string forms)", () => { + // UTF-16 code unit order: U+1F600 (surrogate pair D83D DE00) sorts before U+FF61. + assert.equal(canonicalize({ "\uff61": 3, "\u{1F600}": 2, "\u20ac": 1 }), '{"€":1,"😀":2,"。":3}'); + assert.equal(canonicalize({ b: 2, a: 1, A: 0 }), '{"A":0,"a":1,"b":2}'); + assert.equal(canonicalize([1e21, 1e-7, -0, -12.5]), "[1e+21,1e-7,0,-12.5]"); + assert.equal(canonicalize("\u007f\u2028"), '"\u007f\u2028"'); + assert.equal(canonicalize("\u0000\u001f\b"), '"\\u0000\\u001f\\b"'); + // No Unicode normalization: decomposed and precomposed forms stay distinct. + assert.equal(canonicalizeToBytes("e\u0301").toString("hex"), "2265cc8122"); + assert.equal(canonicalizeToBytes("\u00e9").toString("hex"), "22c3a922"); + // Values outside the JSON data model (library callers only): undefined members are + // omitted and an undefined array element is written as null, as JSON.stringify does. + assert.equal(canonicalize({ a: undefined, b: 1 }), '{"b":1}'); + assert.equal(canonicalize([undefined, 1]), "[null,1]"); + // A lone surrogate is written as the bytes of U+FFFD (documented in SPEC.md §3.1). + assert.equal(canonicalizeToBytes("\ud800").toString("hex"), "22efbfbd22"); + // A repeated member name keeps its last value (JSON.parse; SPEC.md §3.1 rule 9). + assert.equal(canonicalize(JSON.parse('{"a":1,"a":2}')), '{"a":2}'); + }); + + it("a repeated member name in a surface file hashes as its last value (CLI)", () => { + const tmp = mkdtempSync(join(tmpdir(), "sp-dup-")); + const dup = join(tmp, "dup.json"); + const dedup = join(tmp, "dedup.json"); + writeFileSync( + dup, + '{"tools":[{"name":"t","description":"safe","description":"evil"}]}', + ); + writeFileSync(dedup, '{"tools":[{"name":"t","description":"evil"}]}'); + const lockA = join(tmp, "a.lock.json"); + const lockB = join(tmp, "b.lock.json"); + for (const [src, out] of [ + [dup, lockA], + [dedup, lockB], + ]) { + const r = spawnSync(process.execPath, [cli, "lock", src, "-o", out], { encoding: "utf8" }); + assert.equal(r.status, 0, r.stderr); + } + const rootA = (JSON.parse(readFileSync(lockA, "utf8")) as { root: string }).root; + const rootB = (JSON.parse(readFileSync(lockB, "utf8")) as { root: string }).root; + assert.equal(rootA, rootB); + assert.equal(rootA, "428ad318f69f78cd9ae8fed7a508055766e5210b627d3b147a281ffddcf99244"); + const v = spawnSync(process.execPath, [cli, "verify", dedup, lockA], { encoding: "utf8" }); + assert.equal(v.status, 0, v.stdout + v.stderr); + }); + + it("a one-character change in any golden input changes its digest (drift is detected)", () => { + const c = caseByName("full"); + const doc = json(c.surface) as { tools: Array<{ name: string; description?: string; title?: string }> }; + const changed = structuredClone(doc); + const t = changed.tools.find((x) => x.name === "export_records")!; + t.title = `${t.title}.`; + assert.equal(verify(changed, json(c.lockfile)).ok, false); + }); +}); diff --git a/src/test/spec-1.6.test.ts b/src/test/spec-1.6.test.ts index e080e36..c1483c2 100644 --- a/src/test/spec-1.6.test.ts +++ b/src/test/spec-1.6.test.ts @@ -86,7 +86,7 @@ describe("spec 1.6 — surfacepin-jcs-v2 (titles pinned)", () => { assert.deepEqual(r2.diff.surfaces.find((s) => s.kind === "prompts")!.changed[0].fields!.map((f) => f.path), ["title"]); }); - it("a prompt argument title change is drift, reported at its argument path (SP-1)", () => { + it("a prompt argument title change is drift, reported at its argument path", () => { const doc = (t?: unknown) => ({ prompts: [{ name: "send", arguments: [{ name: "to", required: true, ...(t === undefined ? {} : { title: t }) }] }], }); @@ -330,7 +330,7 @@ describe("spec 1.6 — stdio environment", () => { assert.equal(run({ SURFACEPIN_STUB_INSTRUCTIONS: "B" }, "verify", "--stdio", lockPath, "--", process.execPath, stub).status, 1); }); - it("--clean-env hides the caller's variables; --env-allow passes only the named ones (SP-4)", () => { + it("--clean-env hides the caller's variables; --env-allow passes only the named ones", () => { const dir = mkdtempSync(join(tmpdir(), "surfacepin-env-")); const lockPath = join(dir, "l.json"); const stub = join(testdata, "stub-mcp-server.mjs"); diff --git a/src/verify.ts b/src/verify.ts index 18e3a01..4b90fd6 100644 --- a/src/verify.ts +++ b/src/verify.ts @@ -339,14 +339,14 @@ export function parseLockfile(doc: unknown): Lockfile { o.canonicalization !== "surfacepin-jcs-v2" ) { throw new SurfacePinError( - `unsupported canonicalization: ${String(o.canonicalization)}`, + `unsupported canonicalization: ${JSON.stringify(o.canonicalization)}`, ); } const canon = o.canonicalization as Canonicalization; // jcs-v2 exists only in lockfile v3 (1.6.0+). Older formats are always jcs-v1. if (canon === "surfacepin-jcs-v2" && o.version !== 3) { throw new SurfacePinError( - `canonicalization surfacepin-jcs-v2 requires lockfile version 3 (got ${String(o.version)})`, + `canonicalization surfacepin-jcs-v2 requires lockfile version 3 (got ${JSON.stringify(o.version)})`, ); } const titles = canon === "surfacepin-jcs-v2"; @@ -404,7 +404,7 @@ export function parseLockfile(doc: unknown): Lockfile { return lock; } - throw new SurfacePinError(`unsupported lockfile version: ${String(o.version)}`); + throw new SurfacePinError(`unsupported lockfile version: ${JSON.stringify(o.version)}`); } /** Surface kinds present in a lockfile. */ diff --git a/src/version.ts b/src/version.ts index f189cf0..3fa56f2 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1,2 +1,2 @@ /** Package version. A test keeps this equal to package.json. */ -export const VERSION = "1.6.0"; +export const VERSION = "1.6.1"; diff --git a/testdata/basic.v2.lock.json b/testdata/basic.v2.lock.json new file mode 100644 index 0000000..8e014f9 --- /dev/null +++ b/testdata/basic.v2.lock.json @@ -0,0 +1,45 @@ +{ + "version": 2, + "algorithm": "sha256", + "canonicalization": "surfacepin-jcs-v1", + "root": "21e88a5125e9d687ef27d1fbe4e3259c20a0fd6b0b8a0300d5cc3d5fbb371317", + "tools": { + "root": "eca572b549d73a6db0c8c2a44f865982c67aaf291f4c57d80dfd6031af62c2f2", + "entries": [ + { + "name": "echo", + "digest": "f35d75b2245239a726029a0248d0c740479b8d6f7eb2b48b4cb14e1c5b1cad5f" + }, + { + "name": "ping", + "digest": "c2021025279d6e9c71b78a6c99ecb6c4d82ef96a9ac76756036f2b8b8de51104" + } + ] + }, + "resources": { + "root": "c72a37d7a376fd78edd342d6d60ef07e58b01186940f895d50affa3498a07f52", + "entries": [ + { + "uri": "file:///data/config.json", + "digest": "c5927d263bbb986cdee55a36d3ab1ea849bfb6317d009fb2d7c120b15540de9e" + }, + { + "uri": "file:///docs/readme.md", + "digest": "5f3c889850dfe37c001cd15ae36ae4dc3588e6643bc7e1773ccc038196db422f" + } + ] + }, + "prompts": { + "root": "6e21d1309c7fc2dc94a0f858353989915cd60043b67f691910c95bb55f8b3803", + "entries": [ + { + "name": "greet", + "digest": "33580c8a565986ec263ee8c6c2e5fa4ca0ad0526c91efbcd7f84df6ac4b60b9a" + }, + { + "name": "summarize", + "digest": "bdc675d2c1f1dbe4f95f8c44113e8b2540dd1fc9a45931f0136fe641b7590a4a" + } + ] + } +} diff --git a/testdata/golden/.gitattributes b/testdata/golden/.gitattributes new file mode 100644 index 0000000..26eda5b --- /dev/null +++ b/testdata/golden/.gitattributes @@ -0,0 +1,2 @@ +# Golden fixtures are compared byte for byte. Never convert line endings. +* -text diff --git a/testdata/golden/jcs-v2/full.instructions.0.jcs b/testdata/golden/jcs-v2/full.instructions.0.jcs new file mode 100644 index 0000000..20809c0 --- /dev/null +++ b/testdata/golden/jcs-v2/full.instructions.0.jcs @@ -0,0 +1 @@ +{"name":"instructions","text":"Call ping before export_records.\nNever export without approval."} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.lock.json b/testdata/golden/jcs-v2/full.lock.json new file mode 100644 index 0000000..323a9c0 --- /dev/null +++ b/testdata/golden/jcs-v2/full.lock.json @@ -0,0 +1,216 @@ +{ + "version": 3, + "algorithm": "sha256", + "canonicalization": "surfacepin-jcs-v2", + "root": "07dee637abb8eb13c64d4ef779a0e2037a6fe3cf3217dee1a85dda7dc5fb6945", + "tools": { + "root": "ea2506ae701651e262562e2746940a4f2c3dffb886352456262ef12b7074f882", + "entries": [ + { + "name": "Zeta", + "digest": "99f04f859157d061c2ae6d8ca9b2235599c100e1cec2874a345a3311510accba", + "surface": { + "description": "Uppercase sorts before lowercase.", + "inputSchema": { + "type": "object" + }, + "name": "Zeta", + "outputSchema": {} + } + }, + { + "name": "export_records", + "digest": "c52077718dca25cd0b63c415c3435de826bf5430777bdca12dd3817589fab2b6", + "surface": { + "description": "Export ticket records to an approved destination.", + "inputSchema": { + "type": "object", + "properties": { + "destination": { + "type": "string", + "enum": [ + "s3", + "gcs" + ] + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "default": 100 + } + }, + "required": [ + "destination" + ], + "additionalProperties": false + }, + "name": "export_records", + "annotations": { + "title": "Export", + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": false, + "openWorldHint": true, + "x-vendor-review": "pending" + }, + "outputSchema": { + "type": "object", + "properties": { + "count": { + "type": "integer" + } + } + }, + "title": "Export Records" + } + }, + { + "name": "ping", + "digest": "35abed201f560ee252b2277201026c367e4db8c6a369b74784f040686dcfc3dc", + "surface": { + "description": "", + "inputSchema": {}, + "name": "ping" + } + }, + { + "name": "ünïcode", + "digest": "c444ab0b4b042c5020dcd4db26fda6ce7caa9f24a111985e0a9d183fbba0f0af", + "surface": { + "description": "Escapes: \"q\" \\ / \b \f \n \r \t \u0000 \u0001 \u001f; kept raw:  é € 😀 
 
", + "inputSchema": { + "type": "object", + "properties": { + "€": { + "const": "euro" + }, + "é": { + "const": "e-acute" + }, + "😀": { + "const": "emoji" + }, + "。": { + "const": "halfwidth" + }, + "B": { + "const": "upper" + }, + "a": { + "const": "lower" + }, + "": { + "const": "empty key" + } + }, + "examples": [ + [ + 1e+21, + 1e-7, + 0.1, + 0, + 100, + 1.5e+300, + 123456789012345680000, + 5e-324, + -12.5, + 0.000001, + 100 + ], + [ + true, + false, + null, + [], + {} + ] + ] + }, + "name": "ünïcode", + "title": "Ünïcode — “quotes” ✓" + } + } + ] + }, + "resources": { + "root": "991e67b51ba98918d5d468abba01e418c9d4dba0a19ef622b563e66e50c312a3", + "entries": [ + { + "uri": "db://tickets", + "digest": "0a1105bb37a3d4af0a388f950cdb8d1c3cadbe2d21ad3cf5f7b1f87b6eaf593f", + "surface": { + "description": "", + "mimeType": "", + "name": "tickets", + "uri": "db://tickets" + } + }, + { + "uri": "file:///docs/readme.md", + "digest": "3b77813fd95ad4605b3b3294ed536135cb0b2f4a9d6f121c108d816d93d3ea70", + "surface": { + "description": "Top-level readme.", + "mimeType": "text/markdown", + "name": "readme", + "uri": "file:///docs/readme.md", + "title": "Project README" + } + } + ] + }, + "prompts": { + "root": "862641f72f5baa010a3fc53340261ad49cbd01db0898dc975878eb2a2af62629", + "entries": [ + { + "name": "greet", + "digest": "733b6f2a0730237bf433090f4f19a2c8b2e2b669e006bea358b2a7fea9c4b852", + "surface": { + "arguments": [], + "description": "", + "name": "greet" + } + }, + { + "name": "summarize", + "digest": "7463cee7b6a7c1a947024c08548a29ba64c39274dfeb33b7111b4696c33a2fb8", + "surface": { + "arguments": [ + { + "description": "Ticket number.", + "name": "id", + "required": true, + "title": "Ticket id" + }, + { + "description": "", + "name": "audience", + "required": false + }, + { + "description": "", + "name": "format", + "required": false + } + ], + "description": "Summarize one ticket.", + "name": "summarize", + "title": "Summarize a ticket" + } + } + ] + }, + "instructions": { + "root": "2546bedcd4683da6bded49fc85732f1ae75f781efbaf3af7dfb789a160577ebd", + "entries": [ + { + "name": "instructions", + "digest": "c144dc1c1822ef2a28ef12819fc1ded19f7e7e75e31995006018c482970b2cad", + "surface": { + "name": "instructions", + "text": "Call ping before export_records.\nNever export without approval." + } + } + ] + } +} diff --git a/testdata/golden/jcs-v2/full.prompts.0.jcs b/testdata/golden/jcs-v2/full.prompts.0.jcs new file mode 100644 index 0000000..7569f35 --- /dev/null +++ b/testdata/golden/jcs-v2/full.prompts.0.jcs @@ -0,0 +1 @@ +{"arguments":[],"description":"","name":"greet"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.prompts.1.jcs b/testdata/golden/jcs-v2/full.prompts.1.jcs new file mode 100644 index 0000000..10403de --- /dev/null +++ b/testdata/golden/jcs-v2/full.prompts.1.jcs @@ -0,0 +1 @@ +{"arguments":[{"description":"Ticket number.","name":"id","required":true,"title":"Ticket id"},{"description":"","name":"audience","required":false},{"description":"","name":"format","required":false}],"description":"Summarize one ticket.","name":"summarize","title":"Summarize a ticket"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.resources.0.jcs b/testdata/golden/jcs-v2/full.resources.0.jcs new file mode 100644 index 0000000..342fc58 --- /dev/null +++ b/testdata/golden/jcs-v2/full.resources.0.jcs @@ -0,0 +1 @@ +{"description":"","mimeType":"","name":"tickets","uri":"db://tickets"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.resources.1.jcs b/testdata/golden/jcs-v2/full.resources.1.jcs new file mode 100644 index 0000000..ab1607c --- /dev/null +++ b/testdata/golden/jcs-v2/full.resources.1.jcs @@ -0,0 +1 @@ +{"description":"Top-level readme.","mimeType":"text/markdown","name":"readme","title":"Project README","uri":"file:///docs/readme.md"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.surface.json b/testdata/golden/jcs-v2/full.surface.json new file mode 100644 index 0000000..68cb2cf --- /dev/null +++ b/testdata/golden/jcs-v2/full.surface.json @@ -0,0 +1,90 @@ +{ + "tools": [ + { + "name": "export_records", + "title": "Export Records", + "description": "Export ticket records to an approved destination.", + "inputSchema": { + "type": "object", + "properties": { + "destination": { "type": "string", "enum": ["s3", "gcs"] }, + "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } + }, + "required": ["destination"], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "properties": { "count": { "type": "integer" } } + }, + "annotations": { + "title": "Export", + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": false, + "openWorldHint": true, + "x-vendor-review": "pending" + }, + "icons": [{ "src": "https://example.com/export.png" }], + "_meta": { "example.com/build": 42 } + }, + { + "name": "ping" + }, + { + "name": "Zeta", + "description": "Uppercase sorts before lowercase.", + "inputSchema": { "type": "object" }, + "outputSchema": {}, + "annotations": {} + }, + { + "name": "ünïcode", + "title": "Ünïcode — “quotes” ✓", + "description": "Escapes: \"q\" \\ / \b \f \n \r \t \u0000 \u0001 \u001f; kept raw: \u007f é € 😀 \u2028 \u2029", + "inputSchema": { + "type": "object", + "properties": { + "€": { "const": "euro" }, + "é": { "const": "e-acute" }, + "😀": { "const": "emoji" }, + "\uff61": { "const": "halfwidth" }, + "B": { "const": "upper" }, + "a": { "const": "lower" }, + "": { "const": "empty key" } + }, + "examples": [ + [1e21, 1E-7, 0.1, -0, 100, 1.5e300, 123456789012345678901, 5e-324, -12.50, 0.000001, 1e+2], + [true, false, null, [], {}] + ] + } + } + ], + "resources": [ + { + "uri": "file:///docs/readme.md", + "name": "readme", + "title": "Project README", + "mimeType": "text/markdown", + "description": "Top-level readme.", + "size": 2048, + "annotations": { "audience": ["user"] }, + "_meta": { "etag": "abc" } + }, + { "uri": "db://tickets", "name": "tickets" } + ], + "prompts": [ + { + "name": "summarize", + "title": "Summarize a ticket", + "description": "Summarize one ticket.", + "arguments": [ + { "name": "id", "title": "Ticket id", "description": "Ticket number.", "required": true }, + { "name": "audience", "required": false }, + { "name": "format" } + ] + }, + { "name": "greet" } + ], + "instructions": "Call ping before export_records.\nNever export without approval." +} diff --git a/testdata/golden/jcs-v2/full.tools.0.jcs b/testdata/golden/jcs-v2/full.tools.0.jcs new file mode 100644 index 0000000..77d45d2 --- /dev/null +++ b/testdata/golden/jcs-v2/full.tools.0.jcs @@ -0,0 +1 @@ +{"description":"Uppercase sorts before lowercase.","inputSchema":{"type":"object"},"name":"Zeta","outputSchema":{}} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.tools.1.jcs b/testdata/golden/jcs-v2/full.tools.1.jcs new file mode 100644 index 0000000..d110bcd --- /dev/null +++ b/testdata/golden/jcs-v2/full.tools.1.jcs @@ -0,0 +1 @@ +{"annotations":{"destructiveHint":true,"idempotentHint":false,"openWorldHint":true,"readOnlyHint":false,"title":"Export","x-vendor-review":"pending"},"description":"Export ticket records to an approved destination.","inputSchema":{"additionalProperties":false,"properties":{"destination":{"enum":["s3","gcs"],"type":"string"},"limit":{"default":100,"maximum":1000,"minimum":1,"type":"integer"}},"required":["destination"],"type":"object"},"name":"export_records","outputSchema":{"properties":{"count":{"type":"integer"}},"type":"object"},"title":"Export Records"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.tools.2.jcs b/testdata/golden/jcs-v2/full.tools.2.jcs new file mode 100644 index 0000000..0227d0e --- /dev/null +++ b/testdata/golden/jcs-v2/full.tools.2.jcs @@ -0,0 +1 @@ +{"description":"","inputSchema":{},"name":"ping"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/full.tools.3.jcs b/testdata/golden/jcs-v2/full.tools.3.jcs new file mode 100644 index 0000000..a51524a --- /dev/null +++ b/testdata/golden/jcs-v2/full.tools.3.jcs @@ -0,0 +1 @@ +{"description":"Escapes: \"q\" \\ / \b \f \n \r \t \u0000 \u0001 \u001f; kept raw:  é € 😀 
 
","inputSchema":{"examples":[[1e+21,1e-7,0.1,0,100,1.5e+300,123456789012345680000,5e-324,-12.5,0.000001,100],[true,false,null,[],{}]],"properties":{"":{"const":"empty key"},"B":{"const":"upper"},"a":{"const":"lower"},"é":{"const":"e-acute"},"€":{"const":"euro"},"😀":{"const":"emoji"},"。":{"const":"halfwidth"}},"type":"object"},"name":"ünïcode","title":"Ünïcode — “quotes” ✓"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/golden.json b/testdata/golden/jcs-v2/golden.json new file mode 100644 index 0000000..b3ec00f --- /dev/null +++ b/testdata/golden/jcs-v2/golden.json @@ -0,0 +1,161 @@ +{ + "canonicalization": "surfacepin-jcs-v2", + "cases": [ + { + "name": "full", + "surface": "full.surface.json", + "surfaceSha256": "c1981ad81f1c61f6ea92330e39611356341b55fb355881cdf3a2eca2fc7f61eb", + "kinds": [ + "tools", + "resources", + "prompts", + "instructions" + ], + "lockfile": "full.lock.json", + "lockfileSha256": "5d91442e365b85887bb4970b6ced45e412dd488439270bb86c047078f145fb02", + "root": "07dee637abb8eb13c64d4ef779a0e2037a6fe3cf3217dee1a85dda7dc5fb6945", + "sections": { + "tools": "ea2506ae701651e262562e2746940a4f2c3dffb886352456262ef12b7074f882", + "resources": "991e67b51ba98918d5d468abba01e418c9d4dba0a19ef622b563e66e50c312a3", + "prompts": "862641f72f5baa010a3fc53340261ad49cbd01db0898dc975878eb2a2af62629", + "instructions": "2546bedcd4683da6bded49fc85732f1ae75f781efbaf3af7dfb789a160577ebd" + }, + "entries": [ + { + "kind": "tools", + "id": "Zeta", + "canonical": "full.tools.0.jcs", + "sha256": "99f04f859157d061c2ae6d8ca9b2235599c100e1cec2874a345a3311510accba" + }, + { + "kind": "tools", + "id": "export_records", + "canonical": "full.tools.1.jcs", + "sha256": "c52077718dca25cd0b63c415c3435de826bf5430777bdca12dd3817589fab2b6" + }, + { + "kind": "tools", + "id": "ping", + "canonical": "full.tools.2.jcs", + "sha256": "35abed201f560ee252b2277201026c367e4db8c6a369b74784f040686dcfc3dc" + }, + { + "kind": "tools", + "id": "ünïcode", + "canonical": "full.tools.3.jcs", + "sha256": "c444ab0b4b042c5020dcd4db26fda6ce7caa9f24a111985e0a9d183fbba0f0af" + }, + { + "kind": "resources", + "id": "db://tickets", + "canonical": "full.resources.0.jcs", + "sha256": "0a1105bb37a3d4af0a388f950cdb8d1c3cadbe2d21ad3cf5f7b1f87b6eaf593f" + }, + { + "kind": "resources", + "id": "file:///docs/readme.md", + "canonical": "full.resources.1.jcs", + "sha256": "3b77813fd95ad4605b3b3294ed536135cb0b2f4a9d6f121c108d816d93d3ea70" + }, + { + "kind": "prompts", + "id": "greet", + "canonical": "full.prompts.0.jcs", + "sha256": "733b6f2a0730237bf433090f4f19a2c8b2e2b669e006bea358b2a7fea9c4b852" + }, + { + "kind": "prompts", + "id": "summarize", + "canonical": "full.prompts.1.jcs", + "sha256": "7463cee7b6a7c1a947024c08548a29ba64c39274dfeb33b7111b4696c33a2fb8" + }, + { + "kind": "instructions", + "id": "instructions", + "canonical": "full.instructions.0.jcs", + "sha256": "c144dc1c1822ef2a28ef12819fc1ded19f7e7e75e31995006018c482970b2cad" + } + ] + }, + { + "name": "tools-only", + "surface": "tools-only.surface.json", + "surfaceSha256": "b63c255c876e5b25b3d8493f9ac91e9d3161bffe59253c4972b7d023f950a153", + "kinds": [ + "tools" + ], + "lockfile": "tools-only.lock.json", + "lockfileSha256": "7a2c9c10b697c93e5c7803a5e77d0bba62becaaf58179bc23005989ff2a7eb84", + "root": "092658bdcbfb2d55d67e71d84ded776cc6aca42d88ca8b9f8c36e53cae7e2188", + "sections": { + "tools": "de5ce3eb35765828eff84b8c887b50fa27444f8068bffb7c76731fb0bd025d7a" + }, + "entries": [ + { + "kind": "tools", + "id": "echo", + "canonical": "tools-only.tools.0.jcs", + "sha256": "cb81432a33b1146ec8706e6024adf1a92371af79e188ede9aa2b3f8279dae7b1" + }, + { + "kind": "tools", + "id": "search", + "canonical": "tools-only.tools.1.jcs", + "sha256": "142339df60feaa3a352f8f9af1abc06a7f4bd861178722b4075f1070321743fb" + } + ] + } + ], + "values": [ + { + "input": "{\"b\":2,\"a\":1,\"A\":0}", + "canonicalHex": "7b2241223a302c2261223a312c2262223a327d", + "sha256": "5f05c47104ba1ac24d8cb54dd5f23b15487f4770c9eb767c1c64b64aefba6501" + }, + { + "input": "{\"\\u20ac\":1,\"\\ud83d\\ude00\":2,\"\\uff61\":3}", + "canonicalHex": "7b22e282ac223a312c22f09f9880223a322c22efbda1223a337d", + "sha256": "4a441821b51a0f7eb797ad668dd932bf1ea5ce0cf927aee6092a431dd720ec70" + }, + { + "input": "[1e21,1E-7,0.1,-0,1.5e300,123456789012345678901,5e-324,-12.50]", + "canonicalHex": "5b31652b32312c31652d372c302e312c302c312e35652b3330302c3132333435363738393031323334353638303030302c35652d3332342c2d31322e355d", + "sha256": "cb826ec933e7993fec9f425b4eb82f7b3bbd3591de6454db24132cc9608e4108" + }, + { + "input": "\"\\\"\\\\/\\b\\f\\n\\r\\t\\u0000\\u001f\\u007f\\u2028\\u2029\"", + "canonicalHex": "225c225c5c2f5c625c665c6e5c725c745c75303030305c75303031667fe280a8e280a922", + "sha256": "af8166e914d04478218116333129f25745e8b010bc8a5cc305918b29fc6bcc52" + }, + { + "input": "\"\\ud800\"", + "canonicalHex": "22efbfbd22", + "sha256": "568601070314e0f4489c9944b3c151d5251d379330008293bb7e1a826a22a845" + }, + { + "input": "\"\\ufffd\"", + "canonicalHex": "22efbfbd22", + "sha256": "568601070314e0f4489c9944b3c151d5251d379330008293bb7e1a826a22a845" + }, + { + "input": "{\"nested\":{\"z\":[null,true,false],\"y\":{}},\"empty\":[]}", + "canonicalHex": "7b22656d707479223a5b5d2c226e6573746564223a7b2279223a7b7d2c227a223a5b6e756c6c2c747275652c66616c73655d7d7d", + "sha256": "203e82e6f49ad06c2a3b32bda4b58524111022c41d5a9c5695e85738570e6737" + }, + { + "input": "\"e\\u0301 \\u00e9\"", + "canonicalHex": "2265cc8120c3a922", + "sha256": "6e9e066c3e3e5c93cc346d59e214172ba2eb0feddd51bc9d6eb6c8b7de2cafe7" + }, + { + "input": "{\"\\u00e9\":2,\"e\\u0301\":1}", + "canonicalHex": "7b2265cc81223a312c22c3a9223a327d", + "sha256": "c2635d7e15e25b90abc8b3543d92f0ffcee0644372d8b662a0775f88d43278e5" + }, + { + "input": "{\"a\":1,\"a\":2}", + "canonicalHex": "7b2261223a327d", + "sha256": "7e8059f495589fcd981232cc11d00b00da3802c01d688fa1cf1f6bed6e5bb33c" + } + ] +} diff --git a/testdata/golden/jcs-v2/tools-only.lock.json b/testdata/golden/jcs-v2/tools-only.lock.json new file mode 100644 index 0000000..6cc7512 --- /dev/null +++ b/testdata/golden/jcs-v2/tools-only.lock.json @@ -0,0 +1,51 @@ +{ + "version": 3, + "algorithm": "sha256", + "canonicalization": "surfacepin-jcs-v2", + "root": "092658bdcbfb2d55d67e71d84ded776cc6aca42d88ca8b9f8c36e53cae7e2188", + "tools": { + "root": "de5ce3eb35765828eff84b8c887b50fa27444f8068bffb7c76731fb0bd025d7a", + "entries": [ + { + "name": "echo", + "digest": "cb81432a33b1146ec8706e6024adf1a92371af79e188ede9aa2b3f8279dae7b1", + "surface": { + "description": "Echo text back.", + "inputSchema": { + "type": "object", + "properties": { + "text": { + "type": "string" + } + } + }, + "name": "echo" + } + }, + { + "name": "search", + "digest": "142339df60feaa3a352f8f9af1abc06a7f4bd861178722b4075f1070321743fb", + "surface": { + "description": "Full-text search over tickets.", + "inputSchema": { + "type": "object", + "properties": { + "q": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "q" + ] + }, + "name": "search", + "annotations": { + "readOnlyHint": true + }, + "title": "Search tickets" + } + } + ] + } +} diff --git a/testdata/golden/jcs-v2/tools-only.surface.json b/testdata/golden/jcs-v2/tools-only.surface.json new file mode 100644 index 0000000..5993b28 --- /dev/null +++ b/testdata/golden/jcs-v2/tools-only.surface.json @@ -0,0 +1,16 @@ +{ + "tools": [ + { + "name": "search", + "title": "Search tickets", + "description": "Full-text search over tickets.", + "inputSchema": { + "type": "object", + "properties": { "q": { "type": "string", "minLength": 1 } }, + "required": ["q"] + }, + "annotations": { "readOnlyHint": true } + }, + { "name": "echo", "description": "Echo text back.", "inputSchema": { "type": "object", "properties": { "text": { "type": "string" } } } } + ] +} diff --git a/testdata/golden/jcs-v2/tools-only.tools.0.jcs b/testdata/golden/jcs-v2/tools-only.tools.0.jcs new file mode 100644 index 0000000..c229725 --- /dev/null +++ b/testdata/golden/jcs-v2/tools-only.tools.0.jcs @@ -0,0 +1 @@ +{"description":"Echo text back.","inputSchema":{"properties":{"text":{"type":"string"}},"type":"object"},"name":"echo"} \ No newline at end of file diff --git a/testdata/golden/jcs-v2/tools-only.tools.1.jcs b/testdata/golden/jcs-v2/tools-only.tools.1.jcs new file mode 100644 index 0000000..e4093f7 --- /dev/null +++ b/testdata/golden/jcs-v2/tools-only.tools.1.jcs @@ -0,0 +1 @@ +{"annotations":{"readOnlyHint":true},"description":"Full-text search over tickets.","inputSchema":{"properties":{"q":{"minLength":1,"type":"string"}},"required":["q"],"type":"object"},"name":"search","title":"Search tickets"} \ No newline at end of file