@routedock/routedock 0.2.0 → 0.3.0

package/README.md

@@ -136,6 +136,311 @@ app.use('/stream', routedock({
 | `onVoucher(index, cumulativeAmount)` | Each verified ed25519 commitment | No |
 | `onSettled(txHash, amount, mode)` | Channel close transaction confirmed | Yes |
 
+## Running a provider in production
+
+The `routedockHono` defaults — `InMemorySeenTxStore` for `seenTxStore` and
+`Store.memory()` for `sessionStore` — are only safe in a single long-lived
+process. Any runtime that can route requests to different isolates or
+processes (Cloudflare Workers, Deno Deploy, Lambda@Edge, or even a
+multi-instance Node deployment) needs the durable stores below, or an agent
+retry can settle a payment twice or lose voucher tracking mid-session.
+
+### Settlement idempotency (`seenTxStore`)
+
+`seenTxStore` guards against double-settlement when an agent retries the same
+payment after a timeout. The in-memory default is per-handler and per-process,
+so a retry landing in a fresh isolate misses the cache and settles again,
+charging twice on-chain.
+
+`SupabaseSeenTxStore` backs it with Postgres, which gives the read-your-writes
+consistency this needs. **Don't use Workers KV here** — it's eventually
+consistent, so a retry can outrun propagation and reintroduce the double
+settle.
+
+Requires the `settlements` table from migration `003_settlement_idempotency`
+(see `supabase/migrations/003_settlement_idempotency.sql`; the follow-up
+migration `004_settlement_retention.sql` adds cleanup for old rows). The store
+needs two required methods, `get`/`set`, plus an optional `claimReplay`;
+`SupabaseSeenTxStore` also needs `006_settlement_replay_limit.sql`. The
+idempotency key is scoped to the method, path, amount and payee, and a cached
+settlement is only replayed within a 60s window and a bounded number of times:
+
+```ts
+import { createClient } from '@supabase/supabase-js'
+import { routedockHono, SupabaseSeenTxStore } from '@routedock/routedock/provider/hono'
+
+const supabase = createClient(env.SUPABASE_URL, env.SUPABASE_SERVICE_KEY)
+const seenTxStore = new SupabaseSeenTxStore(supabase)
+
+app.use('*', routedockHono({
+  modes: ['x402', 'mpp-charge'],
+  pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
+  asset: 'USDC',
+  assetContract: env.USDC_ASSET_CONTRACT,
+  payee: env.STELLAR_PAYEE_ADDRESS,
+  payeeSecretKey: env.STELLAR_PAYEE_SECRET,
+  network: 'testnet',
+  manifest,
+  seenTxStore,
+}))
+```
+
+On Cloudflare Workers, `InMemorySeenTxStore` logs a `console.warn` when
+constructed so this isn't missed silently — but that check only detects the
+Workers user agent, so Bun and Deno operators get no warning today. Don't rely
+on it; wire a durable store explicitly.
+
+### Session state (`sessionStore`)
+
+`sessionStore` backs the `mpp-session` channel store (voucher monotonicity
+tracking). The in-memory default doesn't survive isolate eviction, and
+`MppSessionClient` issues one HTTP request per voucher — so voucher N and
+voucher N+1 can land in different isolates entirely.
+
+> **Note:** this `sessionStore` option takes a `@stellar/mpp` `Store.Store`.
+> That's a different thing from this SDK's own `SessionStore` /
+> `SupabaseSessionStore` (in `packages/sdk/src/store/SessionStore.ts`), which
+> is a separate interface over the Supabase `sessions` table used for
+> dashboards and reconciliation. Don't confuse the two.
+
+On Cloudflare Workers, back it with a Durable Object per channel so voucher
+reads and writes serialize through one instance:
+
+```ts
+import { DurableObject } from 'cloudflare:workers'
+import { Hono } from 'hono'
+import { routedockHono } from '@routedock/routedock/provider/hono'
+import { Store } from '@stellar/mpp/channel/server'
+
+// The provider needs @stellar/mpp as a direct dependency for Store.
+
+export class ChannelSession extends DurableObject<Env> {
+  private app: Hono | null = null
+
+  private buildApp(): Hono {
+    const env = this.env
+    const sessionStore = Store.from({
+      get: (key: string) => this.ctx.storage.get(key),
+      put: (key: string, value: unknown) => this.ctx.storage.put(key, value),
+      delete: async (key: string) => {
+        await this.ctx.storage.delete(key)
+      },
+    })
+
+    const app = new Hono()
+    app.use('*', routedockHono({
+      modes: ['mpp-session'],
+      pricing: {
+        'mpp-session': { rate: '0.0001', channelFactory: env.CHANNEL_CONTRACT_ID },
+      },
+      asset: 'USDC',
+      assetContract: env.USDC_ASSET_CONTRACT,
+      payee: env.STELLAR_PAYEE_ADDRESS,
+      payeeSecretKey: env.STELLAR_PAYEE_SECRET,
+      network: 'testnet',
+      commitmentPublicKey: env.COMMITMENT_PUBLIC_KEY!,
+      sessionStore,
+      manifest,
+    }))
+    return app
+  }
+
+  override async fetch(request: Request): Promise<Response> {
+    this.app ??= this.buildApp()
+    return this.app.fetch(request)
+  }
+}
+```
+
+Route all requests for a given channel to the same object, keyed by channel
+contract, so vouchers for one channel always serialize through one instance:
+
+```ts
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const id = env.CHANNEL_SESSION.idFromName(env.CHANNEL_CONTRACT_ID)
+    return env.CHANNEL_SESSION.get(id).fetch(request)
+  },
+}
+```
+
+Wire the binding and migration in `wrangler.jsonc`:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "CHANNEL_SESSION", "class_name": "ChannelSession" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ChannelSession"] }]
+}
+```
+
+**Limitation:** the Durable Object persists the `@stellar/mpp` channel store
+only. `routedockHono` still tracks `lastCumulativeAmount`, `voucherCount`,
+`lastSignatureHex` and `sessionPayerAddress` in closure scope, so if the
+instance is evicted mid-session those reset, and the close path falls back to
+the client-supplied amount and signature. Moving them into the same durable
+store is tracked separately — check the current state of that work before
+relying on it.
+
+### Orphaned sessions and reconciliation
+
+Without recovery wiring, a session abandoned mid-stream (client disconnects,
+goes idle) just sits open forever with funds locked in the channel. Two pieces
+are required together:
+
+`onOrphaned` writes the session row as `status: 'closing'` (the `sessions`
+table comes from migration `001_init.sql`) so the reconciler can find it.
+
+`idleTimeoutMs` has to be set explicitly. Without it no idle timer is armed,
+and an idle (as opposed to disconnected) session is never flagged orphaned.
+
+On Cloudflare Workers it doesn't help yet. The idle timer is a `setTimeout`
+inside the Durable Object, and Cloudflare evicts an idle object after roughly
+70 to 140 seconds, so the timer never fires. provider-b has the same gap, see
+[#314](https://github.com/winsznx/routedock/issues/314).
+
+The status and cumulative-amount fields need to be written separately.
+Writing `cumulative_amount` in the same update as `status: 'closing'` can
+collide with the `monotonic_cumulative` trigger (`supabase/migrations/001_init.sql:40,48-50`),
+which rejects any update where the new amount isn't strictly greater than the
+stored one — and `onVoucher` has usually already stored that exact amount, so
+the combined update silently fails and the row never reaches `closing`. This
+is the same bug tracked as [#338](https://github.com/winsznx/routedock/issues/338):
+
+```ts
+app.use('*', routedockHono({
+  // ...
+  idleTimeoutMs: 5 * 60_000,
+  onOrphaned: async (channelId, info) => {
+    await supabase.from('sessions')
+      .update({ status: 'closing' })
+      .eq('channel_id', channelId)
+    await supabase.from('sessions')
+      .update({
+        cumulative_amount: info.cumulativeAmount,
+        last_signature: info.lastSignature || null,
+        voucher_count: info.voucherCount,
+      })
+      .eq('channel_id', channelId)
+      .lt('cumulative_amount', info.cumulativeAmount)
+  },
+}))
+```
+
+Then schedule `reconcileAbandonedSessions` to actually settle those `closing`
+sessions with their latest voucher:
+
+```ts
+import { reconcileAbandonedSessions } from '@routedock/routedock/provider/hono'
+
+export default {
+  async scheduled(_controller: unknown, env: Env): Promise<void> {
+    await reconcileAbandonedSessions({
+      supabase,
+      network: 'testnet',
+      payeeSecretKey: env.STELLAR_PAYEE_SECRET,
+      onRecovered: async (channelId, txHash, totalPaid) => {
+        console.log(`[reconcile] recovered ${channelId}: ${txHash} (${totalPaid} USDC)`)
+      },
+    })
+  },
+}
+```
+
+Trigger it on a schedule in `wrangler.jsonc`:
+
+```jsonc
+{
+  "triggers": {
+    "crons": ["*/15 * * * *"]
+  }
+}
+```
+
+### Registering in discovery
+
+A provider doesn't show up in the discovery registry unless it registers
+itself. Sign the manifest, then call `registerProvider` inside
+`ctx.waitUntil(...)` with a `.catch` so a registry hiccup never blocks serving
+a request:
+
+```ts
+import { registerProvider, signManifest } from '@routedock/routedock/provider/hono'
+
+const signed = signManifest(manifest, env.STELLAR_PAYEE_SECRET)
+ctx.waitUntil(
+  registerProvider({
+    supabase,
+    manifest: signed,
+    baseUrl: 'https://your-provider.example.com',
+  }).catch((err) => {
+    console.error('[registry] failed to register provider:', err)
+  }),
+)
+```
+
+This writes to the `providers` table from migration `001_init.sql`.
+
+### Serving `mpp-session-ws`
+
+`mpp-session-ws` upgrades the HTTP connection to a WebSocket after the
+handshake's payment is verified. Hono's `upgradeWebSocket` calls its callback
+before it looks at the `Upgrade` header, so a guard placed only inside that
+callback (throwing when `mppSessionWsVerified(c)` is false) also fires — and
+throws — for an ordinary `mpp-session` GET on the same route, which has
+nothing to do with a WebSocket handshake. Check the header in a separate
+middleware ahead of the upgrade route instead, and let a second, plain route
+serve `mpp-session` requests once the payment middleware has verified them:
+
+```ts
+import { upgradeWebSocket } from 'hono/cloudflare-workers'
+import { routedockHono, mppSessionWsVerified } from '@routedock/routedock/provider/hono'
+
+app.use('*', routedockHono({
+  modes: ['mpp-session', 'mpp-session-ws'],
+  pricing: {
+    'mpp-session': { rate: '0.0001', channelFactory: env.CHANNEL_CONTRACT_ID },
+    'mpp-session-ws': { rate: '0.0001', channelFactory: env.CHANNEL_CONTRACT_ID },
+  },
+  asset: 'USDC',
+  assetContract: env.USDC_ASSET_CONTRACT,
+  payee: env.STELLAR_PAYEE_ADDRESS,
+  payeeSecretKey: env.STELLAR_PAYEE_SECRET,
+  network: 'testnet',
+  commitmentPublicKey: env.COMMITMENT_PUBLIC_KEY!,
+  manifest,
+}))
+
+app.get(
+  '/stream',
+  async (c, next) => {
+    const isUpgrade = c.req.header('upgrade')?.toLowerCase() === 'websocket'
+    if (isUpgrade && !mppSessionWsVerified(c)) {
+      return c.json({ error: 'refusing unverified WebSocket handshake' }, 403)
+    }
+    await next()
+  },
+  upgradeWebSocket(() => ({
+    onMessage: (_evt, ws) => {
+      ws.send(JSON.stringify({ type: 'ack' }))
+    },
+  })),
+)
+
+// mpp-session (HTTP) requests land here after the middleware verified the voucher.
+app.get('/stream', (c) => c.json({ data: '...' }))
+```
+
+### Workers-safe imports
+
+Every snippet above imports from `@routedock/routedock/provider/hono`, which
+re-exports `routedockHono`, `mppSessionWsVerified`, `registerProvider`,
+`signManifest`, `SupabaseSeenTxStore` and `reconcileAbandonedSessions`. Don't
+import from `@routedock/routedock/provider` in a Workers snippet — that's the
+Node-only Express entry point and pulls in dependencies (like `express`) that
+don't run on Workers.
+
 ## React Integration
 
 > **Warning:** These hooks create a RouteDockClient in the browser, so the wallet secret and any commitmentSecret are readable by anyone who loads the page.

package/dist/MppSessionHandler-1EL8QBAn.d.cts

@@ -0,0 +1,215 @@
+import { g as RouteDockLogger, h as RouteDockManifest } from './logger-D8_Q2ytp.cjs';
+import { RequestHandler } from 'express';
+import { Store } from 'mppx';
+
+/**
+ * Idempotency store for payment settlement.
+ *
+ * `x402Handler` and `MppChargeHandler` settle on every request carrying a
+ * payment header. An agent that retries after a post-settlement network
+ * timeout resends the *same* signed payment, which would settle a second time
+ * and invoke `onSettled` twice — double-counting in billing.
+ *
+ * Before settling, a handler derives an idempotency key from the inbound
+ * payment header(s) *together with the resource being paid for* and checks
+ * this store. On a hit it replays the cached settlement response and skips
+ * both the on-chain settle and `onSettled`. A hit older than
+ * {@link SETTLEMENT_REPLAY_WINDOW_MS}, or one replayed more than
+ * {@link MAX_SETTLEMENT_REPLAYS} times, is rejected instead of replayed so a
+ * leaked header cannot buy unlimited requests.
+ *
+ * `claimReplay` and {@link SettlementRecord.createdAt} are optional so a
+ * custom store written against the original two-method (`get`/`set`) contract
+ * keeps compiling. See {@link checkSettlementReplay} for how a store that
+ * supplies neither bounds a replay.
+ *
+ * The default {@link InMemorySeenTxStore} is per-handler and per-process. For
+ * multi-instance deployments, supply a shared implementation backed by Redis,
+ * Supabase, etc.
+ */
+/** The resource a settlement idempotency key is scoped to. */
+interface SettlementScope {
+    /** HTTP method of the paid request (e.g. `GET`). */
+    method: string;
+    /** Path of the paid request, without query string (e.g. `/price`). */
+    path: string;
+    /** Charge amount as declared by the route's requirements. */
+    amount: string;
+    /** Payee address the route settles to. */
+    payTo: string;
+}
+/** Cached outcome of a settlement, replayed on a duplicate payment. */
+interface SettlementRecord {
+    /** On-chain transaction hash (or settlement reference), if known. */
+    txHash: string | null;
+    /** Response headers to re-apply on a replay (e.g. `X-Payment-Response`). */
+    headers?: Record<string, string>;
+    /**
+     * Epoch milliseconds at which the settlement was recorded. Optional for
+     * backwards compatibility with custom stores that predate the replay bound;
+     * a record without it can only be bounded by the replay count.
+     */
+    createdAt?: number;
+}
+interface SeenTxStore {
+    /** Returns the cached settlement for a key, or `undefined` if unseen. */
+    get(key: string): Promise<SettlementRecord | undefined> | SettlementRecord | undefined;
+    /** Records the settlement outcome for a key. */
+    set(key: string, record: SettlementRecord): Promise<void> | void;
+    /**
+     * Optionally, atomically record one replay of `key` and return the new
+     * replay count. Returns `Infinity` when the key is unknown (e.g. evicted
+     * between a `get` and this call), so the caller treats the payment as spent
+     * rather than replaying an unbounded number of times.
+     *
+     * Optional so a custom store written against the original two-method
+     * (`get`/`set`) contract keeps compiling. A store that omits it is still
+     * bounded by {@link SETTLEMENT_REPLAY_WINDOW_MS} when its records carry
+     * {@link SettlementRecord.createdAt}.
+     */
+    claimReplay?(key: string): Promise<number> | number;
+}
+interface InMemorySeenTxStoreOptions {
+    /** Maximum number of entries before FIFO eviction. Defaults to 10,000. */
+    maxEntries?: number;
+    /** Log a startup warning about non-durability. Defaults to true. */
+    warn?: boolean;
+    /** Log sink for the non-durability warning. Defaults to a console-backed logger. */
+    logger?: RouteDockLogger;
+}
+/**
+ * How long after a settlement a byte-identical retry may still replay the
+ * cached response. Matches the `maxTimeoutSeconds: 60` both x402 requirement
+ * objects declare, so past this point the payment is expired anyway.
+ */
+declare const SETTLEMENT_REPLAY_WINDOW_MS = 60000;
+/**
+ * How many times one settled payment may be replayed beyond the original
+ * settlement. The SDK's own clients never resend a byte-identical header —
+ * they re-sign on every retry — so a tight limit costs nothing while stopping
+ * a leaked header from buying unlimited requests.
+ */
+declare const MAX_SETTLEMENT_REPLAYS = 1;
+/** Outcome of checking whether an idempotency key may replay a settlement. */
+type SettlementReplayCheck = {
+    kind: 'miss';
+} | {
+    kind: 'replay';
+    record: SettlementRecord;
+} | {
+    kind: 'spent';
+};
+/**
+ * Decide what a payment bearing `key` should do.
+ *
+ * - `miss`  — no cached settlement; fall through to decode and settle.
+ * - `replay`— a fresh settlement within the replay window and under the replay
+ *             limit; re-apply the recorded headers and skip settling.
+ * - `spent` — the settlement is older than the replay window, or has already
+ *             been replayed the maximum number of times; respond 402 without
+ *             decoding, settling, or invoking callbacks.
+ *
+ * The age check runs first so an expired record never touches the replay
+ * counter.
+ *
+ * Custom stores may predate this function and implement only `get`/`set`:
+ *
+ * - a record that carries `createdAt` but a store without `claimReplay` is
+ *   bounded by {@link SETTLEMENT_REPLAY_WINDOW_MS} alone;
+ * - a record without `createdAt` offers no window to check, so a store's own
+ *   `claimReplay` is the only bound available; a store that supplies neither
+ *   replays as it did before this function existed.
+ */
+declare function checkSettlementReplay(store: SeenTxStore, key: string, now?: number): Promise<SettlementReplayCheck>;
+/**
+ * Default in-memory {@link SeenTxStore}. Bounded by `maxEntries` with FIFO
+ * eviction so a long-running process cannot grow without limit.
+ *
+ * **Not durable.** On serverless/edge runtimes each request may land on a
+ * fresh isolate with an empty cache, which causes duplicate settlements.
+ * Supply a persistent implementation (Supabase, Redis, …) in production.
+ */
+declare class InMemorySeenTxStore implements SeenTxStore {
+    private readonly map;
+    private readonly replayCounts;
+    private readonly order;
+    constructor(maxEntriesOrOptions?: number | InMemorySeenTxStoreOptions);
+    private readonly maxEntries;
+    get(key: string): SettlementRecord | undefined;
+    set(key: string, record: SettlementRecord): void;
+    claimReplay(key: string): number;
+}
+/**
+ * Derive a collision-resistant idempotency key from the inbound
+ * payment-bearing headers, scoped to the resource being paid for. Uses
+ * SHA-256 instead of 32-bit FNV-1a (which has a 2^32 keyspace — birthday
+ * collisions become likely well before the 10_000-entry default store is
+ * full).
+ *
+ * x402 clients send the signed payment in `payment-signature` / `x-payment`;
+ * mppx clients send it in `authorization` (the `Payment` scheme). A retry
+ * resends byte-identical headers, so hashing the first present one yields a
+ * stable key.
+ *
+ * The `scope` (method, path, amount, payTo) is hashed alongside the header so
+ * a payment settled for one route can never replay against another route,
+ * even when the same store is shared across routes. Returns `null` when no
+ * payment header is present (nothing to dedupe — e.g. the initial 402
+ * challenge request).
+ */
+declare function paymentIdempotencyKey(getHeader: (name: string) => string | undefined, scope: SettlementScope): Promise<string | null>;
+
+/** Store shape extended with optional atomic update operation. */
+type ChannelStore = Store.Store & {
+    update?: (key: string, fn: (prev: unknown) => unknown) => Promise<unknown>;
+};
+/** Expected payload shape for voucher cumulative amount entries. */
+interface VoucherStoreValue {
+    amount: string;
+    [key: string]: unknown;
+}
+/** Validates that a stored store value is an object containing a numeric string amount. */
+declare function isVoucherStoreValue(value: unknown): value is VoucherStoreValue;
+type Network = 'testnet' | 'mainnet';
+/** Why a live session was flagged as orphaned (never cleanly closed). */
+type OrphanReason = 'connection-closed' | 'idle-timeout';
+/** Latest signed state of an orphaned session, enough for the reconciler to settle. */
+interface OrphanedSessionInfo {
+    /** Cumulative amount of the highest voucher seen (human-readable, 7 dp). */
+    cumulativeAmount: string;
+    /** Hex-encoded signature of the highest voucher seen. */
+    lastSignature: string;
+    /** Number of vouchers received before teardown. */
+    voucherCount: number;
+    /** What triggered the orphan flag. */
+    reason: OrphanReason;
+}
+interface MppSessionHandlerOptions {
+    payeeSecretKey: string;
+    network: Network;
+    channelFactory: string;
+    rate: string;
+    assetContract?: string;
+    manifest: RouteDockManifest;
+    commitmentPublicKey: string;
+    onSettled?: (txHash: string, totalPaid: string, mode: string, payer: string | null) => Promise<void>;
+    onSessionOpen?: (channelId: string, payer: string | null) => Promise<void>;
+    onVoucher?: (channelId: string, voucherIndex: number, cumulativeAmount: string, signature: string) => Promise<void>;
+    onCallbackError?: (err: unknown, cb: string) => void;
+    /**
+     * Called when the client connection drops mid-session or the session goes
+     * idle, before a clean close. Persist the session as `closing` so the
+     * SessionReconciler can settle it with the latest signed voucher.
+     */
+    onOrphaned?: (channelId: string, info: OrphanedSessionInfo) => Promise<void>;
+    /**
+     * Flag the session orphaned after this many milliseconds with no voucher
+     * activity. Disabled when unset.
+     */
+    idleTimeoutMs?: number;
+    /** Log sink for internal error paths. Defaults to a console-backed logger. */
+    logger?: RouteDockLogger;
+}
+declare function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler;
+
+export { type ChannelStore as C, InMemorySeenTxStore as I, MAX_SETTLEMENT_REPLAYS as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VoucherStoreValue as V, type SettlementRecord as a, type InMemorySeenTxStoreOptions as b, type MppSessionHandlerOptions as c, type OrphanReason as d, SETTLEMENT_REPLAY_WINDOW_MS as e, type SettlementReplayCheck as f, type SettlementScope as g, checkSettlementReplay as h, createMppSessionHandler as i, isVoucherStoreValue as j, paymentIdempotencyKey as p };