@craigruks/x402-server-guard 0.1.0

package/src/nonce-store.ts

@@ -0,0 +1,149 @@
+/**
+ * The in-memory nonce store, and the shared store contract (re-exported).
+ *
+ * `reserve` is the load-bearing primitive and MUST be atomic: the check and the set
+ * are never split by an `await`. The in-memory store below is atomic by construction
+ * (a synchronous body runs to completion); a distributed store must use a genuine
+ * atomic compare-and-set (a Durable Object, Redis `SET .. NX`, a unique constraint).
+ * Get-then-put stores (Workers KV, S3) reopen the race and are not safe here.
+ *
+ * `reserve` and `release` return a `Result`, so a store failure is a value the guard
+ * turns into a fail-closed deny. Replay keys on the nonce, never the signature, which
+ * is what makes it immune to signature malleability. Full rationale: docs/hardening.md.
+ * The contract itself lives in `store-types.ts` (Node-free, so non-Node adapters can
+ * import it); this module owns the Node in-memory implementation.
+ */
+import { guardError } from "./error.js";
+import { err, ok, type Result } from "./result.js";
+import type {
+  NonceStore,
+  ReleaseOutcome,
+  ReserveError,
+  ReserveOutcome,
+  ReserveParams,
+  StoreError,
+} from "./store-types.js";
+
+export type {
+  NonceStore,
+  ReleaseOutcome,
+  ReserveError,
+  ReserveOutcome,
+  ReserveParams,
+  StoreError,
+} from "./store-types.js";
+
+interface Entry {
+  readonly resource: string;
+  readonly expiresAt: number;
+  readonly token: string;
+}
+
+/** Construction options for {@link MemoryNonceStore} / {@link createMemoryNonceStore}. */
+export interface MemoryNonceStoreOptions {
+  /** Clock as unix seconds. Defaults to the system clock. Inject for tests. */
+  readonly now?: () => number;
+  /** Hard cap on retained reservations; a fresh reserve past it fails closed. */
+  readonly maxEntries?: number;
+}
+
+/** How often (in the store's clock, unix seconds) to sweep expired reservations. */
+const SWEEP_INTERVAL_SECONDS = 60;
+
+/**
+ * Hard ceiling on retained reservations: a fresh reserve past this fails closed
+ * rather than growing without bound (`expiresAt` is attacker-signed, so the sweep
+ * cannot reclaim a far-future entry). Override for the deployment.
+ */
+const DEFAULT_MAX_ENTRIES = 1_000_000;
+
+const nowSeconds = (): number => Math.floor(Date.now() / 1000);
+
+/**
+ * In-memory nonce store for a single process. Atomic because the check and the set
+ * share one synchronous tick.
+ *
+ * Memory is bounded two ways: expired reservations are swept (lossless past
+ * `validBefore`), and because `expiresAt` is the attacker-signed `validBefore` the
+ * sweep alone is no bound, so a hard `maxEntries` cap rejects fresh reservations once
+ * reached (fail closed). Not for serverless isolates; use a shared store with a native
+ * compare-and-set there. Assumes a monotonic clock (the on-chain `validBefore` check is
+ * the end-to-end backstop). Exported for observability in tests; production code should
+ * use `createMemoryNonceStore`.
+ */
+export class MemoryNonceStore implements NonceStore {
+  private readonly reserved = new Map<string, Entry>();
+  private lastSweep = Number.NEGATIVE_INFINITY;
+  private readonly now: () => number;
+  private readonly maxEntries: number;
+
+  constructor(options: MemoryNonceStoreOptions = {}) {
+    this.now = options.now ?? nowSeconds;
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  }
+
+  /** Number of reservations currently retained. */
+  get size(): number {
+    return this.reserved.size;
+  }
+
+  reserve({
+    nonce,
+    resource,
+    expiresAt,
+  }: ReserveParams): Promise<Result<ReserveOutcome, ReserveError>> {
+    const now = this.now();
+    this.maybeSweep(now);
+
+    // An already-expired authorization is never grantable: refuse it in the same
+    // atomic step, before touching the reservation map.
+    if (expiresAt <= now) {
+      return Promise.resolve(ok({ status: "expired" }));
+    }
+
+    const existing = this.reserved.get(nonce);
+    if (existing !== undefined && existing.expiresAt > now) {
+      return Promise.resolve(ok({ status: "already-reserved", boundResource: existing.resource }));
+    }
+    // Reject a fresh reservation once full rather than grow unbounded or evict a live
+    // entry (which reopens the race). Overwriting a dead entry is exempt (no growth).
+    if (existing === undefined && this.reserved.size >= this.maxEntries) {
+      return Promise.resolve(err(guardError("store-at-capacity", "nonce store at capacity")));
+    }
+    const token = crypto.randomUUID();
+    this.reserved.set(nonce, { resource, expiresAt, token });
+    return Promise.resolve(ok({ status: "reserved", token }));
+  }
+
+  release(nonce: string, token: string): Promise<Result<ReleaseOutcome, StoreError>> {
+    const entry = this.reserved.get(nonce);
+    // Fencing: free the nonce only for the holder of the matching token. A missing
+    // entry (expired, swept, already released) or a wrong token frees nothing.
+    if (entry === undefined || entry.token !== token) {
+      return Promise.resolve(ok({ status: "not-held" }));
+    }
+    this.reserved.delete(nonce);
+    return Promise.resolve(ok({ status: "released" }));
+  }
+
+  /** Periodically drop expired reservations so unique-nonce floods stay bounded. */
+  private maybeSweep(now: number): void {
+    if (now - this.lastSweep < SWEEP_INTERVAL_SECONDS) {
+      return;
+    }
+    this.lastSweep = now;
+    for (const [nonce, entry] of this.reserved) {
+      if (entry.expiresAt <= now) {
+        this.reserved.delete(nonce);
+      }
+    }
+  }
+}
+
+/**
+ * Create an in-memory nonce store. Optionally inject a clock (`() => unixSeconds`)
+ * and a hard `maxEntries` cap (fresh reserves past it fail closed).
+ */
+export function createMemoryNonceStore(options: MemoryNonceStoreOptions = {}): NonceStore {
+  return new MemoryNonceStore(options);
+}

