@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.11

package/out/cli/commands/store.js

@@ -37,6 +37,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.storeCommand = storeCommand;
+exports.installFromStore = installFromStore;
 exports.resolvePublishBundleMode = resolvePublishBundleMode;
 /**
  * Store Command - Search and install from the store
@@ -54,6 +55,7 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const zlib_1 = require("zlib");
 const branding_1 = require("../../branding");
+const reconcile_1 = require("../../pack/reconcile");
 const index_1 = require("../../registry/index");
 const shared_1 = require("../../store/shared");
 const install_1 = require("../../engines/install");
@@ -361,7 +363,9 @@ async function installFromStore(options) {
             installDir = path.join(workspace, branding_1.AGENTIDE_DIR_NAME, 'agents', agentId, 'skills', slug);
             break;
         case 'pack':
-            installDir = path.join(os.homedir(), branding_1.AGENTIDE_DIR_NAME, 'agents', slug, targetVersion);
+            installDir = options.installDir
+                ? path.resolve(options.installDir)
+                : path.join(os.homedir(), branding_1.AGENTIDE_DIR_NAME, 'agents', slug, targetVersion);
             break;
         case 'mcp':
             installDir = path.join(workspace, branding_1.AGENTIDE_DIR_NAME, 'agents', agentId, 'mcp', slug);
@@ -392,12 +396,16 @@ async function installFromStore(options) {
     console.log(`  Extracting ${files.length} files...`);
     await fs.mkdir(installDir, { recursive: true });
     for (const file of files) {
-        const filePath = path.join(installDir, file.path);
+        const filePath = (0, reconcile_1.safeJoin)(installDir, file.path);
+        if (!filePath) {
+            console.error(`Error: refusing install — artifact path escapes destination (${file.path})`);
+            process.exit(1);
+        }
         await fs.mkdir(path.dirname(filePath), { recursive: true });
         await fs.writeFile(filePath, file.content);
     }
-    // For packs, create current.txt
-    if (type === 'pack') {
+    // Default library layout tracks current.txt beside versioned dirs; a custom --to dir is flat.
+    if (type === 'pack' && !options.installDir) {
         const packRoot = path.join(os.homedir(), branding_1.AGENTIDE_DIR_NAME, 'agents', slug);
         await fs.writeFile(path.join(packRoot, 'current.txt'), targetVersion);
     }

package/out/cli/credential-context.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ON_DENIED_TIMEOUT_MS = exports.WARRANT_DENIED_REASON = void 0;
 exports.runWithCredential = runWithCredential;
 exports.currentCredential = currentCredential;
+exports.resolveEngineHomeUserKey = resolveEngineHomeUserKey;
 exports.requireUserId = requireUserId;
 /**
  * Request-scoped credential context — the "Design B" seam from serve-v3 §11.1.
@@ -23,6 +24,7 @@ exports.requireUserId = requireUserId;
  * (secure-obo-design §2/§3 — the agent gets a capability, not the credential).
  */
 const async_hooks_1 = require("async_hooks");
+const paths_1 = require("../agentpack/paths");
 /** Stable, queryable reason code for the one case runWithCredential rejects. */
 exports.WARRANT_DENIED_REASON = 'token_without_verified_user';
 /** Default bound on `onDenied` so a hung audit write cannot stall admission forever. */
