tersign 0.4.10 → 0.5.0

package/dist/verify-bin.js

@@ -1,43 +1,131 @@
 #!/usr/bin/env node
-/** tersign-verify — third-party receipt verification. No API key, no trust in Tersign:
- * signature recovery is local, and the ledger check only asks the public endpoint whether
- * the counter-signed hash-chain holds.
+/** tersign-verify — third-party receipt verification. No API key. A receipt FILE is checked
+ * locally (signature recovery, canonical digest) with no trust in Tersign. A DIGEST lookup, and
+ * the optional --ledger step after a file, only ASK a ledger whether it holds the record and
+ * whether its counter-signed hash-chain holds: that answer is the ledger's own, nothing in it is
+ * re-verified here, and the output says so (`VALID (ledger-reported)`).
  *
- *   tersign-verify <receipt.json> [--signer 0xseller] [--ledger https://…]
+ *   tersign-verify <receipt.json> [--signer 0xissuer] [--ledger https://…]
  *   tersign-verify <0xdigest> [--ledger https://…]
  *
+ * --signer binds the receipt to its issuer: pass the issuer's address, obtained out-of-band
+ * (from the issuer through a channel you trust, never from the receipt itself). Without it the
+ * signer is reported UNAUTHENTICATED, because a signature recovers to SOME address for any
+ * payload: an unbound VALID proves neither who signed nor that the receipt is unmodified.
+ * Receipts signed with a published test key are flagged either way. Until 2026-09-27 this
+ * printed `signature: OK (signer X)` and a bare `VALID` for exactly those receipts, and ignored
+ * a mistyped flag, which is the worst shape a verifier can have: not a wrong answer, an
+ * unearned confidence.
+ *
+ * A file is one of three shapes (verify-report.ts resolveReceiptFile): the receipt itself,
+ * {receipt, record}, or an evidence-bundle record file, whose verdict is qualified `record
+ * artifact only` because its chain fields are not checked here. Anything else that nests a
+ * receipt is refused, as are duplicate keys, non-integer number tokens, and a signed field in
+ * another JSON type.
+ *
+ * Exit status: 0 VALID (read the last line: an unbound, test-key or ledger-reported VALID is
+ * qualified there), 1 INVALID, 2 usage (an unknown, valueless or repeated flag, --signer with a
+ * digest, a malformed address, a file that is missing, a directory, or not UTF-8 JSON) — the
+ * same scheme as `python3 -m tersign verify`, NOT the same status on every input. Measured
+ * 2026-09-27 (this build vs sdk-py 0.1.7; 33 adversarial probe files, each run unbound and
+ * with two --signer values, plus three extra cases): the two agree except on these inputs,
+ * npm/Python exit —
+ *   {receipt, record} and {receipt} wrapper files        0/1  (Python has no `receipt` wrapper)
+ *   a top-level receipt that also carries a `receipt` key 1/0  (refused here; Python lists it unsigned)
+ *   a UTF-8 byte-order mark before the JSON               0/2
+ *   a non-integer number token in a record file's own fields 1/0
+ *   a NaN token                                           2/1
+ *   a receipt FILE with --ledger (deliberate: this checks its digest's chain after the local
+ *     checks; Python keeps files offline)                 0/2
+ *   absurdly nested JSON                                  1/2
+ * The signature-encoding class was re-measured after both twins adopted one canonical encoding
+ * (final release pass, same day): 11 probe files (genuine; no 0x; the v 0/1 twin; upper-case hex,
+ * all or one digit; a space or a trailing newline in the hex; the high-s twin with v 27/28 and
+ * with v 0/1; an object; an array), each unbound and bound — 0/0 on the genuine file, 1/1 on the
+ * rest, with the same reason text. The no-0x difference measured earlier is gone.
+ * Any other difference is unmeasured, not absent.
+ *
  * A bare digest needs a ledger to check against, and with none named it uses the public
  * Tersign ledger — the one the published digests live on — rather than refusing. The
  * ledger actually used is always printed, so a reader can see which chain answered and
  * that the choice was theirs to change. `--ledger` still wins whenever it is given; a
- * receipt FILE with no `--ledger` verifies its signature locally and checks no chain,
- * which is unchanged.
+ * receipt FILE with no `--ledger` verifies its signature locally and checks no chain.
  */
 import { readFileSync } from 'node:fs';
 import { digestOf } from './canonical.js';
 import { verifyReceipt } from './receipt/eip712.js';
 import { verifyComplianceRecord } from './compliance/record.js';
