@onchaindiligence/sdk 0.3.1 → 0.4.0

package/README.md

@@ -122,7 +122,8 @@ Key pieces:
 |---|---|
 | `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. |
+| `X402BaseUsdcExecutor` | The one production executor for a local signer: Base mainnet, USDC, x402 v2 exact. Its `recoveryMode` is honestly `'manual'` — see the file's own header for why. |
+| `PayBoxCommerceExecutor` | The one production executor for [PayBox](https://paybox.sh) (an independent, non-custodial agent payment vault): Base mainnet, USDC, one wallet credential. PayBox's own grant/approval rules stay fully independent from OCD's policy decision — an OCD `ALLOW` never overrides a PayBox denial, and a PayBox approval never implies OCD `ALLOW`. Its `recoveryMode` is `'stable-payment-identity'` (PayBox's `get_request` can be polled/resumed against a stable `request_id`, but its `pay_x402` has no idempotency key — see the file's own header). Needs its own small `PayBoxRequestStore` (`InMemoryPayBoxRequestStore` is test-only) because PayBox's request id isn't part of `CommerceRecoveryRecord`. |
 | `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. |

package/dist/commerce/client.d.ts

@@ -19,6 +19,17 @@ 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';
+/**
+ * D2.6 review fix #1: thrown by execute() whenever the operation's
+ * authoritative stored PREFLIGHT decision is not ALLOW (BLOCK,
+ * REQUIRE_APPROVAL, UNKNOWN, or — defensively — undeterminable). This is the
+ * generic, executor-independent enforcement point: no executor (PayBox,
+ * X402BaseUsdcExecutor, a custom one) is ever reachable from execute() for
+ * an operation that didn't authoritatively reach ALLOW.
+ */
+export declare class PreflightNotAllowedError extends Error {
+    constructor(operationId: string, status: string | null);
+}
 export declare class RecoveryRequiredError extends Error {
     constructor(operationId: string);
 }
