comisai 1.0.41 → 1.0.44

package/node_modules/@comis/gateway/dist/acp/acp-server.js

@@ -16,6 +16,9 @@
  */
 import { AgentSideConnection, ndJsonStream, } from "@agentclientprotocol/sdk";
 import { createAcpSessionMap } from "./acp-session-map.js";
+import { createAcpActivityBridge } from "./acp-activity-bridge.js";
+import { createAcpApprovalBridge } from "./acp-approval-bridge.js";
+import { createAcpPlanBridge } from "./acp-plan-bridge.js";
 /**
  * Extract user text from ACP prompt content blocks.
  *
@@ -36,17 +39,32 @@ function extractUserMessage(prompt) {
  *
  * The returned object satisfies the ACP Agent interface with:
  * - initialize: Returns protocol version, agent info, and capabilities
- * - newSession: Creates an Comis session mapped to the ACP session
+ * - newSession: Creates an Comis session mapped to the ACP session and retains
+ *   the active connection per session id
  * - prompt: Extracts user message and delegates to executeAgent
  * - authenticate: No-op for local agent
- * - cancel: Removes session from map (execution abort is a future enhancement)
+ * - cancel: Removes session from the map AND drops the retained connection
+ *
+ * The connection itself is constructed in {@link startAcpServer} (the SDK's
+ * `AgentSideConnection` is built there over the stdio stream). It is threaded
+ * back in via {@link AcpAgentHandle.registerConnection} so `newSession` can key
+ * it per ACP session id — giving the bridges a handle to push `sessionUpdate`.
  *
  * @param deps - Server dependencies (executeAgent, logger, version)
- * @returns Object exposing the ACP Agent interface and the internal session map
+ * @returns Handle exposing the ACP Agent, the session map, and the connection
+ *   registry accessors
  */
 export function createAcpAgent(deps) {
     const sessionMap = createAcpSessionMap();
     const version = deps.version ?? "0.0.1";
+    // Per-session AgentSideConnection registry. Keyed by ACP sessionId
+    // (which equals AcpSessionKey.peerId — see acp-session-map.ts). The bridges
+    // (Wave 2) read it via getConnection; populated in newSession, dropped in
+    // cancel and on connection-signal abort (close).
+    const connections = new Map();
+    // The connection registered by startAcpServer; sessions opened after
+    // registration are keyed to it.
+    let activeConnection;
     const agent = {
         async initialize(params) {
             deps.logger.info({ protocolVersion: params.protocolVersion }, "ACP initialize request received");
@@ -63,6 +81,20 @@ export function createAcpAgent(deps) {
         async newSession(_params) {
             const sessionId = crypto.randomUUID();
             sessionMap.create(sessionId);
+            // Retain the active connection per ACP session id so the bridges
+            // (Wave 2) can push sessionUpdate / requestPermission from outside this
+            // handler. Dropped in cancel and on connection-signal abort.
+            if (activeConnection) {
+                connections.set(sessionId, activeConnection);
+            }
+            // Register an ACP activity renderer through the injected
+            // ActivityStreamPort on session open so the activity pipe is reachable from
+            // ACP. The full per-turn subscription + frame→`connection.sessionUpdate`
+            // bridge lives in acp-activity-bridge.ts; this seam only proves the
+            // port is wired and reachable here (the registration seam).
+            if (deps.activityStreamPort) {
+                deps.logger.info({ sessionId, submodule: "acp-activity-renderer" }, "ACP activity renderer registered for session (Structured strategy; full bridge lands separately)");
+            }
             deps.logger.info({ sessionId }, "ACP session created");
             return { sessionId };
         },
@@ -88,10 +120,47 @@ export function createAcpAgent(deps) {
         async cancel(params) {
             deps.logger.info({ sessionId: params.sessionId }, "ACP cancel request received");
             sessionMap.remove(params.sessionId);
+            // Drop the retained connection for this session so a cancelled
+            // session is no longer reachable via getConnection (a dropped entry makes
+            // the bridges no-op).
+            connections.delete(params.sessionId);
             // Actual execution abort is a future enhancement
         },
     };
-    return { agent, sessionMap };
+    function getConnection(acpSessionId) {
+        return connections.get(acpSessionId);
+    }
+    function registerConnection(connection) {
+        activeConnection = connection;
+        // Drop every retained connection when this connection closes (the SDK
+        // aborts connection.signal on close — acp.d.ts:150). A closed/aborted
+        // connection must never be used to write to a dead session.
+        connection.signal.addEventListener("abort", () => {
+            connections.clear();
+            activeConnection = undefined;
+        });
+    }
+    // Construct the activity + approval bridge FACTORIES once
+    // (when the redacted ActivityStreamPort is injected) from that port + this
+    // handle's getConnection. §19.6 M6: only the redacted port + getConnection
+    // cross into the bridges — no raw event source. Their per-turn `subscribe(ctx)`
+    // is invoked from the ACP turn lifecycle (the live-IDE seam).
+    const bridges = deps.activityStreamPort
+        ? {
+            // logger omitted: the narrow AcpServerDeps.logger ({info,error,warn})
+            // is not a ComisLogger (no `.debug`); the bridges' DEBUG traces are
+            // optional, so the construction stays type-honest without a cast.
+            activity: createAcpActivityBridge({
+                activityStreamPort: deps.activityStreamPort,
+                getConnection,
+            }),
+            approval: createAcpApprovalBridge({
+                activityStreamPort: deps.activityStreamPort,
+                getConnection,
+            }),
+        }
+        : undefined;
+    return { agent, sessionMap, getConnection, registerConnection, bridges };
 }
 /**
  * Start the ACP server with stdio transport.
@@ -114,10 +183,49 @@ export async function startAcpServer(deps) {
     const readableStdin = fromStream(process.stdin);
     // Create ndJson stream for ACP communication
     const stream = ndJsonStream(writableStdout, readableStdin);
+    // Build the ACP agent handle ONCE so the per-session connection registry
+    // survives for the life of the connection. The handle's agent is
+    // handed to the SDK; the constructed connection is threaded back via
+    // registerConnection so newSession can key it per ACP session id.
+    const handle = createAcpAgent(deps);
     // Create the agent-side connection
-    const connection = new AgentSideConnection(() => createAcpAgent(deps).agent, stream);
+    const connection = new AgentSideConnection(() => handle.agent, stream);
+    // Retain the connection in the per-session registry. Sessions opened
+    // after this point are keyed to it; the registry empties on signal abort.
+    handle.registerConnection(connection);
+    // Construct the plan bridge ONCE per connection when both the
+    // read-only ExecutionPlanPort and the event bus are injected. The bridge
+    // subscribes `sep:plan_extracted` + `tool:executed` on the bus and pushes a
+    // `{ sessionUpdate: "plan", entries }` frame through the connection resolved
+    // via handle.getConnection. §19.6 M6: ONLY the read-only port + getConnection
+    // cross into the bridge — no raw plan ref / unredacted source. If the
+    // port is present but the bus is absent, log a single WARN and skip (fail-safe
+    // no-frames rather than fail-open). The activity + approval bridges are
+    // constructed on the handle (handle.bridges) — their per-turn `subscribe(ctx)`
+    // is the live-IDE seam invoked from the ACP turn lifecycle.
+    let unsubscribePlan;
+    if (deps.executionPlanPort) {
+        if (deps.eventBus) {
+            unsubscribePlan = createAcpPlanBridge({
+                eventBus: deps.eventBus,
+                executionPlanPort: deps.executionPlanPort,
+                getConnection: handle.getConnection,
+            });
+        }
+        else {
+            deps.logger.warn({
+                submodule: "acp-server",
+                hint: "Inject AcpServerDeps.eventBus alongside executionPlanPort to enable the SEP plan bridge",
+                errorKind: "config",
+            }, "ACP executionPlanPort present but eventBus absent — plan bridge skipped");
+        }
+    }
     deps.logger.info("ACP server started, awaiting IDE connection on stdio");
     // Wait for the connection to close (stdin ends or IDE disconnects)
     await connection.closed;
+    // Teardown symmetry: detach the plan bridge's bus handlers so it stops
+    // re-emitting once the connection ends (no frame written to a dead/wrong
+    // session after close).
+    unsubscribePlan?.();
     deps.logger.info("ACP server connection closed, shutting down");
 }

package/node_modules/@comis/gateway/dist/acp/index.d.ts

@@ -1,4 +1,12 @@
 export { createAcpAgent, startAcpServer } from "./acp-server.js";
-export type { AcpServerDeps } from "./acp-server.js";
+export type { AcpServerDeps, AcpAgentHandle } from "./acp-server.js";
 export { createAcpSessionMap } from "./acp-session-map.js";
 export type { AcpSessionMap, AcpSessionKey } from "./acp-session-map.js";
+export { createAcpBoundedQueue, DEFAULT_ACP_QUEUE_CAPACITY } from "./acp-bounded-queue.js";
+export type { AcpBoundedQueue, AcpBoundedQueueOptions } from "./acp-bounded-queue.js";
+export { createAcpActivityBridge } from "./acp-activity-bridge.js";
+export type { AcpActivityBridge, CreateAcpActivityBridgeDeps, } from "./acp-activity-bridge.js";
+export { createAcpPlanBridge } from "./acp-plan-bridge.js";
+export type { CreateAcpPlanBridgeDeps } from "./acp-plan-bridge.js";
+export { createAcpApprovalBridge } from "./acp-approval-bridge.js";
+export type { AcpApprovalBridge, CreateAcpApprovalBridgeDeps, } from "./acp-approval-bridge.js";

package/node_modules/@comis/gateway/dist/acp/index.js

@@ -2,3 +2,10 @@
 // ACP (Agent Communication Protocol) — IDE integration via ndJson/stdio
 export { createAcpAgent, startAcpServer } from "./acp-server.js";
 export { createAcpSessionMap } from "./acp-session-map.js";
+// Local 256-slot FIFO drop-oldest queue the activity bridge drains.
+export { createAcpBoundedQueue, DEFAULT_ACP_QUEUE_CAPACITY } from "./acp-bounded-queue.js";
+// The three ACP bridges the composition root constructs per ACP session
+// (activity → session/update, SEP plan → plan panel, approval → requestPermission).
+export { createAcpActivityBridge } from "./acp-activity-bridge.js";
+export { createAcpPlanBridge } from "./acp-plan-bridge.js";
+export { createAcpApprovalBridge } from "./acp-approval-bridge.js";

package/node_modules/@comis/gateway/dist/auth/token-auth.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Per-MCP-client config block surfaced on a verified TokenClient when the
+ * token's GatewayTokenSchema entry includes an `mcpClient` block. Shape
+ * mirrors the Zod schema at `packages/core/src/config/schema-gateway.ts:46-56`.
+ *
+ * Only meaningful when `scopes` includes `"mcp-client"`. The fields are
+ * carried through opaquely by the token store — the gateway endpoint
+ * (`mcp-server-endpoint.ts`) consults them for the default-deny filter.
+ */
+export interface McpClientConfig {
+    /** Tool names this MCP client may invoke when `mcpExportPolicy` is
+     *  `"permission-gated"`. Empty array = only `"safe"` tools exposed. */
+    readonly allowlist: readonly string[];
+    /** Session keys this MCP client may read via `resources/*`. */
+    readonly sessionAllowlist: readonly string[];
+    /** Per-tool rate-limit override (calls/min). Falls back to the
+     *  30-calls/min/tool default. */
+    readonly toolRateLimit: Readonly<Record<string, number>>;
+}
 /**
  * Authenticated client identity resolved from a bearer token.
  */
@@ -6,6 +25,10 @@ export interface TokenClient {
     readonly id: string;
     /** Allowed scopes for this client (e.g., ["rpc", "ws", "admin"]) */
     readonly scopes: readonly string[];
+    /** Per-MCP-client config block. Present iff the GatewayTokenSchema entry
+     *  declared an `mcpClient` block; usually only meaningful when `scopes`
+     *  includes `"mcp-client"`. */
+    readonly mcpClient?: McpClientConfig;
 }
 /**
  * Token verification store — maps bearer tokens to client identities.
@@ -21,6 +44,8 @@ export interface TokenEntry {
     readonly id: string;
     readonly secret: string;
     readonly scopes: readonly string[];
+    /** Optional per-MCP-client config block. */
+    readonly mcpClient?: McpClientConfig;
 }
 /**
  * Create a TokenStore from a list of token entries.

package/node_modules/@comis/gateway/dist/auth/token-auth.js

@@ -13,6 +13,7 @@ export function createTokenStore(tokens) {
         id: t.id,
         secretBuf: Buffer.from(t.secret, "utf-8"),
         scopes: t.scopes,
+        mcpClient: t.mcpClient,
     }));
     return {
         verify(token) {
@@ -24,7 +25,9 @@ export function createTokenStore(tokens) {
                     continue;
                 }
                 if (timingSafeEqual(tokenBuf, entry.secretBuf)) {
-                    return { id: entry.id, scopes: entry.scopes };
+                    return entry.mcpClient
+                        ? { id: entry.id, scopes: entry.scopes, mcpClient: entry.mcpClient }
+                        : { id: entry.id, scopes: entry.scopes };
                 }
             }
             return null;

package/node_modules/@comis/gateway/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { createGatewayServer } from "./server/hono-server.js";
 export type { GatewayServerHandle } from "./server/hono-server.js";
 export { createTokenStore, extractBearerToken, checkScope } from "./auth/token-auth.js";
+export type { TokenClient } from "./auth/token-auth.js";
+export { validateCertificates, extractClientCN } from "./auth/mtls-verifier.js";
+export type { CertPaths } from "./auth/mtls-verifier.js";
 export { createRateLimiter } from "./rate-limit/rate-limiter.js";
 export { createDynamicMethodRouter } from "./rpc/method-router.js";
 export type { DynamicMethodRouter } from "./rpc/method-router.js";
@@ -12,10 +15,14 @@ export { getPresetMappings } from "./webhook/webhook-presets.js";
 export { createOAuthCallbackRoute, insertPendingFlow, PENDING_FLOW_TIMEOUT_MS, } from "./oauth/oauth-callback-route.js";
 export type { OAuthCallbackDeps, PendingFlow, } from "./oauth/oauth-callback-route.js";
 export { createMediaRoutes } from "./web/index.js";
+export { createApprovalTokenRoute, insertPendingApprovalToken, APPROVAL_TOKEN_TIMEOUT_MS, } from "./web/index.js";
+export type { ApprovalTokenDeps, PendingApprovalToken, ApprovalLinkChoice, } from "./web/index.js";
 export { createOpenaiCompletionsRoute } from "./openai/index.js";
 export { createOpenaiModelsRoute } from "./openai/index.js";
 export { createOpenaiEmbeddingsRoute } from "./openai/index.js";
 export { createResponsesRoute } from "./responses/index.js";
-export { createAcpAgent } from "./acp/index.js";
-export type { AcpServerDeps } from "./acp/index.js";
+export { createAcpAgent, startAcpServer } from "./acp/index.js";
+export type { AcpServerDeps, AcpAgentHandle } from "./acp/index.js";
+export { createAcpActivityBridge, createAcpPlanBridge, createAcpApprovalBridge, createAcpBoundedQueue, } from "./acp/index.js";
+export type { CreateAcpActivityBridgeDeps, CreateAcpPlanBridgeDeps, CreateAcpApprovalBridgeDeps, } from "./acp/index.js";
 export { createMdnsAdvertiser } from "./discovery/index.js";

package/node_modules/@comis/gateway/dist/index.js

@@ -3,8 +3,15 @@
 // Public API -- all exports have verified external consumers.
 // Server
 export { createGatewayServer } from "./server/hono-server.js";
+// MCP server endpoint: the mount helper itself stays
+// gateway-internal (consumed via relative import by hono-server.ts). The
+// daemon-side factory in packages/daemon/src/api/mcp-server-handlers.ts
+// imports TokenClient from this index to type its `buildMcpServerForClient`
+// signature; that re-export is below ("Auth -- Token").
 // Auth -- Token
 export { createTokenStore, extractBearerToken, checkScope } from "./auth/token-auth.js";
+// Auth -- mTLS
+export { validateCertificates, extractClientCN } from "./auth/mtls-verifier.js";
 // Rate limiting
 export { createRateLimiter } from "./rate-limit/rate-limiter.js";
 // RPC -- method router
@@ -20,6 +27,8 @@ export { getPresetMappings } from "./webhook/webhook-presets.js";
 export { createOAuthCallbackRoute, insertPendingFlow, PENDING_FLOW_TIMEOUT_MS, } from "./oauth/oauth-callback-route.js";
 // Web -- media routes
 export { createMediaRoutes } from "./web/index.js";
+// Web -- email approval-token route (single-use, 5-min, revoke-on-first-touch)
+export { createApprovalTokenRoute, insertPendingApprovalToken, APPROVAL_TOKEN_TIMEOUT_MS, } from "./web/index.js";
 // OpenAI compatibility endpoints
 export { createOpenaiCompletionsRoute } from "./openai/index.js";
 export { createOpenaiModelsRoute } from "./openai/index.js";
@@ -27,6 +36,10 @@ export { createOpenaiEmbeddingsRoute } from "./openai/index.js";
 // OpenResponses endpoint
 export { createResponsesRoute } from "./responses/index.js";
 // ACP server for IDE integration
-export { createAcpAgent } from "./acp/index.js";
+export { createAcpAgent, startAcpServer } from "./acp/index.js";
+// ACP activity/plan/approval bridges + local queue — the daemon composition
+// root constructs these per ACP session (createAcpAgent's AcpAgentHandle
+// provides getConnection; the holder from @comis/agent is the ExecutionPlanPort).
+export { createAcpActivityBridge, createAcpPlanBridge, createAcpApprovalBridge, createAcpBoundedQueue, } from "./acp/index.js";
 // mDNS/Bonjour service discovery
 export { createMdnsAdvertiser } from "./discovery/index.js";

package/node_modules/@comis/gateway/dist/mcp-server-endpoint.d.ts

@@ -0,0 +1,86 @@
+/**
+ * POST /mcp/v1 endpoint mount.
+ *
+ * Mounts the Streamable HTTP MCP server route on the gateway's Hono app.
+ * Per-request lifecycle:
+ *
+ *   1. Extract bearer via `extractBearerToken(c.req.header("authorization"))`.
+ *   2. `tokenStore.verify(token)` — null ⇒ 401 (errorKind:"auth").
+ *   3. `checkScope(client.scopes, "mcp-client")` — false ⇒ 403
+ *      (errorKind:"auth").
+ *   4. `client.scopes.includes("admin")` ⇒ 403 (errorKind:"security"). This
+ *      is defense-in-depth: the `.refine` on `GatewayTokenSchema`
+ *      already blocks co-issuance at config-load. If this branch fires,
+ *      something has bypassed schema validation (a config-validation bug).
+ *   5. `mcp = deps.buildMcpServerForClient(client)` — per-client McpServer
+ *      with default-deny tools/list filter (the policy gate runs inside the
+ *      factory; see `packages/daemon/src/api/mcp-server-handlers.ts`).
+ *   6. `transport = new StreamableHTTPServerTransport({ sessionIdGenerator })`
+ *      → `mcp.connect(transport)` → `transport.handleRequest(req, res,
+ *      parsedBody)`.
+ *
+ * Hono c.env accessor:
+ *   The `@hono/node-server@1.19.14` `HttpBindings` type declares
+ *   `{ incoming: IncomingMessage; outgoing: ServerResponse }`. Verified by
+ *   reading `node_modules/@hono/node-server/dist/types.d.ts` directly.
+ *
+ * Body parsing (body pre-parse pitfall): Hono pre-parses POST bodies on demand. The
+ * SDK transport's `handleRequest(req, res, parsedBody?)` accepts a
+ * pre-parsed body as the 3rd arg; pass `await c.req.json().catch(() =>
+ * undefined)` so the SDK does not re-read the consumed stream.
+ *
+ * @module
+ */
+import type { Hono } from "hono";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type TokenClient, type TokenStore } from "./auth/token-auth.js";
+import type { GatewayLogger } from "./server/gateway-logger.js";
+/**
+ * Hono environment bindings exposed by `@hono/node-server`. Matches the
+ * `HttpBindings` type at `node_modules/@hono/node-server/dist/types.d.ts`.
+ *
+ * Generic-typed locally so the Hono handler can read `c.env.incoming` /
+ * `c.env.outgoing` without an `as` cast. Defined inline rather than imported
+ * to avoid coupling the gateway to a private `@hono/node-server` subpath
+ * (`./types`) — the public package exports HttpBindings only via the bundled
+ * types, not a stable runtime entry.
+ */
+type NodeHttpBindings = {
+    incoming: IncomingMessage;
+    outgoing: ServerResponse;
+};
+/** Dependencies for mounting `POST /mcp/v1` on a Hono app. */
+export interface McpServerEndpointDeps {
+    /** Token verification store (TokenClient surfaces the `mcpClient` block). */
+    readonly tokenStore: TokenStore;
+    /** Per-client McpServer factory — see
+     *  `packages/daemon/src/api/mcp-server-handlers.ts`. */
+    readonly buildMcpServerForClient: (client: TokenClient) => McpServer;
+    /** Gateway-scoped logger. Log calls emit with
+     *  `module:"mcp-server"` via the parent binding plus
+     *  `submodule:"endpoint"` here. */
+    readonly logger: GatewayLogger;
+    /**
+     * Maximum POST body size in bytes. The Hono `bodyLimit` middleware fires
+     * BEFORE the route handler buffers the body via `c.req.json()`, so a
+     * holder of a valid mcp-client-scoped token cannot exhaust daemon heap
+     * memory by streaming a multi-gigabyte POST body (DoS
+     * defense). Mirrors `config.httpBodyLimitBytes` -- the same ceiling
+     * `rest-api.ts` applies to POST /api/chat at line 329-337.
+     */
+    readonly bodyLimitBytes: number;
+}
+/**
+ * Mount POST /mcp/v1 on the supplied Hono app.
+ *
+ * MUST be mounted AFTER the global rate-limit middleware (so layer-1 IP
+ * caps apply) and BEFORE the catch-all `app.notFound` handler. The caller
+ * (`packages/daemon/src/wiring/...`) is responsible for that ordering;
+ * `hono-server.ts` mounts via this helper between rate-limit (~line 124)
+ * and the /ws route (~line 147).
+ */
+export declare function mountMcpServerEndpoint(app: Hono<{
+    Bindings: NodeHttpBindings;
+}>, deps: McpServerEndpointDeps): void;
+export {};

package/node_modules/@comis/gateway/dist/mcp-server-endpoint.js

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * POST /mcp/v1 endpoint mount.
+ *
+ * Mounts the Streamable HTTP MCP server route on the gateway's Hono app.
+ * Per-request lifecycle:
+ *
+ *   1. Extract bearer via `extractBearerToken(c.req.header("authorization"))`.
+ *   2. `tokenStore.verify(token)` — null ⇒ 401 (errorKind:"auth").
+ *   3. `checkScope(client.scopes, "mcp-client")` — false ⇒ 403
+ *      (errorKind:"auth").
+ *   4. `client.scopes.includes("admin")` ⇒ 403 (errorKind:"security"). This
+ *      is defense-in-depth: the `.refine` on `GatewayTokenSchema`
+ *      already blocks co-issuance at config-load. If this branch fires,
+ *      something has bypassed schema validation (a config-validation bug).
+ *   5. `mcp = deps.buildMcpServerForClient(client)` — per-client McpServer
+ *      with default-deny tools/list filter (the policy gate runs inside the
+ *      factory; see `packages/daemon/src/api/mcp-server-handlers.ts`).
+ *   6. `transport = new StreamableHTTPServerTransport({ sessionIdGenerator })`
+ *      → `mcp.connect(transport)` → `transport.handleRequest(req, res,
+ *      parsedBody)`.
+ *
+ * Hono c.env accessor:
+ *   The `@hono/node-server@1.19.14` `HttpBindings` type declares
+ *   `{ incoming: IncomingMessage; outgoing: ServerResponse }`. Verified by
+ *   reading `node_modules/@hono/node-server/dist/types.d.ts` directly.
+ *
+ * Body parsing (body pre-parse pitfall): Hono pre-parses POST bodies on demand. The
+ * SDK transport's `handleRequest(req, res, parsedBody?)` accepts a
+ * pre-parsed body as the 3rd arg; pass `await c.req.json().catch(() =>
+ * undefined)` so the SDK does not re-read the consumed stream.
+ *
+ * @module
+ */
+import { bodyLimit } from "hono/body-limit";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { checkScope, extractBearerToken, } from "./auth/token-auth.js";
+// ---------------------------------------------------------------------------
+// Mount function
+// ---------------------------------------------------------------------------
+/**
+ * Mount POST /mcp/v1 on the supplied Hono app.
+ *
+ * MUST be mounted AFTER the global rate-limit middleware (so layer-1 IP
+ * caps apply) and BEFORE the catch-all `app.notFound` handler. The caller
+ * (`packages/daemon/src/wiring/...`) is responsible for that ordering;
+ * `hono-server.ts` mounts via this helper between rate-limit (~line 124)
+ * and the /ws route (~line 147).
+ */
+export function mountMcpServerEndpoint(app, deps) {
+    const { tokenStore, buildMcpServerForClient, logger, bodyLimitBytes } = deps;
+    // Body-size limit before c.req.json() buffers the body.
+    // Without this gate, a holder of any valid mcp-client-scoped token can
+    // POST a multi-gigabyte body and the daemon's heap grows proportionally
+    // per concurrent request. The IP-level rate limiter caps request COUNT
+    // but not request BYTE COUNT. 413 is the canonical Hono bodyLimit
+    // response; we also wrap it in JSON-RPC error shape so MCP-aware clients
+    // see a structured response instead of a bare HTTP status.
+    const bodyLimitMw = bodyLimit({
+        maxSize: bodyLimitBytes,
+        onError: (c) => c.json({
+            jsonrpc: "2.0",
+            error: { code: -32600, message: "Request body too large" },
+            id: null,
+        }, 413),
+    });
+    app.post("/mcp/v1", bodyLimitMw, async (c) => {
+        // Gate 1 — extract bearer.
+        const token = extractBearerToken(c.req.header("authorization") ?? "") ?? "";
+        if (token === "") {
+            logger.warn({
+                submodule: "endpoint",
+                errorKind: "auth",
+                hint: "Send Authorization: Bearer <token> with an mcp-client-scoped token",
+            }, "MCP server connection rejected: no bearer token");
+            return c.json({
+                jsonrpc: "2.0",
+                error: { code: -32001, message: "Unauthorized" },
+                id: null,
+            }, 401);
+        }
+        // Gate 2 — verify token.
+        const client = tokenStore.verify(token);
+        if (!client) {
+            logger.warn({
+                submodule: "endpoint",
+                errorKind: "auth",
+                hint: "Verify the token matches a gateway.tokens[].secret entry",
+            }, "MCP server connection rejected: invalid token");
+            return c.json({
+                jsonrpc: "2.0",
+                error: { code: -32001, message: "Unauthorized" },
+                id: null,
+            }, 401);
+        }
+        // Gate 3 — scope check: require "mcp-client".
+        if (!checkScope(client.scopes, "mcp-client")) {
+            logger.warn({
+                clientId: client.id,
+                submodule: "endpoint",
+                errorKind: "auth",
+                hint: "Issue a token with scope mcp-client via tokens_manage; admin scope MUST NOT be co-issued",
+            }, "MCP server connection rejected: token missing mcp-client scope");
+            return c.json({
+                jsonrpc: "2.0",
+                error: { code: -32001, message: "Insufficient scope" },
+                id: null,
+            }, 403);
+        }
+        // Gate 4 — defense-in-depth: reject admin-EQUIVALENT + mcp-client
+        // co-issuance. GatewayTokenSchema.refine already blocks at
+        // config-load; if this branch fires, a config-validation bug let an
+        // invalid token through.
+        //
+        // The wildcard scope `"*"` grants ALL scopes (including `"admin"`) via
+        // `checkScope`, so the literal `includes("admin")` check was an
+        // information-hole -- a token with `["*", "mcp-client"]` had
+        // admin-equivalent access yet passed Gate 4. Reject `"*"` for the same
+        // reason `"admin"` is rejected.
+        if (client.scopes.includes("admin") || client.scopes.includes("*")) {
+            logger.error({
+                clientId: client.id,
+                submodule: "endpoint",
+                errorKind: "internal",
+                hint: "admin-equivalent scope (admin or wildcard '*') co-issued with mcp-client violates the GatewayTokenSchema disjointness refine -- this should be impossible; investigate config-load validation",
+            }, "Refusing MCP connection from admin-equivalent-scoped token (defense-in-depth)");
+            return c.json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32001,
+                    message: "Token has disjoint-scope violation",
+                },
+                id: null,
+            }, 403);
+        }
+        // All gates passed — build per-client McpServer, wire transport,
+        // delegate request handling to the SDK.
+        //
+        // STATELESS MODE (sessionIdGenerator: undefined): each request creates a
+        // fresh McpServer + transport pair scoped to this authenticated client.
+        // The MCP spec's session-id handshake is bypassed; every POST is
+        // self-contained (initialize → tools/list/call → response). This matches
+        // the per-request lifecycle: the policy filter set is computed at the
+        // moment the request lands, so subsequent calls in the same Streamable
+        // HTTP session would need session-pinning we do not yet maintain. Plan
+        // 04+ may switch to stateful mode if session-pinned state (rate-limit
+        // bucket, ResourceTemplate subscriptions) is added; today, stateless is
+        // the correct lifecycle.
+        let mcp;
+        let transport;
+        try {
+            mcp = buildMcpServerForClient(client);
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            await mcp.connect(transport);
+        }
+        catch (err) {
+            logger.error({
+                clientId: client.id,
+                submodule: "endpoint",
+                errorKind: "internal",
+                err,
+                hint: "Inspect daemon logs for tool-metadata registry failures or SDK transport construction errors",
+            }, "MCP server initialization failed");
+            return c.json({
+                jsonrpc: "2.0",
+                error: { code: -32603, message: "MCP server initialization failed" },
+                id: null,
+            }, 500);
+        }
+        // Mitigates Hono body pre-parse pitfall: Hono pre-parses body but SDK
+        // transport expects raw stream. SDK accepts a pre-parsed JSON body as the
+        // 3rd arg; on parse failure pass undefined and let the SDK surface the
+        // JSON-RPC error.
+        const parsedBody = await c.req.json().catch(() => undefined);
+        const incoming = c.env.incoming;
+        const outgoing = c.env.outgoing;
+        try {
+            await transport.handleRequest(incoming, outgoing, parsedBody);
+        }
+        catch (err) {
+            // The SDK transport writes its own JSON-RPC error responses on
+            // protocol-level failures. Reaching this branch means the underlying
+            // Node ServerResponse threw before/after the SDK finished — log and
+            // attempt a structured fallback only if headers haven't shipped.
+            logger.error({
+                clientId: client.id,
+                submodule: "endpoint",
+                errorKind: "internal",
+                err,
+                hint: "Inspect MCP SDK transport logs",
+            }, "MCP transport handleRequest threw");
+            if (!outgoing.headersSent) {
+                return c.json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Internal MCP transport error",
+                    },
+                    id: null,
+                }, 500);
+            }
+        }
+        // The transport writes the response stream directly on `outgoing`
+        // (StreamableHTTPServerTransport supports both SSE + JSON modes). Return
+        // a null body so Hono does not attempt to overwrite the response.
+        return c.body(null);
+    });
+    logger.debug({ submodule: "endpoint", route: "POST /mcp/v1" }, "MCP server endpoint mounted");
+}

