tersign 0.4.10 → 0.5.0

package/README.md

@@ -24,10 +24,19 @@ npx tersign verify 0xe5874f1ffe87f0a6dd9eb157730f67b86ee4538b125fe30fcc4e165213d
 ```
 
 ```text
-ledger: counter-signed OK (seller tersign-first, seq 1 …) VALID
+ledger:    https://tersign.ai
+           reports: found, counter-signed chain intact (seller tersign-first, seq 1, …) — not checked locally
+VALID (ledger-reported) — https://tersign.ai reports the record and its counter-signed chain; nothing was verified locally
 ```
 
-`npx tersign verify <receipt.json | 0xdigest> [--ledger url]` recovers the EIP-712 signature **locally**. A bare digest is then checked against the Tersign ledger unless `--ledger` names another; a receipt file verifies offline and touches no chain at all. The ledger consulted is always printed. Prefer raw HTTP? The same proof, no CLI:
+`npx tersign verify <receipt.json | 0xdigest> [--signer 0xaddr] [--ledger url]` takes a receipt file or a digest.
+
+- A **receipt file** is checked locally and touches no network unless you add `--ledger`. The EIP-712 signature is recovered, and `--signer` compares it with the issuer's address, which you take from the issuer through a channel you trust, never from the receipt. Without `--signer` the signer is reported `UNAUTHENTICATED` and the verdict reads `VALID (signer UNAUTHENTICATED)`: recovery yields an address for any payload, so an edited receipt reaches that same line with a different address.
+- A receipt signed with a **published test key** (the 20 Hardhat/Anvil default dev-mnemonic accounts, or private key 1, 2 or 3) is flagged `published test key` either way: anyone can produce that signature. Fields in the file that the signature does not cover are listed by name, and a signed field in another JSON type (`"version": "1"`) is refused. The signature must be the one canonical encoding (`0x` + 130 lower-case hex digits, v 27/28, low-s): a re-encoding of a genuine signature (v 0/1, upper-case hex, the high-s twin) also recovers the issuer, under a different digest, so it is refused.
+- The file is a receipt, `{receipt, record}`, or an evidence-bundle record file (`records/NNNNNN.json`, verdict qualified `record artifact only`: its chain fields are not checked here). Anything else that nests a receipt — a second receipt at the top level, or any other field beside it — is refused, because a reader would take those fields for the receipt that was checked. Duplicate keys and non-integer numbers are refused too.
+- A **digest** is looked up on the Tersign ledger unless `--ledger` names another; the answer is that ledger's own counter-signed chain check, nothing in it is re-verified locally, and the verdict says so (`VALID (ledger-reported)`). The ledger consulted is always printed. The local check is the receipt file with `--signer`.
+
+Exit status: `0` valid (read the last line — for a file, a bare `VALID` means a bound, non-test-key signer on a receipt or `{receipt, record}`; a digest is always `VALID (ledger-reported)`), `1` invalid, `2` usage (an unknown or valueless flag, `--signer` with a digest, a missing or non-JSON file). Prefer raw HTTP? The same proof, no CLI:
 
 ```sh
 curl https://tersign.ai/v1/receipts/0xe5874f1ffe87f0a6dd9eb157730f67b86ee4538b125fe30fcc4e165213dd3fc4/verify
@@ -41,7 +50,7 @@ Counter-signed evidence that your agent presented a disclosure — one command,
 npx tersign disclose "You are chatting with an AI assistant." --medium chat --agent-id my-agent
 ```
 
-The text is digested **locally** (only the digest travels — data-minimization by construction). Your key signs the record; the ledger counter-signs it into a per-signer hash chain whose head is submitted for Bitcoin anchoring on a six-hourly cron. First call self-provisions a free signer-keyed account bound set-once to your key (key resolution: `TERSIGN_SELLER_KEY` env → macOS keychain `tersign-signer` → `~/.tersign/signer.key`, created on first use). Free tier is quota- and rate-limited — [limits](https://tersign.ai/pricing). What this is: independently verifiable evidence the disclosure was attested at that time. What it is not: a compliance certification.
+The text is digested **locally** (only the digest travels — data-minimization by construction). Your key signs the record; the ledger counter-signs it into a per-signer hash chain whose head is submitted for Bitcoin anchoring on a six-hourly cron. The first call self-provisions a free signer-keyed account bound set-once to your key, unless that key is already registered to an API-key ledger account (409: submit through that account) or the day's provisioning caps are reached (429). Key resolution: `TERSIGN_SELLER_KEY` env → macOS keychain `tersign-signer` → `~/.tersign/signer.key`, created on first use. Free tier is quota- and rate-limited — [limits](https://tersign.ai/pricing). What this is: independently verifiable evidence the disclosure was attested at that time. What it is not: a compliance certification.
 
 ## Chain of Custody
 
@@ -112,25 +121,27 @@ when that stabilizes. It makes no conformance claim to that draft.
   "mcpServers": {
     "tersign": {
       "command": "npx",
-      "args": ["tersign"],
-      "env": { "TERSIGN_SELLER_KEY": "0x<your-seller-key>" }
+      "args": ["tersign"]
     }
   }
 }
 ```
 
