@craigruks/x402-server-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craig Ruks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# x402-server-guard
+
+**Server-side hardening middleware for [x402](https://github.com/coinbase/x402)
+payment endpoints.**
+
+[![CI](https://github.com/craigruks/x402-server-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/craigruks/x402-server-guard/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Documentation: https://craigruks.github.io/x402-server-guard/
+
+x402 lets a server charge for a resource by returning `402 Payment Required` and
+verifying a signed payment. Published research has shown that a naïve resource
+server is exploitable in several ways: a payment can be replayed, reused against
+a different resource, raced to duplicate delivery before settlement confirms, or
+leaked to unpaid clients through a shared cache. This library is the enforcement
+layer a merchant wraps their endpoint in to close those gaps.
+
+> [!WARNING]
+> **Status: early, pre-1.0.** All four enumerated attack classes below have a
+> mitigation implemented. It is **not audited** and is **not a security
+> guarantee**; it mitigates these specific classes only and cannot make an insecure
+> endpoint safe on its own. See the mitigation table for scope.
+
+## 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.
+**The authors accept no liability for any loss of funds or damages.** See
+[SECURITY.md](./SECURITY.md) and the [LICENSE](./LICENSE).
+
+## Install
+
+```sh
+npm install @craigruks/x402-server-guard
+```
+
+Node ≥ 22. Zero runtime dependencies. Ships ESM with type declarations; a
+TypeScript or JavaScript consumer both import the same build.
+
+## Usage
+
+Reserve a payment's nonce through the guard before you grant the resource. The
+first request for a nonce wins; a replay or a concurrent race is denied. The
+decision is a value, never a throw, so a stray `try/catch` cannot turn a deny
+into an accidental grant.
+
+```ts
+import { createGuard } from "@craigruks/x402-server-guard";
+
+const guard = createGuard();
+
+// Inside your paid handler, after the facilitator verifies the payment:
+const reservation = await guard.reserve({
+  nonce: authorization.nonce, // the EIP-3009 nonce
+  resource: request.url, // which resource this payment is for
+  expiresAt: Number(authorization.validBefore), // unix seconds
+});
+
+if (!reservation.reserved) {
+  return deny(reservation.reason.code); // e.g. "nonce-already-reserved"
+}
+
+// Settle before granting: a payment that fails to settle yields no resource.
+const settled = await facilitator.settle(payload, requirements);
+if (!settled.success) {
+  return deny("settle failed");
+}
+
+return grant(resource);
+```
+
+> [!WARNING]
+> `createGuard()` with no store uses an in-memory store that protects **one process
+> only**. On Cloudflare Workers, Vercel, AWS Lambda, or any autoscaled fleet, each
+> isolate holds its own map, so replay and race protection do not hold across
+> instances. For those deploys, pass a store backed by an atomic compare-and-set: a
+> Durable Object, Redis `SET NX`, or a database unique constraint (not a plain
+> get-then-put store like Workers KV, which reopens the race). Any backend that
+> implements the `NonceStore` contract works. One is built start to finish in the box, a
+> Cloudflare Durable Object adapter:
+> `import { createDurableObjectNonceStore } from "@craigruks/x402-server-guard/cloudflare"`
+> (see [the deployment guide](https://craigruks.github.io/x402-server-guard/deployment/cloudflare-durable-objects/)).
+> The atomic compare-and-set contract for other backends is in
+> [`docs/hardening.md`](./docs/hardening.md).
+
+### One call: `protect`
+
+`protect` runs the whole secure flow (`reserve → settle → (confirm) → deliver`) and
+returns the cache directives on grant, releasing the reservation if the settle
+fails or finality is not reached. It has no runtime dependencies and takes plain
+callbacks, so it drops into any framework:
+
+```ts
+import { protect } from "@craigruks/x402-server-guard";
+
+// After the facilitator verifies the payment:
+const decision = await protect(
+  guard,
+  { nonce, resource: request.url, expiresAt: Number(authorization.validBefore) },
+  {
+    // settle resolves true only when the payment actually settled.
+    settle: async () => (await facilitator.settle(payload, requirements)).success,
+    deliver: () => resource,
+    // Grant on settle success (finality rests with the facilitator and the chain).
+    // Use `finality: "confirm"` with a `confirm()` callback to hold for k confirmations.
+    finality: "facilitator",
+  },
+);
+if (!decision.granted) return deny(decision.reason.code);
+response.headers.set("Cache-Control", decision.cacheControl);
+return grant(decision.resource);
+```
+
+Two runnable examples: [`examples/secure-flow.ts`](./examples/secure-flow.ts)
+(the concurrent race, blocked) and [`examples/hono-server.ts`](./examples/hono-server.ts)
+(a Hono route protected end to end). Bind the nonce to the **served** route (the
+request URL), not the payload's claimed resource, which is why the binding lives at
+the framework layer.
+
+All four enumerated attack classes are covered; see the table below.
+
+## Design principles
+
+- **Zero runtime dependencies.** The core uses only the Web Platform `crypto` global
+  (`crypto.randomUUID`), present on Node 22+, Cloudflare Workers, and Deno, so the guard
+  runs in any modern runtime without a polyfill. Every dependency is attack surface; a
+  hardening library should have as little of it as possible. Independent signature
+  verification would need cryptographic primitives, so it stays out of the core path by
+  design; the facilitator verifies payments, and the guard hardens the flow around that.
+- **Installs clean under npm v12's hardened defaults**: no lifecycle scripts, no
+  `npm approve-scripts` step, nothing to allow.
+- **Small enough to read.** Source files are capped so the whole library can be
+  audited in an afternoon. Built with plain `tsc` so the published output maps
+  one-to-one to the source you can see.
+- **Framework-agnostic core.** `protect` takes plain callbacks, so the same guard
+  drops into Hono, Express, Next, or Fastify. A Hono binding is shown in the
+  examples; an `@x402/core`-hook convenience wrapper is a thin layer over `protect`.
+
+## Mitigations
+
+Each ships with a paired test proving the attack against a vanilla server and
+proving it blocked by the guard. Every class is mapped to its research, mechanism,
+and proving test in [`docs/coverage-map.md`](./docs/coverage-map.md); the rationale
+is in [`docs/hardening.md`](./docs/hardening.md). The hardest questions about scope
+and honesty (is this a strawman, does the reference actually have these gaps, what
+this does not do) are answered in
+[`docs/objection-handling.md`](./docs/objection-handling.md).
+
+| Attack class | Status |
+| --- | --- |
+| Duplicate-settlement race | done |
+| Payment replay | done (same nonce reservation) |
+| Cross-resource substitution | done (same nonce reservation, distinct reason) |
+| Grant-before-finality (k-confirmations) | done |
+| Cache leakage of paid content | done |
+
+## Development
+
+The local toolchain is pinned with [mise](https://mise.jdx.dev):
+
+```sh
+mise install   # installs Node (Active LTS) + just from mise.toml
+npm ci         # installs the dev toolchain, exact-pinned
+just           # lists every repo command
+just check     # full local gate: typecheck + lint + file-length + tests
+```
+
+Node 24 (Active LTS) is used locally; the published package supports Node ≥22,
+and CI tests both. `npm run build` emits the package with plain `tsc`.
+
+Dev tooling lives in `package.json` scripts (`npm run …`); the [`justfile`](./justfile)
+is the discoverable index for repo operations that aren't npm: supply-chain
+checks, CI, release prep. Run `just` to see them all.
+
+## License
+
+[MIT](./LICENSE) © Craig Ruks

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+## Disclaimer
+
+This software is provided **"AS IS"**, without warranty of any kind, express or
+implied. It is **not audited** and is **not a security guarantee**. It mitigates
+specific, enumerated attack classes against x402 payment endpoints. It cannot
+make an insecure endpoint safe on its own, and it does not remove your
+responsibility to secure your own payment path.
+
+**The authors accept no liability for any loss of funds or damages** arising from
+the use of this software. See the [LICENSE](./LICENSE) (MIT) for the full terms.
+
+How this code is reviewed before merge, and the limits of that review, are described
+in [docs/review.md](./docs/review.md).
+
+An independent audit is welcome. If you review security code professionally, the
+reporting channel below works for audit findings too; we would rather have this
+checked than ask anyone to take our word for it.
+
+## Scope
+
+This library targets server-side ("resource server" / merchant) hardening for the
+x402 protocol. It mitigates five listed line items across four distinct attack
+classes, drawn from published research
+([arXiv:2605.11781](https://arxiv.org/abs/2605.11781),
+[arXiv:2605.30998](https://arxiv.org/abs/2605.30998)):
+the duplicate-settlement race, payment replay, cross-resource substitution,
+grant-before-finality, and cache leakage of paid content. Each is mapped to its
+mechanism and the test that proves it in
+[docs/coverage-map.md](./docs/coverage-map.md), with the rationale in
+[docs/hardening.md](./docs/hardening.md). Anything not listed is out of scope and
+should not be assumed covered.
+
+## Supported versions
+
+Pre-1.0: only the latest published version receives security fixes. The `latest`
+dist-tag will never point at code that has not passed review; unreviewed cuts are
+published under a separate tag.
+
+| Version | Supported |
+| ------- | --------- |
+| latest  | ✅        |
+| < latest | ❌       |
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities **privately** via GitHub Security
+Advisories ("Report a vulnerability" on the repository's Security tab), not
+through public issues.
+
+Include a description, affected version, and a reproduction if possible. Expect an
+acknowledgement within 72 hours. Please allow a reasonable window for a fix before
+public disclosure.

package/dist/cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cache directives for paid responses.
+ *
+ * A shared cache (CDN or reverse proxy) keys on the URL and knows nothing about
+ * payment, so a cacheable paid 200 can be stored and served to the next caller, paid
+ * or not. The reference x402 adapters set no cache directive, leaving that door open.
+ *
+ * The mitigation is a response directive, not a decision about a nonce, so it lives
+ * here as a small pure helper the server or adapter applies to every paid response.
+ * `no-store` is load-bearing (no conforming cache stores it); `private` and `Vary` on
+ * the payment header are defense in depth.
+ */
+/** HTTP header directives to attach to a paid response so no cache serves it onward. */
+export interface CacheDirectives {
+    /** `Cache-Control` value. */
+    readonly cacheControl: string;
+    /** `Vary` value: the request headers a stored response must key on. */
+    readonly vary: string;
+}
+export interface CacheDirectivesOptions {
+    /**
+     * The request header the payment travels in, added to `Vary` so a cache that
+     * stores despite `no-store` still keys by payer. Defaults to `X-PAYMENT`.
+     */
+    readonly paymentHeader?: string;
+}
+/** The cache directives to attach to a paid (200) response. */
+export declare function paidResponseCacheDirectives(options?: CacheDirectivesOptions): CacheDirectives;
+/**
+ * Whether a shared (CDN / reverse-proxy) cache may store a response with this
+ * `Cache-Control`. A conforming shared cache refuses to store a `no-store` or
+ * `private` response. Used by the caching model in the tests. A CDN in force-cache
+ * mode ignores `Cache-Control`; this models a cache that honors it.
+ */
+export declare function isStorableBySharedCache(cacheControl: string | undefined): boolean;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,+DAA+D;AAC/D,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAGjG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMjF"}

package/dist/cache.js

@@ -0,0 +1,31 @@
+/**
+ * Cache directives for paid responses.
+ *
+ * A shared cache (CDN or reverse proxy) keys on the URL and knows nothing about
+ * payment, so a cacheable paid 200 can be stored and served to the next caller, paid
+ * or not. The reference x402 adapters set no cache directive, leaving that door open.
+ *
+ * The mitigation is a response directive, not a decision about a nonce, so it lives
+ * here as a small pure helper the server or adapter applies to every paid response.
+ * `no-store` is load-bearing (no conforming cache stores it); `private` and `Vary` on
+ * the payment header are defense in depth.
+ */
+/** The cache directives to attach to a paid (200) response. */
+export function paidResponseCacheDirectives(options = {}) {
+    const paymentHeader = options.paymentHeader ?? "X-PAYMENT";
+    return { cacheControl: "no-store, private", vary: paymentHeader };
+}
+/**
+ * Whether a shared (CDN / reverse-proxy) cache may store a response with this
+ * `Cache-Control`. A conforming shared cache refuses to store a `no-store` or
+ * `private` response. Used by the caching model in the tests. A CDN in force-cache
+ * mode ignores `Cache-Control`; this models a cache that honors it.
+ */
+export function isStorableBySharedCache(cacheControl) {
+    if (cacheControl === undefined || cacheControl === "") {
+        return true;
+    }
+    const normalized = cacheControl.toLowerCase();
+    return !normalized.includes("no-store") && !normalized.includes("private");
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkBH,+DAA+D;AAC/D,MAAM,UAAU,2BAA2B,CAAC,OAAO,GAA2B,EAAE;IAC9E,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,WAAW,CAAC;IAC3D,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,YAAgC;IACtE,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,UAAU,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;IAC9C,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC7E,CAAC"}

package/dist/canonical.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical keys for the nonce and the resource.
+ *
+ * The guard uses the nonce and resource strings directly as map keys. If one nonce (or
+ * resource) reaches the guard in two encodings, the two forms become two keys for one
+ * payment: the string-encoding cousin of signature malleability. `createGuard` folds
+ * these encodings by default; a caller with a case- or prefix-sensitive scope can
+ * override or opt out (see GuardOptions).
+ */
+/**
+ * Canonicalize a payment nonce: lowercase it and drop a leading `0x`, so `0xABCD`,
+ * `0xabcd`, and `abcd` are one key. Hex case and the `0x` prefix are not part of the
+ * value (the same bytes either way), so folding them cannot merge two distinct nonces.
+ * A caller whose nonce scope is case- or prefix-sensitive should pass their own function.
+ */
+export declare function canonicalNonce(nonce: string): string;
+/**
+ * Canonicalize a resource key. When it is an absolute URL, return the WHATWG-URL
+ * canonical form: scheme and host case-folded, the default port dropped, and
+ * dot-segments resolved. It does NOT decode percent-encoded octets (`%41` stays
+ * `%41`, not `A`), so this is not full RFC 3986 equivalence; two RFC-equivalent paths
+ * that differ only in percent-encoding get different keys. Path, query, and fragment
+ * CASE is preserved, so `/Foo` and `/foo` stay distinct and merging cannot open a
+ * substitution hole; normalize trailing slashes and query order yourself if a resource
+ * needs it. A non-URL key (a bare path or an opaque string) is returned unchanged.
+ * Note: the URL parser's IDN/punycode output can vary with the runtime's ICU, so a
+ * persistent distributed store should pin a stable resource form rather than rely on
+ * this across engine upgrades.
+ */
+export declare function canonicalResource(resource: string): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D"}

package/dist/canonical.js

@@ -0,0 +1,38 @@
+/**
+ * Canonical keys for the nonce and the resource.
+ *
+ * The guard uses the nonce and resource strings directly as map keys. If one nonce (or
+ * resource) reaches the guard in two encodings, the two forms become two keys for one
+ * payment: the string-encoding cousin of signature malleability. `createGuard` folds
+ * these encodings by default; a caller with a case- or prefix-sensitive scope can
+ * override or opt out (see GuardOptions).
+ */
+import { tryCatch } from "./result.js";
+/**
+ * Canonicalize a payment nonce: lowercase it and drop a leading `0x`, so `0xABCD`,
+ * `0xabcd`, and `abcd` are one key. Hex case and the `0x` prefix are not part of the
+ * value (the same bytes either way), so folding them cannot merge two distinct nonces.
+ * A caller whose nonce scope is case- or prefix-sensitive should pass their own function.
+ */
+export function canonicalNonce(nonce) {
+    const lower = nonce.toLowerCase();
+    return lower.startsWith("0x") ? lower.slice(2) : lower;
+}
+/**
+ * Canonicalize a resource key. When it is an absolute URL, return the WHATWG-URL
+ * canonical form: scheme and host case-folded, the default port dropped, and
+ * dot-segments resolved. It does NOT decode percent-encoded octets (`%41` stays
+ * `%41`, not `A`), so this is not full RFC 3986 equivalence; two RFC-equivalent paths
+ * that differ only in percent-encoding get different keys. Path, query, and fragment
+ * CASE is preserved, so `/Foo` and `/foo` stay distinct and merging cannot open a
+ * substitution hole; normalize trailing slashes and query order yourself if a resource
+ * needs it. A non-URL key (a bare path or an opaque string) is returned unchanged.
+ * Note: the URL parser's IDN/punycode output can vary with the runtime's ICU, so a
+ * persistent distributed store should pin a stable resource form rather than rely on
+ * this across engine upgrades.
+ */
+export function canonicalResource(resource) {
+    const parsed = tryCatch(() => new URL(resource));
+    return parsed.ok ? parsed.value.href : resource;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAClC,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjD,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClD,CAAC"}

package/dist/cloudflare/durable-object.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cloudflare Durable Object nonce store: atomic compare-and-set across isolates.
+ *
+ * The default in-memory store protects one process; on Workers each isolate has its
+ * own Map, so N isolates would each grant one nonce N times. This routes every nonce
+ * to its own Durable Object (`idFromName(nonce)`). A Durable Object serves one request
+ * at a time and holds delivery of other events while a storage op to the same object
+ * is in flight (input gating), so the reserve check-and-set runs atomically with no
+ * lock. That is the compare-and-set the store contract requires. See the Cloudflare
+ * store docs for the wrangler binding and deployment shape.
+ */
+import { DurableObject } from "cloudflare:workers";
+import type { NonceStore, ReleaseOutcome, ReserveOutcome } from "../store-types.js";
+/**
+ * The Durable Object the guard reserves against. Bind it in wrangler and export it
+ * from your Worker entry; the adapter routes each nonce to its own instance, so the
+ * single stored entry per object is the reservation for that one nonce.
+ */
+export declare class NonceReservationDO extends DurableObject {
+    /** Atomic reserve: input gating serializes concurrent calls to this same object. */
+    reserve(resource: string, expiresAt: number): Promise<ReserveOutcome>;
+    /** Fenced release: free the nonce only for the holder of the matching token. */
+    release(token: string): Promise<ReleaseOutcome>;
+    /** Cleanup: drop the entry once its window has closed. */
+    alarm(): Promise<void>;
+}
+/** An opaque Durable Object id. A real `DurableObjectId` satisfies this. */
+interface NonceReservationId {
+    toString(): string;
+}
+/** The RPC surface the adapter calls on a {@link NonceReservationDO} stub. */
+interface NonceReservationStub {
+    reserve(resource: string, expiresAt: number): Promise<ReserveOutcome>;
+    release(token: string): Promise<ReleaseOutcome>;
+}
+/**
+ * The Durable Object namespace binding the adapter needs. A real
+ * `DurableObjectNamespace<NonceReservationDO>` satisfies this structurally; type your
+ * binding with that generic so the stub carries the reserve/release RPC methods.
+ */
+export interface NonceReservationNamespace {
+    idFromName(name: string): NonceReservationId;
+    get(id: NonceReservationId): NonceReservationStub;
+}
+/**
+ * Build a {@link NonceStore} backed by the Durable Object namespace. Pass it to
+ * `createGuard({ store })` on any multi-isolate deploy. A transport failure (the object
+ * is unreachable) becomes a `store-unavailable` value, so the guard fails closed.
+ */
+export declare function createDurableObjectNonceStore(namespace: NonceReservationNamespace): NonceStore;
+export {};
+//# sourceMappingURL=durable-object.d.ts.map

package/dist/cloudflare/durable-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-object.d.ts","sourceRoot":"","sources":["../../src/cloudflare/durable-object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EAEd,cAAc,EAGf,MAAM,mBAAmB,CAAC;AAU3B;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,oFAAoF;IAC9E,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAiB1E;IAED,gFAAgF;IAC1E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAOpD;IAED,0DAA0D;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAKpC;CACF;AAMD,4EAA4E;AAC5E,UAAU,kBAAkB;IAC1B,QAAQ,IAAI,MAAM,CAAC;CACpB;AAED,8EAA8E;AAC9E,UAAU,oBAAoB;IAC5B,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACtE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAC7C,GAAG,CAAC,EAAE,EAAE,kBAAkB,GAAG,oBAAoB,CAAC;CACnD;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,yBAAyB,GAAG,UAAU,CAqB9F"}

package/dist/cloudflare/durable-object.js

@@ -0,0 +1,83 @@
+/**
+ * Cloudflare Durable Object nonce store: atomic compare-and-set across isolates.
+ *
+ * The default in-memory store protects one process; on Workers each isolate has its
+ * own Map, so N isolates would each grant one nonce N times. This routes every nonce
+ * to its own Durable Object (`idFromName(nonce)`). A Durable Object serves one request
+ * at a time and holds delivery of other events while a storage op to the same object
+ * is in flight (input gating), so the reserve check-and-set runs atomically with no
+ * lock. That is the compare-and-set the store contract requires. See the Cloudflare
+ * store docs for the wrangler binding and deployment shape.
+ */
+import { DurableObject } from "cloudflare:workers";
+import { guardError } from "../error.js";
+import { err, ok, tryCatchAsync } from "../result.js";
+const ENTRY_KEY = "entry";
+/**
+ * The Durable Object the guard reserves against. Bind it in wrangler and export it
+ * from your Worker entry; the adapter routes each nonce to its own instance, so the
+ * single stored entry per object is the reservation for that one nonce.
+ */
+export class NonceReservationDO extends DurableObject {
+    /** Atomic reserve: input gating serializes concurrent calls to this same object. */
+    async reserve(resource, expiresAt) {
+        const now = nowSeconds();
+        // Refuse an already-closed window before touching storage (matches the memory store).
+        if (expiresAt <= now) {
+            return { status: "expired" };
+        }
+        const existing = await this.ctx.storage.get(ENTRY_KEY);
+        // No `await` on anything but storage between the get and the put, so input gating
+        // keeps this read-modify-write atomic against a concurrent reserve of the same nonce.
+        if (existing !== undefined && existing.expiresAt > now) {
+            return { status: "already-reserved", boundResource: existing.resource };
+        }
+        const token = crypto.randomUUID();
+        await this.ctx.storage.put(ENTRY_KEY, { resource, expiresAt, token });
+        // Evict once the window closes: past `validBefore` the nonce is unreplayable on-chain.
+        await this.ctx.storage.setAlarm(expiresAt * 1000);
+        return { status: "reserved", token };
+    }
+    /** Fenced release: free the nonce only for the holder of the matching token. */
+    async release(token) {
+        const entry = await this.ctx.storage.get(ENTRY_KEY);
+        if (entry === undefined || entry.token !== token) {
+            return { status: "not-held" };
+        }
+        await this.ctx.storage.deleteAll();
+        return { status: "released" };
+    }
+    /** Cleanup: drop the entry once its window has closed. */
+    async alarm() {
+        const entry = await this.ctx.storage.get(ENTRY_KEY);
+        if (entry !== undefined && entry.expiresAt <= nowSeconds()) {
+            await this.ctx.storage.deleteAll();
+        }
+    }
+}
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Build a {@link NonceStore} backed by the Durable Object namespace. Pass it to
+ * `createGuard({ store })` on any multi-isolate deploy. A transport failure (the object
+ * is unreachable) becomes a `store-unavailable` value, so the guard fails closed.
+ */
+export function createDurableObjectNonceStore(namespace) {
+    const stubFor = (nonce) => namespace.get(namespace.idFromName(nonce));
+    return {
+        async reserve({ nonce, resource, expiresAt, }) {
+            const outcome = await tryCatchAsync(() => stubFor(nonce).reserve(resource, expiresAt));
+            return outcome.ok
+                ? ok(outcome.value)
+                : err(guardError("store-unavailable", "durable object reserve failed", outcome.error));
+        },
+        async release(nonce, token) {
+            const outcome = await tryCatchAsync(() => stubFor(nonce).release(token));
+            return outcome.ok
+                ? ok(outcome.value)
+                : err(guardError("store-unavailable", "durable object release failed", outcome.error));
+        },
+    };
+}
+//# sourceMappingURL=durable-object.js.map

package/dist/cloudflare/durable-object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-object.js","sourceRoot":"","sources":["../../src/cloudflare/durable-object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,aAAa,EAAE,MAAM,cAAc,CAAC;AAgBnE,MAAM,SAAS,GAAG,OAAO,CAAC;AAE1B;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACnD,oFAAoF;IACpF,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,SAAiB;QAC/C,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;QACzB,sFAAsF;QACtF,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;YACrB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC/B,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAc,SAAS,CAAC,CAAC;QACpE,kFAAkF;QAClF,sFAAsF;QACtF,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;YACvD,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC1E,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAc,SAAS,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QACnF,uFAAuF;QACvF,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QAClD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,OAAO,CAAC,KAAa;QACzB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAc,SAAS,CAAC,CAAC;QACjE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YACjD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAChC,CAAC;QACD,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACnC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAChC,CAAC;IAED,0DAA0D;IACjD,KAAK,CAAC,KAAK;QAClB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAc,SAAS,CAAC,CAAC;QACjE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,UAAU,EAAE,EAAE,CAAC;YAC3D,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;CACF;AAED,SAAS,UAAU;IACjB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC;AAuBD;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,SAAoC;IAChF,MAAM,OAAO,GAAG,CAAC,KAAa,EAAwB,EAAE,CACtD,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7C,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,EACZ,KAAK,EACL,QAAQ,EACR,SAAS,GACK;YACd,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;YACvF,OAAO,OAAO,CAAC,EAAE;gBACf,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;gBACnB,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,mBAAmB,EAAE,+BAA+B,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3F,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,KAAa,EAAE,KAAa;YACxC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YACzE,OAAO,OAAO,CAAC,EAAE;gBACf,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;gBACnB,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,mBAAmB,EAAE,+BAA+B,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3F,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/error.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Typed errors: viem's error taste, adapted to errors-as-values.
+ *
+ * viem gives every failure a structured error you branch on by identity rather than by
+ * string-matching a message. We want that discipline, but viem THROWS and we carry
+ * errors as values (result.ts), so a `GuardError` is a plain typed object, not a class:
+ * it serializes, needs no `instanceof`, and drops into a discriminated union or a
+ * `Result`'s error slot. The load-bearing field is `code`, a stable branchable
+ * discriminant; `cause` preserves the original throw so wrapping never loses the chain.
+ */
+/** A typed error carried as a value. Branch on `code`, not on `message`. */
+export interface GuardError<Code extends string = string> {
+    /** Stable, branchable discriminant. */
+    readonly code: Code;
+    /** Human-readable detail, for logs and messages, not for control flow. */
+    readonly message: string;
+    /** The originating error, when this wraps a throw. Preserves the chain. */
+    readonly cause?: unknown;
+}
+/** Construct a typed `GuardError`, omitting `cause` when there is none. */
+export declare function guardError<const Code extends string>(code: Code, message: string, cause?: unknown): GuardError<Code>;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,UAAU,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACtD,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAE3E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAClD,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EAEf,KAAK,CAAC,EAAE,OAAO,GACd,UAAU,CAAC,IAAI,CAAC,CAElB"}

package/dist/error.js

@@ -0,0 +1,17 @@
+/**
+ * Typed errors: viem's error taste, adapted to errors-as-values.
+ *
+ * viem gives every failure a structured error you branch on by identity rather than by
+ * string-matching a message. We want that discipline, but viem THROWS and we carry
+ * errors as values (result.ts), so a `GuardError` is a plain typed object, not a class:
+ * it serializes, needs no `instanceof`, and drops into a discriminated union or a
+ * `Result`'s error slot. The load-bearing field is `code`, a stable branchable
+ * discriminant; `cause` preserves the original throw so wrapping never loses the chain.
+ */
+/** Construct a typed `GuardError`, omitting `cause` when there is none. */
+export function guardError(code, message, 
+// biome-ignore lint/plugin: a wrapped cause can be any thrown value
+cause) {
+    return cause === undefined ? { code, message } : { code, message, cause };
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CACxB,IAAU,EACV,OAAe;AACf,oEAAoE;AACpE,KAAe;IAEf,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5E,CAAC"}