tersign 0.0.1 → 0.1.0

package/dist/receipt/eip712.js

@@ -0,0 +1,95 @@
+import { recoverTypedDataAddress } from 'viem';
+/** Canonical EIP-712 material from the merged offer-receipt extension. Domain chainId is
+ * hardcoded to 1 by spec (off-chain signing format; payment network lives in payload.network). */
+export const RECEIPT_DOMAIN = { name: 'x402 receipt', version: '1', chainId: 1n };
+export const OFFER_DOMAIN = { name: 'x402 offer', version: '1', chainId: 1n };
+export const RECEIPT_TYPES = {
+    Receipt: [
+        { name: 'version', type: 'uint256' },
+        { name: 'network', type: 'string' },
+        { name: 'resourceUrl', type: 'string' },
+        { name: 'payer', type: 'string' },
+        { name: 'issuedAt', type: 'uint256' },
+        { name: 'transaction', type: 'string' },
+    ],
+};
+export const OFFER_TYPES = {
+    Offer: [
+        { name: 'version', type: 'uint256' },
+        { name: 'resourceUrl', type: 'string' },
+        { name: 'scheme', type: 'string' },
+        { name: 'network', type: 'string' },
+        { name: 'asset', type: 'string' },
+        { name: 'payTo', type: 'string' },
+        { name: 'amount', type: 'string' },
+        { name: 'validUntil', type: 'uint256' },
+    ],
+};
+function receiptMessage(p) {
+    return {
+        version: BigInt(p.version),
+        network: p.network,
+        resourceUrl: p.resourceUrl,
+        payer: p.payer,
+        issuedAt: BigInt(p.issuedAt),
+        transaction: p.transaction,
+    };
+}
+function offerMessage(p) {
+    return {
+        version: BigInt(p.version),
+        resourceUrl: p.resourceUrl,
+        scheme: p.scheme,
+        network: p.network,
+        asset: p.asset,
+        payTo: p.payTo,
+        amount: p.amount,
+        validUntil: BigInt(p.validUntil),
+    };
+}
+export async function signReceipt(payload, account) {
+    if (!account.signTypedData)
+        throw new Error('account cannot sign typed data');
+    const signature = await account.signTypedData({
+        domain: RECEIPT_DOMAIN,
+        types: RECEIPT_TYPES,
+        primaryType: 'Receipt',
+        message: receiptMessage(payload),
+    });
+    return { format: 'eip712', payload, signature };
+}
+export async function signOffer(payload, account, acceptIndex) {
+    if (!account.signTypedData)
+        throw new Error('account cannot sign typed data');
+    const signature = await account.signTypedData({
+        domain: OFFER_DOMAIN,
+        types: OFFER_TYPES,
+        primaryType: 'Offer',
+        message: offerMessage(payload),
+    });
+    return acceptIndex === undefined
+        ? { format: 'eip712', payload, signature }
+        : { format: 'eip712', payload, signature, acceptIndex };
+}
+/** 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 async function verifyReceipt(artifact, expectedSigner) {
+    if (artifact.format !== 'eip712')
+        return { valid: false, reason: 'jws verification not implemented in v0' };
+    try {
+        const signer = await recoverTypedDataAddress({
+            domain: RECEIPT_DOMAIN,
+            types: RECEIPT_TYPES,
+            primaryType: 'Receipt',
+            message: receiptMessage(artifact.payload),
+            signature: artifact.signature,
+        });
+        if (expectedSigner && signer.toLowerCase() !== expectedSigner.toLowerCase()) {
+            return { valid: false, signer, reason: 'signer does not match expected authorization key' };
+        }
+        return { valid: true, signer };
+    }
+    catch (e) {
+        return { valid: false, reason: e instanceof Error ? e.message : 'signature recovery failed' };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+/** Wire types for the merged x402 `offer-receipt` extension (spec: x402-foundation/x402
+ * specs/extensions/extension-offer-and-receipt.md, fetched 2026-07-07). The wire shape is
+ * declared unstable upstream; everything outside this module treats these as opaque via
+ * the codec functions, so upstream churn lands here only. */
+export interface ReceiptPayload {
+    version: 1;
+    /** CAIP-2, e.g. "eip155:8453" */
+    network: string;
+    resourceUrl: string;
+    payer: string;
+    /** unix seconds */
+    issuedAt: number;
+    /** tx hash, or "" when privacy-minimal (EIP-712 empty-optional rule) */
+    transaction: string;
+}
+export interface OfferPayload {
+    version: 1;
+    resourceUrl: string;
+    scheme: string;
+    network: string;
+    asset: string;
+    payTo: string;
+    amount: string;
+    /** unix seconds; 0 = absent (EIP-712 zero-optional rule) */
+    validUntil: number;
+}
+export type SignedArtifact<P> = {
+    format: 'eip712';
+    payload: P;
+    signature: `0x${string}`;
+    acceptIndex?: number;
+} | {
+    format: 'jws';
+    signature: string;
+    acceptIndex?: number;
+};
+export type SignedReceipt = SignedArtifact<ReceiptPayload>;
+export type SignedOffer = SignedArtifact<OfferPayload>;
+/** ACP/UCP converged adjustment vocabulary (verified against both specs 2026-07-07).
+ * Adopted verbatim so records round-trip card-rail order objects unchanged. */
+export type AdjustmentType = 'refund' | 'return' | 'credit' | 'price_adjustment' | 'dispute' | 'cancellation';
+export type AdjustmentStatus = 'pending' | 'completed' | 'failed';
+export interface Adjustment {
+    type: AdjustmentType;
+    status: AdjustmentStatus;
+    /** minor units, tax-inclusive, as string */
+    amount: string;
+    currency: string;
+    reason?: string;
+    /** digest of the receipt/record this adjusts — the hash-chain link */
+    adjusts: `0x${string}`;
+}
+/** Tersign compliance record v1 — a SEPARATE artifact bound to the base receipt by digest.
+ * The base receipt's EIP-712 schema is fixed upstream; extending it would break signatures,
+ * so compliance data composes by reference. MINIMAL tier ≈ EU VAT Art 226b simplified-invoice
+ * content (legally sufficient sub-€100); FULL tier adds EN 16931-aligned fields. */
+export interface ComplianceRecordV1 {
+    version: 1;
+    /** keccak256 of the canonicalized base receipt artifact */
+    receiptDigest: `0x${string}`;
+    /** sequential per issuer (Art 226(2)); assigned by the ledger when countersigned */
+    seq?: number;
+    issuedAt: number;
+    issuer: {
+        name: string;
+        /** VAT ID / JP T-number / HK BR no. — labeled by jurisdiction */
+        taxId?: string;
+        jurisdiction: string;
+    };
+    buyer?: {
+        /** signed principal identity — AP2 mandate subject / deployer, never a bare wallet */
+        principal?: string;
+        /** AP2 Checkout/Payment-Mandate reference (hash), when present */
+        mandateRef?: `0x${string}`;
+    };
+    /** nature of goods/services (Art 226b(c)) */
+    supply: {
+        description: string;
+        category?: string;
+    };
+    lines?: Array<{
+        description: string;
+        quantity: string;
+        unitPrice: string;
+        net: string;
+    }>;
+    tax: {
+        scheme: 'none' | 'vat' | 'gst' | 'jct' | 'sales';
+        currency: string;
+        /** total tax, minor units; omit only when scheme = none */
+        amount?: string;
+        breakdown?: Array<{
+            rate: string;
+            taxable: string;
+            tax: string;
+            category?: string;
+        }>;
+    };
+    /** fiat-equivalent valuation of the crypto settlement at issuance (1099-DA / profits-tax) */
+    settlement?: {
+        fiat: {
+            amount: string;
+            currency: string;
+            source: string;
+            asOf: number;
+        };
+        txHash?: string;
+    };
+    /** hash-chain to the record this corrects/refunds (Art 226b(e); ViDA corrective-invoice ref) */
+    refundOf?: `0x${string}`;
+    adjustment?: Adjustment;
+    /** retention floor in years; default 7 (HK IRO s.51C ≥ MiCA 5+2) */
+    retentionYears: number;
+}
+/** EIP-712-signed attestation over a compliance record. The record itself is JSON (schema may
+ * evolve); the attestation schema stays fixed by binding digests only. */
+export interface ComplianceAttestationPayload {
+    version: 1;
+    recordDigest: `0x${string}`;
+    receiptDigest: `0x${string}`;
+    issuedAt: number;
+}
+export type SignedComplianceRecord = {
+    record: ComplianceRecordV1;
+    attestation: SignedArtifact<ComplianceAttestationPayload>;
+};

