tersign 0.0.1 → 0.1.0

package/dist/idempotency/d1.d.ts

@@ -0,0 +1,32 @@
+import type { CachedResponse, IdempotencyStore } from './middleware.js';
+/** Structural subset of Cloudflare's D1Database — declared locally so the SDK carries no
+ * @cloudflare/workers-types dependency; a real D1 binding satisfies it as-is. */
+export interface D1Like {
+    prepare(query: string): {
+        bind(...values: unknown[]): {
+            first<T = unknown>(): Promise<T | null>;
+            run(): Promise<{
+                meta?: {
+                    changes?: number;
+                };
+            }>;
+        };
+    };
+}
+/** DDL for the table this store expects. Run once per database (idempotent). */
+export declare const D1_IDEMPOTENCY_DDL = "CREATE TABLE IF NOT EXISTS assure_idempotency (\n  scope TEXT NOT NULL,\n  key TEXT NOT NULL,\n  fingerprint TEXT NOT NULL,\n  response_json TEXT,\n  created_at INTEGER NOT NULL,\n  PRIMARY KEY (scope, key)\n);";
+/** Durable IdempotencyStore on Cloudflare D1 for sellers running on Workers — the
+ * MemoryIdempotencyStore resets on every isolate recycle, which silently re-executes
+ * paid work on retry. Reservation atomicity rides on the primary key: INSERT OR IGNORE
+ * reports 0 changes when another request holds the id, which maps to `in-flight`. */
+export declare class D1IdempotencyStore implements IdempotencyStore {
+    private readonly db;
+    private readonly table;
+    constructor(db: D1Like, table?: string);
+    get(scope: string, id: string): Promise<{
+        fingerprint: string;
+        response: CachedResponse | null;
+    } | undefined>;
+    reserve(scope: string, id: string, fingerprint: string): Promise<boolean>;
+    complete(scope: string, id: string, response: CachedResponse): Promise<void>;
+}

package/dist/idempotency/d1.js

@@ -0,0 +1,46 @@
+/** DDL for the table this store expects. Run once per database (idempotent). */
+export const D1_IDEMPOTENCY_DDL = `CREATE TABLE IF NOT EXISTS assure_idempotency (
+  scope TEXT NOT NULL,
+  key TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  response_json TEXT,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (scope, key)
+);`;
+/** Durable IdempotencyStore on Cloudflare D1 for sellers running on Workers — the
+ * MemoryIdempotencyStore resets on every isolate recycle, which silently re-executes
+ * paid work on retry. Reservation atomicity rides on the primary key: INSERT OR IGNORE
+ * reports 0 changes when another request holds the id, which maps to `in-flight`. */
+export class D1IdempotencyStore {
+    db;
+    table;
+    constructor(db, table = 'assure_idempotency') {
+        this.db = db;
+        this.table = table;
+    }
+    async get(scope, id) {
+        const row = await this.db
+            .prepare(`SELECT fingerprint, response_json FROM ${this.table} WHERE scope = ? AND key = ?`)
+            .bind(scope, id)
+            .first();
+        if (!row)
+            return undefined;
+        return {
+            fingerprint: row.fingerprint,
+            response: row.response_json === null ? null : JSON.parse(row.response_json),
+        };
+    }
+    async reserve(scope, id, fingerprint) {
+        const result = await this.db
+            .prepare(`INSERT OR IGNORE INTO ${this.table} (scope, key, fingerprint, response_json, created_at) VALUES (?, ?, ?, NULL, ?)`)
+            .bind(scope, id, fingerprint, Math.floor(Date.now() / 1000))
+            .run();
+        return (result.meta?.changes ?? 0) === 1;
+    }
+    async complete(scope, id, response) {
+        await this.db
+            .prepare(`UPDATE ${this.table} SET response_json = ? WHERE scope = ? AND key = ?`)
+            .bind(JSON.stringify(response), scope, id)
+            .run();
+    }
+}

package/dist/idempotency/middleware.d.ts

