@metamynd/agentsafe-http-gateway 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaMynd
+
+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,58 @@
+# AgentSafe HTTP interception gateway (SAFR §17)
+
+A **generic reverse proxy** that governs *arbitrary* HTTP calls — not just MCP. Put it in front of
+any upstream service; requests matching a **protected route** are re-evaluated through the AgentSafe
+gate before they are forwarded, and everything else passes through untouched. Zero dependencies
+(`node:http` + built-in `fetch` + the zero-dep `agentsafe-mcp-guard`).
+
+This closes the gap where governance only sat at the MCP boundary + hand-written demo gateways — now
+a legacy or third-party agent that speaks plain HTTP can be governed at the network edge.
+
+## How it works
+
+```
+agent → [ HTTP gateway ] → upstream service
+              │
+              ├─ route not protected      → forward as-is
+              └─ route protected:
+                    verifyRequest(signed)  → allow/observe → forward upstream (+ x-agentsafe-decision)
+                                           → block/escalate → 403 (upstream never called)
+                                           → no signed request → 401
+                                           → gate error       → 502 (fail closed)
+```
+
+Protected routes are declared in `agentsafe-routes.json` (path patterns: `*` = one segment, `**` =
+the rest). The route **pins the governed action**, so a client cannot relabel a purchase as a cheap
+read. The agent presents its signed MAGP request in the `x-magp-request` header (the same object the
+guard already verifies); the gateway forwards only on `allow`/`observe`.
+
+```json
+[
+  { "method": "POST", "path": "/book/*",     "action": "flight-purchase" },
+  { "method": "POST", "path": "/payments/**", "action": "payment-execute" }
+]
+```
+
+## Run
+
+```bash
+AGENTSAFE_UPSTREAM=https://api.example.com \
+MAGP_API=https://metamynd.ai/api/v1 \
+SERVICE_DID=did:hedera:testnet:... SERVICE_KEY=<hex> \
+AGENTSAFE_ROUTES=agentsafe-routes.json \
+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.
+
+## Embed the core
+
+```js
+import { createHttpGateway } from '@metamynd/agentsafe-http-gateway';
+const handle = createHttpGateway({ guard, routes, forward });          // forward(req) → upstream
+const result = await handle({ method, path, headers, body });          // { status, body, governance? }
+```
+
+Self-check: `node gateway.smoke.mjs` (route matching, pass-through, allow→forward, block→403,
+missing-governance→401, fail-closed, action-pinning, allow-list posture).

package/gateway.mjs

@@ -0,0 +1,74 @@
+// gateway.mjs — the generic HTTP interception gateway (SAFR §17, Phase-5 PR-4). A reverse proxy
+// that GOVERNS arbitrary HTTP calls (not just MCP): matched protected routes are re-evaluated
+// through the guard before the request is forwarded upstream; everything else passes through.
+//
+// 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
+// { 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).
+
+import { matchRoute } from './route-match.mjs';
+
+/** Default extractor: parse the signed MAGP request from the `x-magp-request` header (JSON). */
+export function defaultExtractGovernance(req) {
+  const raw = req.headers?.['x-magp-request'] ?? req.headers?.['X-MAGP-Request'];
+  if (!raw) return null;
+  try {
+    return typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the governed request handler.
+ *   guard   — anything with `verifyRequest(signed) => { decision, reasonCode, ... }` (an MCP guard).
+ *   routes  — protected-route configs (see matchRoute). No match ⇒ pass through (unless denyByDefault).
+ *   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.
+ *
+ * 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 } = {}) {
+  if (typeof forward !== 'function') throw new Error('createHttpGateway requires a forward(req) function');
+
+  return async function handle(req) {
+    const route = matchRoute(routes, req.method, req.path);
+
+    // Unprotected route → pass through (or fail closed under an allow-list posture).
+    if (!route) {
+      if (denyByDefault) {
+        return { status: 403, body: { decision: 'block', reasonCode: 'ROUTE_NOT_ALLOWED', path: req.path } };
+      }
+      return forward(req);
+    }
+
+    // Protected route → the caller must present a signed MAGP request to be governed.
+    const signed = (route.extract ?? extractGovernance)(req);
+    if (!signed) {
+      return { status: 401, body: { decision: 'block', reasonCode: 'MISSING_GOVERNANCE', action: route.action } };
+    }
+    // The route pins the action — a client cannot relabel a governed call as something cheaper.
+    const request = { ...signed, action: route.action ?? signed.action };
+
+    let decision;
+    try {
+      decision = await guard.verifyRequest(request);
+    } catch (err) {
+      // Fail CLOSED: a governance error blocks the upstream call.
+      return { status: 502, body: { decision: 'block', reasonCode: 'GOVERNANCE_ERROR', error: String(err?.message ?? err) } };
+    }
+
+    // allow + observe both PERMIT the upstream call (observe = permit-but-flag, SAFR §11).
+    if (decision?.decision !== 'allow' && decision?.decision !== 'observe') {
+      return { status: 403, body: { decision: decision?.decision ?? 'block', reasonCode: decision?.reasonCode ?? 'BLOCKED' }, governance: decision };
+    }
+    const upstream = await forward(req);
+    return { ...upstream, governance: decision };
+  };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@metamynd/agentsafe-http-gateway",
+  "version": "0.1.1",
+  "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",
+  "exports": {
+    ".": "./gateway.mjs",
+    "./route-match": "./route-match.mjs",
+    "./server": "./server.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "gateway.mjs",
+    "route-match.mjs",
+    "server.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server.mjs",
+    "test": "node gateway.smoke.mjs"
+  },
+  "dependencies": {
+    "@metamynd/agentsafe-mcp-guard": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "http",
+    "gateway",
+    "reverse-proxy",
+    "ai",
+    "agent",
+    "agents",
+    "governance",
+    "authorization",
+    "trustless",
+    "zero-trust",
+    "magp",
+    "metamynd",
+    "agentsafe"
+  ],
+  "author": "MetaMynd",
+  "license": "MIT",
+  "homepage": "https://metamynd.ai/en/developers/spec",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Metamynd/agentsafe-guard.git",
+    "directory": "packages/agentsafe-http-gateway"
+  },
+  "bugs": {
+    "url": "https://github.com/Metamynd/agentsafe-guard/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/route-match.mjs

@@ -0,0 +1,47 @@
+// route-match.mjs — pure protected-route matching for the generic HTTP interception gateway
+// (SAFR §17, Phase-5 PR-4). No IO, so the matching rules are deterministic + unit-testable.
+//
+// A protected route is { method, path, action, ... }. `method` is case-insensitive ('*' = any).
+// `path` is a pattern where a `*` matches EXACTLY ONE segment and a trailing `**` matches the rest
+// (one-or-more segments) — enough to express "/book/*", "/api/**", "/quote". An exact path with no
+// wildcard matches only itself.
+
+/** Split a URL path into non-empty segments (ignoring query + trailing slash). */
+export function segments(path) {
+  const p = String(path || '').split('?')[0];
+  return p.split('/').filter(Boolean);
+}
+
+/**
+ * Whether `path` matches `pattern`. `*` matches exactly one segment; a trailing `**` matches
+ * one-or-more remaining segments. Otherwise segments must match 1:1 (and the lengths must be equal).
+ */
+export function pathMatches(pattern, path) {
+  const pat = segments(pattern);
+  const seg = segments(path);
+  for (let i = 0; i < pat.length; i++) {
+    const token = pat[i];
+    if (token === '**') return seg.length >= pat.length; // tail wildcard: absorb the rest (≥1 segment)
+    if (seg[i] === undefined) return false;
+    if (token === '*') continue; // single-segment wildcard
+    if (token !== seg[i]) return false;
+  }
+  return seg.length === pat.length; // exact length unless a tail wildcard consumed the remainder
+}
+
+/** Whether a route's method matches the request method ('*' or absent = any). */
+export function methodMatches(routeMethod, reqMethod) {
+  if (!routeMethod || routeMethod === '*') return true;
+  return String(routeMethod).toUpperCase() === String(reqMethod || '').toUpperCase();
+}
+
+/**
+ * The first protected route matching (method, path), or null. Order matters — put more specific
+ * routes first. A matched route tells the gateway to GOVERN the request; no match ⇒ pass through.
+ */
+export function matchRoute(routes, method, path) {
+  for (const r of routes || []) {
+    if (methodMatches(r.method, method) && pathMatches(r.path, path)) return r;
+  }
+  return null;
+}

package/server.mjs

@@ -0,0 +1,88 @@
+// server.mjs — binds the generic HTTP interception gateway (SAFR §17, Phase-5 PR-4) to node:http
+// with a fetch-based upstream forwarder + an MCP guard. ZERO external dependencies (node:http +
+// built-in fetch + the zero-dep agentsafe-mcp-guard). Protected routes are re-evaluated through the
+// guard before proxying; everything else passes through to the upstream service unchanged.
+//
+//   AGENTSAFE_UPSTREAM=https://api.example.com \
+//   MAGP_API=https://metamynd.ai/api/v1 SERVICE_DID=did:hedera:... SERVICE_KEY=<hex> \
+//   node server.mjs
+//
+// Protected routes are declared in agentsafe-routes.json (or AGENTSAFE_ROUTES path):
+//   [{ "method": "POST", "path": "/book/*", "action": "flight-purchase" }]
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import { createMcpGuard } from '@metamynd/agentsafe-mcp-guard';
+import { createHttpGateway } from './gateway.mjs';
+
+const UPSTREAM = (process.env.AGENTSAFE_UPSTREAM || '').replace(/\/$/, '');
+const PORT = Number(process.env.PORT || 4000);
+const MAGP_API = process.env.MAGP_API || 'http://localhost:9926/api/v1';
+const ROUTES_PATH = process.env.AGENTSAFE_ROUTES || 'agentsafe-routes.json';
+
+function loadRoutes() {
+  try {
+    return JSON.parse(readFileSync(ROUTES_PATH, 'utf8'));
+  } catch {
+    console.warn(`[gateway] no routes file at ${ROUTES_PATH} — nothing is governed (all pass through)`);
+    return [];
+  }
+}
+
+/** Read the raw request body (bounded) as a Buffer. */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > 5 * 1024 * 1024) reject(new Error('body too large'));
+      else chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+/** fetch-based forwarder to the configured upstream (preserves method, path, headers, body). */
+async function forwardToUpstream(req) {
+  if (!UPSTREAM) return { status: 502, body: { error: 'no AGENTSAFE_UPSTREAM configured' } };
+  const url = UPSTREAM + req.path;
+  const headers = { ...req.headers };
+  delete headers.host; // let fetch set the upstream host
+  const init = { method: req.method, headers };
+  if (req.method !== 'GET' && req.method !== 'HEAD' && req.rawBody?.length) init.body = req.rawBody;
+  const r = await fetch(url, init);
+  const buf = Buffer.from(await r.arrayBuffer());
+  const out = {};
+  r.headers.forEach((v, k) => (out[k] = v));
+  return { status: r.status, headers: out, rawBody: buf };
+}
+
+async function main() {
+  const guard = createMcpGuard({ serviceDid: process.env.SERVICE_DID, serviceKey: process.env.SERVICE_KEY, issuerApi: MAGP_API });
+  const routes = loadRoutes();
+  const gateway = createHttpGateway({ guard, routes, forward: forwardToUpstream });
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const rawBody = await readBody(req);
+      const normalized = { method: req.method, path: req.url, headers: req.headers, rawBody, body: null };
+      const result = await gateway(normalized);
+      const headers = result.headers ?? { 'content-type': 'application/json' };
+      if (result.governance) headers['x-agentsafe-decision'] = result.governance.decision;
+      res.writeHead(result.status, headers);
+      if (result.rawBody) res.end(result.rawBody);
+      else res.end(typeof result.body === 'string' ? result.body : JSON.stringify(result.body ?? {}));
+    } catch (err) {
+      // Fail CLOSED on any gateway error.
+      res.writeHead(502, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ decision: 'block', reasonCode: 'GATEWAY_ERROR', error: String(err?.message ?? err) }));
+    }
+  });
+
+  server.listen(PORT, () => {
+    console.log(`[gateway] AgentSafe HTTP interception gateway on :${PORT} → upstream ${UPSTREAM || '(none)'} (${routes.length} protected route(s))`);
+  });
+}
+
+main().catch((e) => { console.error('[gateway] fatal', e); process.exit(1); });