tersign 0.1.2 → 0.1.4

package/README.md

@@ -1,55 +1,133 @@
-# tersign
+<p align="center">
+  <a href="https://tersign-ledger.kevinn-zhang.workers.dev"><img src="https://raw.githubusercontent.com/tersignhq/.github/main/assets/banner.svg" alt="Tersign — the evidence layer for the agent economy" width="760"></a>
+</p>
 
-**The evidence layer for the agent economy.** When software buys from software, someone has to keep the records straight — this SDK gives agent-commerce sellers counter-signed receipts, tamper-evident action records, and jury-ready evidence envelopes on top of x402 settlement.
+<p align="center">
+  <a href="https://www.npmjs.com/package/tersign"><img src="https://img.shields.io/npm/v/tersign?style=flat-square" alt="npm version"></a>
+  <a href="https://github.com/tersignhq/tersign-js/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/tersign?style=flat-square" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/npm-provenance%20attested-2ea44f?style=flat-square" alt="npm provenance attested">
+  <img src="https://img.shields.io/badge/MCP%20registry-io.github.tersignhq%2Fevidence-1c1c1c?style=flat-square" alt="MCP registry">
+</p>
+
+**Tersign is the evidence layer for the agent economy** — a neutral, counter-signed, hash-chained ledger for agent commerce. Sellers sign EIP-712 receipts; Tersign chains them per seller and counter-signs every entry. When the dispute comes, the transcript is already sealed.
+
+> **Venues rotate. The transcript endures.**
+
+---
+
+## Verify a Real Entry — Right Now
+
+No account. No API key. This is the genesis receipt, `seq 1` on the production chain:
+
+```sh
+npx tersign verify 0xe5874f1ffe87f0a6dd9eb157730f67b86ee4538b125fe30fcc4e165213dd3fc4 --ledger https://tersign-ledger.kevinn-zhang.workers.dev
+```
+
+```text
+ledger: counter-signed OK (seller tersign-first, seq 1 …) VALID
+```
+
+`npx tersign verify <receipt.json | 0xdigest> [--ledger url]` recovers the EIP-712 signature **locally**, then checks the entry against the public chain — yours or anyone's. Prefer raw HTTP? The same proof, no CLI:
+
+```sh
+curl https://tersign-ledger.kevinn-zhang.workers.dev/v1/receipts/0xe5874f1ffe87f0a6dd9eb157730f67b86ee4538b125fe30fcc4e165213dd3fc4/verify
+```
+
+## Chain of Custody
+
+Every entry takes the same path: the seller **signs** the receipt (EIP-712, x402 offer-receipt extension) → Tersign computes the **keccak256 canonical digest** → the digest joins that **seller's hash chain**, each `seq n` bound to `seq n−1` → the neutral ledger **counter-signs** (secp256k1) → **anyone verifies**, and any venue gets a serialized envelope.
+
+```mermaid
+graph LR
+    A["agent transaction<br/>x402"] --> B["seller-signed receipt<br/>EIP-712"]
+    B --> C["canonical digest<br/>keccak256"]
+    C --> D["per-seller hash chain<br/>seq n binds seq n−1"]
+    D --> E["neutral counter-signature<br/>secp256k1 ledger"]
+    E --> F["verifiable by anyone<br/>venue-ready envelope"]
+```
+
+<sub>Diagram renders on GitHub. On npm, the paragraph above IS the diagram.</sub>
+
+Refunds chain back to the original receipt via `refundOf`. Disputes attach to the digest with objective reason codes. Party statements are structurally segregated behind an `UNVERIFIED` marker — the evidence stays prompt-injection-hardened.
+
+## Enter the Record
 
 ```sh
-npm install tersign
+npm i tersign
 ```
 