@@ -0,0 +1,63 @@
+/** Idempotency ENFORCEMENT for x402/MPP sellers. The x402 `payment-identifier` extension
+ * ships the key; retry/replay semantics are explicitly left to the application layer
+ * (x402 issue #452). This module implements the strictest published behavior table
+ * (ACP-grade): new id → process; same id + same fingerprint → cached replay; same id +
+ * different fingerprint → 409; required-but-missing → 400. */
+export interface CachedResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface IdempotencyStore {
+    get(scope: string, id: string): Promise<{
+        fingerprint: string;
+        response: CachedResponse | null;
+    } | undefined>;
+    /** reserve an id before processing (null response = in flight) */
+    reserve(scope: string, id: string, fingerprint: string): Promise<boolean>;
+    complete(scope: string, id: string, response: CachedResponse): Promise<void>;
+}
+export declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private m;
+    get(scope: string, id: string): Promise<{
+        fingerprint: string;
+        response: CachedResponse | null;
+    } | undefined>;
+    reserve(scope: string, id: string, fingerprint: string): Promise<boolean>;
+    complete(scope: string, id: string, response: CachedResponse): Promise<void>;
+}
+/** Extract the payment-identifier id from an x402 PaymentPayload's extensions, if present. */
+export declare function extractPaymentId(paymentPayload: unknown): string | undefined;
+export interface FingerprintParts {
+    method: string;
+    path: string;
+    scheme?: string;
+    network?: string;
+    asset?: string;
+    amount?: string;
+    payTo?: string;
+    operation?: string;
+}
+/** Per the payment-identifier spec: bind the id to a normalized request fingerprint. */
+export declare function fingerprint(parts: FingerprintParts): string;
+export type IdempotencyOutcome = {
+    kind: 'process';
+    onComplete: (response: CachedResponse) => Promise<void>;
+} | {
+    kind: 'replay';
+    response: CachedResponse;
+} | {
+    kind: 'in-flight';
+} | {
+    kind: 'conflict';
+} | {
+    kind: 'missing';
+};
+export interface IdempotencyOptions {
+    store: IdempotencyStore;
+    required: boolean;
+    /** tenant/route scope so ids never collide across sellers (spec guidance) */
+    scope: string;
+}
+export declare function checkIdempotency(opts: IdempotencyOptions, id: string | undefined, fp: string): Promise<IdempotencyOutcome>;
+export declare const REPLAY_HEADER = "Idempotent-Replayed";

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from './types.js';
+export { canonicalStringify, digestOf } 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, buildMinimalRecord, recordDigest, signComplianceRecord, verifyComplianceRecord, 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';
+export { DISPUTE_DOMAIN, EVIDENCE_DOMAIN, CRITERIA_DOMAIN, DISPUTE_TYPES, EVIDENCE_TYPES, CRITERIA_TYPES, DISPUTE_WIRE_VECTOR, disputeDigest, evidenceDigest, criteriaDigest, signDispute, verifyDispute, signEvidence, verifyEvidence, signCriteria, verifyCriteria, } from './dispute/sign.js';
+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 { 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 { 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

@@ -0,0 +1,13 @@
+export * from './types.js';
+export { canonicalStringify, digestOf } from './canonical.js';
+export { RECEIPT_DOMAIN, RECEIPT_TYPES, OFFER_DOMAIN, OFFER_TYPES, signReceipt, signOffer, verifyReceipt, } from './receipt/eip712.js';
+export { COMPLIANCE_DOMAIN, COMPLIANCE_TYPES, 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';
+export { DISPUTE_DOMAIN, EVIDENCE_DOMAIN, CRITERIA_DOMAIN, DISPUTE_TYPES, EVIDENCE_TYPES, CRITERIA_TYPES, DISPUTE_WIRE_VECTOR, disputeDigest, evidenceDigest, criteriaDigest, signDispute, verifyDispute, signEvidence, verifyEvidence, signCriteria, verifyCriteria, } from './dispute/sign.js';
+export { ACTION_DOMAIN, ACTION_TYPES, ACTION_WIRE_VECTOR, actionDigest, signActionRecord, verifyActionRecord, } from './evidence/action.js';
+export { LedgerClient } from './ledgerClient.js';
+export { Assure, attachToExtensions } from './assure.js';
+export { withAssure, extractSettlement, extractPaymentPayload } 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

@@ -0,0 +1,34 @@
+import type { SignedComplianceRecord, SignedReceipt } from './types.js';
+import type { EnvelopeVenue, EvidenceEnvelopeV1 } from './envelope/types.js';
+import { type Kleros1497Evidence } from './envelope/serialize.js';
+export interface LedgerConfig {
+    url: string;
+    apiKey: string;
+    sellerId: string;
+    fetchImpl?: typeof fetch;
+}
+export interface CountersignResult {
+    id: string;
+    digest: `0x${string}`;
+    seq: number;
+    prevDigest: `0x${string}` | null;
+    countersignature: string;
+}
+/** Client for the hosted Tersign ledger: counter-signature + hash-chain + exports.
+ * The counter-signed chain is what makes a receipt independently verifiable and
+ * audit-exportable after the fact — the hosted half of the product. */
+export declare class LedgerClient {
+    private cfg;
+    constructor(cfg: LedgerConfig);
+    private get f();
+    submitReceipt(artifact: SignedReceipt, compliance?: SignedComplianceRecord): Promise<CountersignResult>;
+    recordRefund(originalDigest: `0x${string}`, amount: string, reason: string): Promise<{
+        id: 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
+     * party claim (≤500 chars) folded into the envelope, never raw evidence. */
+    fetchEnvelope(digest: `0x${string}`, statement?: string): Promise<EvidenceEnvelopeV1>;
+    /** Fetch + serialize in one call: a jury-ready submission for the named venue. */
+    fetchVenueSubmission(digest: `0x${string}`, venue: Exclude<EnvelopeVenue, 'generic'>, statement?: string): Promise<string | Kleros1497Evidence>;
+}

package/dist/ledgerClient.js

@@ -0,0 +1,58 @@
+import { toInternetCourtSubmission, toKlerosEvidence, toUMAClaim } from './envelope/serialize.js';
+/** Client for the hosted Tersign ledger: counter-signature + hash-chain + exports.
+ * The counter-signed chain is what makes a receipt independently verifiable and
+ * audit-exportable after the fact — the hosted half of the product. */
+export class LedgerClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get f() {
+        return this.cfg.fetchImpl ?? fetch;
+    }
+    async submitReceipt(artifact, compliance) {
+        const res = await this.f(`${this.cfg.url}/v1/receipts`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${this.cfg.apiKey}`,
+            },
+            body: JSON.stringify({ sellerId: this.cfg.sellerId, artifact, compliance }),
+        });
+        if (!res.ok)
+            throw new Error(`ledger submit failed: ${res.status} ${await res.text()}`);
+        return (await res.json());
+    }
+    async recordRefund(originalDigest, amount, reason) {
+        const res = await this.f(`${this.cfg.url}/v1/refunds`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${this.cfg.apiKey}`,
+            },
+            body: JSON.stringify({ originalDigest, amount, reason }),
+        });
+        if (!res.ok)
+            throw new Error(`ledger refund record failed: ${res.status} ${await res.text()}`);
+        return (await res.json());
+    }
+    /** 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
+     * party claim (≤500 chars) folded into the envelope, never raw evidence. */
+    async fetchEnvelope(digest, statement) {
+        const q = statement !== undefined ? `?statement=${encodeURIComponent(statement)}` : '';
+        const res = await this.f(`${this.cfg.url}/v1/receipts/${digest}/envelope${q}`);
+        if (!res.ok)
+            throw new Error(`envelope fetch failed: ${res.status} ${await res.text()}`);
+        return (await res.json());
+    }
+    /** Fetch + serialize in one call: a jury-ready submission for the named venue. */
+    async fetchVenueSubmission(digest, venue, statement) {
+        const env = await this.fetchEnvelope(digest, statement);
+        if (venue === 'internet-court')
+            return toInternetCourtSubmission(env);
+        if (venue === 'kleros')
+            return toKlerosEvidence(env);
+        return toUMAClaim(env);
+    }
+}

package/dist/mcp/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer, envDeps } from './server.js';
+const server = buildServer(envDeps());
+await server.connect(new StdioServerTransport());

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type McpDeps } from './tools.js';
+/** MCP packaging: exposes assure as tools any MCP-speaking agent can call, so an agent
+ * (or its framework) can issue, verify, and chain receipts without importing the SDK.
+ * Config via env — see envDeps(). */
+export declare function envDeps(env?: Record<string, string | undefined>): McpDeps;
+export declare function buildServer(deps: McpDeps): McpServer;

