@craigruks/x402-server-guard 0.1.0

package/dist/guard.d.ts

@@ -0,0 +1,46 @@
+import { type GuardError } from "./error.js";
+import { type NonceStore, type ReleaseOutcome, type ReserveParams, type StoreError } from "./nonce-store.js";
+import { type Result } from "./result.js";
+/** The deny reasons a reservation can carry. */
+export type GuardErrorCode = "nonce-already-reserved" | "nonce-resource-mismatch" | "nonce-expired" | "store-unavailable" | "store-at-capacity";
+export interface GuardOptions {
+    /** Where reserved nonces are tracked. Defaults to an in-memory store. */
+    store?: NonceStore;
+    /**
+     * Fold a nonce to a canonical key before it is reserved, so two encodings of one
+     * nonce cannot become two grants. Defaults to {@link canonicalNonce}. Pass the
+     * identity `(n) => n` to opt out and key on the exact bytes.
+     */
+    canonicalizeNonce?: (nonce: string) => string;
+    /**
+     * Fold the resource to a canonical key before it is bound. Defaults to
+     * {@link canonicalResource}. Pass the identity `(r) => r` to opt out.
+     */
+    canonicalizeResource?: (resource: string) => string;
+}
+/**
+ * A guard decision: reserved (grant may proceed) or denied with a typed reason.
+ *
+ * The reserved handle carries `release`, to free the nonce if the payment does not go
+ * through so the payer can retry the same authorization. The fencing token that
+ * authorizes the release is held inside the handle, never exposed. Not calling
+ * `release` is safe: the reservation expires with the authorization.
+ */
+export type Reservation = {
+    readonly reserved: true;
+    release(): Promise<Result<ReleaseOutcome, StoreError>>;
+} | {
+    readonly reserved: false;
+    readonly reason: GuardError<GuardErrorCode>;
+};
+export interface Guard {
+    /**
+     * Reserve a payment's nonce before granting. The first caller for a nonce is
+     * reserved; any later caller (replay or concurrent race) is denied. A store
+     * failure denies (fail closed).
+     */
+    reserve(params: ReserveParams): Promise<Reservation>;
+}
+/** Create a guard backed by an in-memory nonce store (or a supplied one). */
+export declare function createGuard(options?: GuardOptions): Guard;
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,YAAY,CAAC;AACzD,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAO,KAAK,MAAM,EAAiB,MAAM,aAAa,CAAC;AAE9D,gDAAgD;AAChD,MAAM,MAAM,cAAc,GACtB,wBAAwB,GACxB,yBAAyB,GACzB,eAAe,GACf,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACrD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC,CAAA;CAAE,CAAC;AAE9E,MAAM,WAAW,KAAK;IACpB;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACtD;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CA6D7D"}

package/dist/guard.js