package/node_modules/@comis/gateway/dist/oauth/oauth-callback-route.d.ts

@@ -11,7 +11,7 @@
  * page (200) on success or a "Login Failed" HTML page (400/500) on failure.
  *
  * HTTP method is GET, NOT POST (OAuth servers always redirect with GET).
- * Logging discipline (CLAUDE.md): submodule: "oauth-callback"
+ * Logging discipline: submodule: "oauth-callback"
  * on every line; NEVER log code/state/verifier/access/refresh values.
  *
  * @module

package/node_modules/@comis/gateway/dist/oauth/oauth-callback-route.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// @allow-throw: OAuth HTTP callback route; throws caught by Hono error-handler boundary per AGENTS.md §2.1 web-user-facing flows exception.
+// @allow-throw: OAuth HTTP callback route; throws caught by Hono error-handler boundary (web-user-facing flows exception).
 /**
  * OAuth callback route for the Comis gateway.
  *
@@ -13,7 +13,7 @@
  * page (200) on success or a "Login Failed" HTML page (400/500) on failure.
  *
  * HTTP method is GET, NOT POST (OAuth servers always redirect with GET).
- * Logging discipline (CLAUDE.md): submodule: "oauth-callback"
+ * Logging discipline: submodule: "oauth-callback"
  * on every line; NEVER log code/state/verifier/access/refresh values.
  *
  * @module