@@ -89,6 +100,15 @@ export declare class CommerceOperation {
     /** @internal -- exposed for evidence export and tests. */
     currentRecord(): CommerceRecoveryRecord;
     private reload;
+    /**
+     * Fail-closed gate (D2.6 review fix #1): execute() calls this before ANY
+     * executor method is reachable. Prefers the locally cached
+     * `preflightDecisionStatus` (set the moment preflight() itself received an
+     * authoritative decision) — falls back to re-fetching the signed receipt
+     * itself for a record that predates this field, or whose cache write
+     * never landed, rather than ever assuming ALLOW.
+     */
+    private assertPreflightAllowed;
     private casUpdate;
     /**
      * Claims `clientSubmissionKey` for a fresh submission attempt -- but

package/dist/commerce/client.js

@@ -4,6 +4,20 @@ import { buildEvidenceExport } from './evidenceExport.js';
 const DEFAULT_ENDPOINT = 'https://mcp.onchaindiligence.com';
 const OPERATION_HEADER = 'x-ocd-operation-id';
 const RECOVERY_HEADER = 'x-ocd-recovery-credential';
+/**
+ * D2.6 review fix #1: thrown by execute() whenever the operation's
+ * authoritative stored PREFLIGHT decision is not ALLOW (BLOCK,
+ * REQUIRE_APPROVAL, UNKNOWN, or — defensively — undeterminable). This is the
+ * generic, executor-independent enforcement point: no executor (PayBox,
+ * X402BaseUsdcExecutor, a custom one) is ever reachable from execute() for
+ * an operation that didn't authoritatively reach ALLOW.
+ */
+export class PreflightNotAllowedError extends Error {
+    constructor(operationId, status) {
+        super(`cannot execute operation ${operationId}: its stored PREFLIGHT decision is "${status ?? 'unknown'}", not ALLOW -- no executor may be invoked`);
+        this.name = 'PreflightNotAllowedError';
+    }
+}
 export class RecoveryRequiredError extends Error {
     constructor(operationId) {
         super(`no local recovery record for operation ${operationId} -- call client.resume(operationId, recoveryCredential) with the credential you saved when this operation was opened. Never silently start a replacement purchase.`);
@@ -13,6 +27,8 @@ export class RecoveryRequiredError extends Error {
 function mapExecutorIdToProvider(executorId) {
     if (executorId === 'x402-base-usdc-exact')
         return 'x402';
+    if (executorId === 'paybox-x402-base-usdc')
+        return 'paybox';
     return 'other';
 }
 /**
@@ -94,6 +110,7 @@ export class OnchainDiligenceCommerceClient {
             operationId: created.operation_id,
             recoveryCredential: created.recovery_credential,
             preflightReceiptId: null,
+            preflightDecisionStatus: null,
             finalizationCapability: null,
             finalizationCapabilityExpiresAt: null,
             executionRequestId: null,
@@ -121,6 +138,9 @@ export class OnchainDiligenceCommerceClient {
                 operationId,
                 recoveryCredential,
                 preflightReceiptId: status.preflight_receipt_id,
+                // Not known from OperationStatus alone -- execute() re-fetches the
+                // authoritative receipt when this is null (see assertPreflightAllowed()).
+                preflightDecisionStatus: null,
                 finalizationCapability: null,
                 finalizationCapabilityExpiresAt: null,
                 executionRequestId: null,
@@ -188,6 +208,27 @@ export class CommerceOperation {
         if (fresh)
             this.record = fresh;
     }
+    /**
+     * Fail-closed gate (D2.6 review fix #1): execute() calls this before ANY
+     * executor method is reachable. Prefers the locally cached
+     * `preflightDecisionStatus` (set the moment preflight() itself received an
+     * authoritative decision) — falls back to re-fetching the signed receipt
+     * itself for a record that predates this field, or whose cache write
+     * never landed, rather than ever assuming ALLOW.
+     */
+    async assertPreflightAllowed() {
+        if (!this.record.preflightReceiptId) {
+            throw new Error('cannot execute before a READY preflight -- call op.preflight() first and confirm evaluation.kind === "ready"');
+        }
+        let status = this.record.preflightDecisionStatus;
+        if (!status) {
+            const receipt = await this.client.getReceipt(this.record.preflightReceiptId);
+            status = receipt?.receipt.decision.status ?? null;
+        }
+        if (status !== 'ALLOW') {
+            throw new PreflightNotAllowedError(this.operationId, status);
+        }
+    }
     async casUpdate(patch) {
         for (let attempt = 0; attempt < 3; attempt++) {
             try {
@@ -253,8 +294,12 @@ export class CommerceOperation {
             // the record and there is nothing left to evaluate.
             if (this.record.preflightReceiptId) {
                 const receipt = await this.client.getReceipt(this.record.preflightReceiptId);
-                if (receipt)
+                if (receipt) {
+                    if (this.record.preflightDecisionStatus !== receipt.receipt.decision.status) {
+                        await this.casUpdate({ preflightDecisionStatus: receipt.receipt.decision.status }).catch(() => { }); // best-effort cache fill; assertPreflightAllowed() re-fetches if this never lands
+                    }
                     return this.evaluationFromReceipt(receipt, null);
+                }
             }
             throw new Error('no pending preflight input for this operation -- after a restart, call client.open({operationId, action, policy}) to re-supply it before calling preflight() again');
         }
@@ -297,6 +342,7 @@ export class CommerceOperation {
         const result = (await res.json());
         await this.casUpdate({
             preflightReceiptId: result.receipt.receipt.receipt_id,
+            preflightDecisionStatus: result.receipt.receipt.decision.status,
             finalizationCapability: result.finalization.capability,
             finalizationCapabilityExpiresAt: result.finalization.expires_at,
             localPhase: 'preflight-complete',
@@ -358,6 +404,15 @@ export class CommerceOperation {
         // this one sharing the same durable store) may have already claimed or
         // advanced this operation since we last loaded it.
         await this.reload();
+        // D2.6 review fix #1: the ONLY gate that matters is the operation's
+        // actual stored PREFLIGHT decision -- not a caller's evaluation.kind
+        // check, which is application-level discipline this class cannot see or
+        // enforce. preflightReceiptId alone is not sufficient: it is set for
+        // BLOCK and REQUIRE_APPROVAL exactly as it is for ALLOW. Fail closed on
+        // anything that isn't an authoritative ALLOW, before prepare()/submit()/
+        // resume() is ever reachable -- this runs on EVERY execute() call
+        // (including a resumed in-flight submission), not just the first.
+        await this.assertPreflightAllowed();
         // Resuming an in-flight submission: never re-prepare/re-submit.
         if (this.record.clientSubmissionKey && this.record.executionRequestId) {
             if (this.record.transactionHash) {
@@ -393,6 +448,11 @@ export class CommerceOperation {
                 executor_version: executor.version,
                 recovery_capability_class: toRecoveryCapabilityClass(executor.recoveryMode),
                 expected_payer: null,
+                // D2.6: forwarded verbatim into the D2.4 execution binding (and from
+                // there, the lifecycle evidence bundle) so a third-party executor's
+                // own request identity (e.g. a PayBox request id) is durably
+                // correlated to this OCD operation — see PrepareResult.providerReference.
+                provider_reference: prepared.providerReference ?? null,
             }),
         });
         if (!bindingRes.ok) {

package/dist/commerce/executor.d.ts

@@ -35,6 +35,20 @@ export interface PrepareResult {
     /** Executor-specific durable reference to what was prepared (e.g. a validated 402 challenge) — opaque to the orchestrator, round-tripped back into submit()/resume() unchanged. */
     reference: unknown;
     preparedAt: string;
+    /**
+     * Optional third-party execution-provider reference established at
+     * prepare() time (e.g. a PayBox request id, a payment processor's
+     * transaction reference) — UNLIKE `reference`, this is NOT opaque: the
+     * orchestrator forwards it verbatim as `provider_reference` on the
+     * execution-bindings call (D2.6), so it becomes part of the durable
+     * server-side binding and, from there, the D2.4 lifecycle evidence bundle
+     * — letting a receipt reader say "provider request X was associated with
+     * this OCD lifecycle" without OCD ever needing to understand what that
+     * provider's reference means. Omit when the executor has no such
+     * provider-issued identity (e.g. a local wallet signer like
+     * X402BaseUsdcExecutor).
+     */
+    providerReference?: string | null;
 }
 export type ExecutionOutcome = {
     status: 'transaction-known';

package/dist/commerce/index.d.ts

@@ -24,6 +24,7 @@ export * from './executor.js';
 export * from './recoveryStore.js';
 export * from './mockExecutor.js';
 export * from './x402Executor.js';
+export * from './payboxExecutor.js';
 export * from './client.js';
 export * from './policyTemplates.js';
 export * from './evidenceExport.js';

package/dist/commerce/index.js

@@ -24,6 +24,7 @@ export * from './executor.js';
 export * from './recoveryStore.js';
 export * from './mockExecutor.js';
 export * from './x402Executor.js';
+export * from './payboxExecutor.js';
 export * from './client.js';
 export * from './policyTemplates.js';
 export * from './evidenceExport.js';

package/dist/commerce/node.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @onchaindiligence/sdk/commerce/node — Node-only durable store
+ * implementations (wrap `node:fs`), kept out of the main `./commerce`
+ * barrel so importing that barrel from a browser bundle can never
+ * accidentally pull in Node built-ins. See client.ts's own header for why
+ * this separation exists.
+ */
+export * from './nodeFileRecoveryStore.js';
+export * from './nodeFilePayboxRequestStore.js';

package/dist/commerce/node.js

@@ -0,0 +1,9 @@
+/**
+ * @onchaindiligence/sdk/commerce/node — Node-only durable store
+ * implementations (wrap `node:fs`), kept out of the main `./commerce`
+ * barrel so importing that barrel from a browser bundle can never
+ * accidentally pull in Node built-ins. See client.ts's own header for why
+ * this separation exists.
+ */
+export * from './nodeFileRecoveryStore.js';
+export * from './nodeFilePayboxRequestStore.js';

package/dist/commerce/nodeFilePayboxRequestStore.d.ts

@@ -0,0 +1,12 @@
+import type { PayBoxRequestStore, PayBoxRequestRecord } from './payboxExecutor.js';
+export declare class NodeFilePayboxRequestStore implements PayBoxRequestStore {
+    private readonly directory;
+    constructor(directory: string);
+    private pathFor;
+    get(clientSubmissionKey: string): Promise<PayBoxRequestRecord | null>;
+    set(record: PayBoxRequestRecord): Promise<void>;
+    claim(clientSubmissionKey: string, placeholder: PayBoxRequestRecord): Promise<{
+        claimed: boolean;
+        record: PayBoxRequestRecord;
+    }>;
+}

package/dist/commerce/nodeFilePayboxRequestStore.js

@@ -0,0 +1,100 @@
+/**
+ * nodeFilePayboxRequestStore.ts — a real, restart-surviving, single-machine
+ * PayBoxRequestStore for Node (D2.6 live reference preparation).
+ *
+ * Storage: one JSON file per clientSubmissionKey under `directory`, named
+ * `<clientSubmissionKey>.json` — same layout discipline as
+ * nodeFileRecoveryStore.ts.
+ *
+ * ATOMIC CLAIM, GENUINELY CROSS-PROCESS: `claim()` creates the file with
+ * Node's `'wx'` flag (`O_WRONLY|O_CREAT|O_EXCL` at the OS level) — the
+ * filesystem itself guarantees that of two processes racing to create the
+ * SAME path, exactly one `open()` call succeeds and the other fails with
+ * `EEXIST`. This is a STRONGER guarantee than nodeFileRecoveryStore.ts's own
+ * in-process lock queue (which that file's own header honestly documents as
+ * "NOT a multi-process/multi-machine lock") — PayBoxRequestStore.claim()'s
+ * own contract specifically requires genuine cross-process atomicity (D2.6
+ * review fix #3: "exactly one claimant may call pay_x402"), so this
+ * implementation earns that requirement at the filesystem level rather than
+ * only within one Node process.
+ *
+ * `set()` (used only by the winning claimant, to record the real
+ * `payboxRequestId` once known, and later `transactionHash`) uses the same
+ * write-to-temp-then-rename pattern as nodeFileRecoveryStore.ts so a crash
+ * mid-write can never leave a half-written, corrupt record.
+ *
+ * Single-machine, shared-filesystem scope only (same as
+ * NodeFileRecoveryStore) — a multi-machine deployment needs a real database
+ * with a native atomic insert-if-absent (e.g. `INSERT ... ON CONFLICT DO
+ * NOTHING`) instead.
+ */
+import { mkdir, readFile, writeFile, rename, open as openFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+/** Matches the shape onchaindiligence-mcp/onchaindiligence-sdk generate for clientSubmissionKey (operationId:timestamp:random, see client.ts's claimSubmissionSlot) -- rejected characters could otherwise be used to escape `directory`. */
+function isValidClientSubmissionKey(key) {
+    return /^[A-Za-z0-9_:.-]{1,200}$/.test(key);
+}
+export class NodeFilePayboxRequestStore {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    pathFor(clientSubmissionKey) {
+        if (!isValidClientSubmissionKey(clientSubmissionKey)) {
+            throw new TypeError(`invalid clientSubmissionKey for file storage: ${clientSubmissionKey}`);
+        }
+        // ':' is valid in a clientSubmissionKey but not portable in a filename on
+        // every filesystem -- encode it rather than reject otherwise-valid keys.
+        const safeName = encodeURIComponent(clientSubmissionKey);
+        return join(this.directory, `${safeName}.json`);
+    }
+    async get(clientSubmissionKey) {
+        try {
+            const text = await readFile(this.pathFor(clientSubmissionKey), 'utf8');
+            return JSON.parse(text);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async set(record) {
+        await mkdir(this.directory, { recursive: true });
+        const finalPath = this.pathFor(record.clientSubmissionKey);
+        const tempPath = join(this.directory, `.${encodeURIComponent(record.clientSubmissionKey)}.${randomBytes(4).toString('hex')}.tmp`);
+        await writeFile(tempPath, JSON.stringify(record, null, 2), 'utf8');
+        await rename(tempPath, finalPath); // atomic on the same filesystem
+    }
+    async claim(clientSubmissionKey, placeholder) {
+        await mkdir(this.directory, { recursive: true });
+        const finalPath = this.pathFor(clientSubmissionKey);
+        let handle;
+        try {
+            // 'wx' = O_WRONLY | O_CREAT | O_EXCL -- the OS guarantees exactly one
+            // concurrent caller (in this process or another) wins this open().
+            handle = await openFile(finalPath, 'wx');
+        }
+        catch (err) {
+            if (err?.code === 'EEXIST') {
+                const existing = await this.get(clientSubmissionKey);
+                if (existing)
+                    return { claimed: false, record: existing };
+                // TOCTOU sliver: the file existed a moment ago (EEXIST) but is
+                // unreadable/gone now -- this store never deletes records, so this
+                // should not happen in practice; retry once rather than fail closed
+                // on a transient race.
+                return this.claim(clientSubmissionKey, placeholder);
+            }
+            throw err;
+        }
+        try {
+            await handle.writeFile(JSON.stringify(placeholder, null, 2), 'utf8');
+        }
+        finally {
+            await handle.close();
+        }
+        return { claimed: true, record: { ...placeholder } };
+    }
+}

package/dist/commerce/payboxExecutor.d.ts

@@ -0,0 +1,159 @@
+import type { CommerceExecutor, PrepareContext, PrepareResult, ExecutionResult, ExecutorRecoveryMode } from './executor.js';
+import { BASE_NETWORK, BASE_USDC, type MinimalResumeClient } from './x402Executor.js';
+export { BASE_NETWORK as PAYBOX_BASE_NETWORK, BASE_USDC as PAYBOX_BASE_USDC };
+export type PayBoxRequestStatus = 'pending_approval' | 'pending_signature' | 'success' | 'denied' | 'error';
+export interface PayBoxRequestEnvelope {
+    request_id: string;
+    status: PayBoxRequestStatus;
+    /** Present on `success`. For pay_x402, carries `{ x_payment: { header, value } }` -- the signed payment header to present to the paid resource. PayBox does not itself call the resource. */
+    output?: {
+        value?: {
+            x_payment?: {
+                header: string;
+                value: string;
+            };
+        };
+    } & Record<string, unknown>;
+    /** Present on `denied`. */
+    reason?: string;
+    /** Present on `error`. */
+    message?: string;
+}
+export interface PayBoxPayX402Input {
+    /** A wallet-kind credential id. */
+    credential_id: string;
+    /** The 402's `accepts` PaymentRequirements array, verbatim. */
+    accepts: unknown[];
+    /** The paid resource URL, for audit/display. */
+    resource_url: string;
+    /** 1 for JSON-body requirements, 2 for header requirements. */
+    x402_version?: 1 | 2;
+}
+/**
+ * The minimal PayBox public surface this executor depends on -- exactly
+ * `pay_x402` and `get_request`, structurally typed so any transport (the
+ * real `@paybox-sh/sdk` PayboxClient, an MCP tool-call wrapper, or a test
+ * double) can satisfy it without this package taking a hard dependency on
+ * a specific vendor SDK version.
+ */
+export interface PayBoxClient {
+    payX402(input: PayBoxPayX402Input): Promise<PayBoxRequestEnvelope>;
+    getRequest(requestId: string): Promise<PayBoxRequestEnvelope>;
+}
+export interface PayBoxRequestRecord {
+    clientSubmissionKey: string;
+    /** null only in the narrow window between "we called pay_x402" and "we recorded its request_id" -- see prepare(). */
+    payboxRequestId: string | null;
+    resourceUrl: string;
+    network: string;
+    asset: string;
+    atomicAmount: string;
+    recipient: string;
+    /** Set once the merchant resource confirms the payment and returns a hash -- once set, this adapter never re-presents the PayBox-signed header to the merchant again. */
+    transactionHash: string | null;
+}
+export interface PayBoxRequestStore {
+    get(clientSubmissionKey: string): Promise<PayBoxRequestRecord | null>;
+    set(record: PayBoxRequestRecord): Promise<void>;
+    /**
+     * Atomically claims the attempt slot for `clientSubmissionKey` (D2.6
+     * review fix #3): if no record exists yet, stores `placeholder` (which
+     * MUST have `payboxRequestId: null`) and returns `{ claimed: true, record:
+     * placeholder }` -- the caller, and ONLY the caller, may now call
+     * `pay_x402` for this key. If a record already exists (whether still in
+     * the ambiguous pre-request-id window, or already holding a
+     * `payboxRequestId`), returns `{ claimed: false, record: <the existing
+     * record, unmodified> }` and the caller MUST NOT call `pay_x402`.
+     *
+     * This is the ONE operation in this interface that a real, multi-process
+     * implementation MUST make genuinely atomic (e.g. a SQL `INSERT ... ON
+     * CONFLICT DO NOTHING` followed by a `SELECT`, or an equivalent
+     * conditional-put) -- the same discipline as `CommerceRecoveryStore.create()`
+     * throwing `RecoveryRecordExistsError` rather than silently overwriting.
+     * `InMemoryPayBoxRequestStore`'s implementation is atomic only because a
+     * single JS `Map` access with no `await` in between can never interleave
+     * with another call in the same process.
+     */
+    claim(clientSubmissionKey: string, placeholder: PayBoxRequestRecord): Promise<{
+        claimed: boolean;
+        record: PayBoxRequestRecord;
+    }>;
+}
+/** Volatile, single-process, TEST/EXAMPLE-ONLY implementation -- same discipline as recoveryStore.ts's InMemoryRecoveryStore. Does not survive a restart; a real deployment must implement this against durable storage. */
+export declare class InMemoryPayBoxRequestStore implements PayBoxRequestStore {
+    private readonly records;
+    get(clientSubmissionKey: string): Promise<PayBoxRequestRecord | null>;
+    set(record: PayBoxRequestRecord): Promise<void>;
+    claim(clientSubmissionKey: string, placeholder: PayBoxRequestRecord): Promise<{
+        claimed: boolean;
+        record: PayBoxRequestRecord;
+    }>;
+}
+/** Thrown by the PayBoxCommerceExecutor constructor when no durable store was supplied (D2.6 review fix #2). */
+export declare class PayBoxStoreRequiredError extends Error {
+    constructor();
+}
+/** Thrown by prepare() when a PRIOR attempt for this exact clientSubmissionKey called pay_x402 but this process never learned the outcome -- see this file's header for why this cannot be silently retried. */
+export declare class PayBoxAmbiguousPrepareError extends Error {
+    constructor(clientSubmissionKey: string);
+}
+export interface PayBoxExecutorOptions {
+    /** The PayBox client used to call pay_x402/get_request. Never logged, never persisted by this class. */
+    paybox: PayBoxClient;
+    /** The single PayBox wallet-kind credential this executor pays from (Section 2: one credential, one operation at a time for the reference flow). */
+    credentialId: string;
+    /**
+     * Durable store for this adapter's own request identity -- REQUIRED, no
+     * default (D2.6 review fix #2). This class advertises
+     * `recoveryMode: 'stable-payment-identity'`, which is only true if the
+     * PayBox request_id genuinely survives a restart; silently defaulting to
+     * `InMemoryPayBoxRequestStore` would make that claim false the moment the
+     * process restarts. `InMemoryPayBoxRequestStore` remains available for
+     * tests/examples but must be passed explicitly, exactly like
+     * `CommerceRecoveryStore` has no safe default either.
+     */
+    store: PayBoxRequestStore;
+    fetch?: typeof globalThis.fetch;
+    /** Base RPC used ONLY for read-only resume confirmation of an already-known transaction hash. Defaults to the public Base RPC. */
+    rpcUrl?: string;
+    /** Test seam: inject a fake read-only client instead of connecting to rpcUrl. */
+    publicClient?: MinimalResumeClient;
+}
+export declare class PayBoxCommerceExecutor implements CommerceExecutor {
+    readonly id = "paybox-x402-base-usdc";
+    readonly version = "v1";
+    readonly recoveryMode: ExecutorRecoveryMode;
+    private readonly paybox;
+    private readonly credentialId;
+    private readonly store;
+    private readonly fetchImpl;
+    private readonly rpcUrl;
+    private readonly injectedPublicClient?;
+    constructor(options: PayBoxExecutorOptions);
+    prepare(context: PrepareContext): Promise<PrepareResult>;
+    private toPrepareResult;
+    submit(prepared: PrepareResult): Promise<ExecutionResult>;
+    resume(prepared: PrepareResult, priorOutcome?: ExecutionResult): Promise<ExecutionResult>;
+    /**
+     * Shared by submit() (first check, right after prepare()) and resume()
+     * (every later check) -- ONE `get_request` poll, then an honest mapping of
+     * PayBox's current status. This is the entire "polling" mechanism: neither
+     * method loops internally. A still-pending request returns
+     * 'submission-ambiguous' with a retry hint, and the EXISTING orchestrator
+     * retry pattern (the developer calling op.execute() again, which calls
+     * resume(), never submit(), for an already-claimed identity) is what
+     * drives the next poll -- see Section 11: no parallel polling API.
+     */
+    private resolve;
+    /**
+     * Attaches the PayBox-signed x402 payment header and calls the merchant
+     * resource exactly once per invocation. Safe to call again if a PRIOR
+     * attempt never reached a response (the underlying x402 "exact" scheme
+     * authorization is a single-use EIP-3009 `transferWithAuthorization` --
+     * the merchant/facilitator re-broadcasting the SAME authorization a second
+     * time reverts on-chain rather than double-charging; this adapter still
+     * avoids that path whenever possible by checking `record.transactionHash`
+     * first in resolve()).
+     */
+    private presentPaymentToMerchant;
+}

package/dist/commerce/payboxExecutor.js

@@ -0,0 +1,374 @@
+/**
+ * payboxExecutor.ts — the one narrow PayBoxCommerceExecutor adapter (D2.6).
+ *
+ * PROVES: OCD works alongside an INDEPENDENT execution-control system.
+ * PayBox (https://paybox.sh, MoonPay's non-custodial agent payment vault)
+ * independently evaluates its own grant/approval rules and signs the
+ * payment; OCD independently evaluates policy beforehand and independently
+ * observes settlement afterward. Neither system's decision overrides the
+ * other -- see client.ts's execute()/preflight() split, which is what
+ * actually enforces this (the developer checks `preflight.kind === 'ready'`
+ * BEFORE ever calling execute(), and execute() never runs PayBox logic for
+ * an operation that never reached execute()).
+ *
+ * PUBLIC CONTRACT USED (docs.paybox.sh, inspected live 2026-09-06):
+ *   - `pay_x402` (reference/mcp-tools): signs an x402 v2 "exact" payment
+ *     authorization for a wallet-kind credential. Returns a `request_id`
+ *     immediately; on eventual `success`, `output.value.x_payment` carries
+ *     the header name/value to present to the paid resource. PayBox does
+ *     NOT itself call the resource or broadcast anything on-chain for this
+ *     tool -- broadcasting happens when the caller attaches that header to
+ *     an HTTP request to the resource, exactly like x402Executor.ts's own
+ *     `wrapFetchWithPayment` step, except the SIGNING half now happens
+ *     inside PayBox's vault instead of a local private key.
+ *   - `get_request` (reference/mcp-tools): polls the CURRENT status of a
+ *     request by `request_id`. Docs (concepts/requests) state the request
+ *     lifecycle explicitly: non-terminal `pending_approval` ->
+ *     `pending_signature` -> terminal `success` | `denied` | `error`, and
+ *     the "critical rule": "submit once, then poll -- never re-issue the
+ *     original tool call to 'finish' it. Resubmission creates a duplicate
+ *     operation." This adapter follows that rule exactly: `pay_x402` is
+ *     called AT MOST ONCE per clientSubmissionKey (from prepare()); every
+ *     subsequent check, in submit() or resume(), calls `get_request` only.
+ *
+ * THIS FILE DEPENDS ON NO SPECIFIC PAYBOX SDK VERSION: `PayBoxClient` below
+ * is a minimal structural interface mirroring exactly the two documented
+ * tool contracts above (same discipline as x402Executor.ts's `ClientEvmSigner`
+ * -- narrow enough that the real `@paybox-sh/sdk`'s `PayboxClient`, a direct
+ * MCP tool-call wrapper, or a test double can all satisfy it unmodified).
+ *
+ * WHY A SEPARATE PayBoxRequestStore (Section 11's "small adapter-specific
+ * helper" exception): the orchestrator (client.ts's CommerceOperation)
+ * persists only clientSubmissionKey/executorId/executionRequestId/
+ * transactionHash across a restart -- on resume, it reconstructs a GENERIC
+ * `PrepareResult.reference = { action }`, not whatever an individual
+ * executor's own prepare() returned (see client.ts's executeLocked(),
+ * both resume branches). X402BaseUsdcExecutor never needed its own store
+ * because its only durable identity IS the eventual transaction hash, which
+ * the orchestrator already persists. PayBox is different: `pay_x402` has NO
+ * documented idempotency key, so this adapter's OWN durable request_id
+ * (keyed by clientSubmissionKey, which the orchestrator DOES reliably pass
+ * to both prepare() and resume()) is the only thing standing between a lost
+ * response and a duplicate PayBox request. This is the genuinely-required
+ * small helper Section 11 anticipates -- not a parallel lifecycle API.
+ *
+ * RECOVERY MODE: 'stable-payment-identity', not 'provider-idempotent' and
+ * not 'manual'. Chosen by what PayBox's OWN public contract actually
+ * guarantees, not for the strongest-sounding label (Section 5):
+ *   - NOT 'provider-idempotent': that would claim calling `pay_x402` twice
+ *     with the same intent is safe (PayBox itself would dedupe). Docs say
+ *     the opposite -- resubmitting creates a duplicate request. False if
+ *     claimed.
+ *   - IS 'stable-payment-identity': once a request_id exists, `get_request`
+ *     can be polled/resumed against that SAME id indefinitely, deterministically,
+ *     with no risk of creating a new operation -- exactly the definition
+ *     Section 5 gives for this label. The identity is the PayBox request_id
+ *     itself, established once in prepare() and never re-created.
+ *   - The one honest gap: if `pay_x402` is called but the process dies
+ *     before learning whether PayBox ever created a request (no response at
+ *     all), there is no stable identity to resume -- see prepare()'s
+ *     PayBoxAmbiguousPrepareError, which surfaces this narrow window
+ *     explicitly rather than silently retrying pay_x402 a second time.
+ */
+import { createPublicClient, http } from 'viem';
+import { base } from 'viem/chains';
+import { BASE_NETWORK, BASE_USDC } from './x402Executor.js';
+import { X402ChallengeError, decodeChallenge, validateChallenge, decodeSettlementResponse, decimalToAtomic6 } from './x402Challenge.js';
+export { BASE_NETWORK as PAYBOX_BASE_NETWORK, BASE_USDC as PAYBOX_BASE_USDC };
+/** Volatile, single-process, TEST/EXAMPLE-ONLY implementation -- same discipline as recoveryStore.ts's InMemoryRecoveryStore. Does not survive a restart; a real deployment must implement this against durable storage. */
+export class InMemoryPayBoxRequestStore {
+    records = new Map();
+    async get(clientSubmissionKey) {
+        return this.records.get(clientSubmissionKey) ?? null;
+    }
+    async set(record) {
+        this.records.set(record.clientSubmissionKey, { ...record });
+    }
+    async claim(clientSubmissionKey, placeholder) {
+        // No `await` between the check and the write -- this is what makes this
+        // specific implementation race-free for concurrent callers IN THIS PROCESS.
+        const existing = this.records.get(clientSubmissionKey);
+        if (existing)
+            return { claimed: false, record: { ...existing } };
+        const stored = { ...placeholder };
+        this.records.set(clientSubmissionKey, stored);
+        return { claimed: true, record: { ...stored } };
+    }
+}
+/** Thrown by the PayBoxCommerceExecutor constructor when no durable store was supplied (D2.6 review fix #2). */
+export class PayBoxStoreRequiredError extends Error {
+    constructor() {
+        super("PayBoxCommerceExecutor requires an explicit, durable `store` (PayBoxRequestStore) -- InMemoryPayBoxRequestStore is test/example-only and does not survive a restart, which would silently make this executor's advertised recoveryMode ('stable-payment-identity') false. Pass a durable implementation in production; InMemoryPayBoxRequestStore only in tests/examples.");
+        this.name = 'PayBoxStoreRequiredError';
+    }
+}
+/** Thrown by prepare() when a PRIOR attempt for this exact clientSubmissionKey called pay_x402 but this process never learned the outcome -- see this file's header for why this cannot be silently retried. */
+export class PayBoxAmbiguousPrepareError extends Error {
+    constructor(clientSubmissionKey) {
+        super(`a prior prepare() for clientSubmissionKey "${clientSubmissionKey}" called PayBox's pay_x402 but this process never learned whether PayBox created a request -- pay_x402 has no idempotency key, so calling it again here could create a SECOND PayBox request for the same intended payment. Check PayBox directly (dashboard or "paybox request --list") for an orphaned request tied to this payment before retrying.`);
+        this.name = 'PayBoxAmbiguousPrepareError';
+    }
+}
+export class PayBoxCommerceExecutor {
+    id = 'paybox-x402-base-usdc';
+    version = 'v1';
+    recoveryMode = 'stable-payment-identity';
+    paybox;
+    credentialId;
+    store;
+    fetchImpl;
+    rpcUrl;
+    injectedPublicClient;
+    constructor(options) {
+        if (!options.store)
+            throw new PayBoxStoreRequiredError();
+        this.paybox = options.paybox;
+        this.credentialId = options.credentialId;
+        this.store = options.store;
+        // See client.ts's constructor comment: binding here is what keeps a bare
+        // `globalThis.fetch` reference safe to call as `this.fetchImpl(...)` in
+        // a real browser.
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.rpcUrl = options.rpcUrl ?? 'https://mainnet.base.org';
+        this.injectedPublicClient = options.publicClient;
+    }
+    async prepare(context) {
+        if (context.action.network !== BASE_NETWORK)
+            throw new X402ChallengeError(`this executor only supports ${BASE_NETWORK}, got "${context.action.network}"`);
+        if (context.action.asset.toLowerCase() !== BASE_USDC.toLowerCase()) {
+            throw new X402ChallengeError(`this executor only supports USDC (${BASE_USDC}), got "${context.action.asset}"`);
+        }
+        if (!context.action.resource)
+            throw new X402ChallengeError('action.resource (the x402 resource URL) is required to prepare a submission');
+        // Read-only probe -- no PayBox call, no signing, no payment. Establishes
+        // exactly what would be agreed to pay BEFORE any authorization exists,
+        // identical in spirit to X402BaseUsdcExecutor.prepare(). Safe to run
+        // more than once even under a concurrent race (it has no side effects),
+        // so it happens BEFORE the atomic claim below.
+        const probe = await this.fetchImpl(context.action.resource);
+        if (probe.status !== 402)
+            throw new X402ChallengeError(`expected HTTP 402 from ${context.action.resource}, got ${probe.status}`);
+        const challenge = decodeChallenge(probe);
+        const atomicAmount = decimalToAtomic6(context.action.amount);
+        validateChallenge(challenge, { network: context.action.network, asset: context.action.asset, amount: atomicAmount, recipient: context.action.recipient });
+        // D2.6 review fix #3: atomically claim the attempt slot for this
+        // clientSubmissionKey -- exactly one concurrent caller may proceed to
+        // call pay_x402. A loser either reuses the winner's already-established
+        // request (if it finished first) or, if the winner is still in the
+        // ambiguous pre-request-id window, stops safely rather than racing to
+        // call pay_x402 itself.
+        const placeholder = {
+            clientSubmissionKey: context.clientSubmissionKey,
+            payboxRequestId: null,
+            resourceUrl: context.action.resource,
+            network: context.action.network,
+            asset: context.action.asset,
+            atomicAmount,
+            recipient: context.action.recipient,
+            transactionHash: null,
+        };
+        const { claimed, record: claimedRecord } = await this.store.claim(context.clientSubmissionKey, placeholder);
+        if (!claimed) {
+            if (claimedRecord.payboxRequestId) {
+                // Another attempt already established (or is finishing establishing)
+                // a PayBox request for this exact key -- never call pay_x402 again.
+                return this.toPrepareResult(context.clientSubmissionKey, claimedRecord);
+            }
+            // The winner called pay_x402 but this process never learned the
+            // outcome (crash, or the winner is still in flight). Known,
+            // unavoidable crash window (see this file's header) -- surface it
+            // honestly rather than racing to call pay_x402 ourselves.
+            throw new PayBoxAmbiguousPrepareError(context.clientSubmissionKey);
+        }
+        // We won the claim -- exactly this call may proceed to PayBox. This is
+        // PayBox's OWN independent grant/authorization check -- pay_x402
+        // internally applies the credential's approval mode ("Always Ask" vs
+        // autonomous-within-limits per docs.paybox.sh/concepts/model) before
+        // ever producing a signature. Does NOT broadcast anything on-chain (see
+        // header) -- only establishes the durable request_id.
+        const envelope = await this.paybox.payX402({
+            credential_id: this.credentialId,
+            accepts: challenge.accepts,
+            resource_url: context.action.resource,
+            x402_version: challenge.x402Version,
+        });
+        const record = { ...claimedRecord, payboxRequestId: envelope.request_id };
+        await this.store.set(record);
+        return this.toPrepareResult(context.clientSubmissionKey, record);
+    }
+    toPrepareResult(clientSubmissionKey, record) {
+        const reference = {
+            payboxRequestId: record.payboxRequestId,
+            resourceUrl: record.resourceUrl,
+            network: record.network,
+            asset: record.asset,
+            atomicAmount: record.atomicAmount,
+            recipient: record.recipient,
+        };
+        return {
+            clientSubmissionKey,
+            reference,
+            preparedAt: new Date().toISOString(),
+            // Section 7: correlated into the D2.4 execution binding, and from
+            // there the lifecycle evidence bundle, by client.ts.
+            providerReference: record.payboxRequestId ? `paybox:${record.payboxRequestId}` : null,
+        };
+    }
+    async submit(prepared) {
+        const ref = prepared.reference;
+        return this.resolve(prepared.clientSubmissionKey, ref);
+    }
+    async resume(prepared, priorOutcome) {
+        // Mirrors X402BaseUsdcExecutor's own resume(): if a transaction hash is
+        // ALREADY known from a prior call, independently re-confirm it read-only
+        // on-chain -- never guess a new one, never re-present the payment header.
+        if (priorOutcome?.status === 'transaction-known') {
+            const client = this.injectedPublicClient ?? createPublicClient({ chain: base, transport: http(this.rpcUrl) });
+            try {
+                await client.getTransactionReceipt({ hash: priorOutcome.transactionHash });
+                return priorOutcome;
+            }
+            catch {
+                return { clientSubmissionKey: prepared.clientSubmissionKey, status: 'submission-ambiguous', reason: 'previously reported transaction hash was not found on Base mainnet (may still be propagating)' };
+            }
+        }
+        // The orchestrator reconstructs a GENERIC `prepared.reference = { action }`
+        // on resume (see this file's header) -- the PayBox request_id can only be
+        // found via this adapter's OWN durable store, keyed by the one field the
+        // orchestrator DOES reliably pass through: clientSubmissionKey.
+        const record = await this.store.get(prepared.clientSubmissionKey);
+        if (!record || !record.payboxRequestId) {
+            return {
+                clientSubmissionKey: prepared.clientSubmissionKey,
+                status: 'manual-recovery-required',
+                reason: 'no PayBox request is on record for this submission attempt -- check PayBox directly (dashboard or CLI) before retrying',
+            };
+        }
+        return this.resolve(prepared.clientSubmissionKey, {
+            payboxRequestId: record.payboxRequestId,
+            resourceUrl: record.resourceUrl,
+            network: record.network,
+            asset: record.asset,
+            atomicAmount: record.atomicAmount,
+            recipient: record.recipient,
+        });
+    }
+    /**
+     * Shared by submit() (first check, right after prepare()) and resume()
+     * (every later check) -- ONE `get_request` poll, then an honest mapping of
+     * PayBox's current status. This is the entire "polling" mechanism: neither
+     * method loops internally. A still-pending request returns
+     * 'submission-ambiguous' with a retry hint, and the EXISTING orchestrator
+     * retry pattern (the developer calling op.execute() again, which calls
+     * resume(), never submit(), for an already-claimed identity) is what
+     * drives the next poll -- see Section 11: no parallel polling API.
+     */
+    async resolve(clientSubmissionKey, ref) {
+        const record = await this.store.get(clientSubmissionKey);
+        if (record?.transactionHash) {
+            // Already confirmed by the merchant in a prior call -- never re-present
+            // the PayBox-signed payment header again.
+            return { clientSubmissionKey, status: 'transaction-known', transactionHash: record.transactionHash, providerReference: `paybox:${ref.payboxRequestId}` };
+        }
+        if (!ref.payboxRequestId) {
+            return { clientSubmissionKey, status: 'manual-recovery-required', reason: 'no PayBox request_id is available for this submission attempt' };
+        }
+        let envelope;
+        try {
+            envelope = await this.paybox.getRequest(ref.payboxRequestId);
+        }
+        catch (err) {
+            // get_request is a read-only status check -- a failure here is
+            // ambiguous about PayBox's OWN reachability, never about whether the
+            // request itself changed state. Safe to just try again later.
+            return { clientSubmissionKey, status: 'submission-ambiguous', reason: `could not reach PayBox to check request ${ref.payboxRequestId}: ${err?.message || 'no response'}`, retryAfterSeconds: 5 };
+        }
+        if (envelope.status === 'pending_approval' || envelope.status === 'pending_signature') {
+            return {
+                clientSubmissionKey,
+                status: 'submission-ambiguous',
+                reason: `PayBox request ${ref.payboxRequestId} is ${envelope.status} -- poll again, do not resubmit`,
+                retryAfterSeconds: envelope.status === 'pending_approval' ? 15 : 5,
+            };
+        }
+        if (envelope.status === 'denied') {
+            // Terminal and definitive: PayBox's OWN grant/approval rules rejected
+            // this payment. This is NOT an OCD outcome and NOT ambiguous -- no
+            // merchant payment occurred and none will for this request. Mapped to
+            // manual-recovery-required (the closest of the three ExecutionOutcome
+            // states to "no execution, a human should see why and decide next
+            // steps") rather than submission-ambiguous, so the developer is NOT
+            // told to just keep retrying a denial that will never change.
+            return {
+                clientSubmissionKey,
+                status: 'manual-recovery-required',
+                reason: `PayBox denied request ${ref.payboxRequestId}${envelope.reason ? `: ${envelope.reason}` : ''} -- no merchant payment was made`,
+            };
+        }
+        if (envelope.status === 'error') {
+            // D2.6 review fix #4: docs.paybox.sh/concepts/requests lists `error`
+            // under "Terminal (polling stops)" -- treating it as retryable
+            // submission-ambiguous would poll the SAME terminal envelope forever
+            // and, worse, invites a caller to eventually give up and start a NEW
+            // PayBox request for the same intent. Terminal and definitive, exactly
+            // like `denied`: no merchant payment occurred and this request will
+            // never resolve differently. A genuinely NEW attempt requires a NEW
+            // operation/clientSubmissionKey, never a retry of this one.
+            return {
+                clientSubmissionKey,
+                status: 'manual-recovery-required',
+                reason: `PayBox reported a terminal error for request ${ref.payboxRequestId}${envelope.message ? `: ${envelope.message}` : ''} -- no merchant payment was made; this request will not resolve differently on retry`,
+            };
+        }
+        // status === 'success': PayBox signed the payment. It did NOT submit it
+        // to the merchant -- that's this adapter's job now, exactly like
+        // X402BaseUsdcExecutor.submit()'s own post-signing half.
+        const xPayment = envelope.output?.value?.x_payment;
+        if (!xPayment?.header || !xPayment?.value) {
+            // `success` is ALSO terminal (per docs) -- polling get_request again
+            // would return this exact same envelope forever, so this must stop
+            // safely rather than being reported as retryable.
+            return {
+                clientSubmissionKey,
+                status: 'manual-recovery-required',
+                reason: `PayBox request ${ref.payboxRequestId} reached terminal status "success" but no x_payment header could be read from its output -- check PayBox directly before retrying`,
+            };
+        }
+        return this.presentPaymentToMerchant(clientSubmissionKey, ref, xPayment);
+    }
+    /**
+     * Attaches the PayBox-signed x402 payment header and calls the merchant
+     * resource exactly once per invocation. Safe to call again if a PRIOR
+     * attempt never reached a response (the underlying x402 "exact" scheme
+     * authorization is a single-use EIP-3009 `transferWithAuthorization` --
+     * the merchant/facilitator re-broadcasting the SAME authorization a second
+     * time reverts on-chain rather than double-charging; this adapter still
+     * avoids that path whenever possible by checking `record.transactionHash`
+     * first in resolve()).
+     */
+    async presentPaymentToMerchant(clientSubmissionKey, ref, xPayment) {
+        let res;
+        try {
+            res = await this.fetchImpl(ref.resourceUrl, { headers: { [xPayment.header]: xPayment.value } });
+        }
+        catch (err) {
+            return { clientSubmissionKey, status: 'submission-ambiguous', reason: err?.message || 'no response from the resource after presenting the PayBox-signed payment', retryAfterSeconds: 5 };
+        }
+        if (res.status === 402) {
+            return { clientSubmissionKey, status: 'submission-ambiguous', reason: `resource still returned 402 after presenting the PayBox-signed payment (status ${res.status})` };
+        }
+        if (!res.ok) {
+            return { clientSubmissionKey, status: 'submission-ambiguous', reason: `resource returned HTTP ${res.status} after presenting the PayBox-signed payment -- outcome unknown` };
+        }
+        const { transactionHash } = decodeSettlementResponse(res);
+        if (!transactionHash) {
+            return { clientSubmissionKey, status: 'submission-ambiguous', reason: 'resource responded successfully but no transaction hash could be parsed from the settlement response' };
+        }
+        // Durable BEFORE returning -- resolve() must never re-present this
+        // payment header to the merchant again once a hash is known.
+        const record = await this.store.get(clientSubmissionKey);
+        if (record)
+            await this.store.set({ ...record, transactionHash });
+        return { clientSubmissionKey, status: 'transaction-known', transactionHash, providerReference: `paybox:${ref.payboxRequestId}` };
+    }
+}

package/dist/commerce/recoveryStore.d.ts

@@ -29,6 +29,18 @@ export interface CommerceRecoveryRecord {
     createdAt: string;
     updatedAt: string;
     preflightReceiptId: string | null;
+    /**
+     * The stored PREFLIGHT receipt's `decision.status`, exactly as returned by
+     * the server, recorded the moment preflight() succeeds — this is what
+     * CommerceOperation.execute() checks (fail-closed) before ever calling an
+     * executor, so BLOCK/REQUIRE_APPROVAL/UNKNOWN can never reach
+     * prepare()/submit()/resume() merely because a caller forgot to check
+     * evaluation.kind themselves (D2.6 review fix #1). `null` until a
+     * preflight decision is known, or for a record created before this field
+     * existed — execute() re-fetches the authoritative receipt in that case
+     * rather than assuming ALLOW.
+     */
+    preflightDecisionStatus: 'ALLOW' | 'REQUIRE_APPROVAL' | 'BLOCK' | 'UNKNOWN' | null;
     /** The one-time finalization capability token, when known. Never log this. */
     finalizationCapability: string | null;
     finalizationCapabilityExpiresAt: string | null;

package/dist/commerce/x402Challenge.d.ts

@@ -0,0 +1,44 @@
+/**
+ * x402Challenge.ts — shared x402 v2 "exact" challenge helpers (D2.6).
+ *
+ * Extracted verbatim from x402Executor.ts (D2.5) so payboxExecutor.ts (D2.6)
+ * can reuse the SAME proven challenge-decoding/validation logic instead of
+ * maintaining a second copy of security-critical checks (wrong recipient,
+ * wrong amount, wrong network/asset) that protect real money. Behavior is
+ * byte-for-byte unchanged — see liveMerchantChallengeDecoding.test.mjs and
+ * x402Executor.test.mjs, both of which exercise this code through
+ * X402BaseUsdcExecutor and still pass unmodified after this extraction.
+ */
+/**
+ * `Buffer` is a Node global, not a browser one -- calling `Buffer.from(...)`
+ * here used to throw `ReferenceError: Buffer is not defined` in a real
+ * browser (confirmed live, D2.5A: a real OneSource 402 challenge, valid and
+ * byte-identical through the local proxy, failed to decode). That
+ * ReferenceError was thrown INSIDE decodeChallenge()'s try/catch below and
+ * silently relabeled as "Payment-Required header was not base64-encoded
+ * JSON" -- a misleading error that looks like a merchant-format problem but
+ * isn't one. `atob`/`TextDecoder` are the browser-safe equivalents (both
+ * also globally available in Node), mirroring lifecycleCore.ts's own
+ * isomorphic decodeChallenge in onchaindiligence-mcp exactly.
+ */
+export declare function base64ToUtf8(base64: string): string;
+export declare class X402ChallengeError extends Error {
+}
+export declare function decodeChallenge(res: Response): any;
+/** Validates a decoded x402 v2 "exact" challenge against the frozen preflighted action. Never mutates anything; throws before any signing could occur. */
+export declare function validateChallenge(challenge: any, expected: {
+    network: string;
+    asset: string;
+    amount: string;
+    recipient: string;
+}): void;
+export declare function decodeSettlementResponse(res: Response): {
+    transactionHash: string | null;
+};
+/**
+ * Converts a canonical decimal amount (e.g. "1.00") into USDC's 6-decimal
+ * atomic unit string, WITHOUT floating point — mirrors
+ * onchaindiligence-mcp's src/money.ts exactly (kept independent here since
+ * this package does not depend on that server-side module).
+ */
+export declare function decimalToAtomic6(amount: string): string;

package/dist/commerce/x402Challenge.js

@@ -0,0 +1,86 @@
+/**
+ * x402Challenge.ts — shared x402 v2 "exact" challenge helpers (D2.6).
+ *
+ * Extracted verbatim from x402Executor.ts (D2.5) so payboxExecutor.ts (D2.6)
+ * can reuse the SAME proven challenge-decoding/validation logic instead of
+ * maintaining a second copy of security-critical checks (wrong recipient,
+ * wrong amount, wrong network/asset) that protect real money. Behavior is
+ * byte-for-byte unchanged — see liveMerchantChallengeDecoding.test.mjs and
+ * x402Executor.test.mjs, both of which exercise this code through
+ * X402BaseUsdcExecutor and still pass unmodified after this extraction.
+ */
+/**
+ * `Buffer` is a Node global, not a browser one -- calling `Buffer.from(...)`
+ * here used to throw `ReferenceError: Buffer is not defined` in a real
+ * browser (confirmed live, D2.5A: a real OneSource 402 challenge, valid and
+ * byte-identical through the local proxy, failed to decode). That
+ * ReferenceError was thrown INSIDE decodeChallenge()'s try/catch below and
+ * silently relabeled as "Payment-Required header was not base64-encoded
+ * JSON" -- a misleading error that looks like a merchant-format problem but
+ * isn't one. `atob`/`TextDecoder` are the browser-safe equivalents (both
+ * also globally available in Node), mirroring lifecycleCore.ts's own
+ * isomorphic decodeChallenge in onchaindiligence-mcp exactly.
+ */
+export function base64ToUtf8(base64) {
+    const binary = atob(base64);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+export class X402ChallengeError extends Error {
+}
+export function decodeChallenge(res) {
+    const header = res.headers.get('payment-required');
+    if (!header)
+        throw new X402ChallengeError(`${res.url}: 402 response carried no Payment-Required header`);
+    try {
+        return JSON.parse(base64ToUtf8(header));
+    }
+    catch {
+        throw new X402ChallengeError(`${res.url}: Payment-Required header was not base64-encoded JSON`);
+    }
+}
+/** Validates a decoded x402 v2 "exact" challenge against the frozen preflighted action. Never mutates anything; throws before any signing could occur. */
+export function validateChallenge(challenge, expected) {
+    if (challenge?.x402Version !== 2)
+        throw new X402ChallengeError(`unexpected x402 version ${challenge?.x402Version} (expected 2)`);
+    const accepts = challenge?.accepts?.[0];
+    if (!accepts)
+        throw new X402ChallengeError('challenge contained no accepts entry');
+    if (accepts.scheme !== 'exact')
+        throw new X402ChallengeError(`unexpected scheme "${accepts.scheme}" (expected "exact")`);
+    if (accepts.network !== expected.network)
+        throw new X402ChallengeError(`network mismatch: quoted "${accepts.network}", expected "${expected.network}"`);
+    if (String(accepts.asset).toLowerCase() !== expected.asset.toLowerCase()) {
+        throw new X402ChallengeError(`asset mismatch: quoted "${accepts.asset}", expected "${expected.asset}"`);
+    }
+    if (String(accepts.payTo).toLowerCase() !== expected.recipient.toLowerCase()) {
+        throw new X402ChallengeError(`recipient mismatch: quoted "${accepts.payTo}", expected "${expected.recipient}" -- refusing to pay an unexpected address`);
+    }
+    if (String(accepts.amount) !== expected.amount) {
+        throw new X402ChallengeError(`amount mismatch: quoted "${accepts.amount}", expected exactly "${expected.amount}" atomic units`);
+    }
+}
+export function decodeSettlementResponse(res) {
+    const header = res.headers.get('x-payment-response') ?? res.headers.get('payment-response');
+    if (!header)
+        return { transactionHash: null };
+    try {
+        const decoded = JSON.parse(base64ToUtf8(header));
+        return { transactionHash: typeof decoded?.transaction === 'string' ? decoded.transaction : null };
+    }
+    catch {
+        return { transactionHash: null };
+    }
+}
+/**
+ * Converts a canonical decimal amount (e.g. "1.00") into USDC's 6-decimal
+ * atomic unit string, WITHOUT floating point — mirrors
+ * onchaindiligence-mcp's src/money.ts exactly (kept independent here since
+ * this package does not depend on that server-side module).
+ */
+export function decimalToAtomic6(amount) {
+    const [intPart, fracPart = ''] = amount.split('.');
+    if (fracPart.length > 6)
+        throw new X402ChallengeError(`amount "${amount}" has more precision than USDC's 6 decimals support`);
+    return BigInt(intPart + fracPart.padEnd(6, '0')).toString();
+}

package/dist/commerce/x402Executor.d.ts

@@ -1,7 +1,9 @@
 import { toClientEvmSigner, type ClientEvmSigner } from '@x402/evm';
 import type { CommerceExecutor, PrepareContext, PrepareResult, ExecutionResult, ExecutorRecoveryMode } from './executor.js';
+import { X402ChallengeError } from './x402Challenge.js';
 export type { ClientEvmSigner };
 export { toClientEvmSigner };
+export { X402ChallengeError };
 export declare const BASE_NETWORK = "eip155:8453";
 export declare const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 /** The subset of viem's PublicClient resume() actually calls -- narrowed so tests can inject a minimal fake instead of a real RPC connection. */

package/dist/commerce/x402Executor.js

@@ -36,84 +36,11 @@ import { wrapFetchWithPayment } from '@x402/fetch';
 import { x402Client } from '@x402/core/client';
 import { ExactEvmScheme } from '@x402/evm/exact/client';
 import { toClientEvmSigner } from '@x402/evm';
+import { X402ChallengeError, decodeChallenge, validateChallenge, decodeSettlementResponse, decimalToAtomic6 } from './x402Challenge.js';
 export { toClientEvmSigner };
+export { X402ChallengeError };
 export const BASE_NETWORK = 'eip155:8453';
 export const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
-/**
- * `Buffer` is a Node global, not a browser one -- calling `Buffer.from(...)`
- * here used to throw `ReferenceError: Buffer is not defined` in a real
- * browser (confirmed live, D2.5A: a real OneSource 402 challenge, valid and
- * byte-identical through the local proxy, failed to decode). That
- * ReferenceError was thrown INSIDE decodeChallenge()'s try/catch below and
- * silently relabeled as "Payment-Required header was not base64-encoded
- * JSON" -- a misleading error that looks like a merchant-format problem but
- * isn't one. `atob`/`TextDecoder` are the browser-safe equivalents (both
- * also globally available in Node), mirroring lifecycleCore.ts's own
- * isomorphic decodeChallenge in onchaindiligence-mcp exactly.
- */
-function base64ToUtf8(base64) {
-    const binary = atob(base64);
-    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
-    return new TextDecoder().decode(bytes);
-}
-class X402ChallengeError extends Error {
-}
-function decodeChallenge(res) {
-    const header = res.headers.get('payment-required');
-    if (!header)
-        throw new X402ChallengeError(`${res.url}: 402 response carried no Payment-Required header`);
-    try {
-        return JSON.parse(base64ToUtf8(header));
-    }
-    catch {
-        throw new X402ChallengeError(`${res.url}: Payment-Required header was not base64-encoded JSON`);
-    }
-}
-/** Validates a decoded x402 v2 "exact" challenge against the frozen preflighted action. Never mutates anything; throws before any signing could occur. */
-function validateChallenge(challenge, expected) {
-    if (challenge?.x402Version !== 2)
-        throw new X402ChallengeError(`unexpected x402 version ${challenge?.x402Version} (expected 2)`);
-    const accepts = challenge?.accepts?.[0];
-    if (!accepts)
-        throw new X402ChallengeError('challenge contained no accepts entry');
-    if (accepts.scheme !== 'exact')
-        throw new X402ChallengeError(`unexpected scheme "${accepts.scheme}" (expected "exact")`);
-    if (accepts.network !== expected.network)
-        throw new X402ChallengeError(`network mismatch: quoted "${accepts.network}", expected "${expected.network}"`);
-    if (String(accepts.asset).toLowerCase() !== expected.asset.toLowerCase()) {
-        throw new X402ChallengeError(`asset mismatch: quoted "${accepts.asset}", expected "${expected.asset}"`);
-    }
-    if (String(accepts.payTo).toLowerCase() !== expected.recipient.toLowerCase()) {
-        throw new X402ChallengeError(`recipient mismatch: quoted "${accepts.payTo}", expected "${expected.recipient}" -- refusing to pay an unexpected address`);
-    }
-    if (String(accepts.amount) !== expected.amount) {
-        throw new X402ChallengeError(`amount mismatch: quoted "${accepts.amount}", expected exactly "${expected.amount}" atomic units`);
-    }
-}
-function decodeSettlementResponse(res) {
-    const header = res.headers.get('x-payment-response') ?? res.headers.get('payment-response');
-    if (!header)
-        return { transactionHash: null };
-    try {
-        const decoded = JSON.parse(base64ToUtf8(header));
-        return { transactionHash: typeof decoded?.transaction === 'string' ? decoded.transaction : null };
-    }
-    catch {
-        return { transactionHash: null };
-    }
-}
-/**
- * Converts a canonical decimal amount (e.g. "1.00") into USDC's 6-decimal
- * atomic unit string, WITHOUT floating point — mirrors
- * onchaindiligence-mcp's src/money.ts exactly (kept independent here since
- * this package does not depend on that server-side module).
- */
-function decimalToAtomic6(amount) {
-    const [intPart, fracPart = ''] = amount.split('.');
-    if (fracPart.length > 6)
-        throw new X402ChallengeError(`amount "${amount}" has more precision than USDC's 6 decimals support`);
-    return BigInt(intPart + fracPart.padEnd(6, '0')).toString();
-}
 export class X402BaseUsdcExecutor {
     id = 'x402-base-usdc-exact';
     version = 'v1';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onchaindiligence/sdk",
-  "version": "0.3.1",
-  "description": "Typed client for the OnchainDiligence compliance API — pay-per-call sanctions, OFAC name, and UK company checks, with the 402 payment flow handled for you.",
+  "version": "0.4.0",
+  "description": "TypeScript SDK for OnChainDiligence — policy preflight, recoverable agent payment lifecycles, independent settlement observation, and verifiable receipts.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,8 +16,8 @@
       "import": "./dist/commerce/index.js"
     },
     "./commerce/node": {
-      "types": "./dist/commerce/nodeFileRecoveryStore.d.ts",
-      "import": "./dist/commerce/nodeFileRecoveryStore.js"
+      "types": "./dist/commerce/node.d.ts",
+      "import": "./dist/commerce/node.js"
     }
   },
   "files": [
@@ -30,15 +30,23 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
+    "agent-payments",
+    "ai-agents",
+    "x402",
+    "402",
+    "payments",
+    "receipts",
+    "verification",
+    "mcp",
+    "base",
+    "usdc",
+    "web3",
     "compliance",
     "sanctions",
     "ofac",
-    "x402",
-    "402",
     "mppx",
     "tempo",
-    "agent",
-    "web3"
+    "agent"
   ],
   "license": "MIT",
   "peerDependencies": {