@obbyx/sdk 0.0.0-stage → 0.1.0

package/src/seller/consumed-proofs.ts

@@ -0,0 +1,217 @@
+import { DatabaseSync } from 'node:sqlite';
+
+/**
+ * Seller-side registry of consumed payment proofs (invariant I3).
+ *
+ * Keyed by `<caip2>:unit:<hash>`, so it holds even when several APIs or
+ * facilitators serve the same payTo. Each proof serves exactly one operation
+ * (its binding); a repeat of that operation gets the stored response.
+ *
+ *   upfront:       settling → paid_not_served → serving → served
+ *                      └────→ failed                 └──→ paid_not_served (handler failed)
+ *   authorization: settling → serving → awaiting_settle → served
+ *                                 │              └──────→ failed (handler already ran)
+ *                                 └──→ settling (handler failed; nothing settled)
+ *
+ *   serving older than the lease (crash) → paid_not_served | settling (reclaimStale)
+ *
+ * Transitions are compare-and-set, so concurrent requests with the same proof
+ * never run the handler twice.
+ */
+export type ProofState =
+  | 'settling'
+  | 'paid_not_served'
+  | 'serving'
+  | 'served'
+  | 'failed'
+  /** authorization flow: the handler ran, its response waits for the settlement. */
+  | 'awaiting_settle';
+
+export interface StoredResponse {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: Uint8Array;
+}
+
+export interface ProofRecord {
+  readonly key: string;
+  readonly binding: string;
+  readonly state: ProofState;
+  readonly paymentResponse: string | null;
+  readonly response: StoredResponse | null;
+  readonly updatedAt: number;
+}
+
+interface Row {
+  key: string;
+  binding: string;
+  state: ProofState;
+  payment_response: string | null;
+  response_status: number | null;
+  response_headers: string | null;
+  response_body: Uint8Array | null;
+  updated_at: number;
+}
+
+export class ConsumedProofsStore {
+  private readonly db: DatabaseSync;
+
+  constructor(
+    path: string,
+    private readonly now: () => number = () => Math.floor(Date.now() / 1000),
+  ) {
+    this.db = new DatabaseSync(path);
+    this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = FULL;
+      PRAGMA busy_timeout = 5000;
+      CREATE TABLE IF NOT EXISTS consumed_proofs (
+        key TEXT PRIMARY KEY,
+        binding TEXT NOT NULL,
+        state TEXT NOT NULL,
+        payment_response TEXT,
+        response_status INTEGER,
+        response_headers TEXT,
+        response_body BLOB,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS payment_ids (
+        scope_id TEXT PRIMARY KEY,
+        fingerprint TEXT NOT NULL,
+        proof_key TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      ) STRICT;
+    `);
+  }
+
+  /**
+   * x402 `payment-identifier`: remembers which proof served a client-chosen id
+   * for one operation fingerprint. Returns the stored mapping (existing or new).
+   */
+  bindPaymentId(
+    scopeId: string,
+    fingerprint: string,
+    proofKey: string,
+  ): { fingerprint: string; proofKey: string; created: boolean } {
+    const res = this.db
+      .prepare(
+        'INSERT INTO payment_ids (scope_id, fingerprint, proof_key, created_at) VALUES (?, ?, ?, ?) ON CONFLICT(scope_id) DO NOTHING',
+      )
+      .run(scopeId, fingerprint, proofKey, this.now());
+    const row = this.db
+      .prepare('SELECT fingerprint, proof_key FROM payment_ids WHERE scope_id = ?')
+      .get(scopeId) as {
+      fingerprint: string;
+      proof_key: string;
+    };
+    return {
+      fingerprint: row.fingerprint,
+      proofKey: row.proof_key,
+      created: Number(res.changes) === 1,
+    };
+  }
+
+  /** Compare-and-set: moves the id only if it still points at `previous` (one winner). */
+  rebindPaymentId(scopeId: string, previous: string, proofKey: string): boolean {
+    const res = this.db
+      .prepare('UPDATE payment_ids SET proof_key = ? WHERE scope_id = ? AND proof_key = ?')
+      .run(proofKey, scopeId, previous);
+    return Number(res.changes) === 1;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  get(key: string): ProofRecord | undefined {
+    const row = this.db.prepare('SELECT * FROM consumed_proofs WHERE key = ?').get(key) as
+      Row | undefined;
+    return row === undefined ? undefined : toRecord(row);
+  }
+
+  /** Inserts the proof in `settling` unless it exists; returns the stored record. */
+  begin(key: string, binding: string): { created: boolean; record: ProofRecord } {
+    const ts = this.now();
+    const res = this.db
+      .prepare(
+        `INSERT INTO consumed_proofs (key, binding, state, created_at, updated_at)
+         VALUES (?, ?, 'settling', ?, ?) ON CONFLICT(key) DO NOTHING`,
+      )
+      .run(key, binding, ts, ts);
+    const record = this.get(key);
+    if (record === undefined) throw new Error(`consumed proof ${key} vanished`);
+    return { created: Number(res.changes) === 1, record };
+  }
+
+  /** Compare-and-set; returns false if the proof is not in `from`. */
+  transition(
+    key: string,
+    from: ProofState,
+    to: ProofState,
+    patch: { paymentResponse?: string; response?: StoredResponse } = {},
+  ): boolean {
+    const res = this.db
+      .prepare(
+        `UPDATE consumed_proofs
+            SET state = ?, updated_at = ?,
+                payment_response = COALESCE(?, payment_response),
+                response_status = COALESCE(?, response_status),
+                response_headers = COALESCE(?, response_headers),
+                response_body = COALESCE(?, response_body)
+          WHERE key = ? AND state = ?`,
+      )
+      .run(
+        to,
+        this.now(),
+        patch.paymentResponse ?? null,
+        patch.response?.status ?? null,
+        patch.response === undefined ? null : JSON.stringify(patch.response.headers),
+        patch.response?.body ?? null,
+        key,
+        from,
+      );
+    return Number(res.changes) === 1;
+  }
+
+  /**
+   * Recovers a proof stuck in `serving` (the process died while the handler
+   * ran): after `leaseSeconds` it goes back to `paid_not_served` (already
+   * settled) or `settling` (authorization flow, not settled yet), so the SAME
+   * payment can complete the operation. Compare-and-set: one winner.
+   */
+  reclaimStale(key: string, leaseSeconds: number): boolean {
+    const res = this.db
+      .prepare(
+        `UPDATE consumed_proofs
+            SET state = CASE WHEN payment_response IS NULL THEN 'settling' ELSE 'paid_not_served' END,
+                updated_at = ?
+          WHERE key = ? AND state = 'serving' AND updated_at <= ?`,
+      )
+      .run(this.now(), key, this.now() - leaseSeconds);
+    return Number(res.changes) === 1;
+  }
+
+  /** Removes a proof that never reached the network (e.g. rejected at verification). */
+  forget(key: string, state: ProofState): void {
+    this.db.prepare('DELETE FROM consumed_proofs WHERE key = ? AND state = ?').run(key, state);
+  }
+}
+
+function toRecord(row: Row): ProofRecord {
+  return {
+    key: row.key,
+    binding: row.binding,
+    state: row.state,
+    paymentResponse: row.payment_response,
+    response:
+      row.response_status === null
+        ? null
+        : {
+            status: row.response_status,
+            headers: JSON.parse(row.response_headers ?? '{}') as Record<string, string>,
+            body: row.response_body ?? new Uint8Array(),
+          },
+    updatedAt: row.updated_at,
+  };
+}

package/src/seller/payment-identifier.ts

@@ -0,0 +1,104 @@
+import type { PaymentPayload } from '@x402/core/types';
+import { z } from 'zod';
+
+/**
+ * x402 `payment-identifier` extension (seller side): a client-chosen id makes
+ * a repeated operation return the stored response instead of charging again.
+ */
+export const PAYMENT_IDENTIFIER = 'payment-identifier';
+
+/** Same constraints as @x402/extensions (16–128 chars of [A-Za-z0-9_-]). */
+export const paymentIdSchema = z.string().regex(/^[a-zA-Z0-9_-]{16,128}$/);
+
+const extensionSchema = z
+  .object({ info: z.object({ id: z.unknown().optional() }).loose() })
+  .loose();
+
+/** Same declaration as @x402/extensions `declarePaymentIdentifierExtension`. */
+export function paymentIdentifierDeclaration(required: boolean) {
+  return {
+    info: { required },
+    schema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        required: { type: 'boolean' },
+        id: { type: 'string', minLength: 16, maxLength: 128, pattern: '^[a-zA-Z0-9_-]+$' },
+      },
+      required: ['required'],
+    },
+  };
+}
+
+/** The client's id: `undefined` when absent, `'invalid'` when malformed. */
+export function paymentIdOf(payload: PaymentPayload): string | undefined | 'invalid' {
+  const raw = payload.extensions?.[PAYMENT_IDENTIFIER];
+  if (raw === undefined) return undefined;
+  const ext = extensionSchema.safeParse(raw);
+  if (!ext.success) return 'invalid';
+  const id = ext.data.info.id;
+  if (id === undefined) return undefined;
+  const parsed = paymentIdSchema.safeParse(id);
+  return parsed.success ? parsed.data : 'invalid';
+}
+
+/** What the store needs for payment-identifier decisions. */
+export interface PaymentIdStore {
+  bindPaymentId(
+    scopeId: string,
+    fingerprint: string,
+    proofKey: string,
+  ): { fingerprint: string; proofKey: string; created: boolean };
+  /** Compare-and-set: moves the id to `proofKey` only if it still points at `previous`. */
+  rebindPaymentId(scopeId: string, previous: string, proofKey: string): boolean;
+  get(
+    key: string,
+  ): { state: string; response: unknown; paymentResponse: string | null } | undefined;
+}
+
+export type PaymentIdDecision =
+  | { kind: 'proceed' }
+  | { kind: 'replay'; proofKey: string }
+  | { kind: 'reject'; status: 400 | 409; error: string };
+
+/**
+ * One client id = one operation. Contract: the caller has already created the
+ * proof row for `proofKey` (so other requests see it as in progress).
+ * Concurrent retries with DIFFERENT payments
+ * for the same id: exactly one wins the compare-and-set; the others get 409,
+ * so an id can never be charged twice.
+ */
+export function decidePaymentId(
+  store: PaymentIdStore,
+  input: {
+    paymentId: string | undefined | 'invalid';
+    required: boolean;
+    scopeId: (id: string) => string;
+    fingerprint: string;
+    proofKey: string;
+  },
+): PaymentIdDecision {
+  const { paymentId } = input;
+  if (paymentId === 'invalid')
+    return { kind: 'reject', status: 400, error: 'invalid_payment_identifier' };
+  if (paymentId === undefined) {
+    return input.required
+      ? { kind: 'reject', status: 400, error: 'payment_identifier_required' }
+      : { kind: 'proceed' };
+  }
+  const scopeId = input.scopeId(paymentId);
+  const mapping = store.bindPaymentId(scopeId, input.fingerprint, input.proofKey);
+  if (mapping.fingerprint !== input.fingerprint) {
+    return { kind: 'reject', status: 409, error: 'payment_identifier_conflict' };
+  }
+  if (mapping.proofKey === input.proofKey) return { kind: 'proceed' };
+  const original = store.get(mapping.proofKey);
+  if (original?.state === 'served') return { kind: 'replay', proofKey: mapping.proofKey };
+  if (original !== undefined && original.state !== 'failed') {
+    return { kind: 'reject', status: 409, error: 'payment_in_progress' };
+  }
+  // The earlier attempt definitely failed (or never consumed its proof): move the id.
+  return store.rebindPaymentId(scopeId, mapping.proofKey, input.proofKey)
+    ? { kind: 'proceed' }
+    : { kind: 'reject', status: 409, error: 'payment_in_progress' };
+}