package/dist/mcp/server.js

@@ -0,0 +1,131 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { privateKeyToAccount } from 'viem/accounts';
+import { Assure } from '../assure.js';
+import { LedgerClient } from '../ledgerClient.js';
+import { adjudicateDisputeTool, getDisputeTool, issueReceiptTool, openDisputeTool, recordRefundTool, submitEvidenceTool, verifyReceiptTool, verifyRecordTool, } from './tools.js';
+/** MCP packaging: exposes assure as tools any MCP-speaking agent can call, so an agent
+ * (or its framework) can issue, verify, and chain receipts without importing the SDK.
+ * Config via env — see envDeps(). */
+export function envDeps(env = process.env) {
+    const key = env.TERSIGN_SELLER_KEY;
+    if (!key)
+        throw new Error('TERSIGN_SELLER_KEY (0x-prefixed private key) is required');
+    const account = privateKeyToAccount(key);
+    const assure = new Assure({
+        signer: account,
+        issuer: {
+            name: env.TERSIGN_ISSUER_NAME ?? 'unnamed seller',
+            jurisdiction: env.TERSIGN_ISSUER_JURISDICTION ?? 'unknown',
+            ...(env.TERSIGN_ISSUER_TAX_ID !== undefined ? { taxId: env.TERSIGN_ISSUER_TAX_ID } : {}),
+        },
+        ...(env.TERSIGN_LEDGER_URL && env.TERSIGN_LEDGER_API_KEY && env.TERSIGN_LEDGER_SELLER_ID
+            ? { ledger: { url: env.TERSIGN_LEDGER_URL, apiKey: env.TERSIGN_LEDGER_API_KEY, sellerId: env.TERSIGN_LEDGER_SELLER_ID } }
+            : {}),
+    });
+    const ledger = env.TERSIGN_LEDGER_URL && env.TERSIGN_LEDGER_API_KEY && env.TERSIGN_LEDGER_SELLER_ID
+        ? new LedgerClient({ url: env.TERSIGN_LEDGER_URL, apiKey: env.TERSIGN_LEDGER_API_KEY, sellerId: env.TERSIGN_LEDGER_SELLER_ID })
+        : undefined;
+    return {
+        assure,
+        signer: account,
+        ...(ledger ? { ledger } : {}),
+        ...(env.TERSIGN_LEDGER_URL
+            ? {
+                ledgerHttp: {
+                    url: env.TERSIGN_LEDGER_URL,
+                    ...(env.TERSIGN_LEDGER_API_KEY !== undefined ? { apiKey: env.TERSIGN_LEDGER_API_KEY } : {}),
+                },
+            }
+            : {}),
+    };
+}
+function json(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+export function buildServer(deps) {
+    const server = new McpServer({ name: 'tersign-assure', version: '0.0.1' });
+    server.registerTool('issue_receipt', {
+        title: 'Issue signed receipt',
+        description: 'Issue an x402 offer-receipt (EIP-712) plus an Tersign compliance record for a settled payment; counter-signs into the ledger when configured.',
+        inputSchema: {
+            network: z.string().describe('CAIP-2, e.g. eip155:8453'),
+            resourceUrl: z.string().url(),
+            payer: z.string(),
+            supplyDescription: z.string(),
+            settledAt: z.number().int().optional(),
+            txHash: z.string().optional(),
+            taxScheme: z.enum(['none', 'vat', 'gst', 'jct', 'sales']).optional(),
+            currency: z.string().optional(),
+            principal: z.string().optional().describe('signed principal behind the paying agent'),
+        },
+    }, async (args) => json(await issueReceiptTool(deps, args)));
+    server.registerTool('verify_receipt', {
+        title: 'Verify signed receipt',
+        description: 'Verify an offer-receipt artifact (EIP-712) and optionally enforce an expected signer (payTo authorization).',
+        inputSchema: {
+            artifact: z.record(z.unknown()).describe('the receipt artifact object {format, payload, signature}'),
+            expectedSigner: z.string().optional(),
+        },
+    }, async ({ artifact, expectedSigner }) => json(await verifyReceiptTool(artifact, expectedSigner)));
+    server.registerTool('verify_compliance_record', {
+        title: 'Verify compliance record',
+        description: 'Verify an Tersign compliance record + attestation (digest binding and signature).',
+        inputSchema: {
+            record: z.record(z.unknown()),
+            attestation: z.record(z.unknown()),
+            expectedSigner: z.string().optional(),
+        },
+    }, async ({ record, attestation, expectedSigner }) => json(await verifyRecordTool(record, attestation, expectedSigner)));
+    server.registerTool('record_refund', {
+        title: 'Record refund',
+        description: 'Record a refund against a receipt digest in the Tersign ledger (requires ledger configuration).',
+        inputSchema: {
+            originalDigest: z.string().regex(/^0x[0-9a-fA-F]{64}$/),
+            amount: z.string(),
+            reason: z.string(),
+        },
+    }, async ({ originalDigest, amount, reason }) => json(await recordRefundTool(deps, originalDigest, amount, reason)));
+    const digestSchema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+    server.registerTool('open_dispute', {
+        title: 'Open dispute',
+        description: 'Open an objective dispute against a counter-signed receipt as the PAYER (the configured key must be the receipt payer). Reasons: not_delivered, wrong_content, duplicate_charge. Contested non-mechanical claims escalate to the arbiter; duplicate_charge is decided instantly from ledger arithmetic.',
+        inputSchema: {
+            receiptDigest: digestSchema,
+            reason: z.enum(['not_delivered', 'wrong_content', 'duplicate_charge']),
+            claimAmount: z.string().describe('claimed refund in the settlement currency'),
+            statement: z.string().optional().describe('for humans reading the record — never an adjudication input'),
+        },
+    }, async ({ receiptDigest, reason, claimAmount, statement }) => json(await openDisputeTool(deps, { receiptDigest: receiptDigest, reason, claimAmount, statement })));
+    server.registerTool('submit_dispute_evidence', {
+        title: 'Submit dispute evidence',
+        description: 'Submit signed evidence to an open dispute. Claimant evidence must be signed by the payer key; respondent evidence additionally requires the seller API key (TERSIGN_LEDGER_API_KEY).',
+        inputSchema: {
+            disputeDigest: digestSchema,
+            role: z.enum(['claimant', 'respondent']),
+            artifacts: z
+                .array(z.object({
+                kind: z.enum(['content-digest', 'delivery-attestation', 'payment-proof', 'transcript']),
+                digest: digestSchema,
+                at: z.number().int().optional(),
+                note: z.string().optional(),
+            }))
+                .min(1),
+        },
+    }, async ({ disputeDigest, role, artifacts }) => json(await submitEvidenceTool(deps, {
+        disputeDigest: disputeDigest,
+        role,
+        artifacts: artifacts,
+    })));
+    server.registerTool('adjudicate_dispute', {
+        title: 'Adjudicate dispute',
+        description: 'Trigger deterministic adjudication of an open dispute (public — the v0 rulebook is recomputable by anyone). Refund verdicts create refund records automatically.',
+        inputSchema: { disputeDigest: digestSchema },
+    }, async ({ disputeDigest }) => json(await adjudicateDisputeTool(deps, disputeDigest)));
+    server.registerTool('get_dispute', {
+        title: 'Get dispute record',
+        description: 'Fetch a dispute record with its evidence, verdict, rationale, and ledger signature.',
+        inputSchema: { disputeDigest: digestSchema },
+    }, async ({ disputeDigest }) => json(await getDisputeTool(deps, disputeDigest)));
+    return server;
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,57 @@
+import type { Account } from 'viem/accounts';
+import type { Assure } from '../assure.js';
+import type { DisputeReason, EvidenceArtifactRef } from '../dispute/types.js';
+import type { LedgerClient } from '../ledgerClient.js';
+import type { ComplianceRecordV1, SignedComplianceRecord, SignedReceipt } from '../types.js';
+/** Plain-function tool implementations, kept separate from MCP wiring so they are unit-testable
+ * and reusable from non-MCP surfaces. */
+export interface McpDeps {
+    assure: Assure;
+    ledger?: LedgerClient;
+    /** signing key for dispute-side actions. Standing is key-based: opening a dispute
+     * requires this key to be the disputed receipt's payer. */
+    signer?: Account;
+    /** raw ledger HTTP access for the PUBLIC dispute endpoints (no API key needed;
+     * apiKey only authenticates respondent evidence). */
+    ledgerHttp?: {
+        url: string;
+        apiKey?: string;
+    };
+    clock?: () => number;
+}
+export interface IssueReceiptArgs {
+    network: string;
+    resourceUrl: string;
+    payer: string;
+    supplyDescription: string;
+    settledAt?: number | undefined;
+    txHash?: string | undefined;
+    taxScheme?: 'none' | 'vat' | 'gst' | 'jct' | 'sales' | undefined;
+    currency?: string | undefined;
+    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>;
+export declare function recordRefundTool(deps: McpDeps, originalDigest: `0x${string}`, amount: string, reason: string): Promise<{
+    id: string;
+}>;
+export interface OpenDisputeArgs {
+    receiptDigest: `0x${string}`;
+    reason: DisputeReason;
+    claimAmount: string;
+    statement?: string | undefined;
+}
+/** Open a dispute as the PAYER. The configured key signs the dispute; the ledger rejects
+ * it (403) unless the signature recovers to the disputed receipt's payer. */
+export declare function openDisputeTool(deps: McpDeps, args: OpenDisputeArgs): Promise<unknown>;
+export interface SubmitEvidenceArgs {
+    disputeDigest: `0x${string}`;
+    role: 'claimant' | 'respondent';
+    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). */
+export declare function adjudicateDisputeTool(deps: McpDeps, disputeDigest: `0x${string}`): Promise<unknown>;
+export declare function getDisputeTool(deps: McpDeps, disputeDigest: `0x${string}`): Promise<unknown>;

package/dist/mcp/tools.js

@@ -0,0 +1,85 @@
+import { verifyReceipt } from '../receipt/eip712.js';
+import { verifyComplianceRecord } from '../compliance/record.js';
+import { signDispute, signEvidence } from '../dispute/sign.js';
+async function ledgerFetch(base, path, init) {
+    const url = `${base.replace(/\/$/, '')}${path}`;
+    const res = await fetch(url, {
+        method: init?.body === undefined ? 'GET' : 'POST',
+        headers: {
+            ...(init?.body !== undefined ? { 'content-type': 'application/json' } : {}),
+            ...(init?.apiKey ? { authorization: `Bearer ${init.apiKey}` } : {}),
+        },
+        ...(init?.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(`ledger ${res.status}: ${JSON.stringify(json)}`);
+    return json;
+}
+export async function issueReceiptTool(deps, args) {
+    const now = deps.clock ?? (() => Math.floor(Date.now() / 1000));
+    const ctx = {
+        network: args.network,
+        resourceUrl: args.resourceUrl,
+        payer: args.payer,
+        settledAt: args.settledAt ?? now(),
+        supplyDescription: args.supplyDescription,
+        tax: { scheme: args.taxScheme ?? 'none', currency: args.currency ?? 'USD' },
+        ...(args.txHash !== undefined ? { txHash: args.txHash } : {}),
+        ...(args.principal !== undefined ? { buyer: { principal: args.principal } } : {}),
+    };
+    return deps.assure.issueFor(ctx);
+}
+export async function verifyReceiptTool(artifact, expectedSigner) {
+    return verifyReceipt(artifact, expectedSigner);
+}
+export async function verifyRecordTool(record, attestation, expectedSigner) {
+    return verifyComplianceRecord({ record, attestation }, expectedSigner);
+}
+export async function recordRefundTool(deps, originalDigest, amount, reason) {
+    if (!deps.ledger)
+        throw new Error('ledger not configured — set TERSIGN_LEDGER_URL / _API_KEY / _SELLER_ID');
+    return deps.ledger.recordRefund(originalDigest, amount, reason);
+}
+/** Open a dispute as the PAYER. The configured key signs the dispute; the ledger rejects
+ * it (403) unless the signature recovers to the disputed receipt's payer. */
+export async function openDisputeTool(deps, args) {
+    if (!deps.signer)
+        throw new Error('no signing key configured — set TERSIGN_SELLER_KEY (used as the acting key)');
+    if (!deps.ledgerHttp)
+        throw new Error('ledger URL not configured — set TERSIGN_LEDGER_URL');
+    const now = deps.clock ?? (() => Math.floor(Date.now() / 1000));
+    const artifact = await signDispute({
+        version: 1,
+        receiptDigest: args.receiptDigest,
+        reason: args.reason,
+        claimAmount: args.claimAmount,
+        ...(args.statement !== undefined ? { statement: args.statement } : {}),
+        openedAt: now(),
+    }, deps.signer);
+    return ledgerFetch(deps.ledgerHttp.url, '/v1/disputes', { body: { artifact } });
+}
+export async function submitEvidenceTool(deps, args) {
+    if (!deps.signer)
+        throw new Error('no signing key configured');
+    if (!deps.ledgerHttp)
+        throw new Error('ledger URL not configured — set TERSIGN_LEDGER_URL');
+    const now = deps.clock ?? (() => Math.floor(Date.now() / 1000));
+    const artifact = await signEvidence({ version: 1, disputeDigest: args.disputeDigest, role: args.role, artifacts: args.artifacts, submittedAt: now() }, deps.signer);
+    return ledgerFetch(deps.ledgerHttp.url, `/v1/disputes/${args.disputeDigest}/evidence`, {
+        body: { artifact },
+        ...(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). */
+export async function adjudicateDisputeTool(deps, disputeDigest) {
+    if (!deps.ledgerHttp)
+        throw new Error('ledger URL not configured — set TERSIGN_LEDGER_URL');
+    return ledgerFetch(deps.ledgerHttp.url, `/v1/disputes/${disputeDigest}/adjudicate`, { body: {} });
+}
+export async function getDisputeTool(deps, disputeDigest) {
+    if (!deps.ledgerHttp)
+        throw new Error('ledger URL not configured — set TERSIGN_LEDGER_URL');
+    return ledgerFetch(deps.ledgerHttp.url, `/v1/disputes/${disputeDigest}`);
+}

package/dist/receipt/eip712.d.ts

@@ -0,0 +1,72 @@
+import type { Account } from 'viem/accounts';
+import type { OfferPayload, ReceiptPayload, SignedOffer, SignedReceipt } from '../types.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: {
+    readonly name: "x402 receipt";
+    readonly version: "1";
+    readonly chainId: 1n;
+};
+export declare const OFFER_DOMAIN: {
+    readonly name: "x402 offer";
+    readonly version: "1";
+    readonly chainId: 1n;
+};
+export declare const RECEIPT_TYPES: {
+    readonly Receipt: readonly [{
+        readonly name: "version";
+        readonly type: "uint256";
+    }, {
+        readonly name: "network";
+        readonly type: "string";
+    }, {
+        readonly name: "resourceUrl";
+        readonly type: "string";
+    }, {
+        readonly name: "payer";
+        readonly type: "string";
+    }, {
+        readonly name: "issuedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "transaction";
+        readonly type: "string";
+    }];
+};
+export declare const OFFER_TYPES: {
+    readonly Offer: readonly [{
+        readonly name: "version";
+        readonly type: "uint256";
+    }, {
+        readonly name: "resourceUrl";
+        readonly type: "string";
+    }, {
+        readonly name: "scheme";
+        readonly type: "string";
+    }, {
+        readonly name: "network";
+        readonly type: "string";
+    }, {
+        readonly name: "asset";
+        readonly type: "string";
+    }, {
+        readonly name: "payTo";
+        readonly type: "string";
+    }, {
+        readonly name: "amount";
+        readonly type: "string";
+    }, {
+        readonly name: "validUntil";
+        readonly type: "uint256";
+    }];
+};
+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;
+}
+/** 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. */
+export declare function verifyReceipt(artifact: SignedReceipt, expectedSigner?: string): Promise<VerifyResult>;