+No configuration is needed. With `TERSIGN_SELLER_KEY` unset or empty, the server signs with the key in the macOS keychain (`tersign-signer`) or `~/.tersign/signer.key`, and generates one there on first run; the key never leaves your machine. Set `TERSIGN_SELLER_KEY` only to bring your own.
+
 **Tools** — `issue_receipt` · `verify_receipt` · `verify_compliance_record` · `record_disclosure` · `record_refund` · `open_dispute` · `submit_dispute_evidence` · `adjudicate_dispute` · `get_dispute`
 
 | Env var | Required | Purpose |
 |---|---|---|
-| `TERSIGN_SELLER_KEY` | yes | 0x-prefixed private key that signs your receipts and records |
-| `TERSIGN_LEDGER_URL` | no | hosted ledger for counter-signing + chain checks |
-| `TERSIGN_LEDGER_API_KEY` | no | your seller API key on that ledger |
-| `TERSIGN_LEDGER_SELLER_ID` | no | your seller id on that ledger |
+| `TERSIGN_SELLER_KEY` | no | your own 0x-prefixed signing key; unset or empty, the keychain or keyfile key is used (generated on first run). If your ledger account has a registered signing key, set that key here: the ledger rejects respondent dispute evidence signed by any other key |
+| `TERSIGN_LEDGER_URL` | no | ledger for counter-signing + chain checks; needed by the dispute tools; `record_disclosure` defaults to `https://tersign.ai` |
+| `TERSIGN_LEDGER_API_KEY` | no | your seller API key on that ledger; with the seller id, enables `record_refund` and chained `issue_receipt`; also authenticates respondent dispute evidence |
+| `TERSIGN_LEDGER_SELLER_ID` | no | your seller id on that ledger; with the API key, enables `record_refund` and chained `issue_receipt` |
 | `TERSIGN_ISSUER_NAME` | no | issuer name stamped on action records |
 | `TERSIGN_ISSUER_JURISDICTION` | no | issuer jurisdiction stamped on action records |
+| `TERSIGN_ISSUER_TAX_ID` | no | issuer tax / business-registration id stamped on action records |
 