@@ -0,0 +1,88 @@
+/**
+ * The guard: server-side x402 hardening as decisions, not exceptions.
+ *
+ * A merchant reserves a payment's nonce before granting the resource, so a replay, a
+ * concurrent race, or a cross-resource substitution is denied. The decision is a value
+ * (`Reservation`), never a throw, so a stray `try/catch` cannot turn a deny into an
+ * accidental grant; a store failure fails closed (denies, never grants). The attack
+ * narratives are in the docs site; this is the framework-agnostic core.
+ */
+import { canonicalNonce, canonicalResource } from "./canonical.js";
+import { guardError } from "./error.js";
+import { createMemoryNonceStore, } from "./nonce-store.js";
+import { err, tryCatchAsync } from "./result.js";
+/** Create a guard backed by an in-memory nonce store (or a supplied one). */
+export function createGuard(options = {}) {
+    const store = options.store ?? createMemoryNonceStore();
+    const canonicalizeNonce = options.canonicalizeNonce ?? canonicalNonce;
+    const canonicalizeResource = options.canonicalizeResource ?? canonicalResource;
+    return {
+        async reserve(params) {
+            // Fold both keys to canonical form up front; everything below keys on the
+            // canonical values (see canonical.ts for why two encodings must not split).
+            const nonce = canonicalizeNonce(params.nonce);
+            const resource = canonicalizeResource(params.resource);
+            const result = await callStore(() => store.reserve({ nonce, resource, expiresAt: params.expiresAt }));
+            if (!result.ok) {
+                // callStore already mapped throws to store-unavailable; surface a known store
+                // code as-is, but collapse an unrecognized one (a misbehaving adapter) to
+                // store-unavailable so it still fails closed.
+                const error = result.error;
+                const reason = error.code === "store-at-capacity" || error.code === "store-unavailable"
+                    ? error
+                    : guardError("store-unavailable", "nonce store unavailable", error);
+                return { reserved: false, reason };
+            }
+            switch (result.value.status) {
+                case "reserved": {
+                    const { token } = result.value;
+                    return { reserved: true, release: () => releaseReservation(store, nonce, token) };
+                }
+                case "already-reserved":
+                    // Nonce taken. If first bound to a DIFFERENT resource this is a
+                    // cross-resource substitution, not a replay: report it distinctly. Both
+                    // sides are canonical keys (boundResource was stored canonical).
+                    if (result.value.boundResource !== resource) {
+                        return {
+                            reserved: false,
+                            reason: guardError("nonce-resource-mismatch", "payment nonce is bound to a different resource"),
+                        };
+                    }
+                    return {
+                        reserved: false,
+                        reason: guardError("nonce-already-reserved", "payment nonce is already reserved"),
+                    };
+                case "expired":
+                    return {
+                        reserved: false,
+                        reason: guardError("nonce-expired", "payment authorization has expired"),
+                    };
+                default:
+                    // Defensive: an off-contract status fails closed here rather than falling
+                    // through to an undefined return (a throw).
+                    return {
+                        reserved: false,
+                        reason: guardError("store-unavailable", "nonce store returned an unknown status"),
+                    };
+            }
+        },
+    };
+}
+/**
+ * Run a store op with the fail-closed guarantee in one place: a store that THROWS or
+ * REJECTS becomes a `store-unavailable` value rather than an uncaught rejection, so
+ * fail-closed does not depend on each adapter author. A returned error value is passed
+ * through for the caller to map.
+ */
+async function callStore(op) {
+    const outcome = await tryCatchAsync(op);
+    if (!outcome.ok) {
+        return err(guardError("store-unavailable", "nonce store unavailable", outcome.error));
+    }
+    return outcome.value;
+}
+/** Release a reservation through the store, mapping a store throw to a fail-closed error. */
+function releaseReservation(store, nonce, token) {
+    return callStore(() => store.release(nonce, token));
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @craigruks/x402-server-guard
+ *
+ * Server-side hardening middleware for x402 payment endpoints.
+ *
+ * SECURITY DISCLAIMER: This software is provided "AS IS", without warranty of
+ * any kind. It is NOT audited and is NOT a security guarantee. It mitigates
+ * specific, enumerated attack classes only. It cannot make an insecure payment
+ * endpoint safe on its own. See SECURITY.md for scope and reporting.
+ *
+ * Status: v0.1, in progress. The nonce reservation that stops the settlement
+ * race and payment replay is the first mitigation to land.
+ */
+/** Current package version (semver). */
+export declare const VERSION: string;
+export { type CacheDirectives, type CacheDirectivesOptions, isStorableBySharedCache, paidResponseCacheDirectives, } from "./cache.js";
+export { canonicalNonce, canonicalResource } from "./canonical.js";
+export { type GuardError, guardError } from "./error.js";
+export { createGuard, type Guard, type GuardErrorCode, type GuardOptions, type Reservation, } from "./guard.js";
+export { createMemoryNonceStore, type MemoryNonceStoreOptions, type NonceStore, type ReleaseOutcome, type ReserveError, type ReserveOutcome, type ReserveParams, type StoreError, } from "./nonce-store.js";
+export { type ProtectDecision, type ProtectDenyReason, type ProtectHandlers, protect, } from "./protect.js";
+export { err, ok, type Result, tryCatch, tryCatchAsync } from "./result.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wCAAwC;AACxC,eAAO,MAAM,OAAO,EAAE,MAAgB,CAAC;AAEvC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EACL,WAAW,EACX,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @craigruks/x402-server-guard
+ *
+ * Server-side hardening middleware for x402 payment endpoints.
+ *
+ * SECURITY DISCLAIMER: This software is provided "AS IS", without warranty of
+ * any kind. It is NOT audited and is NOT a security guarantee. It mitigates
+ * specific, enumerated attack classes only. It cannot make an insecure payment
+ * endpoint safe on its own. See SECURITY.md for scope and reporting.
+ *
+ * Status: v0.1, in progress. The nonce reservation that stops the settlement
+ * race and payment replay is the first mitigation to land.
+ */
+/** Current package version (semver). */
+export const VERSION = "0.1.0";
+export { isStorableBySharedCache, paidResponseCacheDirectives, } from "./cache.js";
+export { canonicalNonce, canonicalResource } from "./canonical.js";
+export { guardError } from "./error.js";
+export { createGuard, } from "./guard.js";
+export { createMemoryNonceStore, } from "./nonce-store.js";
+export { protect, } from "./protect.js";
+export { err, ok, tryCatch, tryCatchAsync } from "./result.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wCAAwC;AACxC,MAAM,CAAC,MAAM,OAAO,GAAW,OAAO,CAAC;AAEvC,OAAO,EAGL,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EACL,WAAW,GAKZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,GAQvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAIL,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/nonce-store.d.ts

@@ -0,0 +1,41 @@
+import { 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";
+/** 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;
+}
+/**
+ * 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 declare class MemoryNonceStore implements NonceStore {
+    private readonly reserved;
+    private lastSweep;
+    private readonly now;
+    private readonly maxEntries;
+    constructor(options?: MemoryNonceStoreOptions);
+    /** Number of reservations currently retained. */
+    get size(): number;
+    reserve({ nonce, resource, expiresAt, }: ReserveParams): Promise<Result<ReserveOutcome, ReserveError>>;
+    release(nonce: string, token: string): Promise<Result<ReleaseOutcome, StoreError>>;
+    /** Periodically drop expired reservations so unique-nonce floods stay bounded. */
+    private maybeSweep;
+}
+/**
+ * Create an in-memory nonce store. Optionally inject a clock (`() => unixSeconds`)
+ * and a hard `maxEntries` cap (fresh reserves past it fail closed).
+ */
+export declare function createMemoryNonceStore(options?: MemoryNonceStoreOptions): NonceStore;
+//# sourceMappingURL=nonce-store.d.ts.map

package/dist/nonce-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-store.d.ts","sourceRoot":"","sources":["../src/nonce-store.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,EACX,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,kBAAkB,CAAC;AAQ1B,0FAA0F;AAC1F,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAcD;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,OAAO,GAAE,uBAA4B,EAGhD;IAED,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,EACN,KAAK,EACL,QAAQ,EACR,SAAS,GACV,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC,CAsB/D;IAED,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CASjF;IAED,kFAAkF;IAClF,OAAO,CAAC,UAAU;CAWnB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAExF"}

package/dist/nonce-store.js

@@ -0,0 +1,103 @@
+/**
+ * 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 } from "./result.js";
+/** 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 = () => 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 {
+    reserved = new Map();
+    lastSweep = Number.NEGATIVE_INFINITY;
+    now;
+    maxEntries;
+    constructor(options = {}) {
+        this.now = options.now ?? nowSeconds;
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /** Number of reservations currently retained. */
+    get size() {
+        return this.reserved.size;
+    }
+    reserve({ nonce, resource, expiresAt, }) {
+        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, token) {
+        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. */
+    maybeSweep(now) {
+        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 = {}) {
+    return new MemoryNonceStore(options);
+}
+//# sourceMappingURL=nonce-store.js.map

package/dist/nonce-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-store.js","sourceRoot":"","sources":["../src/nonce-store.ts"],"names":[],"mappings":"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"}

package/dist/protect.d.ts

@@ -0,0 +1,45 @@
+import { type GuardError } from "./error.js";
+import type { Guard, GuardErrorCode } from "./guard.js";
+import type { ReserveParams } from "./nonce-store.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 declare function protect<TResource>(guard: Guard, request: ReserveParams, handlers: ProtectHandlers<TResource>): Promise<ProtectDecision<TResource>>;
+export {};
+//# sourceMappingURL=protect.d.ts.map

package/dist/protect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protect.d.ts","sourceRoot":"","sources":["../src/protect.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,0FAA0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,eAAe,GAAG,WAAW,CAAC;AAE/E,UAAU,mBAAmB,CAAC,SAAS;IACrC,kFAAkF;IAClF,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,8DAA8D;IAC9D,OAAO,IAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,CAAC,SAAS,IACjC,CAAC,mBAAmB,CAAC,SAAS,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,CAAC,GACvE,CAAC,mBAAmB,CAAC,SAAS,CAAC,GAAG;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7B,CAAC,CAAC;AAEP,0FAA0F;AAC1F,MAAM,MAAM,eAAe,CAAC,SAAS,IACjC;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAA;CAAE,CAAC;AAEhF;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,SAAS,EACrC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,eAAe,CAAC,SAAS,CAAC,GACnC,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAgCrC"}

package/dist/protect.js

@@ -0,0 +1,54 @@
+/**
+ * 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 { guardError } from "./error.js";
+import { tryCatchAsync } from "./result.js";
+/**
+ * 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(guard, request, handlers) {
+    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,
+    };
+}
+//# sourceMappingURL=protect.js.map

package/dist/protect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protect.js","sourceRoot":"","sources":["../src/protect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAGzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAmC5C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAY,EACZ,OAAsB,EACtB,QAAoC;IAEpC,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;IACxD,CAAC;IAED,iFAAiF;IACjF,uDAAuD;IACvD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,WAAW,CAAC,OAAO,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,eAAe,EAAE,wBAAwB,CAAC,EAAE,CAAC;IAC3F,CAAC;IAED,oFAAoF;IACpF,qFAAqF;IACrF,kFAAkF;IAClF,qDAAqD;IACrD,IAAI,QAAQ,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACxC,4EAA4E;QAC5E,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,WAAW,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,WAAW,EAAE,sBAAsB,CAAC,EAAE,CAAC;QACrF,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,MAAM,QAAQ,CAAC,OAAO,EAAE;QAClC,YAAY,EAAE,2BAA2B,EAAE,CAAC,YAAY;KACzD,CAAC;AACJ,CAAC"}

package/dist/result.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare function ok<T>(value: T): Result<T, never>;
+/** Wrap a failure value. */
+export declare function err<E>(error: E): Result<never, E>;
+/**
+ * The single sanctioned synchronous throw-boundary. Runs `fn`, returning its
+ * value as `ok` or any thrown value coerced to an `Error` as `err`.
+ */
+export declare function tryCatch<T>(fn: () => T): Result<T, Error>;
+/** The single sanctioned asynchronous throw-boundary. */
+export declare function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T, Error>>;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE9C,4BAA4B;AAC5B,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAEhD;AAED,4BAA4B;AAC5B,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEjD;AAOD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAOzD;AAED,yDAAyD;AACzD,wBAAsB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAOtF"}

package/dist/result.js

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+/** Wrap a success value. */
+export function ok(value) {
+    return { ok: true, value };
+}
+/** Wrap a failure value. */
+export function err(error) {
+    return { ok: false, error };
+}
+// biome-ignore lint/plugin: a caught value is typed unknown by the language
+function toError(caught) {
+    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(fn) {
+    // 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(fn) {
+    // biome-ignore lint/plugin: the one sanctioned asynchronous throw-boundary
+    try {
+        return ok(await fn());
+    }
+    catch (caught) {
+        return err(toError(caught));
+    }
+}
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,4BAA4B;AAC5B,MAAM,UAAU,EAAE,CAAI,KAAQ;IAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,GAAG,CAAI,KAAQ;IAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,4EAA4E;AAC5E,SAAS,OAAO,CAAC,MAAe;IAC9B,OAAO,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAI,EAAW;IACrC,0EAA0E;IAC1E,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,EAAoB;IACzD,2EAA2E;IAC3E,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/store-types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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>>;
+}
+//# sourceMappingURL=store-types.d.ts.map