drupal-mcp-connector 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.10.0] - 2026-08-27
+
+### Security
+- **Lab fan-down strips caller credential headers (#229).** The
+  outbound-relay lab harness framed the northbound request's headers down
+  the tenant tunnel verbatim, including `Authorization` — invisible in the
+  lab (the stub is in-process and the lab northbound carries no bearer),
+  but the wrong pattern for anyone wiring the README's optional live hop.
+  `Authorization`, `Cookie`, and `Proxy-Authorization` are now stripped,
+  with hop-by-hop headers, before framing; a test asserts marker
+  credentials never appear in any frame crossing the tunnel. The lab
+  README now states plainly that the lab northbound does not authenticate
+  the caller (the lab credential authenticates the agent channel) — the
+  product edge's northbound OAuth is DEV-294 work, not this harness.
+
+### Added
+- **Deployment documentation for the relay edge and tenant-agent entry
+  points (#232).** `docs/deployment.md` gains the outbound-path section:
+  startup requirements, credential-header stripping, channel credentials,
+  and the issuer claim requirements.
+- **Relay edge and tenant-agent entry points (#232).** `drupal-mcp-edge`
+  terminates northbound MCP on the inbound OAuth resource server — the only
+  authentication arm on this entry point; a missing issuer/audience is fatal
+  at any bind host, including loopback — and fans requests down an outbound
+  tenant channel. The edge requires a non-empty `auth.grants` table and an
+  agent channel credential store to start, resolves the authoritative target
+  per request before fan-down, strips caller credential and
+  identity-assertion headers before framing (the frame carries the validated
+  identity object only), and holds no site credentials — a catalog entry
+  carrying credential material refuses startup. `drupal-mcp-agent` dials out
+  (it never listens), authenticates the channel with its own issued,
+  revocable credential, and serves the real connector tool surface, so site
+  credentials exist only in the tenant process. Northbound is stateless MCP
+  2026-07-28 with no session ids in either direction; revocation of both the
+  northbound principal and the agent channel is per-request with no grace
+  window. The frame codec lives at `src/lib/relay/frames.js` with hard size,
+  teardown, and timeout bounds. These are entry points and libraries only;
+  nothing here is a hosted service.
+- **Lab-only outbound-relay harness (DEV-293).** Isolated under
+  `lab/outbound-relay/` with tests in `tests/lab/`. A tenant agent dials out
+  to a loopback relay; one MCP 2026-07-28 Streamable-HTTP request (stateless,
+  no `Mcp-Session-Id`) reaches an in-process stub private Drupal; reconnect
+  keeps the same tunnel identity; revocation is checked per request (next
+  request denied, no grace window). This is not a public surface, not a
+  hosted-service claim, and not DEV-294. Hosted MCP is unstarted.
+
 ## [2.9.0] - 2026-08-26
 
 ### Fixed

package/bin/drupal-mcp-agent.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * drupal-mcp-agent — relay tenant agent entry point (#232).
+ *
+ * Dials OUT to the relay edge's agent channel and serves the real connector
+ * server (the full governed tool surface, dispatched through the same
+ * middleware as every other transport) over the framed tunnel. This process
+ * never listens: southbound site credentials exist only here, tenant-side.
+ * The channel is authenticated with the agent's own issued, revocable
+ * credential — never a northbound token, never a site credential.
+ *
+ * Environment variables:
+ *   MCP_EDGE_HOST         Relay edge host. Required.
+ *   MCP_EDGE_AGENT_PORT   Relay edge agent-channel port. Required.
+ *   MCP_CHANNEL_TOKEN     Issued channel credential (or MCP_CHANNEL_TOKEN_FILE).
+ *                         Required. The edge stores only its SHA-256 digest.
+ *   MCP_EDGE_ALLOW_TCP    "1" permits a plain TCP channel to loopback only
+ *                         (dev). The default channel is TLS.
+ *
+ * On a lost channel the process exits non-zero — fail loudly and let the
+ * supervisor restart it rather than idling disconnected.
+ */
+
+import { readFileSync } from "node:fs";
+import { connect as netConnect } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+import process from "node:process";
+import { CLIENT_VERSION, listSiteNames, loadConfig } from "../src/lib/config.js";
+import { callTool, listResolvableSiteConfigs } from "../src/lib/dispatch.js";
+import { filterDiscoverableTools } from "../src/lib/governance.js";
+import {
+  loadLocalSecrets,
+  secretLoadFatalMessage,
+  secretTableMismatchMessage,
+} from "../src/lib/load-secrets.js";
+import {
+  filterPromptsByPrincipal,
+  filterResourcesByPrincipal,
+  filterToolsByPrincipal,
+  getRequestIdentity,
+  visibleSiteTargets,
+} from "../src/lib/principal.js";
+import { createRelayAgent } from "../src/lib/relay/agent.js";
+import { buildToolPrompts, getToolPromptMessages } from "../src/lib/tool-prompts.js";
+import { allDefinitions, definitionsByName } from "../src/tools/index.js";
+
+function fatal(message) {
+  console.error(`[drupal-mcp-agent] FATAL: ${message}`);
+  process.exit(1);
+}
+
+const host = process.env.MCP_EDGE_HOST || "";
+const port = Number(process.env.MCP_EDGE_AGENT_PORT || 0);
+if (!host || !port) {
+  fatal("Set MCP_EDGE_HOST and MCP_EDGE_AGENT_PORT to the relay edge's agent channel.");
+}
+
+const tokenFile = process.env.MCP_CHANNEL_TOKEN_FILE || "";
+const token = process.env.MCP_CHANNEL_TOKEN
+  // eslint-disable-next-line security/detect-non-literal-fs-filename -- credential path comes from the operator's environment, not user input
+  || (tokenFile ? readFileSync(tokenFile, "utf8").trim() : "");
+if (!token) {
+  fatal(
+    "The tenant agent requires its issued channel credential: set "
+    + "MCP_CHANNEL_TOKEN or MCP_CHANNEL_TOKEN_FILE.",
+  );
+}
+
+// Apply config/secrets.map before any site resolution, exactly like the
+// primary entry point: this process is where site credentials live.
+const secretLoad = loadLocalSecrets();
+const secretFatal = secretLoadFatalMessage(secretLoad);
+if (secretFatal) fatal(secretFatal);
+const secretMismatch = secretTableMismatchMessage(secretLoad);
+if (secretMismatch) {
+  console.error(`[drupal-mcp-agent] WARNING: ${secretMismatch}`);
+} else if (secretLoad.unset.length) {
+  console.error(
+    "[drupal-mcp-agent] WARNING: config.json names secret env vars that are unset: "
+    + `${secretLoad.unset.join(", ")}. Those sites will fail closed.`,
+  );
+}
+
+try {
+  loadConfig();
+} catch (error) {
+  fatal(error instanceof Error ? error.message : "configuration load failed");
+}
+
+// ---------------------------------------------------------------------------
+// Connector surface — the real governed tool surface. Workflow prompts and
+// the templated resources stay on the primary entry point; the governed
+// surface here is tools (full), the sites resource, and per-tool prompts.
+// ---------------------------------------------------------------------------
+
+const RESOURCES = [{
+  uri: "drupal://sites",
+  name: "Configured Drupal Sites",
+  description: "All named Drupal site profiles (no credentials).",
+  mimeType: "application/json",
+}];
+
+const TOOL_PROMPTS = buildToolPrompts(allDefinitions);
+
+async function discoverableTools() {
+  const sites = listResolvableSiteConfigs();
+  const identity = getRequestIdentity();
+  const governed = await filterDiscoverableTools(allDefinitions, sites);
+  return filterToolsByPrincipal(governed, sites, identity);
+}
+
+const surface = {
+  serverInfo: { name: "drupal-mcp-connector", version: CLIENT_VERSION },
+  tools: {
+    definitions: allDefinitions,
+    list: discoverableTools,
+    call: callTool,
+  },
+  resources: {
+    definitions: RESOURCES,
+    list: async () => {
+      const sites = listResolvableSiteConfigs();
+      return filterResourcesByPrincipal(RESOURCES, getRequestIdentity(), sites);
+    },
+    read: async (uri) => {
+      if (uri === "drupal://sites") {
+        return visibleSiteTargets(
+          getRequestIdentity(),
+          listResolvableSiteConfigs(),
+          listSiteNames(),
+        );
+      }
+      throw new Error(`Unknown resource URI: ${uri}`);
+    },
+  },
+  prompts: {
+    definitions: TOOL_PROMPTS,
+    list: async () => {
+      const identity = getRequestIdentity();
+      const tools = await discoverableTools();
+      return filterPromptsByPrincipal(TOOL_PROMPTS, identity, tools);
+    },
+    get: (name, args) => getToolPromptMessages(name, args, definitionsByName),
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Channel — TLS by default; plain TCP only to loopback, by explicit opt-in.
+// ---------------------------------------------------------------------------
+
+const allowTcp = process.env.MCP_EDGE_ALLOW_TCP === "1";
+const isLoopbackEdge = host === "127.0.0.1" || host === "::1" || host === "localhost";
+let connectFn;
+if (allowTcp) {
+  if (!isLoopbackEdge) {
+    fatal("MCP_EDGE_ALLOW_TCP permits a plain channel to loopback only. Use TLS.");
+  }
+  connectFn = netConnect;
+} else {
+  connectFn = (options, onConnect) =>
+    tlsConnect({ ...options, servername: host }, onConnect);
+}
+
+const agent = createRelayAgent({
+  host,
+  port,
+  token,
+  surface,
+  connectFn,
+  onChannelClose: () => {
+    fatal("The channel to the relay edge was lost. Exiting for a supervised restart.");
+  },
+});
+
+let hello;
+try {
+  hello = await agent.dial();
+} catch (error) {
+  fatal(`Could not dial the relay edge at ${host}:${port}: `
+    + `${error instanceof Error ? error.message : "unknown error"}`);
+}
+if (!hello.ok) {
+  fatal(`The relay edge denied the channel credential (${hello.reason}).`);
+}
+
+console.error(
+  `[drupal-mcp-agent v${CLIENT_VERSION}] Outbound channel to ${host}:${port} `
+  + `established as "${hello.agent?.agentId ?? "unknown"}" · `
+  + `${allDefinitions.length} tools · ${RESOURCES.length} resources · `
+  + `${TOOL_PROMPTS.length} prompts`,
+);

package/bin/drupal-mcp-edge.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * drupal-mcp-edge — relay northbound edge entry point (#232).
+ *
+ * Terminates northbound MCP on the inbound OAuth resource server and fans
+ * requests down the outbound tenant-agent channel (see src/lib/relay/edge.js).
+ * There is no shared-bearer and no unauthenticated mode on this entry point:
+ * MCP_AUTH_TOKEN and MCP_ALLOW_UNAUTHENTICATED are ignored, and a missing
+ * issuer/audience is fatal at every bind host including loopback. The edge
+ * holds no site credentials; its site catalog is names and base URLs only.
+ *
+ * Environment variables:
+ *   MCP_RESOURCE_ISSUER / MCP_RESOURCE_AUDIENCE / MCP_RESOURCE
+ *                     Inbound OAuth resource server (or config auth.issuer /
+ *                     auth.audience / auth.resource). Required.
+ *   MCP_CHANNEL_CREDENTIALS_FILE
+ *                     Agent channel credential store (or config
+ *                     relay.channelCredentialsFile). Required. JSON:
+ *                     {"agents": {"<id>": {"tokenSha256": "<hex>"}}}
+ *   MCP_EDGE_PORT     Northbound port (default: MCP_PORT / config tls.port).
+ *   MCP_EDGE_AGENT_PORT
+ *                     Agent channel port (default: northbound port + 1).
+ *   MCP_BIND_HOST     Northbound bind when TLS is present (default 0.0.0.0).
+ *   MCP_EDGE_AGENT_BIND_HOST
+ *                     Agent channel bind (default: the northbound bind).
+ *   TLS_CERT_PATH / TLS_KEY_PATH
+ *                     TLS material for both listeners.
+ *   MCP_ALLOW_HTTP    "1" permits plain loopback listeners (dev only).
+ *   MCP_RATE_LIMIT / MCP_RATE_WINDOW_SEC
+ *                     Northbound /mcp rate limit (same defaults as the
+ *                     primary entry point).
+ *
+ * Config: auth.grants (client id -> [site names]) is mandatory; the edge
+ * refuses to start without it.
+ */
+
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import { getInboundGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
+import { resolveInboundAuthConfig } from "../src/lib/http-auth.js";
+import { createRateLimiter } from "../src/lib/rate-limit.js";
+import {
+  createChannelCredentialStore,
+  startEdge,
+} from "../src/lib/relay/edge.js";
+
+function fatal(message) {
+  console.error(`[drupal-mcp-edge] FATAL: ${message}`);
+  process.exit(1);
+}
+
+let config;
+try {
+  config = loadConfig();
+} catch (error) {
+  fatal(error instanceof Error ? error.message : "configuration load failed");
+}
+
+const inboundCfg = resolveInboundAuthConfig(config);
+if (!inboundCfg.issuer || !inboundCfg.audience) {
+  fatal(
+    "The relay edge requires an inbound OAuth resource server: set auth.issuer and "
+    + "auth.audience (or MCP_RESOURCE_ISSUER / MCP_RESOURCE_AUDIENCE). There is no "
+    + "shared-bearer or unauthenticated mode on this entry point, at any bind host "
+    + "including loopback.",
+  );
+}
+
+const grants = getInboundGrants();
+if (!grants) {
+  fatal(
+    "The relay edge refuses to start without a non-empty auth.grants table "
+    + "(client id -> [site names]).",
+  );
+}
+
+const channelFile = process.env.MCP_CHANNEL_CREDENTIALS_FILE
+  || config.relay?.channelCredentialsFile
+  || "";
+if (!channelFile) {
+  fatal(
+    "The relay edge requires an agent channel credential store: set "
+    + "MCP_CHANNEL_CREDENTIALS_FILE (or relay.channelCredentialsFile).",
+  );
+}
+
+// The catalog is passed as configured; startEdge refuses any entry carrying
+// credential material, so a tenant config deployed to an edge host fails
+// closed instead of quietly holding site secrets.
+const sites = Object.entries(config.sites ?? {})
+  .map(([name, site]) => ({ _name: name, ...site }));
+
+const tlsCfg = getTlsConfig();
+let tls = null;
+if (tlsCfg.certPath && tlsCfg.keyPath) {
+  tls = {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- TLS cert/key path comes from operator-controlled config, not user input
+    cert: readFileSync(tlsCfg.certPath),
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- TLS cert/key path comes from operator-controlled config, not user input
+    key: readFileSync(tlsCfg.keyPath),
+  };
+}
+const allowHttp = process.env.MCP_ALLOW_HTTP === "1";
+const bindHost = tls ? (process.env.MCP_BIND_HOST || "0.0.0.0") : "127.0.0.1";
+const agentBindHost = process.env.MCP_EDGE_AGENT_BIND_HOST || bindHost;
+const isLoopbackBind = bindHost === "127.0.0.1" || bindHost === "::1" || bindHost === "localhost";
+
+const port = Number(process.env.MCP_EDGE_PORT || tlsCfg.port);
+const agentPort = Number(process.env.MCP_EDGE_AGENT_PORT || port + 1);
+
+// Northbound rate limiting, same defaults as the primary entry point (#141).
+const rateWindowSec = Number(process.env.MCP_RATE_WINDOW_SEC || 60);
+const rateLimitEnv = process.env.MCP_RATE_LIMIT;
+const rateLimitDefault = (tls && !isLoopbackBind) ? 120 : 0;
+const rateLimit = rateLimitEnv === undefined || rateLimitEnv === ""
+  ? rateLimitDefault
+  : Number(rateLimitEnv);
+
+let edge;
+try {
+  edge = await startEdge({
+    auth: inboundCfg,
+    grants,
+    sites,
+    defaultSite: config.defaultSite,
+    channelCredentials: createChannelCredentialStore({ filePath: channelFile }),
+    bindHost,
+    agentBindHost,
+    port,
+    agentPort,
+    tls,
+    allowHttpLoopback: allowHttp,
+    rateLimiter: rateLimit > 0
+      ? createRateLimiter({ limit: rateLimit, windowMs: rateWindowSec * 1000 })
+      : null,
+  });
+} catch (error) {
+  fatal(error instanceof Error ? error.message : "edge startup failed");
+}
+
+console.error(
+  `[drupal-mcp-edge] Northbound ${edge.northboundUrl} · `
+  + `agent channel ${agentBindHost}:${edge.agentPort} · `
+  + `issuer ${inboundCfg.issuer}`,
+);
+if (rateLimit > 0) {
+  console.error(
+    `[drupal-mcp-edge] Rate limiting: ${rateLimit} req / ${rateWindowSec}s per client IP on /mcp.`,
+  );
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
     "drupal-mcp-connector": "src/index.js",
-    "drupal-mcp-verify": "bin/drupal-mcp-verify.js"
+    "drupal-mcp-verify": "bin/drupal-mcp-verify.js",
+    "drupal-mcp-edge": "bin/drupal-mcp-edge.js",
+    "drupal-mcp-agent": "bin/drupal-mcp-agent.js"
   },
   "files": [
     "src/",

package/src/lib/http-auth.js

@@ -11,7 +11,7 @@
 
 import { timingSafeEqual } from "crypto";
 import { readFileSync, statSync } from "fs";
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { createRemoteJWKSet, customFetch, jwtVerify } from "jose";
 
 /** Header names that must never become identity. */
 export const SPOOFABLE_IDENTITY_HEADERS = Object.freeze([
@@ -524,7 +524,9 @@ export async function createInboundHttpsAuth({ inboundCfg, fetchFn = fetch }) {
   const issuer = normalizeIssuer(inboundCfg.issuer);
   const asMeta = await discoverAuthorizationServer(issuer, fetchFn);
   const advertisedIssuer = asMeta.issuer || issuer;
-  const jwks = createRemoteJWKSet(new URL(asMeta.jwks_uri));
+  // JWKS retrieval goes through the same injectable fetch as issuer
+  // discovery; with the default global fetch the behavior is unchanged.
+  const jwks = createRemoteJWKSet(new URL(asMeta.jwks_uri), { [customFetch]: fetchFn });
   const resourceMetadataUrl = resourceMetadataUrlFor(resource);
   const revocationStore = inboundCfg.revocationFile
     ? createRevocationStore({ filePath: inboundCfg.revocationFile })

package/src/lib/relay/agent.js

@@ -0,0 +1,164 @@
+/**
+ * Relay tenant agent (#232) — the DEV-294 AC4 slice, tenant side.
+ *
+ * Dials OUT to the edge's agent channel and serves the real connector server
+ * (`createConnectorServerFactory`) over the framed tunnel. The agent never
+ * listens: nothing tenant-side accepts an inbound connection, so southbound
+ * site credentials exist only in this process.
+ *
+ * The channel is authenticated with the agent's own issued, revocable
+ * credential — distinct from every northbound principal token and from every
+ * site credential. Request frames carry the identity the edge validated;
+ * a frame without one is refused rather than dispatched, because a null
+ * principal downstream would mean "local operator".
+ */
+
+import { connect as netConnect } from "node:net";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { createConnectorServerFactory } from "../mcp-server.js";
+import { runWithIdentity } from "../principal.js";
+import { attachFramer, forwardHeaders, writeFrame } from "./frames.js";
+
+/**
+ * Create the tenant agent.
+ *
+ * @param {object} options
+ * @param {string} options.host Edge agent-channel host.
+ * @param {number} options.port Edge agent-channel port.
+ * @param {string} options.token Issued channel credential (raw; the edge
+ *   stores only its digest).
+ * @param {object} options.surface Connector surface for
+ *   `createConnectorServerFactory` — the real tool/resource/prompt surface,
+ *   holding the site config and credentials tenant-side.
+ * @param {typeof netConnect} [options.connectFn] Injectable dialer (e.g. a
+ *   TLS connect wrapper). The agent only ever dials; it never listens.
+ * @param {?() => void} [options.onChannelClose] Called when an established
+ *   channel is lost (not on deliberate `drop`/`close`), so an entry point
+ *   can fail loudly instead of idling disconnected.
+ * @param {?{recordConnect: Function}} [options.ledger]
+ * @returns {object}
+ */
+export function createRelayAgent({
+  host,
+  port,
+  token,
+  surface,
+  connectFn = netConnect,
+  onChannelClose = null,
+  ledger = null,
+}) {
+  if (!host || !port) {
+    throw new Error("createRelayAgent requires the edge agent-channel host and port.");
+  }
+  if (!token) {
+    throw new Error("createRelayAgent requires an issued channel credential.");
+  }
+  if (!surface) {
+    throw new Error("createRelayAgent requires the connector surface.");
+  }
+
+  const handler = createMcpHandler(createConnectorServerFactory(surface), {
+    legacy: "reject",
+  });
+  let socket = null;
+  let agentInfo = null;
+
+  async function serveFrame(activeSocket, frame) {
+    if (frame.type !== "mcp-request") return;
+    if (!frame.identity || typeof frame.identity !== "object" || Array.isArray(frame.identity)) {
+      // Fail closed: without the validated identity there is no principal to
+      // entitle, and dispatching as null would grant local-operator trust.
+      writeFrame(activeSocket, {
+        type: "mcp-response",
+        id: frame.id,
+        status: 403,
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ error: "missing_identity" }),
+      });
+      return;
+    }
+
+    let response;
+    try {
+      const headers = forwardHeaders(frame.headers);
+      const body = frame.body === null || frame.body === undefined
+        ? undefined
+        : (typeof frame.body === "string" ? frame.body : JSON.stringify(frame.body));
+      const request = new Request("http://127.0.0.1/mcp", {
+        method: frame.method || "POST",
+        headers,
+        ...(body !== undefined ? { body } : {}),
+      });
+      response = await runWithIdentity(frame.identity, () => handler.fetch(request));
+    } catch {
+      writeFrame(activeSocket, {
+        type: "mcp-response",
+        id: frame.id,
+        status: 500,
+        headers: {},
+        body: "",
+      });
+      return;
+    }
+    writeFrame(activeSocket, {
+      type: "mcp-response",
+      id: frame.id,
+      status: response.status,
+      headers: Object.fromEntries(response.headers),
+      body: await response.text(),
+    });
+  }
+
+  return {
+    get agent() {
+      return agentInfo;
+    },
+
+    /**
+     * Dial out to the edge. The edge never connects here.
+     * @returns {Promise<{ok: boolean, reason?: string, agent?: object}>}
+     */
+    dial() {
+      return new Promise((resolve, reject) => {
+        ledger?.recordConnect("agent", { host, port });
+        const next = connectFn({ host, port }, () => {
+          writeFrame(next, { type: "hello", token });
+        });
+        socket = next;
+        let established = false;
+        attachFramer(next, (frame) => {
+          if (frame.type === "hello-ok") {
+            agentInfo = frame.agent ?? null;
+            established = true;
+            resolve({ ok: true, agent: agentInfo });
+            return;
+          }
+          if (frame.type === "denied") {
+            next.end();
+            resolve({ ok: false, reason: frame.reason });
+            return;
+          }
+          void serveFrame(next, frame);
+        });
+        next.on("error", reject);
+        next.on("close", () => {
+          if (socket === next) {
+            socket = null;
+            if (established) onChannelClose?.();
+          }
+        });
+      });
+    },
+
+    /** Drop the outbound channel without destroying the agent. */
+    drop() {
+      socket?.destroy();
+      socket = null;
+    },
+
+    async close() {
+      this.drop();
+      await handler.close();
+    },
+  };
+}

package/src/lib/relay/edge.js

@@ -0,0 +1,470 @@
+/**
+ * Relay northbound edge (#232) — the DEV-294 AC4 slice.
+ *
+ * Terminates northbound MCP over the OAuth resource server and fans requests
+ * down an outbound tenant-agent channel. The edge proposes; the tenant-side
+ * connector disposes. Policy at this seam, fail-closed from birth:
+ *
+ *   - `createInboundHttpsAuth` is the ONLY authentication arm. There is no
+ *     shared-bearer and no unauthenticated mode in this module; a missing
+ *     issuer/audience is fatal at every bind host, loopback included.
+ *   - A non-empty `auth.grants` table is mandatory. The library's all-sites
+ *     fallback (principal.js) is untouched for existing installs; this entry
+ *     point refuses to exist without explicit grants.
+ *   - Caller credential headers (authorization, cookie, proxy-authorization —
+ *     the #229 strip set) and caller identity-assertion headers are stripped
+ *     before framing. The frame carries the validated identity object only.
+ *   - The edge holds no site credentials: a catalog entry carrying credential
+ *     material refuses startup. It cannot leak what it does not hold.
+ *   - Stateless MCP 2026-07-28 northbound: sessionful traffic is refused and
+ *     no `Mcp-Session-Id` crosses in either direction.
+ *   - Revocation is per-request with no grace window, for both credential
+ *     kinds (northbound principal, agent channel).
+ */
+
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { createServer as createNetServer } from "node:net";
+import { createServer as createTlsServer } from "node:tls";
+import { createLocalRelay } from "../contracts/relay.js";
+import { createInboundHttpsAuth, SPOOFABLE_IDENTITY_HEADERS } from "../http-auth.js";
+import { createLegacySessionHandler, createMcpRequestHandler } from "../http-handler.js";
+import { resolveGrantedSites } from "../principal.js";
+import {
+  attachFramer,
+  createRequestBroker,
+  forwardHeaders,
+  writeFrame,
+} from "./frames.js";
+
+/** Northbound protocol pin. Stateless; no session ids in either direction. */
+export const EDGE_MCP_PROTOCOL = "2026-07-28";
+
+/**
+ * Revocation bound restated from the DEV-293 lab for both credential kinds.
+ * The next request after revoke is denied; an in-flight request may finish.
+ */
+export const EDGE_REVOCATION_BOUND = Object.freeze({
+  name: "per-request",
+  graceMs: 0,
+  appliesTo: Object.freeze(["northbound-principal", "agent-channel"]),
+  description:
+    "Revocation is checked at the start of each northbound request for the "
+    + "principal token and the agent channel credential. The next request "
+    + "after revoke is denied. An in-flight request may finish.",
+});
+
+/**
+ * Caller credential headers (#229 parity). The northbound caller's
+ * credentials authenticate the caller to the edge; they must never cross the
+ * tunnel toward the tenant.
+ */
+export const CALLER_CREDENTIAL_HEADERS = new Set([
+  "authorization",
+  "cookie",
+  "proxy-authorization",
+]);
+
+/** Site config keys that mean "this catalog entry carries a credential". */
+const SITE_CREDENTIAL_KEYS = Object.freeze([
+  "apiToken",
+  "username",
+  "password",
+  "oauth",
+  "basicAuth",
+  "drushSsh",
+]);
+
+const DEFAULT_FAN_DOWN_TIMEOUT_MS = 10_000;
+
+/** Startup refusals: configuration that must not become a listener. */
+export class EdgeStartupError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EdgeStartupError";
+  }
+}
+
+/**
+ * Headers a northbound request may carry down the tunnel: hop-by-hop,
+ * caller-credential, and caller identity-assertion headers are stripped
+ * before framing.
+ *
+ * @param {Record<string, string|string[]>} [headers]
+ * @returns {Record<string, string>}
+ */
+export function fanDownHeaders(headers = {}) {
+  const entries = [];
+  for (const [name, value] of Object.entries(forwardHeaders(headers))) {
+    const key = String(name).toLowerCase();
+    if (CALLER_CREDENTIAL_HEADERS.has(key)) continue;
+    if (SPOOFABLE_IDENTITY_HEADERS.includes(key)) continue;
+    entries.push([name, value]);
+  }
+  return Object.fromEntries(entries);
+}
+
+/**
+ * Hot-reloaded agent channel credential store.
+ *
+ * File shape: `{ "agents": { "<agentId>": { "tokenSha256": "<hex>",
+ * "revoked": false } } }`. The edge stores only SHA-256 digests — never a raw
+ * channel token. A missing or unreadable file denies every lookup (a
+ * credential table that cannot be read authorizes nobody), and the file is
+ * re-read when its mtime changes so a revoke needs no restart.
+ *
+ * @param {object} options
+ * @param {string} options.filePath
+ * @returns {{lookup: (token: string) => {agentId: string, revoked: boolean}|null}}
+ */
+export function createChannelCredentialStore({
+  filePath,
+  readFile = readFileSync,
+  stat = statSync,
+} = {}) {
+  let cache = { mtimeMs: Number.NaN, agents: [], denyAll: true };
+
+  function load() {
+    if (!filePath) return cache;
+    let info;
+    try {
+      info = stat(filePath);
+    } catch {
+      cache = { mtimeMs: Number.NaN, agents: [], denyAll: true };
+      return cache;
+    }
+    if (info.mtimeMs === cache.mtimeMs) return cache;
+    try {
+      const raw = JSON.parse(readFile(filePath, "utf8"));
+      const agents = Object.entries(raw.agents ?? {})
+        .filter(([agentId, entry]) => !agentId.startsWith("_")
+          && entry && typeof entry === "object"
+          && typeof entry.tokenSha256 === "string")
+        .map(([agentId, entry]) => ({
+          agentId,
+          tokenSha256: entry.tokenSha256.toLowerCase(),
+          revoked: entry.revoked === true,
+        }));
+      cache = { mtimeMs: info.mtimeMs, agents, denyAll: false };
+    } catch {
+      cache = { mtimeMs: info.mtimeMs, agents: [], denyAll: true };
+    }
+    return cache;
+  }
+
+  return {
+    lookup(token) {
+      if (typeof token !== "string" || !token) return null;
+      const { agents, denyAll } = load();
+      if (denyAll) return null;
+      const digest = Buffer.from(
+        createHash("sha256").update(token).digest("hex"),
+        "utf8",
+      );
+      for (const agent of agents) {
+        const expected = Buffer.from(agent.tokenSha256, "utf8");
+        if (digest.length === expected.length && timingSafeEqual(digest, expected)) {
+          return { agentId: agent.agentId, revoked: agent.revoked };
+        }
+      }
+      return null;
+    },
+  };
+}
+
+function isLoopback(host) {
+  return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
+
+function normalizeGrants(grants) {
+  if (!grants || typeof grants !== "object" || Array.isArray(grants)) return null;
+  const entries = Object.entries(grants)
+    .filter(([clientId, sites]) => !clientId.startsWith("_") && Array.isArray(sites))
+    .map(([clientId, sites]) => [clientId, sites.map(String)]);
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+function assertNoSiteCredentials(sites) {
+  for (const site of sites) {
+    for (const key of SITE_CREDENTIAL_KEYS) {
+      if (new Map(Object.entries(site)).get(key) !== undefined) {
+        throw new EdgeStartupError(
+          `Relay edge site "${site._name ?? "?"}" carries credential material (${key}). `
+          + "The edge holds no site credentials; they exist only in the tenant agent.",
+        );
+      }
+    }
+  }
+}
+
+function assertBindAllowed(role, host, hasTls) {
+  if (hasTls) return;
+  if (!isLoopback(host)) {
+    throw new EdgeStartupError(
+      `Relay edge ${role} bind ${host} requires TLS. `
+      + "Plain listeners are permitted on loopback only, and only when explicitly allowed.",
+    );
+  }
+}
+
+function jsonResponse(res, status, body) {
+  res.writeHead(status, { "content-type": "application/json" })
+    .end(JSON.stringify(body));
+}
+
+/**
+ * Start the relay edge: an authenticated northbound MCP listener and the
+ * agent channel listener the tenant dials into.
+ *
+ * @param {object} options
+ * @param {{issuer: string, audience: string}} options.auth Inbound
+ *   resource-server config (`resolveInboundAuthConfig` shape). Mandatory.
+ * @param {object} options.grants Non-empty client-id → site-name grant table.
+ * @param {Array<{_name: string}>} options.sites Credential-free catalog.
+ * @param {string} [options.defaultSite]
+ * @param {{lookup: Function}} options.channelCredentials Agent channel store.
+ * @param {string} [options.bindHost] Northbound bind (default loopback).
+ * @param {string} [options.agentBindHost] Agent channel bind (default loopback).
+ * @param {number} [options.port] Northbound port (0 = ephemeral).
+ * @param {number} [options.agentPort] Agent channel port (0 = ephemeral).
+ * @param {{cert: string|Buffer, key: string|Buffer}} [options.tls]
+ * @param {boolean} [options.allowHttpLoopback] Permit plain listeners on loopback.
+ * @param {?object} [options.rateLimiter] Optional rate limiter (rate-limit.js).
+ * @param {number} [options.fanDownTimeoutMs]
+ * @param {typeof fetch} [options.fetchFn] Issuer discovery/JWKS fetch.
+ * @param {?{recordListen: Function, recordConnect: Function}} [options.ledger]
+ * @returns {Promise<object>}
+ */
+export async function startEdge({
+  auth,
+  grants,
+  sites,
+  defaultSite,
+  channelCredentials,
+  bindHost = "127.0.0.1",
+  agentBindHost = "127.0.0.1",
+  port = 0,
+  agentPort = 0,
+  tls = null,
+  allowHttpLoopback = false,
+  rateLimiter = null,
+  fanDownTimeoutMs = DEFAULT_FAN_DOWN_TIMEOUT_MS,
+  fetchFn = fetch,
+  ledger = null,
+} = {}) {
+  if (!auth?.issuer || !auth?.audience) {
+    throw new EdgeStartupError(
+      "Relay edge requires an inbound OAuth resource server: set auth.issuer and "
+      + "auth.audience. There is no shared-bearer or unauthenticated mode on this "
+      + "entry point, at any bind host including loopback.",
+    );
+  }
+  const grantTable = normalizeGrants(grants);
+  if (!grantTable) {
+    throw new EdgeStartupError(
+      "Relay edge refuses to start without a non-empty auth.grants table. "
+      + "The library's all-sites fallback does not apply to this entry point.",
+    );
+  }
+  if (typeof channelCredentials?.lookup !== "function") {
+    throw new EdgeStartupError(
+      "Relay edge requires an agent channel credential store; without one no "
+      + "tenant channel could ever be authorized.",
+    );
+  }
+  const catalog = Array.isArray(sites) ? sites : [];
+  if (!catalog.length) {
+    throw new EdgeStartupError("Relay edge requires a non-empty site catalog.");
+  }
+  assertNoSiteCredentials(catalog);
+  const hasTls = Boolean(tls?.cert && tls?.key);
+  if (!hasTls && !allowHttpLoopback) {
+    throw new EdgeStartupError(
+      "Relay edge requires TLS (tls.cert and tls.key), or an explicit "
+      + "loopback-only plain-listener opt-in.",
+    );
+  }
+  assertBindAllowed("northbound", bindHost, hasTls);
+  assertBindAllowed("agent-channel", agentBindHost, hasTls);
+
+  const inbound = await createInboundHttpsAuth({ inboundCfg: auth, fetchFn });
+  const targetRelay = createLocalRelay({ sites: catalog, grants: grantTable, defaultSite });
+  const broker = createRequestBroker({ timeoutMs: fanDownTimeoutMs });
+
+  let session = null;
+
+  const channelServer = (hasTls ? createTlsServer(tls) : createNetServer())
+    .on("connection", handleChannelSocket)
+    .on("secureConnection", handleChannelSocket);
+
+  function handleChannelSocket(socket) {
+    // Plain server emits "connection"; the TLS server emits both "connection"
+    // (raw) and "secureConnection" (cleartext). Attach once, post-handshake.
+    if (hasTls && !socket.encrypted) return;
+    attachFramer(socket, (frame) => {
+      if (frame.type === "hello") {
+        const record = channelCredentials.lookup(frame.token);
+        if (!record) {
+          writeFrame(socket, { type: "denied", reason: "unauthenticated" });
+          socket.end();
+          return;
+        }
+        if (record.revoked) {
+          writeFrame(socket, { type: "denied", reason: "revoked" });
+          socket.end();
+          return;
+        }
+        if (session && session.socket !== socket) session.socket.destroy();
+        session = { socket, token: frame.token, agentId: record.agentId };
+        writeFrame(socket, { type: "hello-ok", agent: { agentId: record.agentId } });
+        return;
+      }
+      if (frame.type === "mcp-response") {
+        broker.settle(frame);
+        return;
+      }
+      // Any other frame type on the agent channel is a protocol violation.
+      socket.destroy();
+    });
+    socket.on("close", () => {
+      if (session?.socket === socket) {
+        session = null;
+        broker.rejectAll(new Error("Relay agent channel closed."));
+      }
+    });
+  }
+
+  async function fanDown(req, res, body) {
+    const identity = req.mcpIdentity ?? null;
+    if (!identity) {
+      // The authenticate arm always sets an identity; a missing one means
+      // this handler was reached outside that arm. Refuse.
+      jsonResponse(res, 403, { error: "not_entitled" });
+      return;
+    }
+
+    // Entitlement at the seam, before anything about the tenant is revealed:
+    // an unlisted client learns nothing, not even whether an agent exists.
+    const granted = resolveGrantedSites(identity, catalog, grantTable);
+    if (!granted.length) {
+      jsonResponse(res, 403, { error: "not_entitled" });
+      return;
+    }
+    if (body?.method === "tools/call") {
+      try {
+        targetRelay.resolve(identity, body?.params?.arguments ?? {});
+      } catch {
+        jsonResponse(res, 403, { error: "not_entitled" });
+        return;
+      }
+    }
+
+    if (!session) {
+      jsonResponse(res, 503, { error: "no_agent" });
+      return;
+    }
+    const record = channelCredentials.lookup(session.token);
+    if (!record || record.revoked) {
+      jsonResponse(res, 403, { error: "revoked", bound: EDGE_REVOCATION_BOUND.name });
+      return;
+    }
+
+    const id = randomUUID();
+    const waited = broker.track(id);
+    const wrote = writeFrame(session.socket, {
+      type: "mcp-request",
+      id,
+      method: req.method,
+      url: "/mcp",
+      headers: fanDownHeaders(req.headers),
+      identity,
+      body,
+    });
+    if (!wrote) {
+      broker.settle({ id, status: 503 });
+      jsonResponse(res, 503, { error: "no_agent" });
+      return;
+    }
+
+    let result;
+    try {
+      result = await waited;
+    } catch {
+      jsonResponse(res, 502, { error: "fan_down_failed" });
+      return;
+    }
+    const headers = Object.fromEntries(
+      Object.entries(forwardHeaders(result.headers ?? {}))
+        .filter(([name]) => String(name).toLowerCase() !== "mcp-session-id"),
+    );
+    res.writeHead(result.status || 200, headers);
+    res.end(result.body ?? "");
+  }
+
+  const requestHandler = createMcpRequestHandler({
+    authenticate: (req) => inbound.authenticate(req),
+    protectedResource: inbound.protectedResource,
+    modernHandler: fanDown,
+    // Northbound is stateless 2026-07-28 only: sessionful legacy traffic is
+    // refused, so no Mcp-Session-Id ever exists in either direction.
+    legacyHandler: createLegacySessionHandler({
+      buildServer: () => {
+        throw new Error("unreachable: legacy transport is rejected at the edge");
+      },
+      mode: "reject",
+    }),
+    toolCount: 0,
+    rateLimiter,
+  });
+
+  const northServer = hasTls
+    ? createHttpsServer(tls, (req, res) => { void requestHandler(req, res); })
+    : createHttpServer((req, res) => { void requestHandler(req, res); });
+
+  const channelAddr = await listen(channelServer, agentBindHost, agentPort, "edge-agent-channel");
+  const northAddr = await listen(northServer, bindHost, port, "edge-northbound");
+
+  function listen(server, host, wantedPort, role) {
+    return new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(wantedPort, host, () => {
+        const address = server.address();
+        const bound = { host: address.address, port: address.port };
+        ledger?.recordListen(role, bound);
+        resolve(bound);
+      });
+    });
+  }
+
+  const scheme = hasTls ? "https" : "http";
+  let closed = false;
+  return {
+    northboundUrl: `${scheme}://${northAddr.host}:${northAddr.port}/mcp`,
+    port: northAddr.port,
+    agentPort: channelAddr.port,
+    resourceMetadataUrl: inbound.resourceMetadataUrl,
+    get hasAgent() {
+      return Boolean(session);
+    },
+    get agentId() {
+      return session?.agentId ?? null;
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      session?.socket.destroy();
+      session = null;
+      broker.rejectAll(new Error("Relay edge closed."));
+      await closeServer(channelServer);
+      await closeServer(northServer);
+    },
+  };
+}
+
+function closeServer(server) {
+  return new Promise((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+}

package/src/lib/relay/frames.js

@@ -0,0 +1,198 @@
+/**
+ * Relay frame codec (#232).
+ *
+ * Length-prefixed JSON frames for the edge/agent channel, promoted from the
+ * DEV-293 lab harness (`lab/outbound-relay/harness.js`). Mechanism only — no
+ * authentication, entitlement, or header policy lives here.
+ *
+ * Wire format: 4-byte big-endian payload length, then UTF-8 JSON. A frame
+ * must be an object whose `type` is one of `FRAME_TYPES`. Anything else —
+ * oversize, malformed JSON, unknown type — tears the channel down rather
+ * than passing garbage through.
+ */
+
+/** Hard bound on a single frame's JSON payload. */
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+
+/** The only frame types that may cross the channel. */
+export const FRAME_TYPES = Object.freeze([
+  "hello",
+  "hello-ok",
+  "denied",
+  "mcp-request",
+  "mcp-response",
+]);
+
+const FRAME_TYPE_SET = new Set(FRAME_TYPES);
+
+/**
+ * RFC 9110 hop-by-hop and transport-scoped headers. They describe one TCP
+ * connection and are meaningless (or harmful) across the tunnel.
+ */
+export const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+  "content-length",
+  "host",
+]);
+
+/**
+ * Attach the length-prefixed frame reader to a socket.
+ *
+ * Oversize declarations, malformed JSON, non-object payloads, and unknown
+ * frame types destroy the socket; buffered bytes are dropped and no further
+ * frames are delivered.
+ *
+ * @param {import("node:stream").Duplex} socket
+ * @param {(frame: object) => void} onFrame
+ */
+export function attachFramer(socket, onFrame) {
+  let buffer = Buffer.alloc(0);
+  let dead = false;
+
+  function teardown() {
+    dead = true;
+    buffer = Buffer.alloc(0);
+    socket.destroy();
+  }
+
+  socket.on("data", (chunk) => {
+    if (dead) return;
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length >= 4) {
+      const size = buffer.readUInt32BE(0);
+      if (size > MAX_FRAME_BYTES) {
+        teardown();
+        return;
+      }
+      if (buffer.length < 4 + size) break;
+      const json = buffer.subarray(4, 4 + size).toString("utf8");
+      buffer = buffer.subarray(4 + size);
+      let frame;
+      try {
+        frame = JSON.parse(json);
+      } catch {
+        teardown();
+        return;
+      }
+      if (!frame || typeof frame !== "object" || Array.isArray(frame)
+        || !FRAME_TYPE_SET.has(frame.type)) {
+        teardown();
+        return;
+      }
+      onFrame(frame);
+      if (dead) return;
+    }
+  });
+}
+
+/**
+ * Write one frame. Refuses unknown types and oversize payloads by throwing;
+ * returns false without writing when the socket is no longer writable.
+ *
+ * @param {import("node:stream").Duplex} socket
+ * @param {object} frame
+ * @returns {boolean} True when the frame was written.
+ */
+export function writeFrame(socket, frame) {
+  if (!frame || typeof frame !== "object" || !FRAME_TYPE_SET.has(frame.type)) {
+    throw new RangeError("Refusing to write an unknown frame type.");
+  }
+  const payload = Buffer.from(JSON.stringify(frame), "utf8");
+  if (payload.length > MAX_FRAME_BYTES) {
+    throw new RangeError("Refusing to write a frame beyond the size bound.");
+  }
+  if (!socket.writable) return false;
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(payload.length, 0);
+  socket.write(Buffer.concat([header, payload]));
+  return true;
+}
+
+/**
+ * Correlate mcp-request ids with their mcp-response frames.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs] Per-request wait bound.
+ * @returns {{size: number, track: (id: string) => Promise<object>, settle: (frame: {id?: string}) => boolean, rejectAll: (error: Error) => void}}
+ */
+export function createRequestBroker({ timeoutMs = 10_000 } = {}) {
+  const pending = new Map();
+
+  return {
+    get size() {
+      return pending.size;
+    },
+
+    /**
+     * @param {string} id
+     * @returns {Promise<object>} Resolves with the matching response frame.
+     */
+    track(id) {
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`Relay fan-down timeout for request ${id}.`));
+        }, timeoutMs);
+        timer.unref?.();
+        pending.set(id, {
+          resolve(frame) {
+            clearTimeout(timer);
+            resolve(frame);
+          },
+          reject(error) {
+            clearTimeout(timer);
+            reject(error);
+          },
+        });
+      });
+    },
+
+    /**
+     * @param {{id?: string}} frame
+     * @returns {boolean} True when a tracked request was resolved.
+     */
+    settle(frame) {
+      if (typeof frame?.id !== "string") return false;
+      const waiter = pending.get(frame.id);
+      if (!waiter) return false;
+      pending.delete(frame.id);
+      waiter.resolve(frame);
+      return true;
+    },
+
+    /**
+     * @param {Error} error
+     */
+    rejectAll(error) {
+      for (const [id, waiter] of pending) {
+        pending.delete(id);
+        waiter.reject(error);
+      }
+    },
+  };
+}
+
+/**
+ * Headers that may cross the tunnel at the transport level: hop-by-hop names
+ * are dropped, list values joined. Credential policy (what the edge strips
+ * beyond this) lives in edge.js, not here.
+ *
+ * @param {Record<string, string|string[]|null|undefined>} [headers]
+ * @returns {Record<string, string>}
+ */
+export function forwardHeaders(headers = {}) {
+  const entries = [];
+  for (const [name, value] of Object.entries(headers)) {
+    if (HOP_BY_HOP.has(String(name).toLowerCase())) continue;
+    if (value === null || value === undefined) continue;
+    entries.push([name, Array.isArray(value) ? value.join(", ") : String(value)]);
+  }
+  return Object.fromEntries(entries);
+}