-## What it does
-
-- **Signed receipts** — implements the merged x402 `offer-receipt` extension (EIP-712), plus **compliance records** (tax/audit-grade fields: EU Art-226b minimal tier / EN 16931 full tier / HK IRO s.51C retention) bound to the base receipt by digest.
-- **Agent action records** — `ActionRecordV1`: digest-bound, GDPR-minimized evidence of agent actions and disclosures, mapped to EU AI Act Art-50 obligations.
-- **Idempotency enforcement** — the x402 `payment-identifier` extension ships the key; this ships the semantics (replay cache, `Idempotent-Replayed`, 409 in-flight/conflict) with pluggable stores (memory, Cloudflare D1).
-- **Refund orchestration** — corrective records hash-chained via `refundOf` (ViDA-style), ACP/UCP adjustment vocabulary verbatim.
-- **Disputes** — signed dispute/evidence/acceptance-criteria artifacts with objective reason codes; deterministic triage upstream of any arbitration venue.
-- **Evidence envelopes** — package any counter-signed record into a jury-ready submission for external venues (Internet Court slot format, Kleros ERC-1497, UMA claims): digests + a public verify URL, never raw evidence, with party statements structurally segregated from ledger-attested content.
-- **Ledger client** — counter-signature + sequential hash-chaining + evidence-pack exports via the hosted Tersign ledger (optional; the SDK works standalone).
-- **MCP server** — `npx tersign-mcp` exposes the full loop (issue / verify / refund / dispute) as Model Context Protocol tools for agent frameworks.
-- **Third-party verification** — `npx tersign verify <receipt.json | 0xdigest>` recovers signatures and checks the public chain with no account and no trust in Tersign. (Installed: `tersign-verify` works directly.)
-
-## Quick start
-
-```ts
-import { privateKeyToAccount } from 'viem/accounts';
-import { Assure, attachToExtensions } from 'tersign';
-
-const assure = new Assure({
-  signer: privateKeyToAccount(process.env.SELLER_KEY as `0x${string}`),
-  issuer: { name: 'Example API Ltd', jurisdiction: 'HK', taxId: 'BR-12345678' },
-  // ledger: { url: 'https://tersign-ledger.kevinn-zhang.workers.dev', apiKey: '…', sellerId: '…' },
-});
-
-// after your x402 middleware reports settlement:
-const issued = await assure.issueFor({
-  network: 'eip155:8453',
-  resourceUrl: 'https://api.example.com/data',
-  payer: settlement.payer,
-  settledAt: Math.floor(Date.now() / 1000),
-  txHash: settlement.transaction,
-  supplyDescription: 'Market data, per call',
-});
-return Response.json(attachToExtensions(body, issued));
+`withAssure()` wraps your x402 fetch handler so every paid call issues a signed, chained receipt. The full register:
+
+| Capability | In the record |
+|---|---|
+| Receipts | Seller-signed EIP-712 (x402 offer-receipt extension), keccak256 canonical digests |
+| `withAssure()` | x402 fetch-handler adapter — a receipt per paid call |
+| Compliance records | EU Art-226b minimal tier · EN 16931 full tier · HK IRO s.51C retention |
+| Action records | `ActionRecordV1` — GDPR-minimized, EU AI Act Art-50 mapped (Art 50 binds 2026-08-02) |
+| Refunds | Chained to the original receipt via `refundOf` |
+| Disputes v0 | Objective reason codes, evidence submission, adjudication |
+| Venue envelopes | Internet Court (5,000-char slot) · Kleros ERC-1497 · UMA · generic |
+| Evidence packs | `format=art50` · `format=safr` (beta) |
+| Idempotency | In-memory + Cloudflare D1 stores |
+
+## For Agents — the MCP Server
+
+`npx tersign` starts the MCP server (stdio). Official registry entry: `io.github.tersignhq/evidence` (active).
+
+```json
+{
+  "mcpServers": {
+    "tersign": {
+      "command": "npx",
+      "args": ["tersign"],
+      "env": { "TERSIGN_SELLER_KEY": "0x<your-seller-key>" }
+    }
+  }
+}
 ```
 
-## Why not just the official x402 SDK?
+**Tools** — `issue_receipt` · `verify_receipt` · `verify_compliance_record` · `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_ISSUER_NAME` | no | issuer name stamped on compliance records |
+| `TERSIGN_ISSUER_JURISDICTION` | no | issuer jurisdiction stamped on compliance 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>`.
+
+The agent skill `tersign-evidence` ships at [tersignhq/skills](https://github.com/tersignhq/skills).
+
+## The Live Record
+
+- **Ledger + dashboard** — public verify page: https://tersign-ledger.kevinn-zhang.workers.dev/verify
+- **Census** — 1,500+ hash-chained observations across 1,000+ x402 seller endpoints, probed hourly and autonomously. Live counts: https://tersign-prober.kevinn-zhang.workers.dev/v1/prober/stats
+
+## Machine Surfaces
+
+Full URLs, readable without auth. If you are an agent, start here.
 
-The official extension gives you the receipt *format*. This gives you the *operation*: replay enforcement (x402 #452 punts it to the app layer), refund records, compliance-grade fields your accountant recognizes, dispute-ready evidence — and third-party verifiability via counter-signed hash chains, so your receipts are exhibits, not testimony.
+| Surface | Address |
+|---|---|
+| npm package | `tersign` — https://www.npmjs.com/package/tersign |
+| MCP registry | `io.github.tersignhq/evidence` |
+| ARD catalog (Agentic Resource Discovery) | https://tersign-ledger.kevinn-zhang.workers.dev/.well-known/ai-catalog.json |
+| Verify API | `GET https://tersign-ledger.kevinn-zhang.workers.dev/v1/receipts/{digest}/verify` |
+| Envelope API | `GET https://tersign-ledger.kevinn-zhang.workers.dev/v1/receipts/{digest}/envelope?venue={internet-court\|kleros\|uma\|generic}` |
+| Ledger stats | `GET https://tersign-ledger.kevinn-zhang.workers.dev/v1/stats` |
+| Ledger signer | `GET https://tersign-ledger.kevinn-zhang.workers.dev/v1/ledger` |
+| llms.txt | https://raw.githubusercontent.com/tersignhq/tersign-js/main/llms.txt |
+| Genesis verify | `npx tersign verify 0xe5874f1ffe87f0a6dd9eb157730f67b86ee4538b125fe30fcc4e165213dd3fc4 --ledger https://tersign-ledger.kevinn-zhang.workers.dev` |
 
-## Verify without trusting anyone
+---
 
-Every counter-signed record is publicly checkable: [live ledger + verification](https://tersign-ledger.kevinn-zhang.workers.dev/verify) — no account, no API key. Venues rotate; the transcript endures.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tersignhq/.github/main/assets/seal.svg" alt="Tersign seal" width="72">
+</p>
 
-## Status
+<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>
 
-v0.1 — EIP-712 receipts, MINIMAL-tier compliance records, action records, disputes v0, evidence envelopes (Internet Court / Kleros / UMA), memory + D1 idempotency stores, MCP server, verify CLI. Wire formats are digest-bound and schema-evolvable; cross-implementation vectors are pinned in CI. MIT.
+<p align="center"><sub><b>Venues rotate. The transcript endures.</b></sub></p>

package/dist/cli.js

@@ -3,6 +3,16 @@ const sub = process.argv[2];
 if (sub === undefined || sub === 'mcp') {
     if (sub === 'mcp')
         process.argv.splice(2, 1);
+    // Bare `npx tersign` with no config is almost always a curious human, not an MCP client —
+    // greet them with the wiring instructions instead of a stack trace.
+    if (!process.env.TERSIGN_SELLER_KEY) {
+        console.error('tersign: this command starts the MCP server, which needs TERSIGN_SELLER_KEY set.\n\n' +
+            'Wire it into your MCP client config:\n' +
+            '  { "mcpServers": { "tersign": { "command": "npx", "args": ["tersign"],\n' +
+            '      "env": { "TERSIGN_SELLER_KEY": "0x<your-seller-key>" } } } }\n\n' +
+            "Just exploring? Try:  tersign help   ·   tersign verify <receipt.json | 0xdigest> [--ledger url]");
+        process.exit(1);
+    }
     await import('./mcp/bin.js');
 }
 else if (sub === 'verify') {

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.1.2";
+    readonly version: "0.1.4";
 };
 export declare function buildServer(deps: McpDeps): McpServer;

package/dist/mcp/server.js

@@ -45,7 +45,7 @@ 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.1.2' };
+export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.1.4' };
 export function buildServer(deps) {
     const server = new McpServer(MCP_SERVER_IDENTITY);
     server.registerTool('issue_receipt', {

package/dist/verify-bin.js

@@ -43,7 +43,20 @@ if (/^0x[0-9a-f]{64}$/i.test(target)) {
     console.log('VALID');
     process.exit(0);
 }
-const parsed = JSON.parse(readFileSync(target, 'utf8'));
+let raw;
+try {
+    raw = readFileSync(target, 'utf8');
+}
+catch {
+    fail(`cannot read '${target}' — pass a receipt JSON file that exists, or a 0x… digest with --ledger`);
+}
+let parsed;
+try {
+    parsed = JSON.parse(raw);
+}
+catch {
+    fail(`'${target}' is not valid JSON — expected a signed receipt file`);
+}
 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tersign",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
   "type": "module",