tersign 0.4.11 → 0.6.0

package/dist/assure.js

@@ -1,10 +1,13 @@
 import { signReceipt } from './receipt/eip712.js';
+import { toCaip2Network } from './receipt/network.js';
 import { buildMinimalRecord, signComplianceRecord } from './compliance/record.js';
 import { LedgerClient } from './ledgerClient.js';
-/** The core primitive: after a settled x402 payment, issue the signed base receipt
- * (merged offer-receipt extension, EIP-712) plus the Tersign compliance record bound to it,
- * and counter-sign into the hosted ledger when configured. Attach the result to the
- * SettlementResponse via `attachToExtensions`. */
+/** The core primitive: after a settled x402 payment, issue the seller-signed receipt
+ * (offer-receipt extension, EIP-712) and the Tersign compliance record. With a ledger configured,
+ * the ledger counter-signs the receipt into the seller's hash chain; the compliance-fields record is not
+ * counter-signed, and is bound to its receipt only by the seller's own signature, which covers the
+ * receipt's digest. Merge the result into the x402 SettlementResponse (the `PAYMENT-RESPONSE`
+ * header) with `attachToSettlementResponse`; `withAssure` does this for you. */
 export class Assure {
     cfg;
     ledger;
@@ -16,7 +19,7 @@ export class Assure {
     async issueFor(ctx) {
         const payload = {
             version: 1,
-            network: ctx.network,
+            network: toCaip2Network(ctx.network),
             resourceUrl: ctx.resourceUrl,
             payer: ctx.payer,
             issuedAt: ctx.settledAt,
@@ -45,8 +48,71 @@ export class Assure {
         return { receipt, compliance, ledger };
     }
 }
-/** Decorate an x402 SettlementResponse body with the receipt at the spec-defined placement
- * (`extensions["offer-receipt"].info.receipt`) and the Tersign record alongside it. */
+/** JSON Schema for `extensions["offer-receipt"]` on a SettlementResponse — the same shape the
+ * upstream reference server attaches (x402-foundation/x402 typescript/packages/extensions/src/
+ * offer-receipt/server.ts RECEIPT_SCHEMA, main 5eee1e3c35, read 2026-09-29). */
+export const OFFER_RECEIPT_RESPONSE_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+    properties: {
+        receipt: {
+            type: 'object',
+            properties: {
+                format: { type: 'string' },
+                payload: {
+                    type: 'object',
+                    properties: {
+                        version: { type: 'integer' },
+                        network: { type: 'string' },
+                        resourceUrl: { type: 'string' },
+                        payer: { type: 'string' },
+                        issuedAt: { type: 'integer' },
+                        transaction: { type: 'string' },
+                    },
+                    required: ['version', 'network', 'resourceUrl', 'payer', 'issuedAt'],
+                },
+                signature: { type: 'string' },
+            },
+            required: ['format', 'signature'],
+        },
+    },
+    required: ['receipt'],
+};
+function complianceInfo(issued) {
+    return {
+        record: issued.compliance.record,
+        attestation: issued.compliance.attestation,
+        ...(issued.ledger
+            ? { ledger: { seq: issued.ledger.seq, digest: issued.ledger.digest, countersignature: issued.ledger.countersignature } }
+            : {}),
+    };
+}
+/** Merge the receipt and the compliance record into an x402 `SettlementResponse` — the object
+ * the HTTP transport carries, base64-encoded, in the `PAYMENT-RESPONSE` header. The receipt goes
+ * to `extensions["offer-receipt"].info.receipt` (offer-receipt spec §5.1, same for v1 and v2)
+ * with its schema; the record and its attestation to `extensions["compliance-fields"].info`
+ * (placement proposed in x402-foundation/x402#2853, open). Every other member of the settlement
+ * response, and every other extension, is kept; an `offer-receipt` entry already present is
+ * replaced, because the record binds to THIS receipt's digest. */
+export function attachToSettlementResponse(settlement, issued) {
+    const prior = isPlainRecord(settlement.extensions) ? settlement.extensions : {};
+    return {
+        ...settlement,
+        extensions: {
+            ...prior,
+            'offer-receipt': { info: { receipt: issued.receipt }, schema: OFFER_RECEIPT_RESPONSE_SCHEMA },
+            'compliance-fields': { info: complianceInfo(issued) },
+        },
+    };
+}
+function isPlainRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** LEGACY: decorate the resource's JSON response BODY with the same extension entries. The x402
+ * v2 HTTP transport carries protocol data in headers only ("Response bodies are a server
+ * implementation concern"), so a wallet reading `PAYMENT-RESPONSE` never sees a body placement.
+ * Kept for readers built against tersign ≤0.5; `withAssure` uses it only with
+ * `legacyBodyPlacement: true`. */
 export function attachToExtensions(responseBody, issued) {
     const prior = (responseBody.extensions ?? {});
     return {
@@ -54,15 +120,7 @@ export function attachToExtensions(responseBody, issued) {
         extensions: {
             ...prior,
             'offer-receipt': { info: { receipt: issued.receipt } },
-            'compliance-fields': {
-                info: {
-                    record: issued.compliance.record,
-                    attestation: issued.compliance.attestation,
-                    ...(issued.ledger
-                        ? { ledger: { seq: issued.ledger.seq, digest: issued.ledger.digest, countersignature: issued.ledger.countersignature } }
-                        : {}),
-                },
-            },
+            'compliance-fields': { info: complianceInfo(issued) },
         },
     };
 }

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,7 +1,8 @@
 import type { Account } from 'viem/accounts';
 import type { Adjustment, ComplianceRecordV1, SignedComplianceRecord, SignedReceipt, VerifyLike } from './types.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
+import { type SignerBinding } from '../receipt/binding.js';
+/** EIP-712 domain named in the proposed compliance-fields extension (x402-foundation/x402#2853,
+ * open — proposed, not settled spec). 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. */
 export declare const COMPLIANCE_DOMAIN: {
     readonly name: "compliance-fields";
@@ -31,7 +32,8 @@ export interface IssuerConfig {
     name: string;
     jurisdiction: string;
     taxId?: string;
-    /** default 7 — HK IRO s.51C floor, ≥ MiCA 5+2 */
+    /** default 7 where no longer period applies (HK IRO s.51C, MiCA 5+2) — set the longest period
+     * that applies to you (e.g. DE § 14b UStG: eight years); 7 is a default, not a sufficiency claim */
     retentionYears?: number;
 }
 export interface MinimalRecordInput {
@@ -44,9 +46,19 @@ export interface MinimalRecordInput {
     refundOf?: `0x${string}`;
     adjustment?: Adjustment;
 }
-/** MINIMAL tier ≈ EU VAT Art 226b simplified-invoice content — legally sufficient for
- * sub-€100 supplies EU-wide, and the default for machine-to-machine micro-receipts. */
+/** Build a record carrying the MINIMAL members of the proposed compliance-fields extension —
+ * content isomorphic to the EU VAT Art 226b simplified invoice. Whether it suffices as an invoice
+ * is decided by the invoicing rules that apply to the supply (Art 219a): Art 220a(1)(a) makes
+ * every Member State allow simplified invoices up to EUR 100, a Member State may require further
+ * details on them (Art 226b), and some supplies can never use one (Art 220(1)(2)-(3), Art 220a(2),
+ * and national bars). MINIMAL needs `tax.amount` whenever `tax.scheme` is not `none`; that is the caller's
+ * input. `seq` is not set here: it is the issuer's to assign before attestation. */
 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,7 +1,8 @@
 import { recoverTypedDataAddress } from 'viem';
 import { digestOf } from '../canonical.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
+import { bindSigner, isPlainObject, parseExpectedSigner, signatureError } from '../receipt/binding.js';
+/** EIP-712 domain named in the proposed compliance-fields extension (x402-foundation/x402#2853,
+ * open — proposed, not settled spec). 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. */
 export const COMPLIANCE_DOMAIN = { name: 'compliance-fields', version: '1', chainId: 1n };
 export const COMPLIANCE_TYPES = {
@@ -19,11 +20,17 @@ export const COMPLIANCE_WIRE_VECTOR = digestOf({
     domain: { ...COMPLIANCE_DOMAIN, chainId: 1 },
     types: COMPLIANCE_TYPES,
 });
-/** MINIMAL tier ≈ EU VAT Art 226b simplified-invoice content — legally sufficient for
- * sub-€100 supplies EU-wide, and the default for machine-to-machine micro-receipts. */
+/** Build a record carrying the MINIMAL members of the proposed compliance-fields extension —
+ * content isomorphic to the EU VAT Art 226b simplified invoice. Whether it suffices as an invoice
+ * is decided by the invoicing rules that apply to the supply (Art 219a): Art 220a(1)(a) makes
+ * every Member State allow simplified invoices up to EUR 100, a Member State may require further
+ * details on them (Art 226b), and some supplies can never use one (Art 220(1)(2)-(3), Art 220a(2),
+ * and national bars). MINIMAL needs `tax.amount` whenever `tax.scheme` is not `none`; that is the caller's
+ * input. `seq` is not set here: it is the issuer's to assign before attestation. */
 export function buildMinimalRecord(issuer, input) {
     const record = {
         version: 1,
+        canonicalizationVersion: 1,
         receiptDigest: digestOf(input.receipt),
         issuedAt: input.issuedAt,
         issuer: {
@@ -71,17 +78,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 +120,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,10 @@
 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 { toCaip2Network } from './receipt/network.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';
@@ -9,7 +12,7 @@ export { DISPUTE_DOMAIN, EVIDENCE_DOMAIN, CRITERIA_DOMAIN, DISPUTE_TYPES, EVIDEN
 export { ACTION_DOMAIN, ACTION_TYPES, ACTION_WIRE_VECTOR, actionDigest, signActionRecord, verifyActionRecord, type ActionKind, type DisclosureKind, type GovernanceOutcome, type ActionRecordV1, type ActionAttestationPayload, type SignedActionRecord, } from './evidence/action.js';
 export { recordDisclosure, type RecordDisclosureOptions, type RecordDisclosureResult } from './evidence/disclose.js';
 export { LedgerClient, type LedgerConfig, type CountersignResult } from './ledgerClient.js';
-export { Assure, attachToExtensions, type AssureConfig, type SettlementContext, type IssuedReceipt } from './assure.js';
-export { withAssure, extractSettlement, extractPaymentPayload, type WithAssureConfig, type SettlementInfo } from './adapter/x402.js';
+export { Assure, attachToExtensions, attachToSettlementResponse, OFFER_RECEIPT_RESPONSE_SCHEMA, type AssureConfig, type SettlementContext, type IssuedReceipt, } from './assure.js';
+export { withAssure, extractSettlement, extractPaymentPayload, encodeX402Header, decodeX402Header, COMPLIANCE_FIELDS_ADVERTISEMENT_SCHEMA, type WithAssureConfig, type SettlementInfo, type ComplianceAdvertisement, } from './adapter/x402.js';
 export { ENVELOPE_STATEMENT_MAX_CHARS, VENUE_SUBMISSION_MAX_CHARS, ENVELOPE_VENUES, type EvidenceEnvelopeV1, type EnvelopeSubjectKind, type EnvelopeVenue, } from './envelope/types.js';
 export { assertEnvelopeCaps, toInternetCourtSubmission, toKlerosEvidence, toUMAClaim, type Kleros1497Evidence, } from './envelope/serialize.js';

package/dist/index.js

@@ -1,6 +1,9 @@
 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 { toCaip2Network } from './receipt/network.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';
@@ -8,7 +11,7 @@ export { DISPUTE_DOMAIN, EVIDENCE_DOMAIN, CRITERIA_DOMAIN, DISPUTE_TYPES, EVIDEN
 export { ACTION_DOMAIN, ACTION_TYPES, ACTION_WIRE_VECTOR, actionDigest, signActionRecord, verifyActionRecord, } from './evidence/action.js';
 export { recordDisclosure } from './evidence/disclose.js';
 export { LedgerClient } from './ledgerClient.js';
-export { Assure, attachToExtensions } from './assure.js';
-export { withAssure, extractSettlement, extractPaymentPayload } from './adapter/x402.js';
+export { Assure, attachToExtensions, attachToSettlementResponse, OFFER_RECEIPT_RESPONSE_SCHEMA, } from './assure.js';
+export { withAssure, extractSettlement, extractPaymentPayload, encodeX402Header, decodeX402Header, COMPLIANCE_FIELDS_ADVERTISEMENT_SCHEMA, } from './adapter/x402.js';
 export { ENVELOPE_STATEMENT_MAX_CHARS, VENUE_SUBMISSION_MAX_CHARS, ENVELOPE_VENUES, } from './envelope/types.js';
 export { assertEnvelopeCaps, toInternetCourtSubmission, toKlerosEvidence, toUMAClaim, } from './envelope/serialize.js';

package/dist/ledgerClient.d.ts

@@ -22,8 +22,11 @@ export declare class LedgerClient {
     constructor(cfg: LedgerConfig);
     private get f();
     submitReceipt(artifact: SignedReceipt, compliance?: SignedComplianceRecord): Promise<CountersignResult>;
+    /** Log a refund against a receipt on this seller's chain. The ledger stores a PENDING refund
+     * entry; it is not counter-signed or chained, so the answer carries no digest or seq. */
     recordRefund(originalDigest: `0x${string}`, amount: string, reason: string): Promise<{
         id: string;
+        status: string;
     }>;
     /** Fetch the venue-neutral evidence envelope for a chained artifact (public endpoint — works
      * without an API key; the apiKey/sellerId in cfg are unused here). `statement` is an optional

package/dist/ledgerClient.js

@@ -23,6 +23,8 @@ export class LedgerClient {
             throw new Error(`ledger submit failed: ${res.status} ${await res.text()}`);
         return (await res.json());
     }
+    /** Log a refund against a receipt on this seller's chain. The ledger stores a PENDING refund
+     * entry; it is not counter-signed or chained, so the answer carries no digest or seq. */
     async recordRefund(originalDigest, amount, reason) {
         const res = await this.f(`${this.cfg.url}/v1/refunds`, {
             method: 'POST',

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.11";
+    readonly version: "0.6.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.11' };
+export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.6.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; when a ledger is configured, the ledger counter-signs the receipt into your hash chain, while the compliance-fields record is not counter-signed and is bound to its receipt only by your own signature, which covers the receipt\'s digest. ' +
             '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,30 +114,29 @@ 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', {
         title: 'Record refund',
-        description: 'Record a refund against an already-chained receipt, as the SELLER. The refund becomes its own counter-signed entry that references the original — nothing is edited or deleted, so the chain stays append-only and both the charge and the refund remain visible. ' +
+        description: 'Log a refund against a receipt already on your chain, as the SELLER. The ledger stores it as a PENDING refund entry that references the original receipt digest; the entry is NOT counter-signed or appended to the hash chain, and it has no digest or sequence number of its own. Nothing is edited or deleted: the original receipt and its chain position stay exactly as they were. ' +
             'Requires ledger configuration (TERSIGN_LEDGER_URL/_API_KEY/_SELLER_ID) and performs one network write; errors if the original digest is not on your chain. ' +
-            'This RECORDS a refund you have already made — it moves no money. ' +
-            'Returns the refund record, its digest, the ledger counter-signature and sequence number.',
+            'This RECORDS a refund you have already made — it moves no money. For a signed refund RECORD, build a compliance record with refundOf set to the original record digest (buildMinimalRecord in the SDK). ' +
+            'Returns { id, status: "pending" }.',
         inputSchema: {
             originalDigest: z
                 .string()
@@ -186,9 +190,9 @@ export function buildServer(deps) {
     })));
     server.registerTool('adjudicate_dispute', {
         title: 'Adjudicate dispute',
-        description: 'Trigger deterministic adjudication of an open dispute. The v0 rulebook is public and the verdict is recomputable by anyone from the chain — no discretion, no model in the loop. ' +
-            'Side effects: writes a verdict entry, and a refund verdict automatically creates the corresponding refund record. Adjudicating twice is not meaningful; the first verdict stands. ' +
-            'Returns the verdict, the rationale naming the rule applied, and the ledger signature over both.',
+        description: 'Trigger deterministic adjudication of an open dispute: the same inputs always produce the same verdict and rationale — no discretion, no model in the loop — and the verdict object embeds the inputs it was computed from. ' +
+            'Side effects: writes the verdict to the dispute record; a refund verdict also logs a PENDING refund entry against the receipt (not counter-signed into the chain; no money moves). Adjudicating twice is not meaningful; the first verdict stands (a second call returns 409). ' +
+            'Returns the verdict, the rationale naming the rule applied, the adjudication inputs, the verdict digest, and the ledger signature over that digest.',
         inputSchema: {
             disputeDigest: digestSchema.describe('0x-prefixed digest of the open dispute to adjudicate, as returned by open_dispute'),
         },