package/src/protect.ts

@@ -0,0 +1,96 @@
+/**
+ * The secure flow as one call: reserve, settle, confirm, grant.
+ *
+ * `protect` is the framework-agnostic "wrap your endpoint" core. Verify the payment
+ * with your facilitator first, then call `protect` with the payment's nonce, the
+ * resource being served, and callbacks to settle and deliver. It runs the safe order
+ *
+ *   reserve -> settle -> (confirm finality) -> deliver
+ *
+ * and releases the reservation if the settle fails or finality is not reached, so the
+ * payer can retry. On a grant the caller MUST apply the returned `cacheControl` to the
+ * response: that header is the cache-leak mitigation, and `protect` cannot set it
+ * across an unknown framework. Verify BEFORE calling; the nonce reserved must be the
+ * one the facilitator authenticated (see the malleability note in the nonce store).
+ */
+import { paidResponseCacheDirectives } from "./cache.js";
+import { type GuardError, guardError } from "./error.js";
+import type { Guard, GuardErrorCode } from "./guard.js";
+import type { ReserveParams } from "./nonce-store.js";
+import { tryCatchAsync } from "./result.js";
+
+/** Why a `protect` call did not grant: a guard deny, a failed settle, or non-finality. */
+export type ProtectDenyReason = GuardErrorCode | "settle-failed" | "not-final";
+
+interface ProtectHandlersBase<TResource> {
+  /** Settle the payment through your facilitator. Resolve `true` iff it settled. */
+  settle(): Promise<boolean>;
+  /** Deliver the resource once the payment is safe to grant. */
+  deliver(): TResource | Promise<TResource>;
+}
+
+/**
+ * The settle/deliver callbacks plus an explicit finality posture. Finality is a
+ * required discriminant, not an optional callback, so granting at zero confirmations
+ * is a decision made at the call site, never an implicit default for a security toggle.
+ *
+ * - `finality: "facilitator"` grants on settle success; finality then rests with the
+ *   facilitator and the chain.
+ * - `finality: "confirm"` holds the grant until `confirm()` resolves `true`. A
+ *   `confirm` that rejects or resolves `false` is treated as not-yet-final: the
+ *   reservation is released and the grant withheld.
+ */
+export type ProtectHandlers<TResource> =
+  | (ProtectHandlersBase<TResource> & { readonly finality: "facilitator" })
+  | (ProtectHandlersBase<TResource> & {
+      readonly finality: "confirm";
+      confirm(): Promise<boolean>;
+    });
+
+/** The decision `protect` returns: granted with the resource, or denied with a reason. */
+export type ProtectDecision<TResource> =
+  | { readonly granted: true; readonly resource: TResource; readonly cacheControl: string }
+  | { readonly granted: false; readonly reason: GuardError<ProtectDenyReason> };
+
+/**
+ * Run the guarded secure flow for one already-verified payment. `request` is the
+ * reservation input (the authenticated nonce, the served resource as a canonical
+ * key, and the authorization's `validBefore` as `expiresAt`).
+ */
+export async function protect<TResource>(
+  guard: Guard,
+  request: ReserveParams,
+  handlers: ProtectHandlers<TResource>,
+): Promise<ProtectDecision<TResource>> {
+  const reservation = await guard.reserve(request);
+  if (!reservation.reserved) {
+    return { granted: false, reason: reservation.reason };
+  }
+
+  // A settle callback that rejects (a transient facilitator/RPC error) is a failed
+  // settle, not a grant: release so the payer can retry.
+  const settled = await tryCatchAsync(() => handlers.settle());
+  if (!settled.ok || !settled.value) {
+    await reservation.release();
+    return { granted: false, reason: guardError("settle-failed", "payment did not settle") };
+  }
+
+  // Fail closed on finality: only the explicit "facilitator" posture grants at settle
+  // success. Any other value (a missing or misspelled `finality` from a non-TS caller)
+  // must clear the confirm gate; a missing `confirm` throws and becomes a not-final
+  // deny, never an unintended zero-confirmation grant.
+  if (handlers.finality !== "facilitator") {
+    // A confirm that rejects is not-yet-final too: withhold and free the nonce.
+    const final = await tryCatchAsync(() => handlers.confirm());
+    if (!final.ok || !final.value) {
+      await reservation.release();
+      return { granted: false, reason: guardError("not-final", "settlement not final") };
+    }
+  }
+
+  return {
+    granted: true,
+    resource: await handlers.deliver(),
+    cacheControl: paidResponseCacheDirectives().cacheControl,
+  };
+}