-function arg(flag) {
-    const i = process.argv.indexOf(flag);
-    return i > 0 ? process.argv[i + 1] : undefined;
+import { ADDRESS_RE, findLoneSurrogate, safeText, signerStatus } from './receipt/binding.js';
+import { DIGEST_RE, UsageError, findDuplicateKey, findNonIntegerNumberToken, oneLine, parseVerifyArgs, resolveReceiptFile, signerExplanation, testKeyNote, unsignedNote, verdictHead, wantsHelp, } from './verify-report.js';
+/** Where a bare digest is checked when the caller names no ledger. */
+export const DEFAULT_LEDGER = 'https://tersign.ai';
+const USAGE = 'usage: tersign-verify <receipt.json | 0xdigest> [--signer 0xaddr] [--ledger url]\n' +
+    `       a bare digest checks against ${DEFAULT_LEDGER} unless --ledger names another\n` +
+    "       --signer binds a receipt file to its issuer's address (obtained out-of-band);\n" +
+    '       without it the signer is reported UNAUTHENTICATED\n' +
+    '       exit: 0 VALID (read the last line) · 1 INVALID · 2 usage';
+function usage(msg) {
+    console.error(`usage: ${msg}\n\n${USAGE}`);
+    process.exit(2);
 }
 function fail(msg) {
-    console.error(`INVALID: ${msg}`);
+    console.error(`INVALID: ${oneLine(msg)}`);
     process.exit(1);
 }
-/** Where a bare digest is checked when the caller names no ledger. */
-export const DEFAULT_LEDGER = 'https://tersign.ai';
-const target = process.argv[2];
-if (!target || target.startsWith('--')) {
-    console.error('usage: tersign-verify <receipt.json | 0xdigest> [--signer 0xaddr] [--ledger url]');
-    console.error(`       a bare digest checks against ${DEFAULT_LEDGER} unless --ledger names another`);
+const args = process.argv.slice(2);
+if (args.length === 0) {
+    console.error(USAGE);
     process.exit(2);
 }
-const ledger = arg('--ledger');
-const expectedSigner = arg('--signer');
+if (wantsHelp(args)) {
+    console.log(USAGE);
+    process.exit(0);
+}
+let target;
+let ledger;
+let expectedSigner;
+try {
+    const parsed = parseVerifyArgs(args);
+    target = parsed.target;
+    ledger = parsed.opts['--ledger'];
+    expectedSigner = parsed.opts['--signer'];
+    if (ledger !== undefined) {
+        let u;
+        try {
+            u = new URL(ledger);
+        }
+        catch {
+            u = undefined;
+        }
+        if (!u || (u.protocol !== 'https:' && u.protocol !== 'http:')) {
+            throw new UsageError(`--ledger must be an http(s) URL, got ${safeText(ledger)}`);
+        }
+    }
+    if (DIGEST_RE.test(target)) {
+        if (expectedSigner !== undefined) {
+            throw new UsageError("--signer binds a receipt FILE's signature; a digest lookup checks the ledger's counter-signed " +
+                'chain instead. Verify the receipt file with --signer.');
+        }
+    }
+    else if (expectedSigner !== undefined && !ADDRESS_RE.test(expectedSigner)) {
+        throw new UsageError(`--signer must be a 20-byte 0x-prefixed hex address, got ${JSON.stringify(expectedSigner)}`);
+    }
+}
+catch (e) {
+    if (e instanceof UsageError)
+        usage(e.message);
+    throw e;
+}
 async function checkLedger(digest, url) {
-    const res = await fetch(`${url.replace(/\/$/, '')}/v1/receipts/${digest}/verify`);
-    const body = (await res.json());
+    let body;
+    try {
+        const res = await fetch(`${url.replace(/\/$/, '')}/v1/receipts/${digest}/verify`);
+        body = (await res.json());
+    }
+    catch (e) {
+        const cause = e instanceof Error && e.cause instanceof Error ? ` (${e.cause.message})` : '';
+        fail(`could not get an answer from the ledger at ${url}: ${e instanceof Error ? e.message : String(e)}${cause}`);
+    }
     // Name the ledger that answered, always — a verifier that hides which chain it consulted is
     // making the reader take its word for the one fact the check exists to establish. Nothing
     // beyond that: `--ledger` is documented in usage and the README, and the failure path is not
@@ -46,54 +134,132 @@ async function checkLedger(digest, url) {
         fail(`no record of ${digest} on the Tersign ledger (${url})`);
     if (!body.chainOk)
         fail('ledger record found but the counter-signed hash-chain does NOT verify');
+    // Strings from the ledger are rendered inert: a hostile --ledger must not be able to print
+    // a line of its own (a bare VALID, say) through a sellerId.
+    const t = (v) => safeText(String(v));
     console.log(`ledger:    ${url}`);
-    console.log(`           counter-signed OK (seller ${body.sellerId}, seq ${body.seq}, ledger key ${body.ledgerSigner})`);
+    // "reports", never "OK": these are the server's own booleans. Nothing here checks the
+    // counter-signature against a pinned ledger key — a look-alike server can answer the same.
+    console.log(`           reports: found, counter-signed chain intact (seller ${t(body.sellerId)}, seq ${t(body.seq)}, ledger key ${t(body.ledgerSigner)}) — not checked locally`);
     // Present once the record sits under an anchored chain commitment (anchors since 2026-08-28):
     // the accumulator covers every seq ≤ commitment.seq, so the anchor binds this record too.
     const c = body.commitment;
     if (c) {
-        const block = c.bitcoinBlockHeight ? ` block ${c.bitcoinBlockHeight}` : '';
-        console.log(`           commitment: seq ≤ ${c.seq} committed (acc ${c.acc.slice(0, 10)}…) — ${c.status}${block}`);
+        const block = c.bitcoinBlockHeight ? ` block ${t(c.bitcoinBlockHeight)}` : '';
+        console.log(`           commitment: seq ≤ ${t(c.seq)} committed (acc ${t(String(c.acc).slice(0, 10))}…) — ${t(c.status)}${block}`);
     }
 }
-if (/^0x[0-9a-f]{64}$/i.test(target)) {
-    await checkLedger(target, ledger ?? DEFAULT_LEDGER);
-    console.log('VALID');
+if (DIGEST_RE.test(target)) {
+    const used = ledger ?? DEFAULT_LEDGER;
+    await checkLedger(target, used);
+    // Qualified: the verdict is the ledger's answer about itself. Verifying the receipt FILE
+    // (with --signer) is the local check.
+    console.log(`VALID (ledger-reported) — ${safeText(used)} reports the record and its counter-signed chain; nothing was verified locally`);
     process.exit(0);
 }
-let raw;
+// ---- a receipt FILE: every check runs before anything is printed, so a failure prints only
+// ---- the INVALID line and never a half-report that reads like a pass.
+let bytes;
 try {
-    raw = readFileSync(target, 'utf8');
+    bytes = readFileSync(target);
 }
-catch {
-    fail(`cannot read '${target}' — pass a receipt JSON file that exists, or a 0x… digest with --ledger`);
+catch (e) {
+    const code = e.code;
+    if (code === 'ENOENT')
+        usage(`no such file: ${target} — pass a receipt JSON file, or a 0x-prefixed 32-byte digest`);
+    if (code === 'EISDIR') {
+        usage(`${target} is a directory: pass a receipt JSON file. An evidence bundle directory is checked by ` +
+            'the bundle verifier (verify/verify_bundle.py).');
+    }
+    usage(`cannot read ${target} (${code ?? (e instanceof Error ? e.message : String(e))})`);
 }
-let parsed;
+let text;
 try {
-    parsed = JSON.parse(raw);
+    // fatal: a lenient decode would swap bad bytes for U+FFFD and verify text the file does not hold
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
 }
 catch {
-    fail(`'${target}' is not valid JSON — expected a signed receipt file`);
+    usage(`${target} is not UTF-8 text — expected a signed receipt JSON file`);
+}
+let doc;
+try {
+    doc = JSON.parse(text);
+}
+catch (e) {
+    usage(`${target} is not JSON (${e instanceof Error ? e.message : 'parse error'}) — expected a signed receipt file`);
 }
-const receipt = 'payload' in parsed || 'signature' in parsed ? parsed : parsed.receipt;
-const record = 'receipt' in parsed ? parsed.record : undefined;
+const dup = findDuplicateKey(text);
+if (dup !== null)
+    fail(`duplicate key ${JSON.stringify(dup)} — one JSON object, two values for one name`);
+const nonInteger = findNonIntegerNumberToken(text);
+if (nonInteger !== null) {
+    fail(`number ${safeText(nonInteger, 40)} is not an integer — the canonical digest is defined over integers only, and this file's bytes do not survive a parse unchanged`);
+}
+// A lone surrogate anywhere (key or value) makes the file's text differ from the bytes that are
+// signed and digested: UTF-8 cannot carry it, so the encoder substitutes U+FFFD. The Python twin
+// refuses such a file too.
+const lone = findLoneSurrogate(doc);
+if (lone !== null) {
+    fail(`${safeText(lone, 64)} holds a lone UTF-16 surrogate (a \\uD800-\\uDFFF escape) that UTF-8 cannot carry — the signed and digested text would be U+FFFD, not what this file says`);
+}
+const file = resolveReceiptFile(doc);
+if (!file.ok)
+    fail(file.reason);
+const receipt = file.receipt;
 const result = await verifyReceipt(receipt, expectedSigner);
-if (!result.valid)
-    fail(`receipt signature: ${result.reason}`);
-const digest = digestOf(receipt);
-console.log(`signature: OK (signer ${result.signer})`);
-console.log(`digest:    ${digest}`);
-if (record) {
-    const rec = await verifyComplianceRecord(record, expectedSigner);
-    if (!rec.valid)
-        fail(`compliance record: ${rec.reason}`);
+if (!result.valid) {
+    fail(signerStatus(result, expectedSigner) === 'MISMATCH'
+        ? `signer MISMATCH — ${signerExplanation(result, expectedSigner, '--signer')}`
+        : `receipt signature: ${result.reason ?? 'invalid receipt'}`);
+}
+let digest;
+try {
+    digest = digestOf(receipt);
+}
+catch (e) {
+    fail(`cannot compute the receipt's canonical digest: ${e instanceof Error ? e.message : String(e)}`);
+}
+let rec;
+if (file.record !== undefined) {
+    const record = file.record;
+    rec = await verifyComplianceRecord(record, expectedSigner);
+    if (!rec.valid) {
+        fail(signerStatus(rec, expectedSigner) === 'MISMATCH'
+            ? `record signer MISMATCH — ${signerExplanation(rec, expectedSigner, '--signer', 'record')}`
+            : `compliance record: ${rec.reason ?? 'invalid record'}`);
+    }
     if (record.record.receiptDigest !== digest)
         fail('compliance record is bound to a DIFFERENT receipt');
-    console.log(`record:    OK (bound to receipt, signer ${rec.signer})`);
 }
+const signer = result.signer;
+console.log(`signature: recovers to ${signer}`);
+console.log(`signer:    ${signerStatus(result, expectedSigner)} — ${signerExplanation(result, expectedSigner, '--signer')}`);
+if (result.testKey)
+    console.log(`test key:  ${testKeyNote(signer, result.testKey)}`);
+if (rec) {
+    console.log(`record:    OK — bound to this receipt's digest; signed by ${rec.signer}, signer ${signerStatus(rec, expectedSigner)}`);
+    if (rec.testKey && rec.signer && rec.signer.toLowerCase() !== signer.toLowerCase()) {
+        console.log(`test key:  ${testKeyNote(rec.signer, rec.testKey)}`);
+    }
+}
+const recordFile = file.under === 'artifact';
+if (recordFile) {
+    console.log(`checked:   the receipt under "artifact" only — the record's own fields (${file.recordFieldsNotChecked.join(', ')}) ` +
+        "were NOT checked: not its place in the chain, not the ledger's countersignature. The bundle verifier " +
+        '(verify/verify_bundle.py) checks those.');
+}
+else if (file.under) {
+    console.log(`checked:   the receipt under ${JSON.stringify(file.under)}${rec ? ' and its compliance record' : ''} in this file`);
+}
+const unsigned = (result.unsignedFields ?? []).map((f) => (file.under ? `${file.under}.${f}` : f));
+if (unsigned.length)
+    console.log(`unsigned:  ${unsignedNote(unsigned)}`);
+console.log(`digest:    ${digest}`);
 // A receipt FILE carries its own signature, so it verifies with no network at all. Only
 // check a chain when the caller asked for one — defaulting here would turn an offline
 // verification into a silent network call, which is the opposite of the point.
 if (ledger)
     await checkLedger(digest, ledger);
-console.log('VALID');
+// The verdict line. Bare `VALID` only when the signer is BOUND, no signer is a test key, and the
+// file is the receipt itself or {receipt, record} (a bundle record file is qualified).
+console.log(verdictHead(true, result.signerBound, Boolean(result.testKey || rec?.testKey), recordFile));

package/dist/verify-report.d.ts

@@ -0,0 +1,75 @@
+import { type SignerBinding } from './receipt/binding.js';
+export declare const SIGNED_FIELDS_TEXT: string;
+/** How the caller binds a signer on this surface: the CLI flag, or the MCP argument. */
+export type BindHint = '--signer' | 'expectedSigner';
+/** `VALID`, or VALID with every qualifier that applies; `INVALID` when not valid. The order is
+ * the Python CLI's: signer UNAUTHENTICATED, published test key, record artifact only. */
+export declare function verdictHead(valid: boolean, signerBound: boolean, testKey: boolean, recordArtifactOnly?: boolean): string;
+/** What the signer status means for a receipt, in one or two sentences. */
+export declare function signerExplanation(r: SignerBinding, expected: string | undefined, hint: BindHint, what?: string): string;
+export declare function testKeyNote(signer: string, label: string): string;
+export declare function unsignedNote(fields: readonly string[]): string;
+/** One sentence for machine readers (the MCP tools' `verdict`): head, then what it means. */
+export declare function verdictSentence(r: SignerBinding & {
+    unsignedFields?: readonly string[];
+}, expected: string | undefined, hint: BindHint, what?: string): string;
+/** A library or viem reason, flattened to one line so it can never add an output line. */
+export declare function oneLine(s: string): string;
+/** Every option `tersign verify` accepts. Anything else is refused: an unknown flag used to be
+ * ignored, so `verify r.json --sigenr 0xWRONG` printed the same VALID as an unbound run and the
+ * operator believed a binding had been checked that never ran. */
+export declare const VERIFY_OPTIONS: {
+    readonly '--signer': "--signer 0x<issuer address>";
+    readonly '--ledger': "--ledger https://tersign.ai";
+};
+export type VerifyOption = keyof typeof VERIFY_OPTIONS;
+export declare class UsageError extends Error {
+}
+export declare const DIGEST_RE: RegExp;
+export declare function wantsHelp(args: readonly string[]): boolean;
+/** verify's arguments → { target, opts }. Throws UsageError on anything ambiguous: an unknown or
+ * valueless flag, a flag given twice, two targets, no target. Flags may come before or after
+ * the target. */
+export declare function parseVerifyArgs(args: readonly string[]): {
+    target: string;
+    opts: Partial<Record<VerifyOption, string>>;
+};
+/** The first key that appears twice in one JSON object, or null. `text` must already have
+ * parsed as JSON. JSON.parse is last-wins while a human reader — and many first-wins parsers —
+ * take the FIRST, so two "resourceUrl" keys would let the file a reader sees differ from the
+ * value this CLI checked, under a VALID. The bundle verifier and the Python CLI refuse them too. */
+export declare function findDuplicateKey(text: string): string | null;
+/** The first number token outside a string that is not a plain integer (`1.0`, `1e2`), or null.
+ * JSON.parse collapses `1783761710.0` to `1783761710`, so a file whose bytes carry a float
+ * would otherwise verify with the SAME digest as the integer original — while the Python
+ * verifier (which parses it as a float) and the ledger (which scans these tokens at ingest)
+ * both refuse it. The canonical digest is defined over integers only; so is this CLI. */
+export declare function findNonIntegerNumberToken(text: string): string | null;
+/** The fields an evidence-bundle record file (records/NNNNNN.json) carries beside the signed
+ * receipt under `artifact`. The ONLY wrapper fields accepted there — the Python CLI's rule. */
+export declare const RECORD_FIELDS: readonly ["seq", "format", "artifactDigest", "prevDigest", "linkDigest", "countersignature"];
+export type ResolvedFile = {
+    ok: true;
+    receipt: unknown;
+    record?: unknown;
+    /** the wrapper key the receipt was found under, when it was not the file itself */
+    under?: 'receipt' | 'artifact';
+    /** for a bundle record file: its own fields, which this command does NOT check */
+    recordFieldsNotChecked: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Which object in a parsed file is the receipt this run checks — never a guess, and never one
+ * the reader could mistake for another.
+ *
+ *  {format, payload, signature}                the receipt itself
+ *  {receipt, record?}                          a receipt with its compliance record (both checked)
+ *  {artifact, seq, format, artifactDigest, …}  an evidence-bundle record file (RECORD_FIELDS)
+ *
+ * Anything else is refused, not dropped: a receipt at the top level AND under "receipt" /
+ * "artifact" (a fabricated top-level receipt borrowing a genuine nested signature), or a
+ * wrapper carrying any other field (a stray resourceUrl beside a genuine `artifact` reads as the
+ * receipt that was checked). The Python CLI accepts only the receipt and the record-file shapes,
+ * so a {receipt, record} file exits differently there (verify-bin.ts lists every measured case). */
+export declare function resolveReceiptFile(doc: unknown): ResolvedFile;

package/dist/verify-report.js

@@ -0,0 +1,241 @@
+/** The words a verify result is reported in — shared by `tersign verify` (verify-bin.ts) and the
+ * MCP verify tools, and the pure halves of the CLI (argument parsing, file-shape resolution,
+ * duplicate-key detection) so they can be tested without running the script.
+ *
+ * The rule every sentence here follows: a verdict never says more than the checks behind it.
+ * An unqualified VALID is printed only when the signer is BOUND to an address the caller
+ * supplied and that address is not a published test key. Every other PASS says, in the verdict
+ * itself, what it does not prove. Same rule as the Python twin (`python3 -m tersign verify`,
+ * sdk-py/tersign/__main__.py), in the same words where both have the case; the inputs on which the
+ * two exit differently are listed, as measured, in verify-bin.ts. */
+import { SIGNED_RECEIPT_FIELDS } from './receipt/eip712.js';
+import { byCodePoint, isPlainObject, quoteField } from './receipt/binding.js';
+export const SIGNED_FIELDS_TEXT = SIGNED_RECEIPT_FIELDS.join(', ');
+/** `VALID`, or VALID with every qualifier that applies; `INVALID` when not valid. The order is
+ * the Python CLI's: signer UNAUTHENTICATED, published test key, record artifact only. */
+export function verdictHead(valid, signerBound, testKey, recordArtifactOnly = false) {
+    if (!valid)
+        return 'INVALID';
+    const q = [];
+    if (!signerBound)
+        q.push('signer UNAUTHENTICATED');
+    if (testKey)
+        q.push('published test key');
+    if (recordArtifactOnly)
+        q.push('record artifact only');
+    return q.length ? `VALID (${q.join(', ')})` : 'VALID';
+}
+/** What the signer status means for a receipt, in one or two sentences. */
+export function signerExplanation(r, expected, hint, what = 'receipt') {
+    const s = r.signer ?? '(none)';
+    if (!r.valid && r.signer && expected) {
+        return `the signature recovers to ${s}, not to the ${hint} ${expected}: this ${what} was not signed by that key, or was altered after signing.`;
+    }
+    const receipt = what === 'receipt';
+    if (r.signerBound) {
+        const covered = receipt ? `the signed receipt fields (${SIGNED_FIELDS_TEXT})` : `this ${what}'s signed digests`;
+        return `${covered} were signed by ${s}, the address you supplied with ${hint}. The binding is only as strong as the channel that address came from.`;
+    }
+    const edit = receipt
+        ? "an edit to any signed field's value recovers a different address and reaches this same result"
+        : `anyone can edit the ${what}, recompute its digest and re-sign it with their own key, and reach this same result`;
+    return (`the signature recovers to ${s}, but no ${hint} was supplied, so nothing binds that address to the issuer. ` +
+        `This proves neither who signed nor that the ${what} is unmodified: ${edit}. For authorship, re-run with ` +
+        `${hint} <the issuer's address, obtained out-of-band>.`);
+}
+export function testKeyNote(signer, label) {
+    return `${signer} is a PUBLISHED test key (${label}): anyone can produce this signature, so it is not evidence of who issued it.`;
+}
+export function unsignedNote(fields) {
+    return `${fields.map(quoteField).join(', ')} — in this file but NOT covered by the signature, and not checked here`;
+}
+/** One sentence for machine readers (the MCP tools' `verdict`): head, then what it means. */
+export function verdictSentence(r, expected, hint, what = 'receipt') {
+    if (!r.valid) {
+        const why = r.signer && expected ? signerExplanation(r, expected, hint, what) : oneLine(r.reason ?? `invalid ${what}`);
+        return `INVALID — ${why}`;
+    }
+    let s = `${verdictHead(true, r.signerBound, Boolean(r.testKey))} — ${signerExplanation(r, expected, hint, what)}`;
+    if (r.testKey && r.signer)
+        s += ` ${testKeyNote(r.signer, r.testKey)}`;
+    // A count, never the names: they are chosen by whoever wrote the file, and the verdict is the
+    // one sentence an agent reads as the tool's own. The names stay in `unsignedFields`.
+    const n = r.unsignedFields?.length ?? 0;
+    if (n)
+        s += ` ${n} field${n === 1 ? '' : 's'} the signature does not cover ${n === 1 ? 'is' : 'are'} listed in unsignedFields.`;
+    return s;
+}
+/** A library or viem reason, flattened to one line so it can never add an output line. */
+export function oneLine(s) {
+    return s.replace(/\s*[\r\n\u2028\u2029]+\s*/g, ' ').trim();
+}
+// ---------------------------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------------------------
+/** Every option `tersign verify` accepts. Anything else is refused: an unknown flag used to be
+ * ignored, so `verify r.json --sigenr 0xWRONG` printed the same VALID as an unbound run and the
+ * operator believed a binding had been checked that never ran. */
+export const VERIFY_OPTIONS = {
+    '--signer': '--signer 0x<issuer address>',
+    '--ledger': '--ledger https://tersign.ai',
+};
+export class UsageError extends Error {
+}
+export const DIGEST_RE = /^0x[0-9a-fA-F]{64}$/;
+export function wantsHelp(args) {
+    return args[0] === 'help' || args.includes('--help') || args.includes('-h');
+}
+/** verify's arguments → { target, opts }. Throws UsageError on anything ambiguous: an unknown or
+ * valueless flag, a flag given twice, two targets, no target. Flags may come before or after
+ * the target. */
+export function parseVerifyArgs(args) {
+    let target;
+    const opts = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('-') && a !== '-') {
+            if (!Object.hasOwn(VERIFY_OPTIONS, a)) {
+                throw new UsageError(`unknown option ${a} (accepted: ${Object.keys(VERIFY_OPTIONS).sort().join(', ')})`);
+            }
+            const flag = a;
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith('-'))
+                throw new UsageError(`${flag} requires a value, e.g. ${VERIFY_OPTIONS[flag]}`);
+            if (opts[flag] !== undefined)
+                throw new UsageError(`${flag} given twice`);
+            opts[flag] = v;
+            i++;
+            continue;
+        }
+        if (target !== undefined)
+            throw new UsageError(`one receipt path or digest per run (got ${target} and ${a})`);
+        target = a;
+    }
+    if (target === undefined)
+        throw new UsageError('verify needs a receipt path or a 0x-prefixed 32-byte digest');
+    return { target, opts };
+}
+// ---------------------------------------------------------------------------------------------
+// Receipt files
+// ---------------------------------------------------------------------------------------------
+/** The first key that appears twice in one JSON object, or null. `text` must already have
+ * parsed as JSON. JSON.parse is last-wins while a human reader — and many first-wins parsers —
+ * take the FIRST, so two "resourceUrl" keys would let the file a reader sees differ from the
+ * value this CLI checked, under a VALID. The bundle verifier and the Python CLI refuse them too. */
+export function findDuplicateKey(text) {
+    const stack = [];
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"') {
+            let j = i + 1;
+            while (j < text.length && text[j] !== '"')
+                j += text[j] === '\\' ? 2 : 1;
+            const top = stack[stack.length - 1];
+            if (top?.keys && top.expectKey) {
+                const key = JSON.parse(text.slice(i, j + 1)); // decodes escapes: "a" and "\u0061" collide
+                if (top.keys.has(key))
+                    return key;
+                top.keys.add(key);
+                top.expectKey = false;
+            }
+            i = j;
+        }
+        else if (c === '{') {
+            stack.push({ keys: new Set(), expectKey: true });
+        }
+        else if (c === '[') {
+            stack.push({ keys: null, expectKey: false });
+        }
+        else if (c === '}' || c === ']') {
+            stack.pop();
+        }
+        else if (c === ',') {
+            const top = stack[stack.length - 1];
+            if (top?.keys)
+                top.expectKey = true;
+        }
+    }
+    return null;
+}
+/** The first number token outside a string that is not a plain integer (`1.0`, `1e2`), or null.
+ * JSON.parse collapses `1783761710.0` to `1783761710`, so a file whose bytes carry a float
+ * would otherwise verify with the SAME digest as the integer original — while the Python
+ * verifier (which parses it as a float) and the ledger (which scans these tokens at ingest)
+ * both refuse it. The canonical digest is defined over integers only; so is this CLI. */
+export function findNonIntegerNumberToken(text) {
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"') {
+            i++;
+            while (i < text.length && text[i] !== '"')
+                i += text[i] === '\\' ? 2 : 1;
+            continue;
+        }
+        if (c === '-' || (c >= '0' && c <= '9')) {
+            const m = /^-?\d+(\.\d+)?([eE][+-]?\d+)?/.exec(text.slice(i, i + 400));
+            if (m && (m[1] !== undefined || m[2] !== undefined))
+                return m[0];
+            i += (m?.[0].length ?? 1) - 1;
+        }
+    }
+    return null;
+}
+/** The fields an evidence-bundle record file (records/NNNNNN.json) carries beside the signed
+ * receipt under `artifact`. The ONLY wrapper fields accepted there — the Python CLI's rule. */
+export const RECORD_FIELDS = ['seq', 'format', 'artifactDigest', 'prevDigest', 'linkDigest', 'countersignature'];
+/** Which object in a parsed file is the receipt this run checks — never a guess, and never one
+ * the reader could mistake for another.
+ *
+ *  {format, payload, signature}                the receipt itself
+ *  {receipt, record?}                          a receipt with its compliance record (both checked)
+ *  {artifact, seq, format, artifactDigest, …}  an evidence-bundle record file (RECORD_FIELDS)
+ *
+ * Anything else is refused, not dropped: a receipt at the top level AND under "receipt" /
+ * "artifact" (a fabricated top-level receipt borrowing a genuine nested signature), or a
+ * wrapper carrying any other field (a stray resourceUrl beside a genuine `artifact` reads as the
+ * receipt that was checked). The Python CLI accepts only the receipt and the record-file shapes,
+ * so a {receipt, record} file exits differently there (verify-bin.ts lists every measured case). */
+export function resolveReceiptFile(doc) {
+    if (!isPlainObject(doc)) {
+        return { ok: false, reason: 'not a signed receipt: expected a JSON object {format, payload, signature}' };
+    }
+    const own = (k) => Object.hasOwn(doc, k);
+    const atTop = own('payload') || own('signature');
+    const wrappers = ['receipt', 'artifact'].filter(own);
+    if (atTop && wrappers.length) {
+        return {
+            ok: false,
+            reason: `not one receipt: a receipt at the top level AND one under ${wrappers.map(quoteField).join(' and ')} — refusing to choose which one the reader means; nothing was verified`,
+        };
+    }
+    if (wrappers.length > 1) {
+        return { ok: false, reason: 'not one receipt: a receipt under both "receipt" and "artifact" — refusing to choose; nothing was verified' };
+    }
+    if (atTop)
+        return { ok: true, receipt: doc, recordFieldsNotChecked: [] };
+    const under = wrappers[0];
+    if (!under) {
+        return {
+            ok: false,
+            reason: 'not a signed receipt: expected {format, payload, signature}, {receipt, record}, or an evidence-bundle record file',
+        };
+    }
+    const allowed = new Set(under === 'receipt' ? ['receipt', 'record'] : ['artifact', ...RECORD_FIELDS]);
+    const extra = Object.keys(doc).filter((k) => !allowed.has(k)).sort(byCodePoint);
+    if (extra.length) {
+        const shape = under === 'receipt' ? '{receipt, record}' : 'evidence-bundle record';
+        return {
+            ok: false,
+            reason: `not one receipt: the file nests a signed ${quoteField(under)} and also carries ${extra.length} top-level ` +
+                `field${extra.length === 1 ? '' : 's'} no ${shape} has (first: ${quoteField(extra[0])}), so its top-level ` +
+                'fields would read as the receipt while the nested one was checked; nothing was verified. Pass the receipt ' +
+                'itself, or an unmodified records/NNNNNN.json.',
+        };
+    }
+    if (under === 'receipt') {
+        return own('record')
+            ? { ok: true, receipt: doc.receipt, record: doc.record, under, recordFieldsNotChecked: [] }
+            : { ok: true, receipt: doc.receipt, under, recordFieldsNotChecked: [] };
+    }
+    return { ok: true, receipt: doc.artifact, under, recordFieldsNotChecked: RECORD_FIELDS.filter(own) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tersign",
-  "version": "0.4.10",
+  "version": "0.5.0",
   "description": "Tersign \u2014 the evidence layer for the agent economy. Counter-signed receipts, agent action records, idempotency enforcement, refunds, disputes, and jury-ready evidence envelopes for x402/agent-commerce sellers.",
   "license": "MIT",
   "type": "module",