@craigruks/x402-server-guard 0.1.0 → 0.1.1

package/README.md

@@ -76,7 +76,7 @@ return grant(resource);
 > 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
+> get-then-put store like Workers KV, which reopens the race condition). 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"`
@@ -137,6 +137,21 @@ All four enumerated attack classes are covered; see the table below.
   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`.
 
+## Taking the dependency (or not)
+
+If you run a payment endpoint, you are right to want as few dependencies as possible.
+This library has none at runtime, and the core is small enough to read in one sitting. If
+you would rather not add a dependency at all, lift the primitives you use straight into
+your own code: the reservation, the finality hold, and the cache directives are each a
+small, self-contained file, and a coding agent can pull over the parts you need in a few
+minutes. That is a supported way to use this.
+
+If you do take the dependency, we have tried to make depending on us safe. Releases
+publish through GitHub Actions using npm trusted publishing (OIDC), so no long-lived npm
+token exists for an attacker to steal; tokens are disallowed on the package, publishing
+requires two-factor auth, and CI-published releases carry build provenance that ties the
+package to the exact commit and workflow that built it.
+
 ## Mitigations
 
 Each ships with a paired test proving the attack against a vanilla server and
@@ -173,6 +188,14 @@ Dev tooling lives in `package.json` scripts (`npm run …`); the [`justfile`](./
 is the discoverable index for repo operations that aren't npm: supply-chain
 checks, CI, release prep. Run `just` to see them all.
 
+## Acknowledgments
+
+Shengchen Ling, an author of "Free-Riding the Agentic Web: A Systematic Security
+Analysis of x402 Payments" ([arXiv:2605.30998](https://arxiv.org/abs/2605.30998)),
+reviewed how this library maps to the paper's flaw classes and invariants and
+confirmed it aligns with the paper's intended interpretation. This is not an
+audit or endorsement of the implementation.
+
 ## License
 
 [MIT](./LICENSE) © Craig Ruks

package/dist/cache.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cache directives for paid responses.
  *
- * A shared cache (CDN or reverse proxy) keys on the URL and knows nothing about
+ * A shared cache (CDN or reverse proxy) is keyed 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.
  *

package/dist/cache.js

@@ -1,7 +1,7 @@
 /**
  * Cache directives for paid responses.
  *
- * A shared cache (CDN or reverse proxy) keys on the URL and knows nothing about
+ * A shared cache (CDN or reverse proxy) is keyed 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.
  *

package/dist/guard.js

@@ -18,7 +18,7 @@ export function createGuard(options = {}) {
     const canonicalizeResource = options.canonicalizeResource ?? canonicalResource;
     return {
         async reserve(params) {
-            // Fold both keys to canonical form up front; everything below keys on the
+            // Fold both keys to canonical form up front; everything below is keyed on the
             // canonical values (see canonical.ts for why two encodings must not split).
             const nonce = canonicalizeNonce(params.nonce);
             const resource = canonicalizeResource(params.resource);

package/dist/guard.js.map

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

package/dist/index.js

@@ -12,7 +12,7 @@
  * race and payment replay is the first mitigation to land.
  */
 /** Current package version (semver). */
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.1";
 export { isStorableBySharedCache, paidResponseCacheDirectives, } from "./cache.js";
 export { canonicalNonce, canonicalResource } from "./canonical.js";
 export { guardError } from "./error.js";

package/dist/nonce-store.js

@@ -5,10 +5,10 @@
  * 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.
+ * Get-then-put stores (Workers KV, S3) reopen the race condition 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
+ * turns into a fail-closed deny. Replay is keyed 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.
@@ -62,7 +62,7 @@ export class MemoryNonceStore {
             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).
+        // entry (which reopens the race condition). 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")));
         }

package/dist/nonce-store.js.map

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

package/dist/store-types.d.ts

@@ -34,7 +34,7 @@ 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).
+     * is keyed 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craigruks/x402-server-guard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Server-side hardening middleware for x402 payment endpoints. Mitigations for settlement races, replay, cross-resource substitution, and cache leakage. Not a security guarantee.",
   "keywords": [
     "x402",
@@ -19,7 +19,7 @@
     "type": "git",
     "url": "git+https://github.com/craigruks/x402-server-guard.git"
   },
-  "homepage": "https://github.com/craigruks/x402-server-guard#readme",
+  "homepage": "https://craigruks.github.io/x402-server-guard/",
   "bugs": {
     "url": "https://github.com/craigruks/x402-server-guard/issues"
   },
@@ -70,16 +70,16 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@biomejs/biome": "2.5.3",
-    "@cloudflare/workers-types": "5.20260714.1",
+    "@biomejs/biome": "2.5.4",
+    "@cloudflare/workers-types": "5.20260718.1",
     "@types/node": "26.1.1",
     "@vitest/coverage-v8": "4.1.10",
-    "@x402/core": "2.18.0",
+    "@x402/core": "2.19.0",
     "esbuild": "0.28.1",
-    "hono": "4.12.29",
-    "miniflare": "4.20260708.1",
+    "hono": "4.12.30",
+    "miniflare": "4.20260722.0",
     "publint": "0.3.21",
-    "tsx": "4.23.0",
+    "tsx": "4.23.1",
     "typescript": "7.0.2",
     "vitest": "4.1.10"
   },

package/src/cache.ts

@@ -1,7 +1,7 @@
 /**
  * Cache directives for paid responses.
  *
- * A shared cache (CDN or reverse proxy) keys on the URL and knows nothing about
+ * A shared cache (CDN or reverse proxy) is keyed 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.
  *

package/src/guard.ts

@@ -70,7 +70,7 @@ export function createGuard(options: GuardOptions = {}): Guard {
   const canonicalizeResource = options.canonicalizeResource ?? canonicalResource;
   return {
     async reserve(params: ReserveParams): Promise<Reservation> {
-      // Fold both keys to canonical form up front; everything below keys on the
+      // Fold both keys to canonical form up front; everything below is keyed on the
       // canonical values (see canonical.ts for why two encodings must not split).
       const nonce = canonicalizeNonce(params.nonce);
       const resource = canonicalizeResource(params.resource);

package/src/index.ts

@@ -13,7 +13,7 @@
  */
 
 /** Current package version (semver). */
-export const VERSION: string = "0.1.0";
+export const VERSION: string = "0.1.1";
 
 export {
   type CacheDirectives,

package/src/nonce-store.ts

@@ -5,10 +5,10 @@
  * 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.
+ * Get-then-put stores (Workers KV, S3) reopen the race condition 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
+ * turns into a fail-closed deny. Replay is keyed 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.
@@ -106,7 +106,7 @@ export class MemoryNonceStore implements NonceStore {
       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).
+    // entry (which reopens the race condition). 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")));
     }

package/src/store-types.ts

@@ -30,7 +30,7 @@ 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).
+   * is keyed 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.