package/src/result.ts

@@ -0,0 +1,60 @@
+/**
+ * Result: errors as values.
+ *
+ * The library does not throw for expected failures. An operation that can fail returns
+ * a `Result`, so the failure is a typed value the caller has to handle, and nothing is
+ * silently swallowed by a stray `try/catch` and turned into an accidental grant.
+ *
+ * Operational failure (parsing, store I/O) is a `Result<T, E>`. Domain decisions
+ * (allow / deny-with-reason) are their own discriminated unions, not `Result`: a deny
+ * is a normal decision, not an error.
+ *
+ * `try/catch` is banned everywhere except the two converters below (see
+ * `.biome/plugins/no-try-catch.grit`). Wrap throwing code once, here.
+ *
+ * Prior art: Rust's `Result`, Haskell's `Either`, and in TypeScript neverthrow and
+ * Effect. We bake our own four primitives rather than take a runtime dependency, which
+ * would break the zero-dependency guarantee that is part of the security pitch.
+ */
+
+export type Result<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+/** Wrap a success value. */
+export function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+/** Wrap a failure value. */
+export function err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+// biome-ignore lint/plugin: a caught value is typed unknown by the language
+function toError(caught: unknown): Error {
+  return caught instanceof Error ? caught : new Error(String(caught));
+}
+
+/**
+ * The single sanctioned synchronous throw-boundary. Runs `fn`, returning its
+ * value as `ok` or any thrown value coerced to an `Error` as `err`.
+ */
+export function tryCatch<T>(fn: () => T): Result<T, Error> {
+  // biome-ignore lint/plugin: the one sanctioned synchronous throw-boundary
+  try {
+    return ok(fn());
+  } catch (caught) {
+    return err(toError(caught));
+  }
+}
+
+/** The single sanctioned asynchronous throw-boundary. */
+export async function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T, Error>> {
+  // biome-ignore lint/plugin: the one sanctioned asynchronous throw-boundary
+  try {
+    return ok(await fn());
+  } catch (caught) {
+    return err(toError(caught));
+  }
+}