-Cold to counter-signed in one session: call `issue_receipt`, then check the issued receipt's digest with `npx tersign verify <digest> --ledger <url>`.
+Cold to counter-signed in one session, with no configuration: call `record_disclosure`, then check the `digest` it returns with `npx tersign verify <digest>` (a bare digest checks against https://tersign.ai). `issue_receipt` counter-signs as well once `TERSIGN_LEDGER_URL`, `TERSIGN_LEDGER_API_KEY` and `TERSIGN_LEDGER_SELLER_ID` are set; without them it returns a locally signed, unchained receipt.
 
 The agent skill `tersign-evidence` ships at [tersignhq/skills](https://github.com/tersignhq/skills).
 
@@ -148,7 +159,7 @@ Full URLs, readable without auth. If you are an agent, start here.
 | Surface | Address |
 |---|---|
 | npm package | `tersign` — https://www.npmjs.com/package/tersign |
-| MCP registry | `io.github.tersignhq/evidence` — `npx tersign` needs no configuration; the first call self-provisions a signer-keyed account |
+| MCP registry | `io.github.tersignhq/evidence` — `npx tersign` needs no configuration; `record_disclosure`'s first call self-provisions a signer-keyed account, unless the key is registered to an API-key account (409) or the daily provisioning caps are reached (429) |
 | ARD catalog (Agentic Resource Discovery) | https://tersign.ai/.well-known/ai-catalog.json |
 | Verify API | `GET https://tersign.ai/v1/receipts/{digest}/verify` |
 | Envelope API | `GET https://tersign.ai/v1/receipts/{digest}/envelope?venue={internet-court\|kleros\|uma\|generic}` |
@@ -156,7 +167,7 @@ Full URLs, readable without auth. If you are an agent, start here.
 | Ledger signer | `GET https://tersign.ai/v1/ledger` |
 | Bundle verifier, out-of-band | https://tersign.ai/verify/v1/ — `verify_bundle.py` · `keccak.py` · `secp256k1.py` · `SHA256SUMS`. A bundle ships its own checker; for evidence from an interested party fetch this copy and diff the two. |
 | llms.txt | https://raw.githubusercontent.com/tersignhq/tersign-js/main/llms.txt |
-| Conformance vectors (RFC 8785 + keccak256) | https://github.com/tersignhq/tersign-js/blob/main/test/fixtures/canonical-vectors.json |
+| Conformance vectors (RFC 8785 + keccak256, two-sided) | https://github.com/tersignhq/evidence-record-conformance |
 | Sample action record + digests | https://github.com/tersignhq/tersign-js/blob/main/test/fixtures/compliance-record.json |
 | Genesis verify | `npx tersign verify 0xe5874f1ffe87f0a6dd9eb157730f67b86ee4538b125fe30fcc4e165213dd3fc4` |
 
@@ -189,7 +200,7 @@ If a maintainer ever asks you to reopen work elsewhere because of this, that is
   <img src="https://raw.githubusercontent.com/tersignhq/.github/main/assets/seal.svg" alt="Tersign seal" width="72">
 </p>
 
-<p align="center"><sub>MIT · built and published from <a href="https://github.com/tersignhq/tersign-js">tersignhq/tersign-js</a> via trusted-publishing CI, provenance attested · <code>tersign</code> reserved on PyPI</sub></p>
+<p align="center"><sub>MIT · built and published from <a href="https://github.com/tersignhq/tersign-js">tersignhq/tersign-js</a> via trusted-publishing CI, provenance attested · Python verifier: <code>pip install tersign</code></sub></p>
 
 <p align="center"><sub><b>Venues rotate. The transcript endures.</b></sub></p>
 

package/dist/canonical.d.ts

@@ -8,6 +8,33 @@ import { type Hex } from 'viem';
  * sort-then-stringify round-trip (JCS orders them "1","10","2"). Byte-identical to the old
  * serializer for every shape without integer-like or control-char keys — the genesis receipt
  * digest and all pinned wire vectors are unchanged. */
+/** Nesting budget for untrusted inputs, byte-for-byte the ledger's MAX_CANONICAL_DEPTH and
+ * canonical.py's MAX_DEPTH. The SDK copy shipped without one: a 65-deep value digested here
+ * and was refused by every Python verifier, so the SDK could sign a record no independent
+ * checker could ever verify. */
+export declare const MAX_CANONICAL_DEPTH = 64;
+export declare class CanonicalDepthError extends Error {
+    constructor();
+}
+/** The digest domain is ints/strings/bools/null/objects/arrays — canonical.py has said so
+ * since it was written; this side simply never enforced it, and `JSON.stringify` is not a
+ * specification. Two consequences, both confirmed against the running code:
+ *
+ *   digestOf({amount: 9007199254740993}) === digestOf({amount: 9007199254740992})
+ *   digestOf({n: 1e400})                 === digestOf({n: null})
+ *
+ * Distinct records, identical bytes, identical digest, identical signature. For a system whose
+ * whole claim is "this digest commits to this record", a non-injective canonical form is the
+ * deepest defect available, and it is reachable: 2^53-1 is about 9.007e15, below any
+ * 18-decimal token amount over 0.009 ETH and below any nanosecond timestamp.
+ *
+ * Floats are rejected for the reason canonical.py already states — the domain boundary is the
+ * number TOKEN, and a float that survives a parse round-trip is precisely the divergence class
+ * the conformance suite exists to kill. Number.isSafeInteger settles all four cases at once:
+ * non-integer, |n| >= 2^53, NaN and Infinity. */
+export declare class CanonicalDomainError extends Error {
+    constructor(value: number);
+}
 export declare function canonicalStringify(value: unknown): string;
 export declare function digestOf(value: unknown): `0x${string}`;
 /** Hash-chain link, byte-identical to the hosted ledger's recompute: the ledger

package/dist/canonical.js

@@ -8,26 +8,67 @@ import { concatHex, keccak256, numberToHex, stringToHex, toBytes } from 'viem';
  * sort-then-stringify round-trip (JCS orders them "1","10","2"). Byte-identical to the old
  * serializer for every shape without integer-like or control-char keys — the genesis receipt
  * digest and all pinned wire vectors are unchanged. */
+/** Nesting budget for untrusted inputs, byte-for-byte the ledger's MAX_CANONICAL_DEPTH and
+ * canonical.py's MAX_DEPTH. The SDK copy shipped without one: a 65-deep value digested here
+ * and was refused by every Python verifier, so the SDK could sign a record no independent
+ * checker could ever verify. */
+export const MAX_CANONICAL_DEPTH = 64;
+export class CanonicalDepthError extends Error {
+    constructor() {
+        super(`value nests deeper than ${MAX_CANONICAL_DEPTH} levels`);
+    }
+}
+/** The digest domain is ints/strings/bools/null/objects/arrays — canonical.py has said so
+ * since it was written; this side simply never enforced it, and `JSON.stringify` is not a
+ * specification. Two consequences, both confirmed against the running code:
+ *
+ *   digestOf({amount: 9007199254740993}) === digestOf({amount: 9007199254740992})
+ *   digestOf({n: 1e400})                 === digestOf({n: null})
+ *
+ * Distinct records, identical bytes, identical digest, identical signature. For a system whose
+ * whole claim is "this digest commits to this record", a non-injective canonical form is the
+ * deepest defect available, and it is reachable: 2^53-1 is about 9.007e15, below any
+ * 18-decimal token amount over 0.009 ETH and below any nanosecond timestamp.
+ *
+ * Floats are rejected for the reason canonical.py already states — the domain boundary is the
+ * number TOKEN, and a float that survives a parse round-trip is precisely the divergence class
+ * the conformance suite exists to kill. Number.isSafeInteger settles all four cases at once:
+ * non-integer, |n| >= 2^53, NaN and Infinity. */
+export class CanonicalDomainError extends Error {
+    constructor(value) {
+        super(`${Number.isFinite(value) ? value : String(value)} is outside the Tersign digest domain ` +
+            '(integers within +/-(2^53-1) only: no floats, NaN or Infinity)');
+    }
+}
 export function canonicalStringify(value) {
-    return serialize(value);
+    return serialize(value, 0);
 }
-function serialize(value) {
+function serialize(value, depth) {
+    if (depth > MAX_CANONICAL_DEPTH)
+        throw new CanonicalDepthError();
     if (value === null)
         return 'null';
     if (Array.isArray(value)) {
-        return '[' + Array.from(value, (v) => serialize(v) ?? 'null').join(',') + ']';
+        return '[' + Array.from(value, (v) => serialize(v, depth + 1) ?? 'null').join(',') + ']';
     }
     if (typeof value === 'object') {
         const obj = value;
         const parts = [];
         for (const key of Object.keys(obj).sort()) {
-            const s = serialize(obj[key]);
+            const s = serialize(obj[key], depth + 1);
             if (s !== undefined)
                 parts.push(JSON.stringify(key) + ':' + s);
         }
         return '{' + parts.join(',') + '}';
     }
-    // string/number/boolean serialize per JCS; undefined/function/symbol yield undefined (dropped)
+    // Numbers carry the domain guard: JSON.stringify would silently round 2^53+1 down and fold
+    // Infinity to null, and both of those are collisions, not encodings.
+    if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value))
+            throw new CanonicalDomainError(value);
+        return String(value);
+    }
+    // string/boolean serialize per JCS; undefined/function/symbol yield undefined (dropped)
     return JSON.stringify(value);
 }
 export function digestOf(value) {

package/dist/cli.js

@@ -16,8 +16,10 @@ if (sub === undefined || sub === 'mcp') {
         console.error('tersign: this starts the MCP server, which speaks JSON-RPC over stdin — nothing to see\n' +
             'at a prompt. Wire it into your MCP client config:\n\n' +
             '  { "mcpServers": { "tersign": { "command": "npx", "args": ["tersign"] } } }\n\n' +
-            'No key needed: the first call self-provisions a signer-keyed account (OS keychain,\n' +
-            'else ~/.tersign/signer.key). Set TERSIGN_SELLER_KEY to use your own.\n\n' +
+            'No key needed: a key is generated and kept in the OS keychain (else ~/.tersign/signer.key),\n' +
+            "and record_disclosure's first call self-provisions a signer-keyed account on the ledger,\n" +
+            'unless that key is registered to an API-key account (409) or the daily provisioning caps\n' +
+            'are reached (429). Set TERSIGN_SELLER_KEY to use your own key.\n\n' +
             "Just exploring? Try:  tersign help   ·   tersign verify <receipt.json | 0xdigest> [--ledger url]");
         process.exit(1);
     }
@@ -40,7 +42,9 @@ else if (sub === 'help' || sub === '--help' || sub === '-h') {
         '  tersign                 start the MCP server (stdio)\n' +
         '  tersign mcp             same, explicit\n' +
         '  tersign verify <receipt.json | 0xdigest> [--signer 0xaddr] [--ledger url]\n' +
-        '                          verify a receipt: local signature recovery + public chain check\n' +
+        '                          verify a receipt FILE locally: --signer binds it to the\n' +
+        "                          issuer's address (without it the signer is reported\n" +
+        '                          UNAUTHENTICATED); or ask a ledger about a DIGEST\n' +
         '  tersign disclose "<text>" [--medium chat] [--agent-id id] [--url resourceUrl]\n' +
         '                          counter-signed disclosure evidence — text digested locally,\n' +
         '                          only the digest travels; key created on first use\n' +

package/dist/compliance/record.d.ts

@@ -1,5 +1,6 @@
 import type { Account } from 'viem/accounts';
 import type { Adjustment, ComplianceRecordV1, SignedComplianceRecord, SignedReceipt, VerifyLike } from './types.js';
+import { type SignerBinding } from '../receipt/binding.js';
 /** Canonical domain per the compliance-fields extension spec (x402-foundation/x402#2853).
  * Migrated from the vendor domain 'tersign compliance-record' on 2026-07-14 while ZERO
  * production compliance records existed — a free change then, a breaking wire change after. */
@@ -49,4 +50,9 @@ export interface MinimalRecordInput {
 export declare function buildMinimalRecord(issuer: IssuerConfig, input: MinimalRecordInput): ComplianceRecordV1;
 export declare function recordDigest(record: ComplianceRecordV1): `0x${string}`;
 export declare function signComplianceRecord(record: ComplianceRecordV1, account: Account): Promise<SignedComplianceRecord>;
-export declare function verifyComplianceRecord(signed: SignedComplianceRecord, expectedSigner?: string): Promise<VerifyLike>;
+/** VerifyLike plus the signer binding: signerBound is true only when expectedSigner was supplied
+ * and matched; testKey flags a published test key. Without a bound signer a PASS proves the
+ * record and attestation are internally consistent and nothing else — anyone can edit a record,
+ * recompute its digest and re-sign the attestation with their own key. */
+export type RecordVerifyResult = VerifyLike & SignerBinding;
+export declare function verifyComplianceRecord(signed: SignedComplianceRecord, expectedSigner?: string): Promise<RecordVerifyResult>;

package/dist/compliance/record.js

@@ -1,5 +1,6 @@
 import { recoverTypedDataAddress } from 'viem';
 import { digestOf } from '../canonical.js';
+import { bindSigner, isPlainObject, parseExpectedSigner, signatureError } from '../receipt/binding.js';
 /** Canonical domain per the compliance-fields extension spec (x402-foundation/x402#2853).
  * Migrated from the vendor domain 'tersign compliance-record' on 2026-07-14 while ZERO
  * production compliance records existed — a free change then, a breaking wire change after. */
@@ -71,17 +72,37 @@ export async function signComplianceRecord(record, account) {
     return { record, attestation: { format: 'eip712', payload, signature } };
 }
 export async function verifyComplianceRecord(signed, expectedSigner) {
+    const expected = parseExpectedSigner(expectedSigner);
+    if (!expected.ok)
+        return { valid: false, signerBound: false, reason: expected.reason };
+    if (!isPlainObject(signed) ||
+        !isPlainObject(signed.record) ||
+        !isPlainObject(signed.attestation) ||
+        !isPlainObject(signed.attestation.payload)) {
+        return { valid: false, signerBound: false, reason: 'not a signed action record: expected {record, attestation{format, payload, signature}}' };
+    }
     const { attestation, record } = signed;
     if (attestation.format !== 'eip712')
-        return { valid: false, reason: 'jws not implemented in v0' };
-    if (attestation.payload.recordDigest !== recordDigest(record)) {
-        return { valid: false, reason: 'record digest mismatch — record was altered after signing' };
+        return { valid: false, signerBound: false, reason: 'jws not implemented in v0' };
+    let digest;
+    try {
+        digest = recordDigest(record);
+    }
+    catch (e) {
+        return { valid: false, signerBound: false, reason: `cannot compute the record digest: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (attestation.payload.recordDigest !== digest) {
+        return { valid: false, signerBound: false, reason: 'record digest mismatch — record was altered after signing' };
     }
     if (attestation.payload.receiptDigest !== record.receiptDigest) {
-        return { valid: false, reason: 'attestation/receipt digest mismatch' };
+        return { valid: false, signerBound: false, reason: 'attestation/receipt digest mismatch' };
     }
+    const badSig = signatureError(attestation.signature);
+    if (badSig)
+        return { valid: false, signerBound: false, reason: `attestation ${badSig}` };
+    let signer;
     try {
-        const signer = await recoverTypedDataAddress({
+        signer = await recoverTypedDataAddress({
             domain: COMPLIANCE_DOMAIN,
             types: COMPLIANCE_TYPES,
             primaryType: 'ComplianceAttestation',
@@ -93,12 +114,9 @@ export async function verifyComplianceRecord(signed, expectedSigner) {
             },
             signature: attestation.signature,
         });
-        if (expectedSigner && signer.toLowerCase() !== expectedSigner.toLowerCase()) {
-            return { valid: false, signer, reason: 'unexpected signer' };
-        }
-        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' };
     }
+    return bindSigner(signer, expected.value, 'unexpected signer');
 }

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export * from './types.js';
 export { canonicalStringify, digestOf, GENESIS_DIGEST, chainLinkDigest, CHAIN_COMMITMENT_SCHEMA, ACC_GENESIS, chainAccumulatorStep, chainCommitment, commitmentDigest, foldAccumulator, verifyCommitment, ChainIntegrityError, type ChainCommitment, type ChainRecordLike, type CommitmentVerifyResult, } from './canonical.js';
-export { RECEIPT_DOMAIN, RECEIPT_TYPES, OFFER_DOMAIN, OFFER_TYPES, signReceipt, signOffer, verifyReceipt, type VerifyResult, } from './receipt/eip712.js';
-export { COMPLIANCE_DOMAIN, COMPLIANCE_TYPES, COMPLIANCE_WIRE_VECTOR, buildMinimalRecord, recordDigest, signComplianceRecord, verifyComplianceRecord, type IssuerConfig, type MinimalRecordInput, } from './compliance/record.js';
+export { RECEIPT_DOMAIN, RECEIPT_TYPES, OFFER_DOMAIN, OFFER_TYPES, signReceipt, signOffer, verifyReceipt, SIGNED_RECEIPT_FIELDS, type VerifyResult, } from './receipt/eip712.js';
+export { PUBLISHED_TEST_KEYS, publishedKeyLabel } from './receipt/known-keys.js';
+export { signerStatus, type SignerBinding, type SignerStatus } from './receipt/binding.js';
+export { COMPLIANCE_DOMAIN, COMPLIANCE_TYPES, COMPLIANCE_WIRE_VECTOR, buildMinimalRecord, recordDigest, signComplianceRecord, verifyComplianceRecord, type RecordVerifyResult, type IssuerConfig, type MinimalRecordInput, } from './compliance/record.js';
 export { MemoryIdempotencyStore, checkIdempotency, extractPaymentId, fingerprint, REPLAY_HEADER, type IdempotencyStore, type IdempotencyOutcome, type IdempotencyOptions, type CachedResponse, type FingerprintParts, } from './idempotency/middleware.js';
 export { D1IdempotencyStore, D1_IDEMPOTENCY_DDL, type D1Like } from './idempotency/d1.js';
 export type { DisputeReason, DisputeVerdict, DisputeStatus, DisputePayloadV1, CriterionV1, AcceptanceCriteriaV1, EvidenceArtifactRef, EvidencePayloadV1, DisputeAttestationPayload, EvidenceAttestationPayload, CriteriaAttestationPayload, SignedDispute, SignedEvidence, SignedCriteria, } from './dispute/types.js';

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './types.js';
 export { canonicalStringify, digestOf, GENESIS_DIGEST, chainLinkDigest, CHAIN_COMMITMENT_SCHEMA, ACC_GENESIS, chainAccumulatorStep, chainCommitment, commitmentDigest, foldAccumulator, verifyCommitment, ChainIntegrityError, } from './canonical.js';
-export { RECEIPT_DOMAIN, RECEIPT_TYPES, OFFER_DOMAIN, OFFER_TYPES, signReceipt, signOffer, verifyReceipt, } from './receipt/eip712.js';
+export { RECEIPT_DOMAIN, RECEIPT_TYPES, OFFER_DOMAIN, OFFER_TYPES, signReceipt, signOffer, verifyReceipt, SIGNED_RECEIPT_FIELDS, } from './receipt/eip712.js';
+export { PUBLISHED_TEST_KEYS, publishedKeyLabel } from './receipt/known-keys.js';
+export { signerStatus } from './receipt/binding.js';
 export { COMPLIANCE_DOMAIN, COMPLIANCE_TYPES, COMPLIANCE_WIRE_VECTOR, buildMinimalRecord, recordDigest, signComplianceRecord, verifyComplianceRecord, } from './compliance/record.js';
 export { MemoryIdempotencyStore, checkIdempotency, extractPaymentId, fingerprint, REPLAY_HEADER, } from './idempotency/middleware.js';
 export { D1IdempotencyStore, D1_IDEMPOTENCY_DDL } from './idempotency/d1.js';

package/dist/keystore.js

@@ -25,6 +25,19 @@ function readKeychain() {
 function writeKeychain(key) {
     if (process.platform !== 'darwin')
         return false;
+    // Preflight, added 2026-08-30. `security add-generic-password` does not merely FAIL when no
+    // login keychain is reachable — it raises a MODAL macOS dialog ("A keychain cannot be found
+    // to store …"), which blocks a headless run and ambushes anyone whose first command is
+    // `npx tersign`. Seen for real while probing first-run behaviour with a sandboxed HOME; the
+    // same shape hits a Mac CI runner, an ssh session with a locked keychain, and any sandbox.
+    // `security default-keychain` answers the question silently, so ask it before writing and
+    // fall through to the 0600 keyfile when the answer is no.
+    try {
+        execFileSync('security', ['default-keychain'], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch {
+        return false;
+    }
     try {
         execFileSync('security', ['add-generic-password', '-s', KEYCHAIN_SERVICE, '-a', userInfo().username, '-w', key, '-U'], { stdio: ['ignore', 'ignore', 'ignore'] });
         return true;

package/dist/mcp/server.d.ts

@@ -8,6 +8,6 @@ export declare function envDeps(env?: Record<string, string | undefined>): McpDe
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
 export declare const MCP_SERVER_IDENTITY: {
     readonly name: "tersign";
-    readonly version: "0.4.10";
+    readonly version: "0.5.0";
 };
 export declare function buildServer(deps: McpDeps): McpServer;

package/dist/mcp/server.js

@@ -14,7 +14,11 @@ export function envDeps(env = process.env) {
     // that first call self-provisions a signer-keyed account; before this the MCP entry point threw
     // instead, so `npx tersign` died on first run for anyone who had not already exported a key —
     // and no directory or sandbox could introspect the server at all.
-    const key = env.TERSIGN_SELLER_KEY ?? resolveSignerKey({ create: true }).key;
+    // `||`, not `??`: an EMPTY TERSIGN_SELLER_KEY means unset, exactly as the keystore reads it.
+    // The listing marks the key optional, and a client that fills a blank optional secret with ""
+    // (which clients do is unmeasured) got a crash: `??` handed "" to privateKeyToAccount
+    // (fixed 2026-09-27). test/listing.test.ts starts the registry command with the key set to "".
+    const key = env.TERSIGN_SELLER_KEY || resolveSignerKey({ create: true }).key;
     const account = privateKeyToAccount(key);
     const assure = new Assure({
         signer: account,
@@ -49,14 +53,14 @@ function json(value) {
 }
 /** MUST match package.json name/version — the MCP handshake self-reports this identity to
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
-export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.4.10' };
+export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.5.0' };
 export function buildServer(deps) {
     const server = new McpServer(MCP_SERVER_IDENTITY);
     server.registerTool('issue_receipt', {
         title: 'Issue signed receipt',
-        description: 'Issue an x402 offer-receipt (EIP-712) plus a Tersign action record for a payment that has ALREADY settled, and counter-sign both into your hash chain when a ledger is configured. ' +
+        description: 'Issue an x402 offer-receipt (EIP-712) plus a Tersign compliance record (returned as `compliance`; verify_compliance_record checks it) for a payment that has ALREADY settled, and counter-sign both into your hash chain when a ledger is configured. ' +
             'Use this for money that moved; use record_disclosure for a non-payment agent action. ' +
-            'Side effects: signs with TERSIGN_SELLER_KEY, and performs ONE network write to the ledger when TERSIGN_LEDGER_URL/_API_KEY/_SELLER_ID are set (without them it signs locally and returns an unchained artifact). ' +
+            'Side effects: signs with your signing key (TERSIGN_SELLER_KEY when set, else the one generated and kept locally on first run), and performs ONE network write to the ledger when TERSIGN_LEDGER_URL/_API_KEY/_SELLER_ID are set (without them it signs locally and returns an unchained artifact). ' +
             'Returns the signed receipt artifact, its keccak256 canonical digest, and — when chained — the ledger counter-signature and sequence number.',
         inputSchema: {
             network: z.string().describe('settlement network as CAIP-2, e.g. "eip155:8453" for Base mainnet'),
@@ -78,10 +82,11 @@ export function buildServer(deps) {
     }, async (args) => json(await issueReceiptTool(deps, args)));
     server.registerTool('verify_receipt', {
         title: 'Verify signed receipt',
-        description: 'Verify an offer-receipt artifact: recover the EIP-712 signature and confirm the payload digest binds to it. ' +
-            'Fully OFFLINE — no network, no API key, no account; verifying someone else\'s receipt is the intended use. ' +
-            'Use this for a receipt (money); use verify_compliance_record for an action record (a non-payment action). ' +
-            'Returns { valid, signer, digest } and, when expectedSigner is supplied and does not match, valid:false with the recovered signer so you can see who actually signed.',
+        description: 'Verify an x402 offer-receipt artifact, fully OFFLINE (no network, no API key, no account; checks no ledger or chain): recover the address whose key produced its EIP-712 signature over the six signed payload fields (version, network, resourceUrl, payer, issuedAt, transaction), and compute its canonical digest (the content address a ledger records it under). ' +
+            'Recovery yields SOME address for any payload, so without expectedSigner the signer is UNAUTHENTICATED: valid:true then proves neither who signed nor that the receipt is unmodified — an edited receipt recovers a different address and still returns valid:true. ' +
+            'Pass expectedSigner, the issuer\'s address obtained out-of-band, to bind it: valid:true then means the signed fields were signed by that key; a mismatch returns valid:false with the recovered signer so you can see who actually signed. ' +
+            'Use this for a receipt (money); use verify_compliance_record for the compliance record issue_receipt returns beside a receipt. ' +
+            'Returns { verdict, valid, signer, signerStatus: BOUND | UNAUTHENTICATED | MISMATCH, signerBound, testKey? (the signer is a PUBLISHED test key — anyone can sign as it), digest, unsignedFields? (present in the artifact but not covered by the signature), reason? }. Read verdict first.',
         inputSchema: {
             artifact: z
                 .record(z.unknown())
@@ -89,12 +94,12 @@ export function buildServer(deps) {
             expectedSigner: z
                 .string()
                 .optional()
-                .describe('0x address the receipt MUST be signed by — obtain it out-of-band, never from the artifact. Omit to recover the signer without enforcing it'),
+                .describe('0x address the receipt MUST be signed by — obtain it out-of-band, never from the artifact. Omit to recover the signer without binding it (it is then reported UNAUTHENTICATED)'),
         },
     }, async ({ artifact, expectedSigner }) => json(await verifyReceiptTool(artifact, expectedSigner)));
     server.registerTool('record_disclosure', {
         title: 'Record counter-signed disclosure',
-        description: 'One-call disclosure evidence (EU AI Act Art 50 dialect): digests the disclosure text LOCALLY, signs an action record with your key, and the public ledger counter-signs it into your per-signer hash chain. No API key needed — first call self-provisions a free signer-keyed account.',
+        description: 'One-call disclosure evidence (EU AI Act Art 50 dialect): digests the disclosure text LOCALLY, signs an action record with your key, and the public ledger counter-signs it into your per-signer hash chain. No API key needed — the first call self-provisions a free signer-keyed account, except when your key is already registered to an API-key account (409) or the daily provisioning caps are reached (429; https://tersign.ai/pricing).',
         inputSchema: {
             text: z.string().optional().describe('the disclosure text as presented — digested locally, never transmitted'),
             textDigest: z.string().regex(/^0x[0-9a-fA-F]{64}$/).optional().describe('pre-computed digest (wins over text)'),
@@ -109,22 +114,21 @@ export function buildServer(deps) {
     }, async (args) => json(await recordDisclosureTool(deps, args)));
     server.registerTool('verify_compliance_record', {
         title: 'Verify compliance record',
-        description: 'Verify a Tersign action record against its attestation: recompute the record\'s canonical digest, confirm the attestation commits to that exact digest, and recover the signature. ' +
-            'Fully OFFLINE — no network, no API key, no account. ' +
-            'Use this for an action record (a disclosure or other non-payment agent action); use verify_receipt for a payment receipt. ' +
-            'PASS proves integrity and internal consistency only. Authorship needs an out-of-band signer address: pass expectedSigner, or the identity is whatever the artifact claims about itself. ' +
-            'Returns { valid, signer, digest }; on mismatch, valid:false plus the recovered signer and the recomputed digest.',
+        description: 'Verify ONE record type: the compliance record that issue_receipt returns beside a receipt (`compliance`: a ComplianceRecordV1 `record` plus its ComplianceAttestation `attestation`, EIP-712 domain "compliance-fields"), fully OFFLINE (no network, no API key, no account): recompute the record\'s canonical digest, check that the attestation\'s signed payload names that exact digest and the same receiptDigest as the record, and recover the address that signed the attestation. ' +
+            'It does NOT verify the disclosure record record_disclosure returns: that is a different record type (an action record, EIP-712 domain "tersign action-record"), and passed here it fails with a digest mismatch that says nothing about tampering. Use verify_receipt for the payment receipt itself. ' +
+            'Without expectedSigner the signer is UNAUTHENTICATED and valid:true proves internal consistency only — anyone can edit a record, recompute its digest and re-sign the attestation with their own key, and still get valid:true with a different signer. Pass expectedSigner, obtained out-of-band, to bind authorship. ' +
+            'Returns { verdict, valid, signer, signerStatus: BOUND | UNAUTHENTICATED | MISMATCH, signerBound, testKey? (a PUBLISHED test key — anyone can sign as it), digest (the recomputed record digest), reason? }. Read verdict first.',
         inputSchema: {
             record: z
                 .record(z.unknown())
-                .describe('the action record object as issued (ComplianceRecordV1 shape). Pass the object, not a JSON string; any field edit changes the digest and fails verification — which is the point'),
+                .describe('the compliance record exactly as issue_receipt returned it (`compliance.record`, ComplianceRecordV1 shape). Pass the object, not a JSON string; any field edit changes the digest and fails verification — which is the point'),
             attestation: z
                 .record(z.unknown())
-                .describe('the attestation that accompanies the record: the signature over the record digest, as returned alongside it at issuance'),
+                .describe('the attestation returned with it (`compliance.attestation`): the seller\'s EIP-712 signature over the record digest'),
             expectedSigner: z
                 .string()
                 .optional()
-                .describe('0x address the record MUST be signed by, obtained out-of-band (for the public ledger: https://tersign.ai/v1/ledger). Omit to recover the signer without enforcing it'),
+                .describe('0x address the record MUST be signed by: the SELLER\'s signing address (the key that signed the receipt and this record), obtained out-of-band — not the ledger\'s counter-signing key, which never signs compliance records. Omit to recover the signer without binding it (it is then reported UNAUTHENTICATED)'),
         },
     }, async ({ record, attestation, expectedSigner }) => json(await verifyRecordTool(record, attestation, expectedSigner)));
     server.registerTool('record_refund', {

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,8 +32,24 @@ 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;
 }>;

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)