@metamynd/agentsafe-http-gateway 0.1.1 → 0.2.0

package/README.md

@@ -15,9 +15,10 @@ agent → [ HTTP gateway ] → upstream service
               │
               ├─ route not protected      → forward as-is
               └─ route protected:
+                    no signed request      → 401
+                    payload ≠ signed value → 403 PAYLOAD_NOT_BOUND (verifyRequest never called)
                     verifyRequest(signed)  → allow/observe → forward upstream (+ x-agentsafe-decision)
                                            → block/escalate → 403 (upstream never called)
-                                           → no signed request → 401
                                            → gate error       → 502 (fail closed)
 ```
 
@@ -46,6 +47,38 @@ node server.mjs   # listens on PORT (default 4000)
 `denyByDefault: true` (in `createHttpGateway`) switches to an **allow-list** posture — an unmatched
 route is blocked (`ROUTE_NOT_ALLOWED`) instead of forwarded.
 
+## Payload binding (confused deputy) — on by default since 0.2.0
+
+The signed request authorizes *specific values*; the bytes forwarded upstream are the request
+body — a different object. Before 0.2.0, nothing compared them: an agent could sign a cheap,
+in-policy request in the `x-magp-request` header while shipping an expensive, out-of-policy body,
+and the gateway would verify the header, then forward the body unchanged. Signed $250, executed
+$5000 — a real, confirmed finding, not a hypothetical.
+
+`bind` (default `defaultBindPayload`) pulls `amount`/`currency`/`merchant` out of a **JSON** body
+and compares each to the value that was actually signed — checked *before* `verifyRequest()`, so
+a tampered request is refused locally: no issuer round trip, no nonce consumed. A mismatch
+returns `403 PAYLOAD_NOT_BOUND` naming the offending field. A value the signature never mentioned
+at all also counts as a mismatch — `verifyRequest()` defaults an absent `amount`/`merchant` to
+`0`/`''`, so a body that introduces one against a signature covering neither is the same attack
+wearing a different hat.
+
+**This is secure by default, not opt-in** — the alternative leaves every existing deployment
+carrying the gap, which is the vulnerability rather than a fix for it. Pass `bind: false`
+(globally, or per route) only for a route whose body carries no value fields worth binding.
+
+**Known limitation, deliberate:** a non-JSON body (protobuf, multipart, form-encoded) or a
+nested one (`{ booking: { amount } }`) binds nothing under the default binder and passes on the
+signature alone — failing those closed would brick every reverse-proxy deployment fronting a
+non-JSON or differently-shaped upstream. Give such a route its own binder instead:
+
+```js
+routes: [{
+  method: 'POST', path: '/book/*', action: 'flight-purchase',
+  bind: (req) => { const b = JSON.parse(req.rawBody.toString('utf8')); return { amount: b.booking?.amount }; },
+}]
+```
+
 ## Embed the core
 
 ```js