package/src/store-types.ts

@@ -0,0 +1,62 @@
+/**
+ * The nonce store contract: the shape every store implements.
+ *
+ * Kept free of any runtime import (no `node:crypto`, no Node globals) so a
+ * non-Node adapter (a Cloudflare Durable Object, Deno, an edge runtime) can import
+ * the contract without dragging Node built-ins into its build. The in-memory store
+ * and its Node-specific bits live in `nonce-store.ts`, which re-exports these.
+ */
+import type { GuardError } from "./error.js";
+import type { Result } from "./result.js";
+
+/**
+ * The outcome of a reserve. `reserved` carries a fencing `token`: only its holder can
+ * later `release`, so releasing an in-flight hold is not a griefing primitive.
+ */
+export type ReserveOutcome =
+  | { readonly status: "reserved"; readonly token: string }
+  | { readonly status: "already-reserved"; readonly boundResource: string }
+  | { readonly status: "expired" };
+
+/** The outcome of a release. `not-held` means no matching token: nothing was freed. */
+export type ReleaseOutcome = { readonly status: "released" } | { readonly status: "not-held" };
+
+/** The only error a `release` reports, and what the guard collapses any unrecognized store failure to (fail closed). */
+export type StoreError = GuardError<"store-unavailable">;
+
+/** What a `reserve` can report: a `StoreError`, or the store being at its hard `maxEntries` capacity. Branch on `code`. */
+export type ReserveError = StoreError | GuardError<"store-at-capacity">;
+
+export interface ReserveParams {
+  /**
+   * The payment's nonce; the x402 exact scheme uses a random 32-byte value. The guard
+   * keys on this nonce alone (folded to a canonical form by default, see canonical.ts).
+   * It does not scope by chain or asset, so a store shared across several chains or
+   * assets should namespace the nonce per (chain, asset) itself to keep two distinct
+   * payments from colliding; a direct store caller must also pre-fold it.
+   */
+  readonly nonce: string;
+  /**
+   * The resource this payment is spent on, as a canonical key. Substitution compares
+   * this to the resource the nonce first bound to, so equal resources must produce an
+   * equal string. The guard canonicalizes URL casing by default.
+   */
+  readonly resource: string;
+  /**
+   * Unix seconds, the authorization's `validBefore`. Used two ways: `reserve` refuses
+   * an authorization whose window has closed (`expiresAt <= now`), and past this time a
+   * live reservation may be evicted (unreplayable on-chain, so dropping it is lossless).
+   */
+  readonly expiresAt: number;
+}
+
+/** A store of reserved payment nonces. `reserve` must be atomic. */
+export interface NonceStore {
+  reserve(params: ReserveParams): Promise<Result<ReserveOutcome, ReserveError>>;
+  /**
+   * Release a reservation so the nonce can be reserved again (e.g. after a failed or
+   * reorged settlement, so a legitimate payer can retry). Releases only if `token`
+   * matches the one `reserve` returned (fencing); otherwise frees nothing (`not-held`).
+   */
+  release(nonce: string, token: string): Promise<Result<ReleaseOutcome, StoreError>>;
+}