@craigruks/x402-server-guard 0.1.1 → 0.1.2

package/README.md

@@ -1,8 +1,9 @@
 # x402-server-guard
 
-**Server-side hardening middleware for [x402](https://github.com/coinbase/x402)
+**Server-side hardening middleware for [x402](https://github.com/x402-foundation/x402)
 payment endpoints.**
 
+[![npm](https://img.shields.io/npm/v/@craigruks/x402-server-guard)](https://www.npmjs.com/package/@craigruks/x402-server-guard)
 [![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)
 
@@ -162,13 +163,17 @@ and honesty (is this a strawman, does the reference actually have these gaps, wh
 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 |
+| Attack class | Status | Upstream `@x402/core` 2.29.0 |
+| --- | --- | --- |
+| Duplicate-settlement race | done | partly: closed by the opt-in `upfront` flow ([#3053](https://github.com/x402-foundation/x402/pull/3053)), open in the default flow |
+| Payment replay | done (same nonce reservation) | partly, as for the race |
+| Cross-resource substitution | done (same nonce reservation, distinct reason) | partly: `upfront` denies the reuse, nothing binds or flags the resource |
+| Grant-before-finality (k-confirmations) | done | no: success is one inclusion; a hook can now fail it closed ([#3994](https://github.com/x402-foundation/x402/pull/3994)) |
+| Cache leakage of paid content | done | partly: `private` on the paid 200 since 2.21.0 ([#2990](https://github.com/x402-foundation/x402/pull/2990)), no `no-store`, no `Vary` |
+
+The upstream column is a survey, not a dependency: the guard does not call
+`@x402/core`. Evidence for each entry is in
+[`docs/hardening.md`](./docs/hardening.md#what-upstream-now-covers).
 
 ## Development
 

package/SECURITY.md

@@ -47,7 +47,9 @@ published under a separate tag.
 
 Please report suspected vulnerabilities **privately** via GitHub Security
 Advisories ("Report a vulnerability" on the repository's Security tab), not
-through public issues.
+through public issues. This covers any case where the guard fails to stop an
+attack it claims to mitigate. A public issue that describes a working attack
+discloses it before a fix exists.
 
 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

package/dist/cache.d.ts

@@ -3,7 +3,9 @@
  *
  * 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.
+ * or not. The reference x402 adapters send `private` on the paid 200 as of
+ * `@x402/core` 2.21.0 (unchanged through 2.29.0), and set no directive at all before
+ * it; neither sets `Vary`.
  *
  * 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.
@@ -20,7 +22,9 @@ export interface CacheDirectives {
 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`.
+     * stores despite `no-store` still keys by payer. Defaults to `X-PAYMENT`, the x402
+     * v1 header; an x402 v2 client sends `PAYMENT-SIGNATURE`, so pass that behind a v2
+     * server.
      */
     readonly paymentHeader?: string;
 }

package/dist/cache.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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;;;;;OAKG;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

@@ -3,7 +3,9 @@
  *
  * 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.
+ * or not. The reference x402 adapters send `private` on the paid 200 as of
+ * `@x402/core` 2.21.0 (unchanged through 2.29.0), and set no directive at all before
+ * it; neither sets `Vary`.
  *
  * 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.

package/dist/cache.js.map

@@ -1 +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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoBH,+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/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.1";
+export const VERSION = "0.1.2";
 export { isStorableBySharedCache, paidResponseCacheDirectives, } from "./cache.js";
 export { canonicalNonce, canonicalResource } from "./canonical.js";
 export { guardError } from "./error.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craigruks/x402-server-guard",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",
@@ -70,21 +70,21 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@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.19.0",
-    "esbuild": "0.28.1",
-    "hono": "4.12.30",
-    "miniflare": "4.20260722.0",
-    "publint": "0.3.21",
-    "tsx": "4.23.1",
+    "@biomejs/biome": "2.6.4",
+    "@cloudflare/workers-types": "5.20261104.1",
+    "@types/node": "26.6.6",
+    "@vitest/coverage-v8": "5.1.0",
+    "@x402/core": "2.29.0",
+    "esbuild": "0.28.2",
+    "hono": "4.13.16",
+    "miniflare": "4.20260730.0",
+    "publint": "0.3.25",
+    "tsx": "4.23.15",
     "typescript": "7.0.2",
-    "vitest": "4.1.10"
+    "vitest": "5.1.0"
   },
   "allowScripts": {
-    "esbuild@0.28.1": true,
-    "workerd@1.20260708.1": true
+    "esbuild@0.28.2": true,
+    "workerd@1.20260730.1": true
   }
 }

package/src/cache.ts

@@ -3,7 +3,9 @@
  *
  * 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.
+ * or not. The reference x402 adapters send `private` on the paid 200 as of
+ * `@x402/core` 2.21.0 (unchanged through 2.29.0), and set no directive at all before
+ * it; neither sets `Vary`.
  *
  * 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.
@@ -22,7 +24,9 @@ export interface CacheDirectives {
 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`.
+   * stores despite `no-store` still keys by payer. Defaults to `X-PAYMENT`, the x402
+   * v1 header; an x402 v2 client sends `PAYMENT-SIGNATURE`, so pass that behind a v2
+   * server.
    */
   readonly paymentHeader?: string;
 }

package/src/index.ts

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