tersign 0.4.11 → 0.6.0

package/dist/receipt/network.js

@@ -0,0 +1,71 @@
+/** x402 v1 network names → CAIP-2, for the receipt payload.
+ *
+ * The offer-receipt extension requires CAIP-2 in the signed payload whatever the protocol version:
+ * "Servers MUST convert v1 network identifiers (e.g., "base-sepolia") to CAIP-2 format (e.g.,
+ * "eip155:84532") in the receipt payload" (x402-foundation/x402 specs/extensions/
+ * extension-offer-and-receipt.md, receipt section; present at main 6b6ee91fee02, read 2026-09-29).
+ * A v1 settlement response carries the v1 name (`"base"`), so a receipt built from it without this
+ * step signs a payload that fails the spec.
+ *
+ * The EVM table is upstream `@x402/evm`'s `EVM_NETWORK_CHAIN_ID_MAP`, copied as written
+ * (typescript/packages/mechanisms/evm/src/constants.ts, blob ab7db42cc1c0: main 6b6ee91fee02, last
+ * changed a9955ae5538e, read 2026-09-29). Those 24 names are the ones upstream's v1 EVM facilitator
+ * settles and reports back as `network`, so each can reach a receipt. The offer-receipt reference's
+ * own table (typescript/packages/extensions/src/offer-receipt/signing.ts `V1_EVM_NETWORK_CHAIN_IDS`,
+ * same commit) holds 17 of them, with the same ids. The Solana table is signing.ts
+ * `V1_SOLANA_NETWORKS`, identical to `@x402/svm`'s `V1_TO_V2_NETWORK_MAP`
+ * (mechanisms/svm/src/constants.ts, same commit). The rules are signing.ts
+ * `convertNetworkStringToCAIP2`'s: a string containing `:` passes through unchanged, a known v1 name
+ * is looked up case-insensitively, anything else throws. One difference: the lookup reads own keys
+ * only, so an inherited object key such as `constructor` throws instead of resolving. Re-check
+ * against both upstream files when a v1 network is added there; test/network.test.ts pins both
+ * tables by exact equality.
+ *
+ * The tables are exported for that test only; the package entry re-exports `toCaip2Network`, not
+ * them. */
+export const V1_EVM_NETWORK_CHAIN_IDS = {
+    ethereum: 1,
+    sepolia: 11155111,
+    abstract: 2741,
+    'abstract-testnet': 11124,
+    'base-sepolia': 84532,
+    base: 8453,
+    'avalanche-fuji': 43113,
+    avalanche: 43114,
+    iotex: 4689,
+    sei: 1329,
+    'sei-testnet': 1328,
+    polygon: 137,
+    'polygon-amoy': 80002,
+    peaq: 3338,
+    story: 1514,
+    educhain: 41923,
+    'skale-base-sepolia': 324705682,
+    megaeth: 4326,
+    monad: 143,
+    'monad-testnet': 10143,
+    stable: 988,
+    'stable-testnet': 2201,
+    celo: 42220,
+    flare: 14,
+};
+export const V1_SOLANA_NETWORKS = {
+    solana: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+    'solana-devnet': 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
+    'solana-testnet': 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z',
+};
+/** A CAIP-2 identifier passes through; a known x402 v1 name (`"base"`, `"base-sepolia"`,
+ * `"solana"`, …) becomes its CAIP-2 form; anything else throws, because a receipt cannot carry
+ * it. */
+export function toCaip2Network(network) {
+    if (network.includes(':'))
+        return network;
+    const key = network.toLowerCase();
+    const chainId = Object.hasOwn(V1_EVM_NETWORK_CHAIN_IDS, key) ? V1_EVM_NETWORK_CHAIN_IDS[key] : undefined;
+    if (chainId !== undefined)
+        return `eip155:${chainId}`;
+    const solana = Object.hasOwn(V1_SOLANA_NETWORKS, key) ? V1_SOLANA_NETWORKS[key] : undefined;
+    if (solana !== undefined)
+        return solana;
+    throw new Error(`Unknown network identifier: "${network}". A receipt needs CAIP-2 (e.g. "eip155:8453") or an x402 v1 name (e.g. "base", "solana").`);
+}

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 /** Wire types for the merged x402 `offer-receipt` extension (spec: x402-foundation/x402
- * specs/extensions/extension-offer-and-receipt.md, fetched 2026-07-07). The wire shape is
- * declared unstable upstream; everything outside this module treats these as opaque via
- * the codec functions, so upstream churn lands here only. */
+ * specs/extensions/extension-offer-and-receipt.md, fetched 2026-07-07; receipt payload fields
+ * and response placement re-read 2026-09-29 at main 5eee1e3c35). Everything outside this module
+ * treats these as opaque via the codec functions, so upstream churn lands here only. */
 export interface ReceiptPayload {
     version: 1;
     /** CAIP-2, e.g. "eip155:8453" */
@@ -36,9 +36,10 @@ export type SignedArtifact<P> = {
 };
 export type SignedReceipt = SignedArtifact<ReceiptPayload>;
 export type SignedOffer = SignedArtifact<OfferPayload>;
-/** ACP/UCP converged adjustment vocabulary (verified against both specs 2026-07-07).
- * Adopted verbatim so records round-trip card-rail order objects unchanged. */
-export type AdjustmentType = 'refund' | 'return' | 'credit' | 'price_adjustment' | 'dispute' | 'cancellation';
+/** Adjustment vocabulary as the proposed compliance-fields extension takes it from UCP: `type` is
+ * an OPEN string whose typical values are listed here, and only `status` is a fixed enum — so any
+ * other `type` string is accepted. */
+export type AdjustmentType = 'refund' | 'return' | 'credit' | 'price_adjustment' | 'dispute' | 'cancellation' | (string & {});
 export type AdjustmentStatus = 'pending' | 'completed' | 'failed';
 export interface Adjustment {
     type: AdjustmentType;
@@ -50,15 +51,24 @@ export interface Adjustment {
     /** digest of the receipt/record this adjusts — the hash-chain link */
     adjusts: `0x${string}`;
 }
-/** Tersign compliance record v1 — a SEPARATE artifact bound to the base receipt by digest.
- * The base receipt's EIP-712 schema is fixed upstream; extending it would break signatures,
- * so compliance data composes by reference. MINIMAL tier ≈ EU VAT Art 226b simplified-invoice
- * content (legally sufficient sub-€100); FULL tier adds EN 16931-aligned fields. */
+/** Compliance record v1 in the shape the `compliance-fields` extension proposes
+ * (x402-foundation/x402#2853, open — not settled spec) — a SEPARATE artifact bound to the base
+ * receipt by digest. The base receipt's EIP-712 schema is fixed upstream; extending it would
+ * break signatures, so compliance data composes by reference. The MINIMAL tier is isomorphic to
+ * the EU VAT Art 226b simplified-invoice content; whether a MINIMAL record suffices as an invoice
+ * is decided by the invoicing rules that apply to the supply (Art 219a), not by this record.
+ * FULL adds EN 16931-aligned fields. */
 export interface ComplianceRecordV1 {
     version: 1;
+    /** 1 = RFC 8785 (JCS) serialization, recordDigest = keccak256(utf8(canonical(record))).
+     * A MINIMAL member of the proposed extension; `buildMinimalRecord` sets it. Records built by
+     * tersign ≤0.5 omit it — readers accept both. */
+    canonicalizationVersion?: 1;
     /** keccak256 of the canonicalized base receipt artifact */
     receiptDigest: `0x${string}`;
-    /** sequential per issuer (Art 226(2)); assigned by the ledger when countersigned */
+    /** sequential number per issuer series (Art 226(2)), assigned by the ISSUER before the record
+     * is attested. A sequence attested only by its issuer evidences ordering only — never that no
+     * record was omitted. `buildMinimalRecord` does not set it. */
     seq?: number;
     issuedAt: number;
     issuer: {
@@ -109,7 +119,10 @@ export interface ComplianceRecordV1 {
     /** hash-chain to the record this corrects/refunds (Art 226b(e); ViDA corrective-invoice ref) */
     refundOf?: `0x${string}`;
     adjustment?: Adjustment;
-    /** retention floor in years; default 7 (HK IRO s.51C ≥ MiCA 5+2) */
+    /** retention floor in years the issuer commits to; set it to at least the longest period
+     * that applies to the issuer (Art 247(1) leaves it to each Member State — e.g. DE § 14b UStG:
+     * eight years). 7 is the default where no longer period applies (HK IRO s.51C, MiCA 5+2), not
+     * a statement that 7 suffices. */
     retentionYears: number;
 }
 /** EIP-712-signed attestation over a compliance record. The record itself is JSON (schema may

package/dist/types.js

@@ -1,5 +1,5 @@
 /** Wire types for the merged x402 `offer-receipt` extension (spec: x402-foundation/x402
- * specs/extensions/extension-offer-and-receipt.md, fetched 2026-07-07). The wire shape is
- * declared unstable upstream; everything outside this module treats these as opaque via
- * the codec functions, so upstream churn lands here only. */
+ * specs/extensions/extension-offer-and-receipt.md, fetched 2026-07-07; receipt payload fields
+ * and response placement re-read 2026-09-29 at main 5eee1e3c35). Everything outside this module
+ * treats these as opaque via the codec functions, so upstream churn lands here only. */
 export {};

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;