@@ -55,4 +88,7 @@ const result = await handle({ method, path, headers, body });          // { stat
 ```
 
 Self-check: `node gateway.smoke.mjs` (route matching, pass-through, allow→forward, block→403,
-missing-governance→401, fail-closed, action-pinning, allow-list posture).
+missing-governance→401, fail-closed, action-pinning, allow-list posture) and
+`node bind-payload.smoke.mjs` (tampered field detection, unmentioned-value detection, runs before
+the guard, numeric-string coercion, empty/non-JSON bodies, nested-value binders, the `bind: false`
+opt-out, a throwing binder failing closed).

package/gateway.mjs

@@ -5,10 +5,16 @@
 // This is the framework-agnostic CORE — a pure-ish request handler with the guard + the upstream
 // forwarder INJECTED, so it is testable with fakes. `server.mjs` binds it to node:http + fetch.
 //
-// A protected route: { method, path, action, extract? }. The gateway needs the agent's SIGNED
-// MAGP request to govern the call — by default it reads header `x-magp-request` (JSON of
+// A protected route: { method, path, action, extract?, bind? }. The gateway needs the agent's
+// SIGNED MAGP request to govern the call — by default it reads header `x-magp-request` (JSON of
 // { agentDid, amount, merchant, itinerary, nonce, issuedAt, signature }); a route may override
 // with its own `extract(req)`. The route's `action` is authoritative (the client can't pick it).
+//
+// PAYLOAD BINDING (see `bind` below): the signed request authorizes SPECIFIC VALUES, but the
+// bytes we forward upstream are the request body — a different object. Governing the header
+// while executing the body is a confused-deputy gap: an agent signs a cheap, in-policy request
+// and ships an expensive one. The gateway therefore refuses to forward a body whose governed
+// value fields disagree with the ones that were signed.
 
 import { matchRoute } from './route-match.mjs';
 
@@ -23,6 +29,54 @@ export function defaultExtractGovernance(req) {
   }
 }
 
+/**
+ * The value fields the canonical signed message actually covers (policy-core buildAuthMessage:
+ * `agentDid|action|amount|currency|merchant|nonce|issuedAt`). These — and only these — are the
+ * fields a signature can be said to authorize, so these are what we bind the payload to.
+ */
+export const BOUND_FIELDS = ['amount', 'currency', 'merchant'];
+
+/**
+ * Default payload binder: pull the governed value fields out of a JSON body.
+ *
+ * Returns null when there is nothing to bind — an empty body, a body that is not JSON, or JSON
+ * that mentions none of the governed fields. That is deliberate: a reverse proxy fronts upstreams
+ * whose payloads it cannot parse (protobuf, multipart, form-encoded), and failing those closed
+ * would brick every such deployment. It also means an OPAQUE BODY IS NOT BOUND — if your governed
+ * route carries the amount somewhere this cannot see (a non-JSON encoding, or nested JSON such as
+ * `{ booking: { amount } }`), give the route its own `bind(req)` that digs it out. Without one,
+ * the signature still gates the call but does not constrain that payload.
+ */
+export function defaultBindPayload(req) {
+  const raw = req.rawBody ?? req.body;
+  if (raw == null) return null;
+  let parsed = raw;
+  if (typeof raw === 'string' || raw instanceof Uint8Array) {
+    const text = typeof raw === 'string' ? raw : Buffer.from(raw).toString('utf8');
+    if (!text.trim()) return null;
+    try { parsed = JSON.parse(text); } catch { return null; } // not JSON → nothing to bind
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const out = {};
+  for (const f of BOUND_FIELDS) if (parsed[f] !== undefined) out[f] = parsed[f];
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Whether a payload value matches the value that was signed. `amount` is compared numerically
+ * (a JSON body may carry "500" where the signer sent 500); the rest as strings. Note the signed
+ * defaults verifyRequest() itself applies — amount 0, merchant '' — so a payload that introduces
+ * a value the signed request never mentioned counts as a MISMATCH, which is the whole point.
+ */
+export function boundValueMatches(field, signedValue, payloadValue) {
+  if (field === 'amount') {
+    const a = Number(signedValue ?? 0);
+    const b = Number(payloadValue);
+    return Number.isFinite(a) && Number.isFinite(b) && a === b;
+  }
+  return String(signedValue ?? '') === String(payloadValue ?? '');
+}
+
 /**
  * Build the governed request handler.
  *   guard   — anything with `verifyRequest(signed) => { decision, reasonCode, ... }` (an MCP guard).
@@ -30,11 +84,14 @@ export function defaultExtractGovernance(req) {
  *   forward — async (req) => { status, headers, body }: performs the upstream call. Injected for tests.
  *   extractGovernance — override the signed-request extractor (default: x-magp-request header).
  *   denyByDefault — when true, an UNMATCHED route is blocked (allow-list posture) instead of forwarded.
+ *   bind    — payload binder (default: defaultBindPayload). A route's own `bind` wins. Pass
+ *             `false` to disable binding entirely and restore pre-0.1.2 behaviour — do that only
+ *             for routes that carry no value fields, since it reopens the confused-deputy gap.
  *
  * Returns async (req) => { status, headers?, body, governance? }, where req is a normalized
  * { method, path, headers, body }.
  */
-export function createHttpGateway({ guard, routes = [], forward, extractGovernance = defaultExtractGovernance, denyByDefault = false } = {}) {
+export function createHttpGateway({ guard, routes = [], forward, extractGovernance = defaultExtractGovernance, denyByDefault = false, bind = defaultBindPayload } = {}) {
   if (typeof forward !== 'function') throw new Error('createHttpGateway requires a forward(req) function');
 
   return async function handle(req) {
@@ -56,6 +113,31 @@ export function createHttpGateway({ guard, routes = [], forward, extractGovernan
     // The route pins the action — a client cannot relabel a governed call as something cheaper.
     const request = { ...signed, action: route.action ?? signed.action };
 
+    // Bind the payload to the signature BEFORE asking the issuer anything: a request whose body
+    // contradicts what was signed is refused here, so it costs no round trip and consumes no
+    // nonce. A decision obtained for one set of values must not authorize another set.
+    const binder = route.bind !== undefined ? route.bind : bind;
+    if (binder) {
+      let payload;
+      try {
+        payload = binder(req);
+      } catch (err) {
+        // Fail CLOSED: if we cannot read the payload, we cannot claim the signature covers it.
+        return { status: 502, body: { decision: 'block', reasonCode: 'BIND_ERROR', error: String(err?.message ?? err) } };
+      }
+      if (payload) {
+        for (const field of BOUND_FIELDS) {
+          if (payload[field] === undefined) continue;
+          if (!boundValueMatches(field, request[field], payload[field])) {
+            return {
+              status: 403,
+              body: { decision: 'block', reasonCode: 'PAYLOAD_NOT_BOUND', field, action: route.action },
+            };
+          }
+        }
+      }
+    }
+
     let decision;
     try {
       decision = await guard.verifyRequest(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-http-gateway",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Generic HTTP interception gateway (SAFR §17) — a zero-dependency reverse proxy that governs arbitrary HTTP calls through the AgentSafe gate before forwarding upstream.",
   "type": "module",
   "main": "gateway.mjs",
@@ -19,7 +19,7 @@
   ],
   "scripts": {
     "start": "node server.mjs",
-    "test": "node gateway.smoke.mjs"
+    "test": "node gateway.smoke.mjs && node bind-payload.smoke.mjs"
   },
   "dependencies": {
     "@metamynd/agentsafe-mcp-guard": "^0.1.0"