package/dist/types.js

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

package/dist/verify-bin.d.ts

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

package/dist/verify-bin.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/** tersign-verify — third-party receipt verification. No API key, no trust in Tersign:
+ * signature recovery is local, and the ledger check only asks the public endpoint whether
+ * the counter-signed hash-chain holds.
+ *
+ *   tersign-verify <receipt.json> [--signer 0xseller] [--ledger https://…]
+ *   tersign-verify <0xdigest> --ledger https://…
+ */
+import { readFileSync } from 'node:fs';
+import { digestOf } from './canonical.js';
+import { verifyReceipt } from './receipt/eip712.js';
+import { verifyComplianceRecord } from './compliance/record.js';
+function arg(flag) {
+    const i = process.argv.indexOf(flag);
+    return i > 0 ? process.argv[i + 1] : undefined;
+}
+function fail(msg) {
+    console.error(`INVALID: ${msg}`);
+    process.exit(1);
+}
+const target = process.argv[2];
+if (!target || target.startsWith('--')) {
+    console.error('usage: tersign-verify <receipt.json | 0xdigest> [--signer 0xaddr] [--ledger url]');
+    process.exit(2);
+}
+const ledger = arg('--ledger');
+const expectedSigner = arg('--signer');
+async function checkLedger(digest) {
+    if (!ledger)
+        return;
+    const res = await fetch(`${ledger.replace(/\/$/, '')}/v1/receipts/${digest}/verify`);
+    const body = (await res.json());
+    if (!body.found)
+        fail(`ledger has no record of ${digest}`);
+    if (!body.chainOk)
+        fail('ledger record found but the counter-signed hash-chain does NOT verify');
+    console.log(`ledger:    counter-signed OK (seller ${body.sellerId}, seq ${body.seq}, ledger key ${body.ledgerSigner})`);
+}
+if (/^0x[0-9a-f]{64}$/i.test(target)) {
+    if (!ledger)
+        fail('a bare digest can only be checked against a ledger — pass --ledger');
+    await checkLedger(target);
+    console.log('VALID');
+    process.exit(0);
+}
+const parsed = JSON.parse(readFileSync(target, 'utf8'));
+const receipt = 'payload' in parsed || 'signature' in parsed ? parsed : parsed.receipt;
+const record = 'receipt' in parsed ? parsed.record : undefined;
+const result = await verifyReceipt(receipt, expectedSigner);
+if (!result.valid)
+    fail(`receipt signature: ${result.reason}`);
+const digest = digestOf(receipt);
+console.log(`signature: OK (signer ${result.signer})`);
+console.log(`digest:    ${digest}`);
+if (record) {
+    const rec = await verifyComplianceRecord(record, expectedSigner);
+    if (!rec.valid)
+        fail(`compliance record: ${rec.reason}`);
+    if (record.record.receiptDigest !== digest)
+        fail('compliance record is bound to a DIFFERENT receipt');
+    console.log(`record:    OK (bound to receipt, signer ${rec.signer})`);
+}
+await checkLedger(digest);
+console.log('VALID');

package/package.json

@@ -1,7 +1,60 @@
 {
   "name": "tersign",
-  "version": "0.0.1",
-  "description": "Tersign — the evidence layer for the agent economy. Name reserved; the SDK lives at @tersign/assure.",
+  "version": "0.1.0",
+  "description": "Tersign \u2014 the evidence layer for the agent economy. Counter-signed receipts, agent action records, idempotency enforcement, refunds, disputes, and jury-ready evidence envelopes for x402/agent-commerce sellers.",
   "license": "MIT",
-  "homepage": "https://github.com/tersignhq"
-}
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "viem": "^2.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "bin": {
+    "tersign-mcp": "dist/mcp/bin.js",
+    "tersign-verify": "dist/verify-bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tersignhq/tersign-js.git"
+  },
+  "homepage": "https://tersign-ledger.kevinn-zhang.workers.dev",
+  "keywords": [
+    "x402",
+    "agent-economy",
+    "evidence",
+    "receipts",
+    "eip-712",
+    "compliance",
+    "disputes",
+    "ai-agents",
+    "mcp",
+    "audit-trail"
+  ]
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};