@treeship/verify 0.31.9 → 0.31.11

package/README.md

@@ -12,7 +12,7 @@ The only dependency is `@treeship/core-wasm` (the compiled Rust core, under 170
 
 ## API
 
-Three functions. Each accepts a parsed object, a JSON string, or a URL.
+`verifyReceipt`, `verifyCertificate` and `crossVerify` accept a parsed object, a JSON string, or a URL. `verifyPackage` takes the files of a `.treeship` package.
 
 ### `verifyReceipt(target)`
 
@@ -32,23 +32,27 @@ if (result.outcome === 'pass') {
 }
 ```
 
-### `verifyCertificate(target, now?)`
+### `verifyCertificate(target, now?, trustRoots?)`
 
-Verifies the Ed25519 signature on an Agent Certificate against the public key embedded in the certificate. With `now` supplied (Date or RFC 3339 string), also classifies the validity window.
+Verifies the Ed25519 signature on an Agent Certificate against a trust root the caller pins via `trustRoots` -- as of the v0.10.3 trust-root audit fix, the certificate's own embedded public key is never trusted on its own; that would make every certificate self-signed. `trustRoots` is required for the signature to be accepted; omit it to get a deliberate fail-closed result for diagnostic UIs. With `now` supplied (Date or RFC 3339 string), also classifies the validity window.
 
 ```typescript
 import { verifyCertificate } from '@treeship/verify';
 
-const result = await verifyCertificate('./researcher.agent/certificate.json', new Date());
+const result = await verifyCertificate(
+  './researcher.agent/certificate.json',
+  new Date(),
+  trustRootsJson, // e.g. the contents of ~/.treeship/trust_roots.json
+);
 
 if (result.outcome === 'pass' && result.validity === 'valid') {
   console.log(`certificate valid for ${result.certificate.agent_name}`);
 }
 ```
 
-### `crossVerify(receipt, certificate, now?)`
+### `crossVerify(receipt, certificate, now?, trustRoots?)`
 
-Answers three questions: do the receipt and certificate reference the same ship, was the certificate valid at `now`, was every tool the session called authorized by the certificate. The `ok` field is the roll-up.
+Answers three questions: do the receipt and certificate reference the same ship, was the certificate valid at `now`, was every tool the session called authorized by the certificate. The `ok` field is the roll-up. Like `verifyCertificate`, the certificate's signature is only accepted against a pinned `trustRoots` set -- omit it for a deliberate fail-closed result.
 
 ```typescript
 import { crossVerify } from '@treeship/verify';
@@ -56,6 +60,8 @@ import { crossVerify } from '@treeship/verify';
 const result = await crossVerify(
   'https://treeship.dev/receipt/ssn_abc',
   'https://example.com/researcher.agent.json',
+  new Date(),
+  trustRootsJson,
 );
 
 if (result.ok) {
@@ -66,6 +72,35 @@ if (result.ok) {
 }
 ```
 
+### `verifyPackage(files, { pinnedKeys? })`
+
+Verifies a whole `.treeship` package, not just its receipt:
+- every artifact envelope's Ed25519 signatures, in core-wasm (the same code as the CLI)
+- each envelope against the receipt's `artifact_id` and full `digest`
+- the signed close record (`record.json`) against the exact bytes of `receipt.json`
+
+`files` maps each path inside the package (`receipt.json`, `record.json`, `keys.json`, `artifacts/<id>.json`, ...) to its unmodified bytes.
+
+```typescript
+import { verifyPackage } from '@treeship/verify';
+
+const result = await verifyPackage(files, {
+  // Keys you got from a source you trust, not from the package.
+  pinnedKeys: { key_57e0c8ba2b2bc32c: 'ed25519:HwiNphKvOWVcuI_-kv8hNz6Ahtt8n1LzngHDJpl5WJI' },
+});
+```
+
+The verdict uses the CLI's vocabulary:
+
+| verdict | means |
+|---|---|
+| `verified` | Every signature holds under a key you pinned, every artifact matches the receipt, and the close record binds this receipt.json. |
+| `signatures-pass` | The same, but at least one signer is known only from the package's own `keys.json`, which comes from the same place as the signatures. |
+| `structural-pass` | Structure only. Either no envelopes were given (`scope: 'receipt-only'`, which includes passing `receipt.json` alone), or the package holds kinds whose rules this library doesn't evaluate: approvals, endorsements, room invitations and participants (`scope: 'partial'`). Run `treeship package verify` for those. |
+| `failed` | A checked signature, id, digest or binding does not hold; a listed envelope or the close record is missing; or `keys.json` contradicts a key you pinned. |
+
+`tests/vectors/packages` runs every honest and tampered package through it: the `verify_js` and `verify_js_pinned` columns of `expected.json`. A tampered package is never `signatures-pass` or `verified`.
+
 ## Runtime compatibility
 
 | Runtime | Supported |
@@ -137,7 +172,7 @@ renderChecks(result.checks);
 ## What this package is NOT
 
 - **Not an attestation SDK.** For signing artifacts, session management, Hub push/pull, or agent registration, use [`@treeship/sdk`](../sdk-ts/) which shells out to the `treeship` CLI.
-- **Not a trust anchor.** The embedded Ed25519 signature on an Agent Certificate is verified against the certificate's own public key. Chaining a certificate to a trusted issuer is the caller's responsibility.
+- **Not a trust anchor.** `verifyCertificate` checks the embedded Ed25519 signature against a `trustRoots` set the caller pins and passes in -- not against the certificate's own embedded key, which would make every certificate self-signed. Deciding *which* roots to trust, and chaining further to an issuer, is the caller's responsibility.
 - **Not a drop-in for local-chain verification.** Some signature verification needs the original envelope bytes, which a URL-fetched receipt does not carry. Use `treeship verify <artifact-id>` on the CLI for that.
 
 ## License

package/dist/index.d.ts

@@ -23,6 +23,23 @@ export interface TrustRootsBundle {
 }
 /** Accepted input shapes across all exported functions. */
 export type VerifyTarget = string | URL | Record<string, unknown>;
+/**
+ * The JSON API URL for a receipt URL a person pasted.
+ *
+ * `/receipt/<id>` (the human page) becomes `/v1/receipt/<id>`; `/v1/receipt/<id>`
+ * and the site's `/api/receipt/<id>` mirror are already the API and are kept.
+ * The host is never rewritten, a trailing slash is dropped, the query string
+ * is kept and the fragment dropped. Anything else throws rather than being
+ * fetched. Through 0.31.9 this was a blind `replace('/receipt/', …)`, which
+ * turned the documented `https://api.treeship.dev/v1/receipt/<id>` into
+ * `/v1/v1/receipt/<id>` and a 404. The rule is shared with the CLI
+ * (`receipt_api_url` in verify_external.rs) through
+ * `tests/vectors/receipt-urls.json`; change both or neither.
+ *
+ * @internal Exported for the shared-vector test; not part of the package's
+ * supported API.
+ */
+export declare function receiptApiUrl(raw: string): string;
 export interface VerifyCheck {
     step: string;
     status: 'pass' | 'fail' | 'warn';
@@ -229,3 +246,65 @@ export declare function verifyPresentation(presentation: Record<string, unknown>
     nonce?: string;
     now?: Date | string;
 }): Promise<PresentationVerdict>;
+/**
+ * The files of a `.treeship` package directory, keyed by their path inside
+ * it (`receipt.json`, `record.json`, `keys.json`, `artifacts/<id>.json`, ...).
+ * Values are the exact bytes; `receipt.json` is hashed as given, so pass file
+ * contents unmodified. A map containing only `receipt.json` is valid input and
+ * verifies structure only.
+ */
+export type PackageFiles = Record<string, string | Uint8Array>;
+export interface VerifyPackageOptions {
+    /**
+     * Keys you trust, by key id: `{ key_...: 'ed25519:<base64url>' }` (the bare
+     * base64url also works). A signature counts toward `verified` only under a
+     * key pinned here. Keys the package carries in keys.json are checked too,
+     * but they come from the same place as the signatures, so they can at most
+     * give `signatures-pass`.
+     */
+    pinnedKeys?: Record<string, string>;
+}
+export interface PackageArtifactResult {
+    artifact_id: string;
+    payload_type?: string;
+    /** `pass`: every signature verifies and the envelope matches the receipt's
+     *  id and full digest. `skipped`: a kind signed over its own canonical
+     *  bytes (a countersigned room participant) that only the CLI checks. */
+    status: 'pass' | 'fail' | 'missing' | 'skipped';
+    signers: {
+        keyid: string;
+        key: 'pinned' | 'package' | 'unknown';
+    }[];
+    detail?: string;
+}
+export interface VerifyPackageResult {
+    /**
+     * Same vocabulary as `treeship package verify`:
+     * - `verified`: every envelope and the close record verify under keys you
+     *   pinned, every artifact matches the receipt, and the receipt is the one
+     *   the close record signed.
+     * - `signatures-pass`: the same, but at least one signer is known only
+     *   from the package's own keys.json.
+     * - `structural-pass`: structure only. Either no envelopes were given
+     *   (`scope: 'receipt-only'`), or the package holds artifact kinds whose
+     *   rules this library doesn't evaluate (`scope: 'partial'`; run
+     *   `treeship package verify` for those).
+     * - `failed`: something checkable did not hold.
+     */
+    verdict: 'verified' | 'signatures-pass' | 'structural-pass' | 'failed';
+    scope: 'receipt-only' | 'partial' | 'signatures';
+    checks: VerifyCheck[];
+    artifacts: PackageArtifactResult[];
+    /** Payload kinds present whose semantics are not checked here. */
+    unevaluated_kinds: string[];
+}
+/**
+ * Verify a `.treeship` package: every artifact envelope's Ed25519
+ * signatures, each envelope's id and full digest against the receipt, and the
+ * signed close record (record.json) against the exact bytes of receipt.json.
+ * Signature math runs in core-wasm, the same code as the CLI.
+ *
+ * Given only receipt.json, the result is `structural-pass` with
+ * `scope: 'receipt-only'`: no signature was checked.
+ */
+export declare function verifyPackage(files: PackageFiles, opts?: VerifyPackageOptions): Promise<VerifyPackageResult>;

package/dist/index.js

@@ -27,14 +27,72 @@ async function loadWasm() {
     wasmBindings = mod;
     return mod;
 }
+/**
+ * The JSON API URL for a receipt URL a person pasted.
+ *
+ * `/receipt/<id>` (the human page) becomes `/v1/receipt/<id>`; `/v1/receipt/<id>`
+ * and the site's `/api/receipt/<id>` mirror are already the API and are kept.
+ * The host is never rewritten, a trailing slash is dropped, the query string
+ * is kept and the fragment dropped. Anything else throws rather than being
+ * fetched. Through 0.31.9 this was a blind `replace('/receipt/', …)`, which
+ * turned the documented `https://api.treeship.dev/v1/receipt/<id>` into
+ * `/v1/v1/receipt/<id>` and a 404. The rule is shared with the CLI
+ * (`receipt_api_url` in verify_external.rs) through
+ * `tests/vectors/receipt-urls.json`; change both or neither.
+ *
+ * @internal Exported for the shared-vector test; not part of the package's
+ * supported API.
+ */
+export function receiptApiUrl(raw) {
+    const refuse = () => new Error(`not a receipt URL: ${raw} (expected …/receipt/<session id> or …/v1/receipt/<session id>)`);
+    const schemeEnd = raw.indexOf('://');
+    if (schemeEnd < 0)
+        throw refuse();
+    const scheme = raw.slice(0, schemeEnd).toLowerCase();
+    if (scheme !== 'http' && scheme !== 'https')
+        throw refuse();
+    const afterScheme = raw.slice(schemeEnd + 3);
+    const slash = afterScheme.indexOf('/');
+    const host = slash < 0 ? afterScheme : afterScheme.slice(0, slash);
+    const pathAndQuery = slash < 0 ? '' : afterScheme.slice(slash);
+    // Userinfo (`treeship.dev@evil.example`) reads as one host and fetches
+    // another; a pasted receipt link never carries it.
+    if (host.length === 0 || host.includes('@'))
+        throw refuse();
+    const noFragment = pathAndQuery.split('#')[0];
+    const q = noFragment.indexOf('?');
+    const query = q < 0 ? null : noFragment.slice(q + 1);
+    const path = (q < 0 ? noFragment : noFragment.slice(0, q)).replace(/\/+$/, '');
+    // The id is whatever follows the receipt segment: exactly one path
+    // segment of id characters, so `..`, `%2F` and friends never reach the
+    // request.
+    const idAfter = (marker) => {
+        const i = path.indexOf(marker);
+        if (i < 0)
+            return null;
+        const id = path.slice(i + marker.length);
+        return /^[A-Za-z0-9_-]+$/.test(id) ? [i, id] : null;
+    };
+    let apiPath;
+    if (idAfter('/v1/receipt/'))
+        apiPath = path;
+    else if (idAfter('/api/receipt/'))
+        apiPath = path;
+    else {
+        const hit = idAfter('/receipt/');
+        if (!hit)
+            throw refuse();
+        apiPath = `${path.slice(0, hit[0])}/v1/receipt/${hit[1]}`;
+    }
+    return `${scheme}://${host}${apiPath}${query === null ? '' : `?${query}`}`;
+}
 async function normalizeToJson(target) {
     if (typeof target === 'object' && !(target instanceof URL)) {
         return JSON.stringify(target);
     }
     const raw = target instanceof URL ? target.toString() : target;
     if (raw.startsWith('http://') || raw.startsWith('https://')) {
-        // Accept both the Hub JSON API path and the human-readable mirror.
-        const apiUrl = raw.replace('/receipt/', '/v1/receipt/');
+        const apiUrl = receiptApiUrl(raw);
         const res = await fetch(apiUrl, { headers: { accept: 'application/json' } });
         if (!res.ok)
             throw new Error(`fetch ${apiUrl} returned HTTP ${res.status}`);
@@ -162,3 +220,442 @@ export async function verifyPresentation(presentation, trustRoots, opts) {
     const wasm = await loadWasm();
     return JSON.parse(wasm.verify_presentation(JSON.stringify(presentation), serializeTrustRoots(trustRoots), opts?.nonce ?? '', nowStr));
 }
+// Kinds whose rules (single-use approvals, endorsement linkage, room
+// invitations and countersigns) live in the Rust package verifier and are not
+// re-implemented here. A package carrying any of them is capped at
+// structural-pass: its signatures can all hold while the set breaks a rule
+// (a single-use invitation redeemed twice, for example).
+const UNEVALUATED_KINDS = new Set([
+    'approval.v1',
+    'endorsement.v1',
+    'invitation.v1',
+    'session-participant.v1',
+    'session-liveness.v1',
+]);
+// Kinds this library evaluates fully: signature, id and digest binding.
+const EVALUATED_KINDS = new Set(['action.v1', 'receipt.v1']);
+// Kinds not signed as plain DSSE: a room participant carries the joiner's
+// signature and the host's countersign over the participant's canonical
+// bytes, and its id comes from the pending envelope. Only the CLI checks
+// them; here they are skipped, which also caps the verdict.
+const SIGNED_ELSEWHERE = new Set(['session-participant.v1']);
+function kindOf(payloadType) {
+    return payloadType.replace(/^application\/vnd\.treeship\./, '').replace(/\+json$/, '');
+}
+function bytesOf(v) {
+    return typeof v === 'string' ? new TextEncoder().encode(v) : v;
+}
+function textOf(v) {
+    return typeof v === 'string' ? v : new TextDecoder().decode(v);
+}
+async function sha256Hex(bytes) {
+    const d = await crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(d), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+function stripKeyPrefix(k) {
+    return k.startsWith('ed25519:') ? k.slice('ed25519:'.length) : k;
+}
+function parseEnvelope(raw) {
+    try {
+        const e = JSON.parse(raw);
+        if (typeof e?.payload === 'string' &&
+            typeof e?.payloadType === 'string' &&
+            Array.isArray(e?.signatures) &&
+            e.signatures.length > 0 &&
+            e.signatures.every((s) => typeof s?.keyid === 'string' &&
+                typeof s?.sig === 'string')) {
+            return e;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return null;
+}
+/**
+ * Verify a `.treeship` package: every artifact envelope's Ed25519
+ * signatures, each envelope's id and full digest against the receipt, and the
+ * signed close record (record.json) against the exact bytes of receipt.json.
+ * Signature math runs in core-wasm, the same code as the CLI.
+ *
+ * Given only receipt.json, the result is `structural-pass` with
+ * `scope: 'receipt-only'`: no signature was checked.
+ */
+export async function verifyPackage(files, opts = {}) {
+    const wasm = await loadWasm();
+    const checks = [];
+    const artifacts = [];
+    const unevaluated = new Set();
+    const done = (verdict, scope) => ({
+        verdict,
+        scope,
+        checks,
+        artifacts,
+        unevaluated_kinds: [...unevaluated].sort(),
+    });
+    const failed = () => checks.some((c) => c.status === 'fail');
+    // 1. receipt.json and its structure (Merkle root, inclusion proofs).
+    const receiptRaw = files['receipt.json'];
+    if (receiptRaw === undefined) {
+        checks.push({ step: 'receipt.json', status: 'fail', detail: 'missing' });
+        return done('failed', 'receipt-only');
+    }
+    let receipt;
+    try {
+        receipt = JSON.parse(textOf(receiptRaw));
+    }
+    catch {
+        checks.push({ step: 'receipt.json', status: 'fail', detail: 'not JSON' });
+        return done('failed', 'receipt-only');
+    }
+    const structural = JSON.parse(wasm.verify_receipt(textOf(receiptRaw)));
+    if (structural.outcome === 'fail' || structural.outcome === 'error') {
+        checks.push({
+            step: 'structure',
+            status: 'fail',
+            detail: structural.message ?? 'receipt structure does not verify',
+        });
+    }
+    else {
+        checks.push({ step: 'structure', status: 'pass', detail: 'Merkle root and inclusion proofs hold' });
+    }
+    // 2. Which envelopes were given. None at all is a receipt-only read (or a
+    //    package from before 0.31.2): structure is all there is to check.
+    const envelopePaths = Object.keys(files).filter((p) => /^artifacts\/[^/]+\.json$/.test(p));
+    if (envelopePaths.length === 0 && files['record.json'] === undefined) {
+        checks.push({
+            step: 'signatures',
+            status: 'warn',
+            detail: 'no artifact envelopes given: structure only, no signature was checked',
+        });
+        return done(failed() ? 'failed' : 'structural-pass', 'receipt-only');
+    }
+    // 3. Keys: pinned by the caller, or carried by the package.
+    const pinned = new Map();
+    for (const [kid, key] of Object.entries(opts.pinnedKeys ?? {}))
+        pinned.set(kid, stripKeyPrefix(key));
+    const packageKeys = new Map();
+    if (files['keys.json'] !== undefined) {
+        try {
+            const k = JSON.parse(textOf(files['keys.json']));
+            for (const [kid, key] of Object.entries(k.keys ?? {}))
+                packageKeys.set(kid, stripKeyPrefix(key));
+        }
+        catch {
+            checks.push({ step: 'keys.json', status: 'fail', detail: 'not JSON' });
+        }
+    }
+    for (const [kid, key] of packageKeys) {
+        if (pinned.has(kid) && pinned.get(kid) !== key) {
+            checks.push({
+                step: 'keys.json',
+                status: 'fail',
+                detail: `keys.json names a different key for ${kid} than the one you pinned`,
+            });
+        }
+    }
+    let allPinned = true;
+    let anyPinned = false;
+    // A signer is its key id AND the key that id resolved to, so a reused
+    // key id under a different key is a different signer.
+    const signerOf = (env) => {
+        if (env.signatures.length !== 1)
+            return null;
+        const kid = env.signatures[0].keyid;
+        const key = pinned.get(kid) ?? packageKeys.get(kid);
+        return key ? `${kid}:${key}` : null;
+    };
+    const decode = (env) => {
+        try {
+            const v = JSON.parse(textOf(base64urlDecode(env.payload)));
+            return v && typeof v === 'object' ? v : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // Verified artifacts of the kinds evaluated here, for the session rules,
+    // and the signed statements of every verified envelope, for chain walks.
+    const verifiedStmts = new Map();
+    const chainStmts = new Map();
+    // Verify one envelope: every signature must hold under a known key.
+    const checkEnvelope = (env) => {
+        const trusted = {};
+        const signers = [];
+        for (const s of env.signatures) {
+            const key = pinned.get(s.keyid) ?? packageKeys.get(s.keyid);
+            signers.push({
+                keyid: s.keyid,
+                key: pinned.has(s.keyid) ? 'pinned' : packageKeys.has(s.keyid) ? 'package' : 'unknown',
+            });
+            if (key)
+                trusted[s.keyid] = key;
+        }
+        const r = JSON.parse(wasm.verify_envelope(JSON.stringify(env), JSON.stringify(trusted)));
+        const everySigner = new Set(r.verified_keys ?? []);
+        const distinct = new Set(env.signatures.map((s) => s.keyid)).size === env.signatures.length;
+        const ok = r.valid === true &&
+            distinct &&
+            (r.verified_keys ?? []).length === env.signatures.length &&
+            signers.every((s) => s.key !== 'unknown' && everySigner.has(s.keyid));
+        if (ok && signers.some((s) => s.key !== 'pinned'))
+            allPinned = false;
+        if (ok && signers.some((s) => s.key === 'pinned'))
+            anyPinned = true;
+        return { ok, signers, r };
+    };
+    // 4. Every artifact the receipt lists: present, signed, and the envelope
+    //    that hashes to exactly the listed id and digest.
+    const listed = receipt.artifacts ?? [];
+    const seen = new Set();
+    for (const a of listed) {
+        const id = a.artifact_id ?? '';
+        if (!/^art_[0-9a-f]{32}$/.test(id)) {
+            checks.push({ step: 'artifacts', status: 'fail', detail: `malformed artifact id ${JSON.stringify(id)}` });
+            continue;
+        }
+        if (seen.has(id)) {
+            checks.push({ step: 'artifacts', status: 'fail', detail: `${id} is listed more than once` });
+            continue;
+        }
+        seen.add(id);
+        const raw = files[`artifacts/${id}.json`];
+        if (raw === undefined) {
+            artifacts.push({ artifact_id: id, status: 'missing', signers: [], detail: 'envelope not in the package' });
+            checks.push({ step: 'artifacts', status: 'fail', detail: `${id}: envelope missing from the package` });
+            continue;
+        }
+        const env = parseEnvelope(textOf(raw));
+        if (!env) {
+            artifacts.push({ artifact_id: id, status: 'fail', signers: [], detail: 'not a DSSE envelope' });
+            checks.push({ step: 'artifacts', status: 'fail', detail: `${id}: not a DSSE envelope` });
+            continue;
+        }
+        const kind = kindOf(env.payloadType);
+        if (!EVALUATED_KINDS.has(kind))
+            unevaluated.add(kind);
+        if (SIGNED_ELSEWHERE.has(kind)) {
+            artifacts.push({
+                artifact_id: id,
+                payload_type: env.payloadType,
+                status: 'skipped',
+                signers: env.signatures.map((s) => ({
+                    keyid: s.keyid,
+                    key: pinned.has(s.keyid) ? 'pinned' : packageKeys.has(s.keyid) ? 'package' : 'unknown',
+                })),
+                detail: 'countersigned over canonical bytes; checked by `treeship package verify`',
+            });
+            continue;
+        }
+        const { ok, signers, r } = checkEnvelope(env);
+        let detail;
+        if (!ok)
+            detail = r.error ?? 'a signature does not verify under a known key';
+        else if (r.artifact_id !== id)
+            detail = `envelope hashes to ${r.artifact_id}, not ${id}`;
+        else if (r.digest !== a.digest)
+            detail = `envelope digest ${r.digest} does not match the receipt's ${a.digest}`;
+        artifacts.push({
+            artifact_id: id,
+            payload_type: env.payloadType,
+            status: detail ? 'fail' : 'pass',
+            signers,
+            detail,
+        });
+        if (detail)
+            checks.push({ step: 'artifacts', status: 'fail', detail: `${id}: ${detail}` });
+        else {
+            const stmt = decode(env);
+            if (!stmt)
+                checks.push({ step: 'artifacts', status: 'fail', detail: `${id}: payload is not a JSON statement` });
+            else {
+                chainStmts.set(id, stmt);
+                if (EVALUATED_KINDS.has(kind))
+                    verifiedStmts.set(id, { env, stmt, kind });
+            }
+        }
+    }
+    if (!failed() && listed.length > 0) {
+        const passed = artifacts.filter((a) => a.status === 'pass').length;
+        const skipped = artifacts.length - passed;
+        checks.push({
+            step: 'artifacts',
+            status: 'pass',
+            detail: `${passed} envelope(s) verify and match the receipt's ids and digests` +
+                (skipped ? `; ${skipped} skipped (checked by the CLI only)` : ''),
+        });
+    }
+    // 5. The session: exactly one chain-root session.start and exactly one
+    //    session.close for this session, the close chained back to the start
+    //    by signed parent ids, and both signed by the same signer. Every
+    //    evaluated artifact's signed parent must be in the package.
+    const sid = receipt.session?.id;
+    const metaSid = (st) => (st.meta && typeof st.meta === 'object' ? st.meta.session_id : undefined);
+    const parentOf = (st) => {
+        // Mirrors treeship_core::verify::signed_parent for the kinds evaluated
+        // here: a present parentId decides (non-string = broken); a receipt.v1
+        // names its subject; otherwise no parent (a chain root).
+        if ('parentId' in st || 'parent_id' in st) {
+            const v = st.parentId ?? st.parent_id;
+            return typeof v === 'string' ? v : undefined;
+        }
+        const subj = st.subject?.artifactId;
+        if (typeof subj === 'string' && subj.startsWith('art_'))
+            return subj;
+        return null;
+    };
+    let closeId = null;
+    let closeSigner = null;
+    let closeStmt = null;
+    if (verifiedStmts.size > 0) {
+        const starts = [...verifiedStmts].filter(([, v]) => v.stmt.action === 'session.start' && metaSid(v.stmt) === sid);
+        const closes = [...verifiedStmts].filter(([, v]) => v.stmt.action === 'session.close' && metaSid(v.stmt) === sid);
+        if (starts.length !== 1 || parentOf(starts[0][1].stmt) !== null) {
+            checks.push({ step: 'session', status: 'fail', detail: `expected one chain-root session.start for ${sid}, found ${starts.length}` });
+        }
+        else if (closes.length !== 1) {
+            checks.push({ step: 'session', status: 'fail', detail: `expected one session.close for ${sid}, found ${closes.length}` });
+        }
+        else {
+            const [startId, start] = starts[0];
+            const [cId, close] = closes[0];
+            const startSigner = signerOf(start.env);
+            const cSigner = signerOf(close.env);
+            // Walk the close back to the start through signed parents.
+            let cur = cId;
+            const visited = new Set();
+            while (cur && cur !== startId && !visited.has(cur)) {
+                visited.add(cur);
+                const st = chainStmts.get(cur);
+                cur = st ? parentOf(st) : undefined;
+            }
+            if (cur !== startId) {
+                checks.push({ step: 'session', status: 'fail', detail: `session.close ${cId} does not chain back to session.start ${startId}` });
+            }
+            else if (!startSigner || startSigner !== cSigner) {
+                checks.push({ step: 'session', status: 'fail', detail: 'session.close is not signed by the signer of session.start' });
+            }
+            else {
+                closeId = cId;
+                closeSigner = cSigner;
+                closeStmt = close.stmt;
+            }
+        }
+        for (const [id, v] of verifiedStmts) {
+            const par = parentOf(v.stmt);
+            if (par === undefined || (par !== null && !seen.has(par))) {
+                checks.push({ step: 'linkage', status: 'fail', detail: `${id}: signed parent ${String(par)} is not in the package` });
+            }
+            else if (par === null && !(v.stmt.action === 'session.start' && metaSid(v.stmt) === sid)) {
+                checks.push({ step: 'linkage', status: 'fail', detail: `${id}: signs no parent but is not this session's session.start` });
+            }
+        }
+    }
+    else if (envelopePaths.length > 0 || files['record.json'] !== undefined) {
+        checks.push({ step: 'session', status: 'fail', detail: 'no verified session artifacts to bind the close record to' });
+    }
+    // 6. The close record: signed, names this session, and binds the exact
+    //    bytes of receipt.json. Without it, nothing binds the receipt body
+    //    (timeline, narrative, side effects) to a signature.
+    const recordRaw = files['record.json'];
+    if (recordRaw === undefined) {
+        checks.push({
+            step: 'receipt_binding',
+            status: 'fail',
+            detail: 'record.json (the signed close record) is missing, so nothing binds receipt.json',
+        });
+    }
+    else {
+        const env = parseEnvelope(textOf(recordRaw));
+        if (!env) {
+            checks.push({ step: 'receipt_binding', status: 'fail', detail: 'record.json is not a DSSE envelope' });
+        }
+        else {
+            // The record may be signed by the close's signer, or by the record key
+            // the close names in its own signed statement, at meta.record_key, in
+            // the CLI's encoding (ed25519:<base64url>). A record under that key is
+            // checked against the key the close vouches for, never keys.json, and
+            // is as trusted as the close's signer, so it adds no signer of its own.
+            const rk = closeStmt?.meta?.record_key;
+            const rkKey = rk && typeof rk.key_id === 'string' && typeof rk.public_key === 'string' &&
+                /^ed25519:[A-Za-z0-9_-]{43}$/.test(rk.public_key)
+                ? { kid: rk.key_id, key: rk.public_key.slice('ed25519:'.length) }
+                : null;
+            const byRecordKey = rkKey !== null && env.signatures.length === 1 && env.signatures[0].keyid === rkKey.kid;
+            let ok;
+            if (byRecordKey) {
+                const conflict = (pinned.has(rkKey.kid) && pinned.get(rkKey.kid) !== rkKey.key) ||
+                    (packageKeys.has(rkKey.kid) && packageKeys.get(rkKey.kid) !== rkKey.key);
+                const r = JSON.parse(wasm.verify_envelope(JSON.stringify(env), JSON.stringify({ [rkKey.kid]: rkKey.key })));
+                ok = !conflict && r.valid === true && (r.verified_keys ?? []).length === 1;
+            }
+            else {
+                ok = checkEnvelope(env).ok;
+            }
+            const stmt = (decode(env) ?? {});
+            const actual = `sha256:${await sha256Hex(bytesOf(receiptRaw))}`;
+            const recSigner = byRecordKey ? 'record_key' : signerOf(env);
+            if (!ok) {
+                checks.push({ step: 'receipt_binding', status: 'fail', detail: 'the close record signature does not verify under a known key' });
+            }
+            else if (env.payloadType !== 'application/vnd.treeship.receipt.v1+json' ||
+                stmt.type !== 'treeship/receipt/v1' ||
+                stmt.kind !== 'session.v1' ||
+                typeof stmt.payload?.receipt_digest !== 'string' ||
+                typeof stmt.payload?.session_id !== 'string') {
+                checks.push({ step: 'receipt_binding', status: 'fail', detail: 'record.json is not a session.v1 close record' });
+            }
+            else if (!closeId || stmt.subject?.artifactId !== closeId) {
+                checks.push({ step: 'receipt_binding', status: 'fail', detail: "the close record does not seal this session's close" });
+            }
+            else if (!recSigner || (recSigner !== closeSigner && !byRecordKey)) {
+                checks.push({ step: 'receipt_binding', status: 'fail', detail: "the close record is not signed by the session's signer" });
+            }
+            else if (stmt.payload?.session_id !== receipt.session?.id) {
+                checks.push({
+                    step: 'receipt_binding',
+                    status: 'fail',
+                    detail: `the close record names session ${stmt.payload?.session_id} but this receipt is ${receipt.session?.id}`,
+                });
+            }
+            else if (stmt.payload?.receipt_digest !== actual) {
+                checks.push({
+                    step: 'receipt_binding',
+                    status: 'fail',
+                    detail: `the close record signed receipt digest ${stmt.payload?.receipt_digest} but receipt.json digests to ${actual}`,
+                });
+            }
+            else {
+                checks.push({ step: 'receipt_binding', status: 'pass', detail: `the close record binds receipt.json (${actual})` });
+            }
+        }
+    }
+    // Some signers pinned and others only package-known: a pin covers part
+    // of the package, so the package as a whole is not what was pinned.
+    if (anyPinned && !allPinned) {
+        checks.push({ step: 'keys', status: 'fail', detail: 'some signers are pinned and others are known only from keys.json' });
+    }
+    if (failed())
+        return done('failed', 'signatures');
+    // Approval evidence travels beside the sealed set: use records and grants
+    // carried in approvals/ (an approval minted before the session is there,
+    // not sealed). Their rules live in the Rust verifier, so their presence
+    // caps the verdict like a sealed approval does.
+    if (Object.keys(files).some((k) => k.startsWith('approvals/'))) {
+        unevaluated.add('approvals/ (use records and carried grants)');
+    }
+    if (unevaluated.size > 0) {
+        checks.push({
+            step: 'semantics',
+            status: 'warn',
+            detail: `not evaluated here: ${[...unevaluated].sort().join(', ')}. Run \`treeship package verify\` for their rules.`,
+        });
+        return done('structural-pass', 'partial');
+    }
+    return done(allPinned ? 'verified' : 'signatures-pass', 'signatures');
+}
+function base64urlDecode(s) {
+    const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
+    const bin = atob(b64 + '='.repeat((4 - (b64.length % 4)) % 4));
+    return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeship/verify",
-  "version": "0.31.9",
+  "version": "0.31.11",
   "description": "Zero-dependency cryptographic verification for Treeship receipts and certificates. Runs anywhere WASM runs: Node, browser, Vercel Edge, Cloudflare Workers, AWS Lambda.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,7 +40,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@treeship/core-wasm": "0.31.9"
+    "@treeship/core-wasm": "0.31.11"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",