@@ -78,6 +80,21 @@ async function runWithCredential(cred, fn, options) {
 function currentCredential() {
     return storage.getStore();
 }
+/**
+ * The per-user engine-home segment for this turn, from whichever source actually has it.
+ *
+ * Two processes need the same answer and only one of them can read the credential. In serve the
+ * frame is authoritative. In a sandbox child there is no frame — that is the design, the
+ * credential never crosses — so the key arrives pre-computed on the run frame and is used as-is.
+ * The frame wins where both exist, so a child cannot widen its own scope by sending a key.
+ *
+ * Every engine must go through this rather than reading the credential directly: doing the latter
+ * is what silently unscoped every sandboxed turn, and the failure was invisible because the
+ * unscoped path is a perfectly good directory that simply holds everyone's data.
+ */
+function resolveEngineHomeUserKey(fromRunFrame) {
+    return (0, paths_1.engineHomeUserKey)(storage.getStore()?.userId) ?? fromRunFrame?.trim() ?? undefined;
+}
 /**
  * Fail-closed accessor for the acting user id. Throws when there is no
  * authenticated user in scope, so a tool can never silently run unscoped.

package/out/cli/data-plane/gateway.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TURN_NONCE_ENV = exports.DATA_MCP_URL_ENV = void 0;
+exports.TURN_NONCE_HEADER = exports.TURN_NONCE_ENV = exports.DATA_MCP_URL_ENV = void 0;
 exports.startDataGateway = startDataGateway;
 /**
  * Data-plane MCP gateway — a streamable-HTTP MCP server inside the serve (broker) process,
@@ -60,6 +60,14 @@ const registry_1 = require("./registry");
 exports.DATA_MCP_URL_ENV = 'AGENTHIPPO_DATA_MCP_URL';
 /** The turn capability. Per-spawn env only; never written to any shared file. */
 exports.TURN_NONCE_ENV = 'AGENTHIPPO_TURN_NONCE';
+/**
+ * Request header carrying an EDGE-registered turn nonce (P1 fix, obo-inprogress §2). The
+ * trusted edge (IdP Caddy) registers the turn with the sidecar via forward_auth and copies
+ * this header onto the request it proxies to serve. Trusted exactly like the pinned identity
+ * header: only the in-network edge can reach serve, and the edge overwrites any client-
+ * supplied value. A forged value fails closed at the gateway (unknown nonce ⇒ 401).
+ */
+exports.TURN_NONCE_HEADER = 'x-agent-turn-nonce';
 function bearerToken(header) {
     const m = header?.match(/^Bearer\s+(\S+)$/i);
     return m?.[1];
@@ -72,6 +80,20 @@ async function startDataGateway(opts) {
     const server = http.createServer(async (req, res) => {
         try {
             const urlPath = req.url?.split('?')[0] ?? '';
+            // Release-by-nonce (edge-registration mode): serve holds the nonce but no control-API
+            // authority, so it ends the turn here. Auth is the nonce itself — releasing is the one
+            // operation safe to grant any nonce holder (fail-closed: it only kills the capability
+            // early; the registry deadline remains the backstop when this is never called).
+            if (urlPath === '/turn' && req.method === 'DELETE') {
+                const nonce = bearerToken(req.headers.authorization);
+                if (nonce) {
+                    const released = opts.registry.releaseByNonce(nonce);
+                    opts.audit?.('edge', 'turn_release', { released, nonce_sha256_prefix: noncePrefix(nonce) });
+                }
+                res.writeHead(204);
+                res.end();
+                return;
+            }
             if (urlPath !== '/mcp') {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'not found' }));
@@ -129,16 +151,17 @@ async function startDataGateway(opts) {
             res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' }, id: null }));
         }
     });
+    const bindHost = opts.host ?? '127.0.0.1';
     await new Promise((resolve, reject) => {
         server.once('error', reject);
-        // Loopback ONLY — the gateway must never be reachable off-box.
-        server.listen(0, '127.0.0.1', () => resolve());
+        // Default loopback; a sidecar binds 0.0.0.0 for the private pod network only.
+        server.listen(opts.port ?? 0, bindHost, () => resolve());
     });
     const address = server.address();
     if (!address || typeof address === 'string') {
-        throw new Error('Data gateway failed to bind a loopback port');
+        throw new Error('Data gateway failed to bind a port');
     }
-    const url = `http://127.0.0.1:${address.port}/mcp`;
+    const url = `http://${opts.advertiseHost ?? '127.0.0.1'}:${address.port}/mcp`;
     opts.logger?.info(`[DataPlane] gateway listening at ${url}`);
     return {
         url,

package/out/cli/data-plane/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataPlane = exports.EGRESS_URL_ENV = exports.startEgressBroker = exports.TURN_NONCE_ENV = exports.DATA_MCP_URL_ENV = exports.startDataGateway = exports.TURN_META_KEY = exports.ConnectorHost = exports.identityProvider = exports.passthroughProvider = exports.resolveProvider = exports.CredentialBroker = exports.DEFAULT_TURN_DEADLINE_MS = exports.hashNonce = exports.TurnRegistry = void 0;
+exports.DataPlane = exports.resolveEdgeDataPlane = exports.EdgeDataPlane = exports.resolveRemoteDataPlane = exports.RemoteDataPlane = exports.ASSERTION_HEADER = exports.startDataPlaneSidecar = exports.EGRESS_URL_ENV = exports.startEgressBroker = exports.TURN_NONCE_HEADER = exports.TURN_NONCE_ENV = exports.DATA_MCP_URL_ENV = exports.startDataGateway = exports.TURN_META_KEY = exports.ConnectorHost = exports.identityProvider = exports.passthroughProvider = exports.resolveProvider = exports.CredentialBroker = exports.DEFAULT_TURN_DEADLINE_MS = exports.hashNonce = exports.TurnRegistry = void 0;
 exports.resolveDataPlaneConfig = resolveDataPlaneConfig;
 /**
  * DataPlane — orchestration of the credential broker + data-plane gateway
@@ -69,9 +69,18 @@ var gateway_2 = require("./gateway");
 Object.defineProperty(exports, "startDataGateway", { enumerable: true, get: function () { return gateway_2.startDataGateway; } });
 Object.defineProperty(exports, "DATA_MCP_URL_ENV", { enumerable: true, get: function () { return gateway_2.DATA_MCP_URL_ENV; } });
 Object.defineProperty(exports, "TURN_NONCE_ENV", { enumerable: true, get: function () { return gateway_2.TURN_NONCE_ENV; } });
+Object.defineProperty(exports, "TURN_NONCE_HEADER", { enumerable: true, get: function () { return gateway_2.TURN_NONCE_HEADER; } });
 var egress_1 = require("./egress");
 Object.defineProperty(exports, "startEgressBroker", { enumerable: true, get: function () { return egress_1.startEgressBroker; } });
 Object.defineProperty(exports, "EGRESS_URL_ENV", { enumerable: true, get: function () { return egress_1.EGRESS_URL_ENV; } });
+var sidecar_1 = require("./sidecar");
+Object.defineProperty(exports, "startDataPlaneSidecar", { enumerable: true, get: function () { return sidecar_1.startDataPlaneSidecar; } });
+Object.defineProperty(exports, "ASSERTION_HEADER", { enumerable: true, get: function () { return sidecar_1.ASSERTION_HEADER; } });
+var remote_1 = require("./remote");
+Object.defineProperty(exports, "RemoteDataPlane", { enumerable: true, get: function () { return remote_1.RemoteDataPlane; } });
+Object.defineProperty(exports, "resolveRemoteDataPlane", { enumerable: true, get: function () { return remote_1.resolveRemoteDataPlane; } });
+Object.defineProperty(exports, "EdgeDataPlane", { enumerable: true, get: function () { return remote_1.EdgeDataPlane; } });
+Object.defineProperty(exports, "resolveEdgeDataPlane", { enumerable: true, get: function () { return remote_1.resolveEdgeDataPlane; } });
 /**
  * Resolve the pack's data-plane declaration. The connector path resolves against the PACK
  * SOURCE directory (operator-authored, broker trust domain) — not the agent-readable
@@ -108,7 +117,10 @@ class DataPlane {
         const broker = new broker_1.CredentialBroker((0, broker_1.resolveProvider)(cfg.provider));
         const connector = await connector_host_1.ConnectorHost.spawn({ connectorPath: cfg.connectorPath, logger: opts?.logger });
         try {
-            const gateway = await (0, gateway_1.startDataGateway)({ registry, broker, connector, logger: opts?.logger, audit: opts?.audit });
+            const gateway = await (0, gateway_1.startDataGateway)({
+                registry, broker, connector, logger: opts?.logger, audit: opts?.audit,
+                host: opts?.gateway?.host, port: opts?.gateway?.port, advertiseHost: opts?.gateway?.advertiseHost,
+            });
             return new DataPlane(gateway.url, registry, broker, connector, gateway);
         }
         catch (err) {
@@ -116,6 +128,10 @@ class DataPlane {
             throw err;
         }
     }
+    /** Register a turn directly in the local registry (used by the sidecar control API). */
+    registerTurnRaw(reg) {
+        return this.registry.register(reg);
+    }
     /**
      * Register a verified turn. Returns the per-spawn env for the engine and the release()
      * to call in the turn's `finally`. The gateway URL itself is boot-stable and rides

package/out/cli/data-plane/registry.js

@@ -53,6 +53,15 @@ class TurnRegistry {
             },
         };
     }
+    /**
+     * Release a turn by its nonce (idempotent). Lets a holder of the nonce end its own turn —
+     * used by the gateway's release endpoint for EDGE-registered turns, where serve holds the
+     * nonce but no registration authority. Strictly fail-closed: the worst a stolen nonce can
+     * do here is end the capability early.
+     */
+    releaseByNonce(nonce) {
+        return this.entries.delete(hashNonce(nonce));
+    }
     /** Resolve a presented nonce to its turn, enforcing the deadline. Fail-closed: unknown/expired → undefined. */
     resolve(nonce, now = Date.now()) {
         const entry = this.entries.get(hashNonce(nonce));

package/out/cli/data-plane/remote.js

@@ -0,0 +1,106 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteDataPlane = exports.EdgeDataPlane = void 0;
+exports.resolveEdgeDataPlane = resolveEdgeDataPlane;
+exports.resolveRemoteDataPlane = resolveRemoteDataPlane;
+/**
+ * RemoteDataPlane — serve's client to a data-plane SIDECAR (secure-obo-design §7.6).
+ *
+ * When the connector runs in its own container, serve (in the agent container) holds NO base
+ * credential. It registers each verified turn with the sidecar's authenticated control API and
+ * hands the engine the returned nonce plus the sidecar's gateway URL. The engine dials the
+ * sidecar gateway with the nonce; the sidecar resolves nonce → user and runs the connector.
+ *
+ * Presents the same `registerTurn()` shape as the in-process `DataPlane`, so serve's turn
+ * handling is identical whether the connector is in-process or a sidecar.
+ */
+const gateway_1 = require("./gateway");
+/** Read the edge-mode wiring from env. Returns null unless explicitly enabled. */
+function resolveEdgeDataPlane(env = process.env) {
+    const enabled = env.AGENTHIPPO_DATA_PLANE_EDGE?.trim();
+    const gatewayUrl = env.AGENTHIPPO_DATA_MCP_URL?.trim();
+    if (!enabled || enabled === '0' || enabled.toLowerCase() === 'false' || !gatewayUrl) {
+        return null;
+    }
+    return { gatewayUrl };
+}
+class EdgeDataPlane {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** The engine-facing gateway URL (boot-stable; set into process.env by serve like the local plane). */
+    get url() { return this.cfg.gatewayUrl; }
+    /**
+     * Adopt an edge-registered nonce for this turn. Release calls the gateway's
+     * nonce-authenticated `DELETE /turn` — the one operation a bare nonce may perform besides
+     * the tool surface, and strictly fail-closed (it only ends the capability early; the
+     * sidecar's registry deadline is the backstop when the call never lands).
+     */
+    adoptTurn(nonce) {
+        return {
+            nonce,
+            env: { [gateway_1.TURN_NONCE_ENV]: nonce, [gateway_1.DATA_MCP_URL_ENV]: this.cfg.gatewayUrl },
+            release: async () => {
+                try {
+                    await fetch(new URL('/turn', this.cfg.gatewayUrl), {
+                        method: 'DELETE',
+                        headers: { Authorization: `Bearer ${nonce}` },
+                    });
+                }
+                catch { /* best-effort release; the sidecar deadline is the backstop */ }
+            },
+        };
+    }
+}
+exports.EdgeDataPlane = EdgeDataPlane;
+/** Read the sidecar wiring from env (set at deploy on the agent container). Returns null if absent. */
+function resolveRemoteDataPlane(env = process.env) {
+    const controlUrl = env.AGENTHIPPO_DATA_PLANE_CONTROL_URL?.trim();
+    const registerToken = env.AGENTHIPPO_DATA_PLANE_TOKEN?.trim();
+    const gatewayUrl = env.AGENTHIPPO_DATA_MCP_URL?.trim();
+    if (!controlUrl || !registerToken || !gatewayUrl) {
+        return null;
+    }
+    return { controlUrl, registerToken, gatewayUrl };
+}
+class RemoteDataPlane {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** The engine-facing gateway URL (boot-stable; set into process.env by serve like the local plane). */
+    get url() { return this.cfg.gatewayUrl; }
+    /**
+     * Register a turn with the sidecar. Returns the per-spawn env + release, matching DataPlane.
+     * The base credential never touches this process — only the nonce comes back.
+     */
+    async registerTurn(reg) {
+        const res = await fetch(`${this.cfg.controlUrl.replace(/\/$/, '')}/turns`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.cfg.registerToken}` },
+            body: JSON.stringify(reg),
+        });
+        if (!res.ok) {
+            throw new Error(`data-plane sidecar register failed: HTTP ${res.status}`);
+        }
+        const { nonce } = await res.json();
+        return {
+            nonce,
+            env: { [gateway_1.TURN_NONCE_ENV]: nonce, [gateway_1.DATA_MCP_URL_ENV]: this.cfg.gatewayUrl },
+            release: async () => {
+                try {
+                    await fetch(`${this.cfg.controlUrl.replace(/\/$/, '')}/turns/${encodeURIComponent(nonce)}`, {
+                        method: 'DELETE',
+                        headers: { Authorization: `Bearer ${this.cfg.registerToken}` },
+                    });
+                }
+                catch { /* best-effort release; the sidecar deadline is the backstop */ }
+            },
+        };
+    }
+}
+exports.RemoteDataPlane = RemoteDataPlane;

package/out/cli/data-plane/sidecar.js

@@ -0,0 +1,225 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASSERTION_HEADER = void 0;
+exports.startDataPlaneSidecar = startDataPlaneSidecar;
+/**
+ * Data-plane SIDECAR (secure-obo-design §7.6 / aperture-thin) — the connector's own trust
+ * domain, a SEPARATE container from the engine/agent.
+ *
+ * It runs the full data plane (TurnRegistry + gateway + connector) and holds the backend BASE
+ * credential (AWS keys, Postgres pool login, …). The agent container gets NONE of it: it only
+ * (a) registers verified turns via this authenticated control API and (b) points the engine at
+ * the gateway URL. Because the sidecar is a different container (different PID namespace), the
+ * engine cannot read the base credential from `/proc/<pid>/environ`, and because the sidecar
+ * resolves the nonce → userId server-side, the engine cannot forge another user's identity.
+ *
+ * Control API (loopback/pod-network, bearer-authenticated):
+ *   POST   /turns        { userId, sessionKey, inboundToken?, egressStoreKey? } → { nonce }
+ *   DELETE /turns/:nonce                                                        → 204
+ *   GET    /edge/turn    (forward_auth from the trusted EDGE; X-Agent-User header)
+ *                        → 200 + `X-Agent-Turn-Nonce` response header
+ * The gateway (nonce-authenticated MCP) is a separate port the engine dials directly.
+ *
+ * EDGE-registration mode (P1 fix, obo-inprogress §2): the bearer secret is held by the IdP
+ * Caddy — NOT the agent container. Caddy registers each chat turn via `forward_auth` against
+ * `/edge/turn` (identity from the X-Agent-User header its auth-broker hop just verified) and
+ * copies the returned nonce header onto the request it proxies to serve. serve then has no
+ * registration authority at all: a compromised engine reading serve's `/proc/<pid>/environ`
+ * finds no token that can mint a nonce for an arbitrary userId. Release rides the gateway's
+ * nonce-authenticated `DELETE /turn`; the registry deadline is the backstop.
+ */
+const http = __importStar(require("http"));
+const crypto_1 = require("crypto");
+const index_1 = require("./index");
+const serve_hardening_1 = require("../serve-hardening");
+const gateway_1 = require("./gateway");
+/**
+ * Header carrying the EDGE-verified user ASSERTION (agent-identity.md §8.5 G1) — the signed
+ * artifact, as opposed to `X-Agent-User` which is only the identifier. It becomes the turn's
+ * `inboundToken`, which is what `passthrough` hands the backend and what an RFC 8693 `exchange`
+ * provider presents as its `subject_token`.
+ *
+ * Set by the trusted edge on the turn-registration hop only, so it never reaches the agent
+ * container. A client-supplied copy must be stripped at the edge, exactly as for the nonce.
+ */
+exports.ASSERTION_HEADER = 'x-agent-user-assertion';
+function headerValue(req, name) {
+    const v = req.headers[name];
+    return (Array.isArray(v) ? v[0] : v)?.trim() || undefined;
+}
+/** Audit-safe fingerprint of a bearer credential — never the credential. */
+function sha256Prefix(value) {
+    return (0, crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, 12);
+}
+function bearer(header) {
+    return header?.match(/^Bearer\s+(\S+)$/i)?.[1];
+}
+function tokenEq(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && (0, crypto_1.timingSafeEqual)(x, y);
+}
+async function startDataPlaneSidecar(opts) {
+    const host = opts.bindHost ?? '0.0.0.0';
+    // The gateway binds `host` on a fixed port so the engine can be told the URL at deploy time.
+    const plane = await index_1.DataPlane.start(opts.config, {
+        logger: opts.logger,
+        audit: opts.audit,
+        gateway: { host, port: opts.gatewayPort, advertiseHost: host === '0.0.0.0' ? undefined : host },
+    });
+    const releases = new Map();
+    const control = http.createServer(async (req, res) => {
+        const reject = (code, msg) => { res.writeHead(code, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: msg })); };
+        try {
+            const tok = bearer(req.headers.authorization);
+            if (!tok || !tokenEq(tok, opts.registerToken)) {
+                opts.audit?.('unauthorized', 'sidecar_register_reject', { reason: tok ? 'bad_token' : 'missing_token' });
+                return reject(401, 'unauthorized');
+            }
+            const path = req.url?.split('?')[0] ?? '';
+            // Edge registration (Caddy forward_auth sends GET, no body): identity comes from the
+            // X-Agent-User header the edge's preceding auth-broker hop verified and set. The nonce
+            // rides a response header so `copy_headers` can lift it onto the proxied request.
+            // sessionKey degrades to userId here — the edge never sees the body's session_id.
+            if ((req.method === 'GET' || req.method === 'POST') && path === '/edge/turn') {
+                const userId = (Array.isArray(req.headers['x-agent-user']) ? req.headers['x-agent-user'][0] : req.headers['x-agent-user'])?.trim();
+                if (!userId) {
+                    opts.audit?.('unauthorized', 'sidecar_edge_reject', { reason: 'missing_user' });
+                    return reject(400, 'X-Agent-User required');
+                }
+                // The user ASSERTION, not just the identifier (agent-identity.md §8.5 G1). The edge
+                // forwarded only X-Agent-User until now, so `registerTurnRaw` got no inboundToken and
+                // edge mode silently supported the `identity` provider alone: `passthrough` failed
+                // closed on every call, and an RFC 8693 `exchange` provider had no subject_token to
+                // exchange. Trusted exactly like X-Agent-User — only the in-network edge can reach
+                // this port, and the edge overwrites any client-supplied copy.
+                const inboundToken = headerValue(req, exports.ASSERTION_HEADER)?.replace(/^Bearer\s+/i, '').trim() || undefined;
+                const { nonce } = plane.registerTurnRaw({ userId, sessionKey: userId, inboundToken });
+                // Never the assertion itself: it is a bearer credential, and these rows ship to the
+                // evidence server. A hash prefix still proves which assertion a turn used.
+                opts.audit?.(userId, 'sidecar_edge_register', {
+                    userId,
+                    assertion: inboundToken ? `sha256:${sha256Prefix(inboundToken)}` : 'none',
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json', [gateway_1.TURN_NONCE_HEADER]: nonce });
+                return res.end(JSON.stringify({ ok: true }));
+            }
+            if (req.method === 'POST' && path === '/turns') {
+                let body;
+                try {
+                    body = JSON.parse(await (0, serve_hardening_1.readBodyWithCap)(req));
+                }
+                catch {
+                    return reject(400, 'bad json');
+                }
+                const userId = (body.userId ?? '').trim();
+                if (!userId) {
+                    return reject(400, 'userId required');
+                }
+                // Which agent SAYS it is asking. Recorded, never trusted: the register token is
+                // shared, so this claim is only as good as whoever holds it. `binding: 'asserted'`
+                // travels with it so nobody reading evidence later mistakes it for a verified fact
+                // (PLAN/agent-identity.md §4.4 — the successor is warrant verification, F3).
+                const claimed = body.agent?.pack?.trim();
+                // One connector is meant to serve one agent. When it does not, this is where it
+                // becomes visible — and visibility is the whole deliverable, since the sidecar
+                // cannot safely refuse on an unverifiable claim.
+                const mismatch = Boolean(claimed && opts.agent?.pack && claimed !== opts.agent.pack);
+                if (mismatch) {
+                    // console.warn, not logger.warn: the logger is a no-op without --verbose, and two
+                    // agents sharing one connector is the exact condition E2's agent bound rests on
+                    // NOT happening. It must be unmissable in the default deployment, not a debug line.
+                    console.warn(`Warning: turn registration claims agent "${claimed}" but this connector loaded ` +
+                        `"${opts.agent?.pack}". One connector is meant to serve one agent ` +
+                        `(PLAN/agent-identity.md §4.4) — both now share this connector's base credential, ` +
+                        `so neither is bounded by the job it was deployed for.`);
+                }
+                opts.audit?.((body.sessionKey ?? '').trim() || userId, 'sidecar_register', {
+                    userId,
+                    claimedAgent: claimed ?? 'none',
+                    binding: 'asserted',
+                    ...(mismatch ? { agentMismatch: true, loadedAgent: opts.agent?.pack } : {}),
+                });
+                const { nonce, release } = plane.registerTurnRaw({
+                    userId, sessionKey: (body.sessionKey ?? '').trim() || userId,
+                    inboundToken: body.inboundToken, egressStoreKey: body.egressStoreKey,
+                });
+                releases.set(nonce, release);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                return res.end(JSON.stringify({ nonce }));
+            }
+            if (req.method === 'DELETE' && path.startsWith('/turns/')) {
+                const nonce = decodeURIComponent(path.slice('/turns/'.length));
+                releases.get(nonce)?.();
+                releases.delete(nonce);
+                res.writeHead(204);
+                return res.end();
+            }
+            reject(404, 'not found');
+        }
+        catch (err) {
+            opts.logger?.warn(`[Sidecar] control error: ${err instanceof Error ? err.message : String(err)}`);
+            if (!res.headersSent) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+            }
+            res.end(JSON.stringify({ error: 'internal' }));
+        }
+    });
+    await new Promise((resolve, reject) => {
+        control.once('error', reject);
+        control.listen(opts.controlPort, host, () => resolve());
+    });
+    const controlAddress = control.address();
+    const controlPort = controlAddress && typeof controlAddress !== 'string' ? controlAddress.port : opts.controlPort;
+    opts.logger?.info(`[Sidecar] gateway ${plane.url} | control :${controlPort} (bound ${host})`);
+    // A `passthrough` provider has nothing of its own: with no inbound token it fails closed on
+    // EVERY call (broker.ts). Before the assertion header existed, an edge-registered turn never
+    // carried one, so this combination looked healthy at boot and then denied every single tool
+    // call at runtime. Say it once, at boot, where an operator can act on it.
+    if ((opts.config.provider ?? 'passthrough').trim().toLowerCase() === 'passthrough') {
+        console.warn(`Warning: provider=passthrough needs a per-user token on every turn. Edge-registered turns ` +
+            `supply it via the ${exports.ASSERTION_HEADER} header — if your edge does not forward it, every tool ` +
+            `call will fail closed. See PLAN/agent-identity.md §8.5 G1.`);
+    }
+    return {
+        gatewayUrl: plane.url,
+        controlPort,
+        close: async () => { await new Promise((r) => control.close(() => r())); await plane.close(); },
+    };
+}