tersign 0.4.11 → 0.6.0

package/dist/mcp/tools.d.ts

@@ -1,5 +1,6 @@
 import type { Account } from 'viem/accounts';
 import type { Assure } from '../assure.js';
+import { type SignerStatus } from '../receipt/binding.js';
 import type { DisputeReason, EvidenceArtifactRef } from '../dispute/types.js';
 import type { LedgerClient } from '../ledgerClient.js';
 import type { ComplianceRecordV1, SignedComplianceRecord, SignedReceipt } from '../types.js';
@@ -31,10 +32,27 @@ export interface IssueReceiptArgs {
     principal?: string | undefined;
 }
 export declare function issueReceiptTool(deps: McpDeps, args: IssueReceiptArgs): Promise<import("../assure.js").IssuedReceipt>;
-export declare function verifyReceiptTool(artifact: SignedReceipt, expectedSigner?: string): Promise<import("../index.js").VerifyResult>;
-export declare function verifyRecordTool(record: ComplianceRecordV1, attestation: SignedComplianceRecord['attestation'], expectedSigner?: string): Promise<import("../compliance/types.js").VerifyLike>;
+/** What the MCP verify tools return: the library result led by a one-sentence `verdict` and an
+ * explicit `signerStatus`, so an agent that reads only the first field is told what was NOT
+ * checked. Same shape as `python3 -m tersign verify`'s JSON (its verdict says PASS/FAIL where
+ * this says VALID/INVALID, the npm CLI's words). */
+export interface VerifyToolResult {
+    verdict: string;
+    valid: boolean;
+    signer?: `0x${string}`;
+    signerStatus?: SignerStatus;
+    signerBound: boolean;
+    expectedSigner?: string;
+    testKey?: string;
+    digest?: `0x${string}`;
+    unsignedFields?: string[];
+    reason?: string;
+}
+export declare function verifyReceiptTool(artifact: SignedReceipt, expectedSigner?: string): Promise<VerifyToolResult>;
+export declare function verifyRecordTool(record: ComplianceRecordV1, attestation: SignedComplianceRecord['attestation'], expectedSigner?: string): Promise<VerifyToolResult>;
 export declare function recordRefundTool(deps: McpDeps, originalDigest: `0x${string}`, amount: string, reason: string): Promise<{
     id: string;
+    status: string;
 }>;
 export interface OpenDisputeArgs {
     receiptDigest: `0x${string}`;
@@ -51,8 +69,8 @@ export interface SubmitEvidenceArgs {
     artifacts: EvidenceArtifactRef[];
 }
 export declare function submitEvidenceTool(deps: McpDeps, args: SubmitEvidenceArgs): Promise<unknown>;
-/** Trigger deterministic adjudication (public — the rulebook is recomputable, so anyone
- * may pull the trigger once the route guard allows it). */
+/** Trigger deterministic adjudication (no API key — the outcome is a deterministic function of
+ * the recorded inputs, so anyone may pull the trigger once the route guard allows it). */
 export declare function adjudicateDisputeTool(deps: McpDeps, disputeDigest: `0x${string}`): Promise<unknown>;
 export declare function getDisputeTool(deps: McpDeps, disputeDigest: `0x${string}`): Promise<unknown>;
 export interface RecordDisclosureArgs {

package/dist/mcp/tools.js

@@ -1,5 +1,8 @@
 import { verifyReceipt } from '../receipt/eip712.js';
-import { verifyComplianceRecord } from '../compliance/record.js';
+import { recordDigest, verifyComplianceRecord } from '../compliance/record.js';
+import { digestOf } from '../canonical.js';
+import { findLoneSurrogate, signerStatus } from '../receipt/binding.js';
+import { verdictSentence } from '../verify-report.js';
 import { signDispute, signEvidence } from '../dispute/sign.js';
 async function ledgerFetch(base, path, init) {
     const url = `${base.replace(/\/$/, '')}${path}`;
@@ -30,11 +33,56 @@ export async function issueReceiptTool(deps, args) {
     };
     return deps.assure.issueFor(ctx);
 }
+function report(r, expectedSigner, digest, what) {
+    const status = signerStatus(r, expectedSigner);
+    // Key order is the Python CLI's: verdict first, the signer and its status next to each other.
+    return {
+        verdict: verdictSentence(r, expectedSigner, 'expectedSigner', what),
+        valid: r.valid,
+        ...(r.signer ? { signer: r.signer } : {}),
+        ...(status ? { signerStatus: status } : {}),
+        signerBound: r.signerBound,
+        ...(expectedSigner ? { expectedSigner } : {}),
+        ...(r.testKey ? { testKey: r.testKey } : {}),
+        ...(digest ? { digest } : {}),
+        ...(r.unsignedFields?.length ? { unsignedFields: r.unsignedFields } : {}),
+        ...(r.reason ? { reason: r.reason } : {}),
+    };
+}
+/** A digest failure (a float, an out-of-range integer) is a FAIL: an artifact with no canonical
+ * content address cannot be the one a ledger recorded. The Python twin decides it the same way. */
+function tryDigest(f) {
+    try {
+        return { digest: f() };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** A lone UTF-16 surrogate anywhere in what is verified: UTF-8 cannot carry it, so the signed and
+ * digested text is U+FFFD, not what the object says. Package text only — no path, since key names
+ * are chosen by whoever wrote the object. */
+const LONE_SURROGATE_REASON = 'a string in the object 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 this text';
 export async function verifyReceiptTool(artifact, expectedSigner) {
-    return verifyReceipt(artifact, expectedSigner);
+    if (findLoneSurrogate(artifact) !== null) {
+        return report({ valid: false, signerBound: false, reason: LONE_SURROGATE_REASON }, expectedSigner, undefined, 'receipt');
+    }
+    const r = await verifyReceipt(artifact, expectedSigner);
+    if (!r.signer)
+        return report(r, expectedSigner, undefined, 'receipt');
+    const d = tryDigest(() => digestOf(artifact));
+    if (d.error !== undefined) {
+        return report({ valid: false, signerBound: false, reason: `cannot compute the canonical digest: ${d.error}` }, expectedSigner, undefined, 'receipt');
+    }
+    return report(r, expectedSigner, d.digest, 'receipt');
 }
 export async function verifyRecordTool(record, attestation, expectedSigner) {
-    return verifyComplianceRecord({ record, attestation }, expectedSigner);
+    if (findLoneSurrogate({ record, attestation }) !== null) {
+        return report({ valid: false, signerBound: false, reason: LONE_SURROGATE_REASON }, expectedSigner, undefined, 'compliance record');
+    }
+    const r = await verifyComplianceRecord({ record, attestation }, expectedSigner);
+    const d = tryDigest(() => recordDigest(record));
+    return report(r, expectedSigner, d.digest, 'compliance record');
 }
 export async function recordRefundTool(deps, originalDigest, amount, reason) {
     if (!deps.ledger)
@@ -71,8 +119,8 @@ export async function submitEvidenceTool(deps, args) {
         ...(args.role === 'respondent' && deps.ledgerHttp.apiKey !== undefined ? { apiKey: deps.ledgerHttp.apiKey } : {}),
     });
 }
-/** Trigger deterministic adjudication (public — the rulebook is recomputable, so anyone
- * may pull the trigger once the route guard allows it). */
+/** Trigger deterministic adjudication (no API key — the outcome is a deterministic function of
+ * the recorded inputs, so anyone may pull the trigger once the route guard allows it). */
 export async function adjudicateDisputeTool(deps, disputeDigest) {
     if (!deps.ledgerHttp)
         throw new Error('ledger URL not configured — set TERSIGN_LEDGER_URL');

package/dist/receipt/binding.d.ts

@@ -0,0 +1,75 @@
+export declare const ADDRESS_RE: RegExp;
+export declare const MALFORMED_EXPECTED_SIGNER = "expectedSigner is not a 20-byte 0x-prefixed hex address";
+/** undefined, null and '' mean "not supplied". Anything else must be a 20-byte hex address:
+ * a malformed value is a FAILURE, never a silently skipped comparison (0, false, [] and {}
+ * included — a caller who passed something meant to bind). */
+export declare function parseExpectedSigner(v: unknown): {
+    ok: true;
+    value: string | undefined;
+} | {
+    ok: false;
+    reason: string;
+};
+export type SignerStatus = 'BOUND' | 'UNAUTHENTICATED' | 'MISMATCH';
+/** The fields every binding-aware verify result carries. */
+export interface SignerBinding {
+    valid: boolean;
+    signer?: `0x${string}`;
+    /** true only when an expected signer was supplied AND the signature recovers to exactly it.
+     * false with valid:true means `signer` is whatever the artifact's own signature recovers to:
+     * that proves neither who signed nor that the artifact is unmodified. */
+    signerBound: boolean;
+    /** present when the recovered signer is a PUBLISHED test key (see known-keys.ts): anyone can
+     * produce that signature, so even a bound match says nothing about who issued it. */
+    testKey?: string;
+    reason?: string;
+}
+/** BOUND: matched the expected signer. MISMATCH: an expected signer was supplied and the
+ * signature recovers to a different address. UNAUTHENTICATED: none was supplied. Undefined when
+ * nothing was recovered. Decided from the inputs, never from the reason text. */
+export declare function signerStatus(r: SignerBinding, expected: string | undefined): SignerStatus | undefined;
+/** Attach signerBound + testKey to a recovered signer, comparing against `expected` when given. */
+export declare function bindSigner(signer: `0x${string}`, expected: string | undefined, mismatchReason: string): SignerBinding;
+/** Why an EIP-712 `signature` is not THE canonical encoding, or undefined. Checked BEFORE
+ * recovery, with the same rules as the Python twin's verify_receipt (sdk-py tersign/verify.py
+ * signature_error). Each signature has exactly one accepted string, so a re-encoding of it is
+ * refused. That is a property of one signature, not of a signer and message: the signer can
+ * produce other valid signatures over the same message, so key any deduplication on (signer,
+ * message), never on the signature bytes. The accepted string is:
+ *
+ *   "0x" + 130 LOWER-CASE hex digits = r (32 bytes) || s (32 bytes) || v (1 byte), with
+ *   1 <= r, s < n; s <= n/2 (low-s); v = 27 or 28 (0x1b / 0x1c) — what viem's
+ *   serializeSignature emits, so every signature this package and the ledger produce.
+ *
+ * Everything else is refused, each with its own reason: a non-string ({r,s,v} object, 65-number
+ * array), a missing 0x, any other length, an upper-case hex digit, the recovery-id twin (v = 0/1
+ * for 27/28), an out-of-range r/s, and the high-s twin. viem accepts every one of those and
+ * recovers the real signer from each, and each re-encoding gives the file a different content
+ * digest — so without this one issuance had several "also valid" byte-distinct copies, each
+ * printing a bound VALID for signature bytes the issuer never produced (high-s, object and array
+ * found 2026-09-27; v 0/1 and upper-case hex found by the release review the same day).
+ *
+ * Scope: verifyReceipt, verifyComplianceRecord and the CLI and MCP tools built on them. The
+ * action-record, dispute and evidence verifiers (evidence/action.ts, dispute/sign.ts) do NOT call
+ * this and still accept what viem accepts (PUNT-REGISTER R8). Neither does the ledger's ingest
+ * (SECURITY-AUDIT A8), so a receipt the ledger counter-signed with a non-canonical signature is
+ * refused here. The reasons are package text only: nothing from the file is echoed. */
+export declare function signatureError(sig: unknown): string | undefined;
+/** A UTF-16 surrogate with no partner. JSON's \uD800-\uDFFF escapes can put one in a parsed string;
+ * UTF-8 cannot carry it, so the EIP-712 encoder (viem's TextEncoder) signs U+FFFD in its place and
+ * the text the file holds is not the text that was signed. The Python verifier refuses such a file
+ * outright ('utf-8' codec can't encode). */
+export declare const LONE_SURROGATE: RegExp;
+/** The first string (key or value) anywhere in `v` holding a lone surrogate, as a path, or null. */
+export declare function findLoneSurrogate(v: unknown, path?: string): string | null;
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/** Code-point order — the order Python's sorted() gives, so both verifiers list fields alike. */
+export declare function byCodePoint(a: string, b: string): number;
+/** Render text that came from the artifact (a field NAME, a ledger's string) so it can never
+ * forge output: control, format and line/paragraph-separator characters become \u escapes.
+ * Without this a payload key such as "x\nVALID" would print a bare VALID line of its own. */
+export declare function safeText(s: string, max?: number): string;
+/** A field name as a JSON string literal — `"payload.amount"` — clipped, quotes and
+ * backslashes escaped by JSON.stringify, and the invisible characters it leaves raw
+ * (U+2028/U+2029, bidi and other format controls) escaped too. */
+export declare function quoteField(name: string): string;

package/dist/receipt/binding.js

@@ -0,0 +1,161 @@
+/** What an EIP-712 verify can and cannot establish about WHO signed — shared by verifyReceipt,
+ * verifyComplianceRecord, the `tersign verify` CLI and the MCP verify tools, so those four
+ * surfaces cannot drift apart on the one question a verify result is read for. verifyActionRecord,
+ * verifyDispute and verifyEvidence do NOT use it: they have no signer binding and no canonical
+ * signature check (PUNT-REGISTER R8).
+ *
+ * ECDSA recovery yields an address for ANY payload and ANY well-formed signature. An edited
+ * receipt therefore still "verifies" — it recovers a different address. A recovered signer is
+ * evidence of authorship only when it is compared against an address the caller obtained
+ * somewhere else; without that comparison it is UNAUTHENTICATED, and every result says so. */
+import { publishedKeyLabel } from './known-keys.js';
+export const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+export const MALFORMED_EXPECTED_SIGNER = 'expectedSigner is not a 20-byte 0x-prefixed hex address';
+/** undefined, null and '' mean "not supplied". Anything else must be a 20-byte hex address:
+ * a malformed value is a FAILURE, never a silently skipped comparison (0, false, [] and {}
+ * included — a caller who passed something meant to bind). */
+export function parseExpectedSigner(v) {
+    if (v === undefined || v === null || v === '')
+        return { ok: true, value: undefined };
+    if (typeof v !== 'string' || !ADDRESS_RE.test(v))
+        return { ok: false, reason: MALFORMED_EXPECTED_SIGNER };
+    return { ok: true, value: v };
+}
+/** BOUND: matched the expected signer. MISMATCH: an expected signer was supplied and the
+ * signature recovers to a different address. UNAUTHENTICATED: none was supplied. Undefined when
+ * nothing was recovered. Decided from the inputs, never from the reason text. */
+export function signerStatus(r, expected) {
+    if (!r.signer)
+        return undefined;
+    if (r.signerBound)
+        return 'BOUND';
+    return expected ? 'MISMATCH' : 'UNAUTHENTICATED';
+}
+/** Attach signerBound + testKey to a recovered signer, comparing against `expected` when given. */
+export function bindSigner(signer, expected, mismatchReason) {
+    const out = { valid: true, signer, signerBound: expected !== undefined };
+    const label = publishedKeyLabel(signer);
+    if (label)
+        out.testKey = label;
+    if (expected !== undefined && signer.toLowerCase() !== expected.toLowerCase()) {
+        out.valid = false;
+        out.signerBound = false;
+        out.reason = mismatchReason;
+    }
+    return out;
+}
+/** secp256k1 group order. A signature's s must be at most N/2 (Ethereum's canonical low-s form). */
+const SECP256K1_N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+/** Why an EIP-712 `signature` is not THE canonical encoding, or undefined. Checked BEFORE
+ * recovery, with the same rules as the Python twin's verify_receipt (sdk-py tersign/verify.py
+ * signature_error). Each signature has exactly one accepted string, so a re-encoding of it is
+ * refused. That is a property of one signature, not of a signer and message: the signer can
+ * produce other valid signatures over the same message, so key any deduplication on (signer,
+ * message), never on the signature bytes. The accepted string is:
+ *
+ *   "0x" + 130 LOWER-CASE hex digits = r (32 bytes) || s (32 bytes) || v (1 byte), with
+ *   1 <= r, s < n; s <= n/2 (low-s); v = 27 or 28 (0x1b / 0x1c) — what viem's
+ *   serializeSignature emits, so every signature this package and the ledger produce.
+ *
+ * Everything else is refused, each with its own reason: a non-string ({r,s,v} object, 65-number
+ * array), a missing 0x, any other length, an upper-case hex digit, the recovery-id twin (v = 0/1
+ * for 27/28), an out-of-range r/s, and the high-s twin. viem accepts every one of those and
+ * recovers the real signer from each, and each re-encoding gives the file a different content
+ * digest — so without this one issuance had several "also valid" byte-distinct copies, each
+ * printing a bound VALID for signature bytes the issuer never produced (high-s, object and array
+ * found 2026-09-27; v 0/1 and upper-case hex found by the release review the same day).
+ *
+ * Scope: verifyReceipt, verifyComplianceRecord and the CLI and MCP tools built on them. The
+ * action-record, dispute and evidence verifiers (evidence/action.ts, dispute/sign.ts) do NOT call
+ * this and still accept what viem accepts (PUNT-REGISTER R8). Neither does the ledger's ingest
+ * (SECURITY-AUDIT A8), so a receipt the ledger counter-signed with a non-canonical signature is
+ * refused here. The reasons are package text only: nothing from the file is echoed. */
+export function signatureError(sig) {
+    if (typeof sig !== 'string') {
+        const t = sig === null ? 'null' : Array.isArray(sig) ? 'an array' : typeof sig === 'undefined' ? 'missing' : typeof sig === 'object' ? 'an object' : `a ${typeof sig}`;
+        return `signature must be a 0x-prefixed hex string of 65 bytes (r||s||v), not ${t}`;
+    }
+    if (!/^0x[0-9a-fA-F]{130}$/.test(sig))
+        return 'signature must be a 0x-prefixed hex string of 65 bytes (r||s||v)';
+    if (/[A-F]/.test(sig))
+        return 'signature hex must be lower-case (non-canonical)';
+    const r = BigInt(`0x${sig.slice(2, 66)}`);
+    const s = BigInt(`0x${sig.slice(66, 130)}`);
+    const v = Number.parseInt(sig.slice(130, 132), 16);
+    if (v === 0 || v === 1)
+        return `recovery id ${v} rejected (non-canonical): v must be 27 or 28`;
+    if (v !== 27 && v !== 28)
+        return `unsupported recovery id ${v}`;
+    if (r < 1n || r >= SECP256K1_N || s < 1n || s >= SECP256K1_N)
+        return 'r/s out of range';
+    if (s > SECP256K1_N / 2n)
+        return 'high-s signature rejected (non-canonical)';
+    return undefined;
+}
+/** A UTF-16 surrogate with no partner. JSON's \uD800-\uDFFF escapes can put one in a parsed string;
+ * UTF-8 cannot carry it, so the EIP-712 encoder (viem's TextEncoder) signs U+FFFD in its place and
+ * the text the file holds is not the text that was signed. The Python verifier refuses such a file
+ * outright ('utf-8' codec can't encode). */
+export const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** The first string (key or value) anywhere in `v` holding a lone surrogate, as a path, or null. */
+export function findLoneSurrogate(v, path = '$') {
+    if (typeof v === 'string')
+        return LONE_SURROGATE.test(v) ? path : null;
+    if (Array.isArray(v)) {
+        for (let i = 0; i < v.length; i++) {
+            const hit = findLoneSurrogate(v[i], `${path}[${i}]`);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }
+    if (isPlainObject(v)) {
+        for (const [k, x] of Object.entries(v)) {
+            if (LONE_SURROGATE.test(k))
+                return `${path} (a key)`;
+            const hit = findLoneSurrogate(x, `${path}.${k}`);
+            if (hit)
+                return hit;
+        }
+    }
+    return null;
+}
+export function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Code-point order — the order Python's sorted() gives, so both verifiers list fields alike. */
+export function byCodePoint(a, b) {
+    const x = a[Symbol.iterator]();
+    const y = b[Symbol.iterator]();
+    for (;;) {
+        const p = x.next();
+        const q = y.next();
+        if (p.done || q.done)
+            return (p.done ? 0 : 1) - (q.done ? 0 : 1);
+        const d = (p.value.codePointAt(0) ?? 0) - (q.value.codePointAt(0) ?? 0);
+        if (d !== 0)
+            return d;
+    }
+}
+/** Render text that came from the artifact (a field NAME, a ledger's string) so it can never
+ * forge output: control, format and line/paragraph-separator characters become \u escapes.
+ * Without this a payload key such as "x\nVALID" would print a bare VALID line of its own. */
+export function safeText(s, max = 96) {
+    return escapeInvisible(clip(s, max));
+}
+/** A field name as a JSON string literal — `"payload.amount"` — clipped, quotes and
+ * backslashes escaped by JSON.stringify, and the invisible characters it leaves raw
+ * (U+2028/U+2029, bidi and other format controls) escaped too. */
+export function quoteField(name) {
+    return escapeInvisible(JSON.stringify(clip(name, 64)));
+}
+function clip(s, max) {
+    const cps = [...s];
+    return cps.length > max ? cps.slice(0, max).join('') + '…' : s;
+}
+function escapeInvisible(s) {
+    return s.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, (ch) => {
+        const cp = ch.codePointAt(0) ?? 0;
+        return cp > 0xffff ? `\\u{${cp.toString(16)}}` : `\\u${cp.toString(16).padStart(4, '0')}`;
+    });
+}

package/dist/receipt/eip712.d.ts

@@ -1,5 +1,6 @@
 import type { Account } from 'viem/accounts';
 import type { OfferPayload, ReceiptPayload, SignedOffer, SignedReceipt } from '../types.js';
+import { type SignerBinding } from './binding.js';
 /** Canonical EIP-712 material from the merged offer-receipt extension. Domain chainId is
  * hardcoded to 1 by spec (off-chain signing format; payment network lives in payload.network). */
 export declare const RECEIPT_DOMAIN: {
@@ -62,11 +63,28 @@ export declare const OFFER_TYPES: {
 };
 export declare function signReceipt(payload: ReceiptPayload, account: Account): Promise<SignedReceipt>;
 export declare function signOffer(payload: OfferPayload, account: Account, acceptIndex?: number): Promise<SignedOffer>;
-export interface VerifyResult {
-    valid: boolean;
-    signer?: `0x${string}`;
-    reason?: string;
+/** What the EIP-712 Receipt signature covers. Anything else in the artifact rides along
+ * unsigned: it changes the canonical digest (the ledger's content address) but not the
+ * recovered signer. */
+export declare const SIGNED_RECEIPT_FIELDS: ("version" | "network" | "resourceUrl" | "payer" | "issuedAt" | "transaction")[];
+/** Fields present in `artifact` that the signature does not cover, as paths relative to the
+ * artifact — `payload.<k>` first, then top-level keys — in code-point order. */
+export declare function unsignedReceiptFields(artifact: Record<string, unknown>): string[];
+/** valid        the signature is well-formed and recovers to an address — and, when
+ *               expectedSigner is given, to exactly that address.
+ *  signerBound  true only when expectedSigner was supplied and matched. When false, `signer`
+ *               is whatever the receipt's own signature recovers to, and recovery yields an
+ *               address for ANY payload: an edited receipt still returns valid:true, with a
+ *               different signer. valid:true with signerBound:false proves neither who signed
+ *               nor that the payload is unmodified.
+ *  testKey      the recovered signer is a PUBLISHED test key (known-keys.ts).
+ *  unsignedFields  fields present in the artifact that the signature does not cover.
+ * The same result shape as the Python twin's verify_receipt (minus its digest, which the
+ * callers here compute themselves). */
+export interface VerifyResult extends SignerBinding {
+    unsignedFields?: string[];
 }
 /** Verify an EIP-712 receipt. `expectedSigner` implements the spec's payTo-key authorization
- * model; pass the seller's payTo address (or a registry-resolved key) to enforce it. */
+ * model; pass the seller's payTo address (or a registry-resolved key), obtained out-of-band,
+ * to enforce it. Without it the recovered signer is UNAUTHENTICATED (signerBound:false). */
 export declare function verifyReceipt(artifact: SignedReceipt, expectedSigner?: string): Promise<VerifyResult>;

package/dist/receipt/eip712.js

@@ -1,4 +1,5 @@
 import { recoverTypedDataAddress } from 'viem';
+import { LONE_SURROGATE, bindSigner, byCodePoint, isPlainObject, parseExpectedSigner, signatureError } from './binding.js';
 /** Canonical EIP-712 material from the merged offer-receipt extension. Domain chainId is
  * hardcoded to 1 by spec (off-chain signing format; payment network lives in payload.network). */
 export const RECEIPT_DOMAIN = { name: 'x402 receipt', version: '1', chainId: 1n };
@@ -71,25 +72,89 @@ export async function signOffer(payload, account, acceptIndex) {
         ? { format: 'eip712', payload, signature }
         : { format: 'eip712', payload, signature, acceptIndex };
 }
+/** What the EIP-712 Receipt signature covers. Anything else in the artifact rides along
+ * unsigned: it changes the canonical digest (the ledger's content address) but not the
+ * recovered signer. */
+export const SIGNED_RECEIPT_FIELDS = RECEIPT_TYPES.Receipt.map((f) => f.name);
+const ENVELOPE_FIELDS = new Set(['format', 'payload', 'signature']);
+const SIGNED = new Set(SIGNED_RECEIPT_FIELDS);
+/** Fields present in `artifact` that the signature does not cover, as paths relative to the
+ * artifact — `payload.<k>` first, then top-level keys — in code-point order. */
+export function unsignedReceiptFields(artifact) {
+    const payload = isPlainObject(artifact.payload) ? artifact.payload : {};
+    return [
+        ...Object.keys(payload).filter((k) => !SIGNED.has(k)).sort(byCodePoint).map((k) => `payload.${k}`),
+        ...Object.keys(artifact).filter((k) => !ENVELOPE_FIELDS.has(k)).sort(byCodePoint),
+    ];
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    if (typeof v === 'number' && !Number.isInteger(v))
+        return 'a non-integer number';
+    if (typeof v === 'number')
+        return v < 0 ? 'a negative integer' : 'an integer outside the safe range';
+    return typeof v;
+}
+/** The payload's signed fields, checked by JSON type before anything is recovered. BigInt()
+ * coerces true, "1", " 1783761710 " and "0x6a4…" to the signed number: each such edit recovered
+ * the real signer under a DIFFERENT digest, and nothing reported it. The ledger counter-signs
+ * only JSON safe integers here, and the Python verifier applies the same rule. */
+function signedFieldError(p) {
+    for (const k of ['version', 'issuedAt']) {
+        const v = p[k];
+        const ok = (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0) || (typeof v === 'bigint' && v >= 0n && v < 2n ** 256n);
+        if (!ok)
+            return `payload.${k} must be a JSON integer, not ${typeName(v)}: the signature covers the number, so another spelling of it is unsigned text`;
+    }
+    for (const k of ['network', 'resourceUrl', 'payer', 'transaction']) {
+        if (typeof p[k] !== 'string')
+            return `payload.${k} must be a string, not ${typeName(p[k])}`;
+        if (LONE_SURROGATE.test(p[k])) {
+            return `payload.${k} holds a lone UTF-16 surrogate (a \\uD800-\\uDFFF escape) that UTF-8 cannot carry: the signature covers U+FFFD in its place, not this text`;
+        }
+    }
+    return undefined;
+}
 /** Verify an EIP-712 receipt. `expectedSigner` implements the spec's payTo-key authorization
- * model; pass the seller's payTo address (or a registry-resolved key) to enforce it. */
+ * model; pass the seller's payTo address (or a registry-resolved key), obtained out-of-band,
+ * to enforce it. Without it the recovered signer is UNAUTHENTICATED (signerBound:false). */
 export async function verifyReceipt(artifact, expectedSigner) {
-    if (artifact.format !== 'eip712')
-        return { valid: false, reason: 'jws verification not implemented in v0' };
+    const expected = parseExpectedSigner(expectedSigner);
+    if (!expected.ok)
+        return { valid: false, signerBound: false, reason: expected.reason };
+    const notReceipt = { valid: false, signerBound: false, reason: 'not a signed receipt: expected {format, payload{...}, signature}' };
+    if (!isPlainObject(artifact))
+        return notReceipt;
+    if (artifact.format !== 'eip712') {
+        return { valid: false, signerBound: false, reason: 'jws verification not implemented in v0' };
+    }
+    if (!isPlainObject(artifact.payload))
+        return notReceipt;
+    const badField = signedFieldError(artifact.payload);
+    if (badField)
+        return { valid: false, signerBound: false, reason: badField };
+    const badSig = signatureError(artifact.signature);
+    if (badSig)
+        return { valid: false, signerBound: false, reason: badSig };
+    let signer;
     try {
-        const signer = await recoverTypedDataAddress({
+        signer = await recoverTypedDataAddress({
             domain: RECEIPT_DOMAIN,
             types: RECEIPT_TYPES,
             primaryType: 'Receipt',
             message: receiptMessage(artifact.payload),
             signature: artifact.signature,
         });
-        if (expectedSigner && signer.toLowerCase() !== expectedSigner.toLowerCase()) {
-            return { valid: false, signer, reason: 'signer does not match expected authorization key' };
-        }
-        return { valid: true, signer };
     }
     catch (e) {
-        return { valid: false, reason: e instanceof Error ? e.message : 'signature recovery failed' };
+        return { valid: false, signerBound: false, reason: e instanceof Error ? e.message : 'signature recovery failed' };
     }
+    const out = bindSigner(signer, expected.value, 'signer does not match expected authorization key');
+    const unsigned = unsignedReceiptFields(artifact);
+    if (unsigned.length)
+        out.unsignedFields = unsigned;
+    return out;
 }

package/dist/receipt/known-keys.d.ts

@@ -0,0 +1,23 @@
+/** Signer addresses whose private keys are PUBLISHED — anyone can sign as them.
+ *
+ * A signature from one of these keys recovers and verifies like any other, so a verifier that
+ * stays silent about it hands a stranger a receipt that looks authored when anyone could have
+ * minted it. They are what worked examples and test suites sign with (ours included: the
+ * synthetic evidence bundle uses dev-mnemonic accounts #0 and #1), which is exactly why a
+ * real-looking artifact carrying one must be flagged rather than passed quietly.
+ *
+ * Twin of `sdk-py/tersign/known_keys.py`. Neither copy is transcribed from the other: each is
+ * DERIVED from the published secrets and pinned by its own suite — test/known-keys.test.ts
+ * re-derives every address here with viem, the Python suite re-derives its table with its own
+ * secp256k1 — and the same test compares the two tables entry by entry (address AND label)
+ * wherever the monorepo carries both. A key added to one side without the other fails there.
+ * Deliberately narrow: keys whose secret is published as a convention, not every key that has
+ * ever leaked. */
+/** BIP-39 mnemonic shipped as the default dev account set by Hardhat (20 accounts) and Anvil
+ * (10), derived at m/44'/60'/0'/0/i. */
+export declare const DEV_MNEMONIC = "test test test test test test test test test test test junk";
+/** lowercase address → the published secret it comes from. A Map, not an object literal: a
+ * lookup of 'constructor' or '__proto__' on a plain object answers with a prototype member. */
+export declare const PUBLISHED_TEST_KEYS: ReadonlyMap<string, string>;
+/** The published-secret label for `address`, or undefined when it is not a known test key. */
+export declare function publishedKeyLabel(address: unknown): string | undefined;

package/dist/receipt/known-keys.js

@@ -0,0 +1,59 @@
+/** Signer addresses whose private keys are PUBLISHED — anyone can sign as them.
+ *
+ * A signature from one of these keys recovers and verifies like any other, so a verifier that
+ * stays silent about it hands a stranger a receipt that looks authored when anyone could have
+ * minted it. They are what worked examples and test suites sign with (ours included: the
+ * synthetic evidence bundle uses dev-mnemonic accounts #0 and #1), which is exactly why a
+ * real-looking artifact carrying one must be flagged rather than passed quietly.
+ *
+ * Twin of `sdk-py/tersign/known_keys.py`. Neither copy is transcribed from the other: each is
+ * DERIVED from the published secrets and pinned by its own suite — test/known-keys.test.ts
+ * re-derives every address here with viem, the Python suite re-derives its table with its own
+ * secp256k1 — and the same test compares the two tables entry by entry (address AND label)
+ * wherever the monorepo carries both. A key added to one side without the other fails there.
+ * Deliberately narrow: keys whose secret is published as a convention, not every key that has
+ * ever leaked. */
+/** BIP-39 mnemonic shipped as the default dev account set by Hardhat (20 accounts) and Anvil
+ * (10), derived at m/44'/60'/0'/0/i. */
+export const DEV_MNEMONIC = 'test test test test test test test test test test test junk';
+const DEV_MNEMONIC_ADDRESSES = [
+    '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+    '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+    '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc',
+    '0x90f79bf6eb2c4f870365e785982e1f101e93b906',
+    '0x15d34aaf54267db7d7c367839aaf71a00a2c6a65',
+    '0x9965507d1a55bcc2695c58ba16fb37d819b0a4dc',
+    '0x976ea74026e726554db657fa54763abd0c3a0aa9',
+    '0x14dc79964da2c08b23698b3d3cc7ca32193d9955',
+    '0x23618e81e3f5cdf7f54c3d65f7fbc0abf5b21e8f',
+    '0xa0ee7a142d267c1f36714e4a8f75612f20a79720',
+    '0xbcd4042de499d14e55001ccbb24a551f3b954096',
+    '0x71be63f3384f5fb98995898a86b02fb2426c5788',
+    '0xfabb0ac9d68b0b445fb7357272ff202c5651694a',
+    '0x1cbd3b2770909d4e10f157cabc84c7264073c9ec',
+    '0xdf3e18d64bc6a983f673ab319ccae4f1a57c7097',
+    '0xcd3b766ccdd6ae721141f452c550ca635964ce71',
+    '0x2546bcd3c84621e976d8185a91a922ae77ecec30',
+    '0xbda5747bfd65f08deb54cb465eb87d40e51b197e',
+    '0xdd2fd4581271e230360230f9337d5c0430bf44c0',
+    '0x8626f6940e2eb28930efb4cef49b2d1f2c9c1199',
+];
+/** Private keys 1, 2 and 3 — the other convention for "obviously a test key". Only these
+ * three: a receipt signed with private key 4 is NOT flagged. */
+const SMALL_SCALAR_ADDRESSES = [
+    '0x7e5f4552091a69125d5dfcb7b8c2659029395bdf',
+    '0x2b5ad5c4795c026514f8317c7a215e218dccd6cf',
+    '0x6813eb9362372eef6200f3b1dbc3f819671cba69',
+];
+/** lowercase address → the published secret it comes from. A Map, not an object literal: a
+ * lookup of 'constructor' or '__proto__' on a plain object answers with a prototype member. */
+export const PUBLISHED_TEST_KEYS = new Map([
+    ...DEV_MNEMONIC_ADDRESSES.map((a, i) => [a, `Hardhat/Anvil default dev mnemonic, account #${i}`]),
+    ...SMALL_SCALAR_ADDRESSES.map((a, i) => [a, `private key 0x${(i + 1).toString(16)} (a small scalar)`]),
+]);
+/** The published-secret label for `address`, or undefined when it is not a known test key. */
+export function publishedKeyLabel(address) {
+    if (typeof address !== 'string')
+        return undefined;
+    return PUBLISHED_TEST_KEYS.get(address.toLowerCase());
+}

package/dist/receipt/network.d.ts

@@ -0,0 +1,31 @@
+/** 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 declare const V1_EVM_NETWORK_CHAIN_IDS: Readonly<Record<string, number>>;
+export declare const V1_SOLANA_NETWORKS: Readonly<Record<string, string>>;
+/** 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 declare function toCaip2Network(network: string): string;