@onchaindiligence/sdk 0.2.0 → 0.3.1

package/README.md

@@ -2,6 +2,8 @@
 
 A small, typed client for the [OnchainDiligence](https://onchaindiligence.com) compliance API. It hides the HTTP `402` pay-per-call flow entirely: you configure a funded account once, and every method transparently answers the payment challenge, settles on Tempo, and returns a typed, signed result.
 
+A separate `@onchaindiligence/sdk/commerce` export orchestrates an *agent's own merchant payment lifecycle* (open → preflight → execute → observe/finalize) against `mcp.onchaindiligence.com` — see [Commerce client](#commerce-client-agent-payments) below.
+
 ```bash
 npm install @onchaindiligence/sdk mppx viem
 ```
@@ -37,8 +39,8 @@ const both = await od.diligence({
   company: '00000006',
 })
 
-// Anchor an attestation on Tempo, then verify it (free)
-const anchored = await od.anchor(wallet.data ? wallet.attestation.signature! : '')
+// Anchor the complete authentic attestation envelope, then check it (free)
+const anchored = await od.anchor(wallet)
 const status = await od.anchored(wallet.attestation.signature!)
 ```
 
@@ -47,7 +49,17 @@ Every paid response is a `Signed<T>` — the result plus an `attestation` you ca
 ```ts
 {
   data: { address: '0x…', sanctioned: false, /* … */ },
-  attestation: { signed: true, key_id: 'ed25519-…', signature: '…' }
+  attestation: {
+    signed: true,
+    schema_version: 'onchaindiligence.attestation.v2',
+    issuer: 'https://api.onchaindiligence.com',
+    purpose: 'compliance-screening-result',
+    issued_at: '…',
+    key_id: 'ed25519-…',
+    algorithm: 'ed25519',
+    canonicalization: 'RFC8785',
+    signature: '…'
+  }
 }
 ```
 
@@ -59,21 +71,96 @@ Every paid response is a `Signed<T>` — the result plus an `attestation` you ca
 | `screenName(name, { threshold? })` | `Signed<NameScreenResult>` | yes |
 | `verifyCompany(number)` | `Signed<CompanyResult>` | yes |
 | `diligence({ wallet?, company? })` | `Signed<DiligenceResult>` | yes |
-| `anchor(signature)` | `Signed<AnchorResult>` | yes |
+| `anchor(envelope)` | `Signed<AnchorResult>` | yes |
 | `anchored(signature)` | `AnchorStatus` | free |
 | `health()` | service status | free |
 
 Errors throw `OnchainDiligenceError` with the HTTP `status` and a message.
 
-## Verifying an attestation
+## Commerce client (agent payments)
+
+```bash
+npm install @onchaindiligence/sdk
+```
+
+A separate, `@onchaindiligence/sdk/commerce` export orchestrates an agent's
+merchant payment lifecycle against `mcp.onchaindiligence.com`:
+
+> **Keep your wallet. Keep your payment provider. Add OCD once.**
 
-The `signature` is an Ed25519 signature over the response data plus issue metadata. Off-chain verification is straightforward with the public key at `/.well-known/attestation-key`:
+OCD evaluates a proposed payment against your policy and observes/reconciles
+what actually settled. It never holds a key, never authorizes a payment, and
+never replaces your executor's own authorization — see
+[`CommerceExecutor`](src/commerce/executor.ts).
 
 ```ts
-import { verify } from '@noble/ed25519'
-// fetch the public key, reconstruct the signed bytes, then verify(signature, message, pubKey)
+import { createCommerceClient, MockCommerceExecutor, apiPurchasePolicy } from '@onchaindiligence/sdk/commerce'
+import { NodeFileRecoveryStore } from '@onchaindiligence/sdk/commerce/node' // Node-only; browser code implements CommerceRecoveryStore itself
+
+const ocd = createCommerceClient({ recovery: new NodeFileRecoveryStore('./ocd-recovery') })
+
+const { policy } = apiPurchasePolicy({ maxAmount: '1.00', allowedNetwork: 'eip155:8453', allowedAsset: BASE_USDC })
+const op = await ocd.open({ action: proposedPayment, policy })
+
+const evaluation = await op.preflight()
+if (evaluation.kind === 'blocked' || evaluation.kind === 'approval-required') return handleThat(evaluation)
+
+const execution = await op.execute({ executor: myExecutor }) // e.g. new X402BaseUsdcExecutor({ signer: toClientEvmSigner(account) })
+if (execution.kind !== 'execution-recorded') return handleThat(execution)
+
+const result = await op.observeAndFinalize() // safe to retry while kind === 'pending'
+console.log(result.receipt.receipt.execution.status) // read the fact, never infer "success" from existence
 ```
 
+See **[examples/quickstart.ts](examples/quickstart.ts)** for the complete,
+runnable, ~20-line integration (uses a mocked executor and an in-process demo
+server — `npx tsx examples/quickstart.ts` costs nothing and needs no wallet).
+
+Key pieces:
+
+| Export | What it is |
+|---|---|
+| `createCommerceClient` / `CommerceOperation` | Orchestrates open → preflight → execute → observe/finalize. |
+| `CommerceExecutor` | The contract your wallet/payment provider implements: `prepare` → `submit` → `resume`. Independent of OCD's policy decision by construction. |
+| `X402BaseUsdcExecutor` | The one production executor: Base mainnet, USDC, x402 v2 exact. Its `recoveryMode` is honestly `'manual'` — see the file's own header for why. |
+| `MockCommerceExecutor` | Deterministic, no-network executor for tests/docs. |
+| `CommerceRecoveryStore` | Durable identity storage — required, no safe default. `NodeFileRecoveryStore` (`@onchaindiligence/sdk/commerce/node` — Node-only, wraps `node:fs`) survives a restart; implement the interface against your own database for a multi-instance deployment, or proxy it through your own local server for a browser UI (never store the secret fields in browser storage). `InMemoryRecoveryStore` is test-only. |
+| `apiPurchasePolicy` / `approvalAboveThresholdPolicy` / `fixedRecipientPolicy` | Three starter policy templates — ordinary strict policy objects, no new semantics. |
+| `buildEvidenceExport` | A minimal, deterministic, secret-free evidence manifest. |
+| `client.getReceipt()` / `client.verifyReceipt()` | Free, structured, reuse OCD's converged verification contract — a convenience, not a stronger trust model than verifying offline yourself. |
+
+Every lifecycle result is a discriminated union (`evaluation.kind`,
+`execution.kind`, `result.kind`) — `'pending'` states carry a machine-readable
+`safeNextAction`, `retryAfterSeconds`, and `mayAlreadyHavePaid`, so a `pending`
+outcome is never confused with failure or with "safe to pay again."
+
+## Offline verification
+
+The security-sensitive verifier performs zero network access. Supply key records
+you independently chose to trust; merely downloading a public key does not make
+it a trusted publisher identity. Version 2 uses domain-separated RFC 8785
+canonical JSON, while explicit legacy v1 attestations retain their original
+verification path.
+
+```ts
+import { verifyAttestationOffline } from '@onchaindiligence/sdk'
+
+const result = await verifyAttestationOffline(signed, trustedRegistry)
+// result.state is exactly VALID, INVALID, or UNVERIFIABLE
+console.log(result.components.signature, result.components.key_window)
+```
+
+`verifyAttestationOnline()` is a separate convenience wrapper. It only treats
+the discovered registry as identity authority when the caller explicitly sets
+`trustRegistry: true` (or supplies an approval callback). The class method
+`od.verifyAttestation()` remains an online compatibility wrapper for existing
+clients; new security-sensitive code should use the standalone offline API.
+
+The signature authenticates the signer's `issued_at` assertion. It does not by
+itself prove objective time. A separately verified on-chain anchor can establish
+an external “existed no later than” bound; freshness, key validity, signature
+validity, and anchor status remain separate checks.
+
 **On-chain verification — read this first.** The EVM has no native Ed25519 precompile (only `ecrecover` for ECDSA), so verifying an Ed25519 signature *inside* a Solidity contract is expensive and non-trivial — it requires a full Ed25519 implementation in the contract. For most use cases, verify off-chain. If you need on-chain proof that a check happened, prefer the **anchoring** flow (`anchor()` / `anchored()`), which records the attestation hash on Tempo so a contract can check a `bytes32` rather than recover an Ed25519 signature. That's the cheaper, EVM-friendly path to on-chain verifiability.
 
 ## License

package/conformance/attestation-v1-v2-vectors.json

@@ -0,0 +1,98 @@
+{
+  "corpus_version": 1,
+  "description": "Test-only OnChainDiligence v1/v2 trust-foundation fixtures. No production key material.",
+  "verifier_options": { "now": "2026-08-27T12:01:00.000Z" },
+  "trust_records": {
+    "active": {
+      "key_id": "ed25519-BuP9j9opu2CrWVV9",
+      "algorithm": "ed25519",
+      "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=\n-----END PUBLIC KEY-----\n",
+      "status": "active",
+      "valid_from": "2026-08-27T00:00:00.000Z",
+      "valid_until": null,
+      "status_changed_at": "2026-08-27T00:00:00.000Z"
+    },
+    "retired": {
+      "key_id": "ed25519-BuP9j9opu2CrWVV9",
+      "algorithm": "ed25519",
+      "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=\n-----END PUBLIC KEY-----\n",
+      "status": "retired",
+      "valid_from": "2026-08-27T00:00:00.000Z",
+      "valid_until": "2026-08-27T12:30:00.000Z",
+      "status_changed_at": "2026-08-27T12:30:00.000Z"
+    },
+    "compromised": {
+      "key_id": "ed25519-BuP9j9opu2CrWVV9",
+      "algorithm": "ed25519",
+      "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=\n-----END PUBLIC KEY-----\n",
+      "status": "compromised",
+      "valid_from": "2026-08-27T00:00:00.000Z",
+      "valid_until": null,
+      "status_changed_at": "2026-08-27T12:30:00.000Z",
+      "compromised_at": "2026-08-27T12:30:00.000Z"
+    }
+  },
+  "envelopes": {
+    "valid_v2": {
+      "data": { "address": "0x0000000000000000000000000000000000000001", "nested": { "empty": [], "unicode": "€ 😀" }, "sanctioned": false },
+      "attestation": {
+        "signed": true,
+        "schema_version": "onchaindiligence.attestation.v2",
+        "issuer": "https://api.onchaindiligence.com",
+        "purpose": "compliance-screening-result",
+        "issued_at": "2026-08-27T12:00:00.000Z",
+        "key_id": "ed25519-BuP9j9opu2CrWVV9",
+        "algorithm": "ed25519",
+        "canonicalization": "RFC8785",
+        "signature": "Q6znt7824vydlzqVP702c_U8krT3eqc30mmBtp2QYmfDC2vVj5LabHdRjeGbfE65aJGny3B_M6SzhcmSasADDQ"
+      }
+    },
+    "tampered_payload": {
+      "data": { "address": "0x0000000000000000000000000000000000000001", "nested": { "empty": [], "unicode": "€ 😀" }, "sanctioned": true },
+      "attestation": {
+        "signed": true,
+        "schema_version": "onchaindiligence.attestation.v2",
+        "issuer": "https://api.onchaindiligence.com",
+        "purpose": "compliance-screening-result",
+        "issued_at": "2026-08-27T12:00:00.000Z",
+        "key_id": "ed25519-BuP9j9opu2CrWVV9",
+        "algorithm": "ed25519",
+        "canonicalization": "RFC8785",
+        "signature": "Q6znt7824vydlzqVP702c_U8krT3eqc30mmBtp2QYmfDC2vVj5LabHdRjeGbfE65aJGny3B_M6SzhcmSasADDQ"
+      }
+    },
+    "valid_v1": {
+      "data": { "address": "0x0000000000000000000000000000000000000001", "nested": { "empty": [], "unicode": "€ 😀" }, "sanctioned": false },
+      "attestation": {
+        "signed": true,
+        "issued_at": "2026-08-27T12:00:00.000Z",
+        "key_id": "ed25519-BuP9j9opu2CrWVV9",
+        "algorithm": "ed25519",
+        "signature": "XOqtW1NgrkkPTIYmcHEEv86WRrQGzK4nEkf7qfXFVRrCwhlEVtffFFeawmaoLHQP5qdPJLugP_-8-OQJQqooDQ"
+      }
+    },
+    "unsupported_version": {
+      "data": { "address": "0x0000000000000000000000000000000000000001", "nested": { "empty": [], "unicode": "€ 😀" }, "sanctioned": false },
+      "attestation": {
+        "signed": true,
+        "schema_version": "onchaindiligence.attestation.v9",
+        "issuer": "https://api.onchaindiligence.com",
+        "purpose": "compliance-screening-result",
+        "issued_at": "2026-08-27T12:00:00.000Z",
+        "key_id": "ed25519-BuP9j9opu2CrWVV9",
+        "algorithm": "ed25519",
+        "canonicalization": "RFC8785",
+        "signature": "eZ6re44eR3zy8PXp93WJ7PDPRy-bovg5LNzh4uxjJpPIlhJIvOnWkSpTZIOPIJT9QG4GMRCiPL_jg9CHYtgtDQ"
+      }
+    }
+  },
+  "fixtures": [
+    { "id": "valid-v2-active", "expected_state": "VALID", "envelope": "valid_v2", "trust_records": ["active"] },
+    { "id": "valid-v2-retired", "expected_state": "VALID", "envelope": "valid_v2", "trust_records": ["retired"] },
+    { "id": "compromised-key", "expected_state": "INVALID", "envelope": "valid_v2", "trust_records": ["compromised"] },
+    { "id": "tampered-payload", "expected_state": "INVALID", "envelope": "tampered_payload", "trust_records": ["active"] },
+    { "id": "unknown-key", "expected_state": "UNVERIFIABLE", "envelope": "valid_v2", "trust_records": [] },
+    { "id": "valid-v1-legacy", "expected_state": "VALID", "envelope": "valid_v1", "trust_records": ["active"] },
+    { "id": "unsupported-version", "expected_state": "UNVERIFIABLE", "envelope": "unsupported_version", "trust_records": ["active"] }
+  ]
+}

package/conformance/rfc8785-vectors.json

@@ -0,0 +1,31 @@
+{
+  "corpus_version": 1,
+  "source": "RFC 8785 sections 3.2.2 and 3.2.3, plus OnChainDiligence parser policy",
+  "canonicalization": [
+    {
+      "id": "recursive-order-arrays-empty-negative-zero",
+      "input": { "z": [], "n": -0, "a": { "y": true, "x": ["b", "a"], "empty": {} } },
+      "expected": "{\"a\":{\"empty\":{},\"x\":[\"b\",\"a\"],\"y\":true},\"n\":0,\"z\":[]}"
+    },
+    {
+      "id": "rfc8785-unicode-property-order",
+      "input": { "€": "Euro Sign", "\r": "Carriage Return", "דּ": "Hebrew Letter Dalet With Dagesh", "1": "One", "😀": "Emoji: Grinning Face", "€": "Control", "ö": "Latin Small Letter O With Diaeresis" },
+      "expected": "{\"\\r\":\"Carriage Return\",\"1\":\"One\",\"€\":\"Control\",\"ö\":\"Latin Small Letter O With Diaeresis\",\"€\":\"Euro Sign\",\"😀\":\"Emoji: Grinning Face\",\"דּ\":\"Hebrew Letter Dalet With Dagesh\"}"
+    },
+    {
+      "id": "rfc8785-numbers-and-escapes",
+      "input": { "numbers": [333333333.3333333, 1e30, 4.5, 0.002, 1e-27], "text": "line\n\"\\" },
+      "expected": "{\"numbers\":[333333333.3333333,1e+30,4.5,0.002,1e-27],\"text\":\"line\\n\\\"\\\\\"}"
+    },
+    {
+      "id": "boundary-safe-integers",
+      "input": [-9007199254740991, 9007199254740991],
+      "expected": "[-9007199254740991,9007199254740991]"
+    }
+  ],
+  "invalid_json": [
+    { "id": "duplicate-key", "input": "{\"data\":1,\"data\":2}", "error_code": "duplicate_key" },
+    { "id": "unsafe-positive-integer", "input": "{\"n\":9007199254740992}", "error_code": "unsafe_integer" },
+    { "id": "unsafe-negative-integer", "input": "{\"n\":-9007199254740992}", "error_code": "unsafe_integer" }
+  ]
+}

package/dist/commerce/client.d.ts

@@ -0,0 +1,134 @@
+/**
+ * client.ts — createCommerceClient (D2.5, Section 1).
+ *
+ * Orchestrates: open/resume -> preflight -> execute -> observe/finalize,
+ * calling onchaindiligence-mcp's D2.4 HTTP surface (POST /operations,
+ * POST /x402/lifecycle/preflight-payment, POST /operations/:id/execution-bindings(+/state),
+ * POST /operations/:id/finalize) while persisting every durable identity to
+ * the caller-supplied CommerceRecoveryStore BEFORE the network call that
+ * could make it ambiguous — never after.
+ *
+ * This class does NOT reimplement any D2.4 guarantee (idempotency, binding
+ * strength, finality) — it is a thin, honest orchestrator over the service
+ * primitives that already provide them. See each method for exactly which
+ * server endpoint it calls and why the local persistence is ordered the way
+ * it is.
+ */
+import type { CommerceAction, CommercePolicy, CommercePublication, OperationStatus, ReceiptEnvelope } from './types.js';
+import type { CommerceExecutor } from './executor.js';
+import type { CommerceRecoveryStore, CommerceRecoveryRecord } from './recoveryStore.js';
+import { type PreflightEvaluation, type ExecutionRecord, type FinalizeResult, type ResumeResult } from './results.js';
+import { type EvidenceExportManifest } from './evidenceExport.js';
+export declare class RecoveryRequiredError extends Error {
+    constructor(operationId: string);
+}
+export interface CreateCommerceClientOptions {
+    /** Base URL of the OCD MCP/x402 server. Defaults to production. */
+    endpoint?: string;
+    /** Durable recovery store. Required -- see recoveryStore.ts. There is no safe default. */
+    recovery: CommerceRecoveryStore;
+    /** When verifyReceipts is true, receipts returned by preflight/finalize are additionally checked via the free /verify-receipt endpoint (D2.5 Section 7) before being surfaced. Off by default: verification is a distinct concern a caller can invoke on its own via client.verifyReceipt(). */
+    trust?: {
+        verifyReceipts?: boolean;
+    };
+    fetch?: typeof globalThis.fetch;
+}
+export interface OpenParams {
+    /** If set and a local recovery record already exists for it, resumes that operation instead of creating a new one -- see this file's header. */
+    operationId?: string;
+    /** Developer-facing label for logs/UI only; never sent to OCD. */
+    intent?: string;
+    action: CommerceAction;
+    policy: CommercePolicy;
+    publication?: CommercePublication;
+}
+export declare class OnchainDiligenceCommerceClient {
+    private readonly endpoint;
+    private readonly recovery;
+    private readonly fetchImpl;
+    private readonly trust;
+    constructor(options: CreateCommerceClientOptions);
+    /** @internal */
+    apiFetch(path: string, init?: RequestInit): Promise<Response>;
+    /** @internal */
+    readError(res: Response): Promise<string>;
+    /** @internal */
+    recoveryStore(): CommerceRecoveryStore;
+    /** @internal */
+    trustOptions(): {
+        verifyReceipts?: boolean;
+    };
+    /** Opens a new operation, or resumes one already known locally by operationId. Never silently creates a second operation for an id that exists locally with different intent. */
+    open(params: OpenParams): Promise<CommerceOperation>;
+    /** Explicit resume after restart/lost-response, per D2.5 Section 6. Returns recovery-failed rather than throwing, since "the credential turned out to be wrong" is an expected, handleable outcome, not a programming error. */
+    resume(operationId: string, recoveryCredential: string): Promise<ResumeResult>;
+    /** Returns a CommerceOperation for an operation already known to the recovery store, without any network call. Use after resume() or across a process restart. */
+    load(operationId: string): Promise<CommerceOperation | null>;
+    /** D2.5 Section 7: free, structured, reuses the server's converged verifier -- no local re-implementation. */
+    verifyReceipt(receiptIdOrEnvelope: string | ReceiptEnvelope): Promise<{
+        state: 'VALID' | 'INVALID' | 'UNVERIFIABLE';
+        code: string;
+        message: string;
+    }>;
+    /** D2.5 Section 7: free, structured lookup by exact receipt id. */
+    getReceipt(receiptId: string): Promise<ReceiptEnvelope | null>;
+}
+export declare function createCommerceClient(options: CreateCommerceClientOptions): OnchainDiligenceCommerceClient;
+export declare class CommerceOperation {
+    readonly operationId: string;
+    private readonly client;
+    private record;
+    private pendingPreflightInput;
+    private lastCommerceReceiptId;
+    private lastLifecycleEvidence;
+    /** Serializes execute() calls against THIS operation instance -- see execute()'s header comment for why. */
+    private executeQueue;
+    constructor(client: OnchainDiligenceCommerceClient, record: CommerceRecoveryRecord);
+    /** @internal */
+    setPendingPreflightInput(action: CommerceAction, policy: CommercePolicy, publication?: CommercePublication): void;
+    /** @internal -- exposed for evidence export and tests. */
+    currentRecord(): CommerceRecoveryRecord;
+    private reload;
+    private casUpdate;
+    /**
+     * Claims `clientSubmissionKey` for a fresh submission attempt -- but
+     * NEVER by blindly overwriting a value a concurrent claimant already won.
+     * Unlike casUpdate (which re-applies the SAME patch after a conflict,
+     * correct for "set this field to this exact value regardless"), a claim
+     * is "set this field to MY value ONLY IF NO ONE ELSE HAS ALREADY SET IT"
+     * -- so a conflict here means re-reading and checking on which value
+     * actually won, not retrying with a new one. This is what closes the race
+     * two concurrent execute() calls (in-process, via a shared store across
+     * processes, or across a restart) would otherwise have on this field.
+     */
+    private claimSubmissionSlot;
+    status(): Promise<OperationStatus>;
+    preflight(): Promise<PreflightEvaluation>;
+    private evaluationFromReceipt;
+    /**
+     * Serialized per operation instance (Section 15 test #9: "concurrent
+     * calls cannot cause duplicate submit"). Two overlapping execute() calls
+     * against the SAME CommerceOperation object run one after the other, so
+     * the second always observes the first's already-persisted
+     * clientSubmissionKey/executionRequestId/transactionHash and resumes
+     * instead of racing to claim a fresh identity. Cross-PROCESS concurrency
+     * is a different, already-covered case: the server's execution-bindings
+     * endpoint is idempotent by client_submission_key (D2.4), and a correctly
+     * implemented executor (see MockCommerceExecutor, X402BaseUsdcExecutor)
+     * refuses to submit twice for the same key on its own.
+     */
+    execute(params: {
+        executor: CommerceExecutor;
+    }): Promise<ExecutionRecord>;
+    private executeLocked;
+    private applyExecutionOutcome;
+    private updateBindingState;
+    observeAndFinalize(): Promise<FinalizeResult>;
+    /**
+     * Builds a minimal, deterministic evidence manifest from PUBLIC artifacts
+     * only (fetched fresh via the client's public receipt/status calls) —
+     * never touches this.record's secret fields (recoveryCredential,
+     * finalizationCapability), so there is no field here to forget to redact.
+     */
+    exportEvidence(): Promise<EvidenceExportManifest>;
+}