boondmanager-mcp-server 2.15.2 → 2.17.0

package/dist/transports/http.js

@@ -1,10 +1,13 @@
-import { createServer } from "node:http";
-import { randomUUID } from "node:crypto";
+import { createServer, IncomingMessage, ServerResponse } from "node:http";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { logger, generateCorrelationId } from "../services/logger.js";
+import { runWithRequestContext } from "../services/request-context.js";
+import { apiRequest, BoondApiError } from "../services/boond-client.js";
+import { readBool, readCsv, readPositiveInt, readString, readUrl } from "../config/env.js";
 import { SERVER_VERSION } from "../server.js";
-import { buildProtectedResourceMetadata, extractBearerToken, oauthContext, resolveAdvertisedScopes, resolveAuthorizationServer, } from "../services/oauth.js";
+import { buildProtectedResourceMetadata, currentAuthIdentity, extractBearerToken, oauthContext, resolveAdvertisedScopes, resolveAuthorizationServer, } from "../services/oauth.js";
 // Defaults: a half-hour idle window matches typical MCP gateway behaviour, and
 // a 5-minute sweep keeps memory bounded without hammering the event loop.
 const DEFAULT_SESSION_TTL_MS = 30 * 60_000;
@@ -13,38 +16,28 @@ const DEFAULT_SESSION_SWEEP_INTERVAL_MS = 5 * 60_000;
 // McpServer + transport until its TTL sweep, so without a cap an authenticated
 // client could spin up unbounded `initialize` requests and exhaust memory.
 const DEFAULT_MAX_SESSIONS = 1000;
+// Server socket timeouts (issue #237). Keep-alive above the usual load-balancer
+// idle timeouts (60 s ALB, 75 s nginx) so the LB never reuses a connection Node
+// has just closed; headers a second above keep-alive (Node's own requirement);
+// request generous because reporting calls are long.
+export const DEFAULT_KEEP_ALIVE_TIMEOUT_MS = 65_000;
+export const DEFAULT_HEADERS_TIMEOUT_MS = 66_000;
+export const DEFAULT_REQUEST_TIMEOUT_MS = 300_000;
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+/** How often `close()` re-reaps idle keep-alive sockets while draining. */
+const IDLE_REAP_INTERVAL_MS = 100;
+// Token validation (issue #234): one BoondManager round-trip per token per
+// minute is the cost of turning an expired token into a real 401.
+export const DEFAULT_TOKEN_VALIDATION_TTL_MS = 60_000;
+export const MAX_TOKEN_VALIDATION_ENTRIES = 500;
 // Loopback addresses that should default to the localhost host allow-list.
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
 const LOCALHOST_ALLOWED_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
-function readEnv(key) {
-    const v = process.env[key];
-    if (!v || v.startsWith("${"))
-        return undefined;
-    return v;
-}
-function readPositiveInt(key, fallback) {
-    const raw = readEnv(key);
-    if (!raw)
-        return fallback;
-    const parsed = Number(raw);
-    if (!Number.isFinite(parsed) || parsed <= 0)
-        return fallback;
-    return Math.floor(parsed);
-}
-function readCsvEnv(key) {
-    const raw = readEnv(key);
-    if (raw === undefined)
-        return undefined;
-    return raw
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0);
-}
 function readAllowedHosts() {
-    return readCsvEnv("MCP_HTTP_ALLOWED_HOSTS");
+    return readCsv("MCP_HTTP_ALLOWED_HOSTS");
 }
 function readAllowedOrigins() {
-    return readCsvEnv("MCP_HTTP_ALLOWED_ORIGINS");
+    return readCsv("MCP_HTTP_ALLOWED_ORIGINS");
 }
 /**
  * Resolves the effective Host header allow-list given user options and the
@@ -203,31 +196,129 @@ function extractHostname(hostHeader) {
         return undefined;
     }
 }
+/** `{ [key]: value }` when the value is defined, `{}` otherwise — keeps optional keys absent rather than `undefined`. */
+function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+/**
+ * SDK 1.30 declares `Transport.onclose` as `onclose?: () => void` but the
+ * `StreamableHTTPServerTransport` accessor as `(() => void) | undefined`. The
+ * SDK assigns one to the other internally; under `exactOptionalPropertyTypes`
+ * the two are incompatible at *our* call sites only. Delete this adapter when
+ * the SDK aligns the two declarations.
+ */
+function asTransport(transport) {
+    return transport;
+}
 export function resolveHttpOptions() {
-    const portRaw = readEnv("MCP_HTTP_PORT");
+    const portRaw = readString("MCP_HTTP_PORT")?.trim();
     const port = portRaw ? Number.parseInt(portRaw, 10) : 3000;
     if (!Number.isFinite(port) || port <= 0 || port > 65535) {
         throw new Error(`Invalid MCP_HTTP_PORT: ${portRaw}`);
     }
-    const stateless = (readEnv("MCP_HTTP_STATEFUL") ?? "false").toLowerCase() !== "true";
-    const enableJsonResponse = (readEnv("MCP_HTTP_JSON_RESPONSE") ?? "false").toLowerCase() === "true";
-    const staticAuthRaw = (readEnv("BOOND_HTTP_STATIC_AUTH") ?? "").toLowerCase();
-    const staticAuth = staticAuthRaw === "true" || staticAuthRaw === "1" || staticAuthRaw === "yes";
+    const stateless = !readBool("MCP_HTTP_STATEFUL", false);
+    const enableJsonResponse = readBool("MCP_HTTP_JSON_RESPONSE", false);
+    const staticAuth = readBool("BOOND_HTTP_STATIC_AUTH", false);
+    const insecureStaticAuth = readBool("MCP_HTTP_INSECURE_STATIC_AUTH", false);
+    // A blank key is "not configured", never an empty secret that every request matches.
+    const apiKey = readString("MCP_HTTP_API_KEY")?.trim();
     return {
-        host: readEnv("MCP_HTTP_HOST") ?? "127.0.0.1",
+        host: readString("MCP_HTTP_HOST")?.trim() ?? "127.0.0.1",
         port,
-        path: readEnv("MCP_HTTP_PATH") ?? "/mcp",
+        path: readString("MCP_HTTP_PATH")?.trim() ?? "/mcp",
         stateless,
         enableJsonResponse,
         sessionTtlMs: readPositiveInt("MCP_HTTP_SESSION_TTL_MS", DEFAULT_SESSION_TTL_MS),
         sessionSweepIntervalMs: readPositiveInt("MCP_HTTP_SESSION_SWEEP_INTERVAL_MS", DEFAULT_SESSION_SWEEP_INTERVAL_MS),
         maxSessions: readPositiveInt("MCP_HTTP_MAX_SESSIONS", DEFAULT_MAX_SESSIONS),
-        allowedHosts: readAllowedHosts(),
-        allowedOrigins: readAllowedOrigins(),
-        publicUrl: readEnv("MCP_HTTP_PUBLIC_URL"),
+        ...optional("allowedHosts", readAllowedHosts()),
+        ...optional("allowedOrigins", readAllowedOrigins()),
+        ...optional("publicUrl", readUrl("MCP_HTTP_PUBLIC_URL")),
         staticAuth,
+        ...optional("apiKey", apiKey),
+        insecureStaticAuth,
+        keepAliveTimeoutMs: readPositiveInt("MCP_HTTP_KEEP_ALIVE_TIMEOUT_MS", DEFAULT_KEEP_ALIVE_TIMEOUT_MS),
+        headersTimeoutMs: readPositiveInt("MCP_HTTP_HEADERS_TIMEOUT_MS", DEFAULT_HEADERS_TIMEOUT_MS),
+        requestTimeoutMs: readPositiveInt("MCP_HTTP_REQUEST_TIMEOUT_MS", DEFAULT_REQUEST_TIMEOUT_MS),
+        shutdownTimeoutMs: readPositiveInt("MCP_HTTP_SHUTDOWN_TIMEOUT_MS", DEFAULT_SHUTDOWN_TIMEOUT_MS),
+        validateToken: readBool("MCP_HTTP_VALIDATE_TOKEN", false),
+        tokenValidationTtlMs: readPositiveInt("MCP_HTTP_TOKEN_VALIDATION_TTL_MS", DEFAULT_TOKEN_VALIDATION_TTL_MS),
     };
 }
+/**
+ * The socket timeouts applied to the Node server, with the one invariant Node
+ * itself enforces made explicit: `headersTimeout` must be strictly greater
+ * than `keepAliveTimeout`, otherwise a kept-alive connection can be timed out
+ * while waiting for its next request's headers. A configuration that breaks it
+ * is repaired (headers = keep-alive + 1 s) and logged rather than refused.
+ */
+export function resolveServerTimeouts(options) {
+    const keepAliveTimeout = options.keepAliveTimeoutMs ?? DEFAULT_KEEP_ALIVE_TIMEOUT_MS;
+    const requestedHeaders = options.headersTimeoutMs ?? DEFAULT_HEADERS_TIMEOUT_MS;
+    const coerced = requestedHeaders <= keepAliveTimeout;
+    const headersTimeout = coerced ? keepAliveTimeout + 1_000 : requestedHeaders;
+    const requestTimeout = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    return { keepAliveTimeout, headersTimeout, requestTimeout, coerced };
+}
+/**
+ * Refuses a static-auth deployment that would expose the operator's
+ * BoondManager credentials to anyone who can reach the port (issue #230).
+ *
+ * Static auth skips the Bearer check entirely, and off loopback the `Host` /
+ * `Origin` validations are disabled too — the Docker image binds `0.0.0.0` by
+ * default — so with no `apiKey` the endpoint is an anonymous proxy carrying
+ * the operator's read *and* write rights. Loopback is exempt (only local
+ * processes can connect), and `insecureStaticAuth` is the explicit,
+ * named opt-out for a deployment whose network is the boundary. Throwing here
+ * rather than warning is deliberate: a warning on stderr is exactly what an
+ * operator running `docker run -e BOOND_HTTP_STATIC_AUTH=true` does not read.
+ */
+export function assertStaticAuthPolicy(options) {
+    if (!options.staticAuth || options.apiKey)
+        return;
+    if (LOOPBACK_HOSTS.has(options.host))
+        return;
+    if (options.insecureStaticAuth)
+        return;
+    throw new Error(`BOOND_HTTP_STATIC_AUTH=true on a non-loopback interface (${options.host}) requires MCP_HTTP_API_KEY: ` +
+        "without it, anyone who can reach the port acts with the operator's BoondManager credentials. " +
+        "Set MCP_HTTP_API_KEY=<secret> (clients send `Authorization: Bearer <secret>` or `X-Api-Key: <secret>`), " +
+        "bind to 127.0.0.1 behind an authenticating proxy, or set MCP_HTTP_INSECURE_STATIC_AUTH=1 to accept the exposure explicitly.");
+}
+/**
+ * Constant-time comparison of a presented API key against the configured one.
+ *
+ * `timingSafeEqual` throws on buffers of different lengths, so a length
+ * mismatch is answered by comparing the expected key against itself first —
+ * the call still costs one full comparison — and then returning `false`. The
+ * key's *length* is therefore observable, which is acceptable: it is not
+ * secret for a random key (the README generates 32 random bytes), and the
+ * alternative — hashing both sides to equalise lengths — reads to static
+ * analysers as a password stored under a fast hash, which it is not.
+ */
+export function isApiKeyMatch(presented, expected) {
+    if (!presented)
+        return false;
+    const a = Buffer.from(presented, "utf8");
+    const b = Buffer.from(expected, "utf8");
+    if (a.length !== b.length) {
+        timingSafeEqual(b, b);
+        return false;
+    }
+    return timingSafeEqual(a, b);
+}
+/** The key a request presents: `Authorization: Bearer <key>` first, then `X-Api-Key`. */
+function presentedApiKey(req) {
+    const bearer = extractBearerToken(req.headers["authorization"]);
+    if (bearer)
+        return bearer;
+    const raw = req.headers["x-api-key"];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 /**
  * Build the canonical "resource" URL advertised in the OAuth2 protected
  * resource metadata and in the `WWW-Authenticate` challenge. Behind a
@@ -241,13 +332,34 @@ function resolveResourceUrl(options) {
 }
 /** Max accepted request body size (1 MiB). MCP initialize payloads are tiny;
  *  this caps the memory a single authenticated request can force us to buffer. */
-const MAX_BODY_BYTES = 1024 * 1024;
+export const MAX_BODY_BYTES = 1024 * 1024;
 class PayloadTooLargeError extends Error {
     constructor() {
         super("Request body exceeds the maximum allowed size");
         this.name = "PayloadTooLargeError";
     }
 }
+/**
+ * Buffer a request body under `MAX_BODY_BYTES`, then parse it as JSON.
+ *
+ * This is the **only** body reader on the MCP endpoint (issue #227). Every
+ * POST — stateless, existing stateful session, or `initialize` — goes through
+ * it and the parsed value is handed to `transport.handleRequest(req, res,
+ * parsedBody)`, so the SDK (which reads without a ceiling) never touches the
+ * stream. The `Content-Length` precheck upstream only covers clients that
+ * announce their size; a chunked transfer (no `Content-Length`, which is also
+ * what a reverse proxy that re-encodes produces) is caught here, by counting
+ * bytes as they arrive.
+ *
+ * On overflow the loop stops without `req.destroy()`: destroying the socket
+ * would tear down the response along with the request, and the client would
+ * see a reset instead of the `413` (the caller answers with `Connection:
+ * close`, and Node closes the socket once that response is flushed).
+ *
+ * An unparseable body is reported as `invalid` rather than `undefined`: a
+ * `parsedBody` of `undefined` makes the SDK fall back to `req.json()` on a
+ * stream that has already been consumed.
+ */
 async function readJsonBody(req) {
     const chunks = [];
     let total = 0;
@@ -255,30 +367,44 @@ async function readJsonBody(req) {
         const buf = chunk;
         total += buf.length;
         if (total > MAX_BODY_BYTES) {
-            req.destroy();
             throw new PayloadTooLargeError();
         }
         chunks.push(buf);
     }
     const raw = Buffer.concat(chunks).toString("utf8");
-    if (!raw)
-        return undefined;
     try {
-        return JSON.parse(raw);
+        return { kind: "json", value: JSON.parse(raw) };
     }
     catch {
-        return undefined;
+        return { kind: "invalid" };
     }
 }
-function writeJsonRpcError(res, status, message) {
+/** JSON-RPC 2.0 reserved code for a body that is not parseable JSON. */
+const JSON_RPC_PARSE_ERROR = -32700;
+function writeJsonRpcError(res, status, message, code = -32000) {
     res.statusCode = status;
     res.setHeader("Content-Type", "application/json");
     res.end(JSON.stringify({
         jsonrpc: "2.0",
-        error: { code: -32000, message },
+        error: { code, message },
         id: null,
     }));
 }
+/**
+ * `413` for a body that blew through `MAX_BODY_BYTES` mid-stream. The request
+ * stream is left unread past the overflow point, so the response must not be
+ * reused on a keep-alive connection: `Connection: close` makes Node destroy
+ * the socket right after this response is flushed, instead of draining (and
+ * therefore fully receiving) whatever the client still has to send.
+ */
+function writePayloadTooLarge(res) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    res.setHeader("Connection", "close");
+    writeJsonRpcError(res, 413, "Request body too large");
+}
 /**
  * Tear down a session's transport + server exactly once. Several paths can race
  * to dispose the same entry (idle sweep, the transport's own `onclose`, the
@@ -297,6 +423,22 @@ function destroySession(entry) {
     return entry.closing;
 }
 export async function startHttpTransport(createServerFactory, options) {
+    assertStaticAuthPolicy(options);
+    if (options.staticAuth) {
+        logger.warn({
+            host: options.host,
+            apiKey: options.apiKey ? "configured" : "none",
+            insecureStaticAuth: options.insecureStaticAuth === true,
+        }, "Static auth mode: every MCP request runs with the operator's BoondManager credentials" +
+            (options.apiKey
+                ? "; clients must present MCP_HTTP_API_KEY"
+                : LOOPBACK_HOSTS.has(options.host)
+                    ? "; no client authentication (loopback bind only)"
+                    : "; NO CLIENT AUTHENTICATION on a non-loopback bind (MCP_HTTP_INSECURE_STATIC_AUTH)"));
+    }
+    else if (options.apiKey) {
+        logger.warn("MCP_HTTP_API_KEY is set but BOOND_HTTP_STATIC_AUTH is not: ignored. In OAuth mode the Bearer is the BoondManager access token.");
+    }
     const sessions = new Map();
     const sessionTtlMs = options.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
     const sessionSweepIntervalMs = options.sessionSweepIntervalMs ?? DEFAULT_SESSION_SWEEP_INTERVAL_MS;
@@ -316,6 +458,50 @@ export async function startHttpTransport(createServerFactory, options) {
         : resourceUrl;
     const metadataUrl = `${resourceOrigin}${OAUTH_METADATA_PATH}${options.path}`;
     const wwwAuthenticate = `Bearer realm="${resourceUrl}", resource_metadata="${metadataUrl}"`;
+    // Bearer validation cache (issue #234): sha256(token) → verdict + expiry,
+    // LRU-bounded like the other per-identity maps. The token itself is never
+    // stored. A negative verdict is cached too, so a client retrying with a
+    // dead token does not turn into a BoondManager call per retry.
+    const tokenValidationTtlMs = options.tokenValidationTtlMs ?? DEFAULT_TOKEN_VALIDATION_TTL_MS;
+    const tokenVerdicts = new Map();
+    const validateAccessToken = async (accessToken) => {
+        const key = createHash("sha256").update(accessToken).digest("hex");
+        const now = Date.now();
+        const cached = tokenVerdicts.get(key);
+        if (cached && cached.expiresAt > now) {
+            // Refresh LRU position.
+            tokenVerdicts.delete(key);
+            tokenVerdicts.set(key, cached);
+            return cached.valid ? "valid" : "invalid";
+        }
+        let verdict;
+        try {
+            await oauthContext.run({ accessToken }, () => apiRequest("/application/current-user"));
+            verdict = "valid";
+        }
+        catch (error) {
+            if (error instanceof BoondApiError && error.status === 401) {
+                verdict = "invalid";
+            }
+            else {
+                // BoondManager down, rate-limited, network error: not a verdict on
+                // the token. Fail open — the tool call will surface the real error —
+                // and cache nothing.
+                logger.warn({ err: error }, "Token validation could not reach BoondManager; letting the request through");
+                verdict = "unknown";
+            }
+        }
+        if (verdict !== "unknown") {
+            tokenVerdicts.set(key, { valid: verdict === "valid", expiresAt: now + tokenValidationTtlMs });
+            while (tokenVerdicts.size > MAX_TOKEN_VALIDATION_ENTRIES) {
+                const oldest = tokenVerdicts.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                tokenVerdicts.delete(oldest);
+            }
+        }
+        return verdict;
+    };
     const sweepIdleSessions = async () => {
         const cutoff = Date.now() - sessionTtlMs;
         const expired = [];
@@ -350,10 +536,17 @@ export async function startHttpTransport(createServerFactory, options) {
         res.setHeader("Cache-Control", "public, max-age=3600");
         res.end(JSON.stringify(doc));
     };
-    /** RFC 6750 §3.1 challenge for missing/invalid bearer tokens. */
-    const writeOAuthChallenge = (res, status, message) => {
+    /**
+     * RFC 6750 §3.1 challenge. `error` is omitted when no token was presented
+     * (the RFC says a bare challenge is the right answer there) and set to
+     * `invalid_token` when one was and BoondManager rejected it — that value is
+     * what an MCP client keys its "start a new authorization" logic on.
+     */
+    const writeOAuthChallenge = (res, status, message, error) => {
         res.statusCode = status;
-        res.setHeader("WWW-Authenticate", wwwAuthenticate);
+        res.setHeader("WWW-Authenticate", error
+            ? `${wwwAuthenticate}, error="${error}", error_description="${message.replace(/"/g, "'")}"`
+            : wwwAuthenticate);
         res.setHeader("Content-Type", "application/json");
         res.end(JSON.stringify({
             jsonrpc: "2.0",
@@ -361,9 +554,50 @@ export async function startHttpTransport(createServerFactory, options) {
             id: null,
         }));
     };
-    const httpServer = createServer(async (req, res) => {
+    const handleRequest = async (req, res) => {
         const corrId = generateCorrelationId();
-        const reqLogger = logger.child({ corrId, method: req.method, path: req.url });
+        // Path only: the query string of a request is never logged (#236).
+        const path = req.url?.split("?")[0];
+        const reqLogger = logger.child({ corrId, method: req.method, path });
+        const startedAt = Date.now();
+        let rejection;
+        // Access log (#236): one line per request when the response is finished,
+        // or when the client went away before that. 401 / 403 / 413 (and the
+        // other rejections this handler writes itself) are `warn` with their
+        // reason; 5xx is `error`; the liveness probe stays at `debug` so a
+        // 10-second Kubernetes probe does not fill the log.
+        let accessLogged = false;
+        const writeAccessLog = () => {
+            if (accessLogged)
+                return;
+            accessLogged = true;
+            const status = res.statusCode;
+            const fields = {
+                status,
+                durationMs: Date.now() - startedAt,
+                ...(rejection !== undefined ? { reason: rejection } : {}),
+                ...(res.writableFinished ? {} : { aborted: true }),
+            };
+            if (path === "/healthz")
+                reqLogger.debug(fields, "http request");
+            else if (status >= 500)
+                reqLogger.error(fields, "http request");
+            else if (rejection !== undefined || status === 401 || status === 403 || status === 413) {
+                reqLogger.warn(fields, "http request");
+            }
+            else
+                reqLogger.info(fields, "http request");
+        };
+        res.on("finish", writeAccessLog);
+        res.on("close", writeAccessLog);
+        const reject = (status, message, code) => {
+            rejection = message;
+            writeJsonRpcError(res, status, message, code);
+        };
+        const challenge = (status, message, error) => {
+            rejection = message;
+            writeOAuthChallenge(res, status, message, error);
+        };
         try {
             // Liveness probe — served before Host validation so Docker/Kubernetes
             // probes (which often send the pod IP as Host) always succeed. GET only,
@@ -384,11 +618,11 @@ export async function startHttpTransport(createServerFactory, options) {
             if (allowedHosts.length > 0) {
                 const hostname = extractHostname(req.headers.host);
                 if (!hostname) {
-                    writeJsonRpcError(res, 403, "Missing or invalid Host header");
+                    reject(403, "Missing or invalid Host header");
                     return;
                 }
                 if (!allowedHosts.includes(hostname)) {
-                    writeJsonRpcError(res, 403, `Invalid Host: ${hostname}`);
+                    reject(403, `Invalid Host: ${hostname}`);
                     return;
                 }
             }
@@ -402,10 +636,9 @@ export async function startHttpTransport(createServerFactory, options) {
             // *because* we pointed it there from a 401 challenge — 403ing it would
             // dead-end the OAuth bootstrap the challenge just started.
             if (originPolicy.enabled && !isDiscoveryPath(req.url, options.path)) {
-                const originHeader = req.headers.origin;
-                const origin = Array.isArray(originHeader) ? originHeader[0] : originHeader;
+                const origin = req.headers.origin;
                 if (origin && !isOriginAllowed(originPolicy, origin)) {
-                    writeJsonRpcError(res, 403, `Invalid Origin: ${origin}`);
+                    reject(403, `Invalid Origin: ${origin}`);
                     return;
                 }
             }
@@ -414,7 +647,12 @@ export async function startHttpTransport(createServerFactory, options) {
             // readJsonBody still covers chunked / lying Content-Length cases.
             const contentLength = Number(req.headers["content-length"]);
             if (Number.isFinite(contentLength) && contentLength > MAX_BODY_BYTES) {
-                writeJsonRpcError(res, 413, "Request body too large");
+                // Plain 413, deliberately *without* `Connection: close`: Node drains
+                // the announced body itself (`req._dump()`), so the connection is
+                // reusable — and closing it early makes a client still uploading see
+                // a reset instead of the 413 (undici's fetch rejects). The mid-stream
+                // overflow below is different: its stream is left unread.
+                reject(413, "Request body too large");
                 return;
             }
             const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
@@ -432,13 +670,29 @@ export async function startHttpTransport(createServerFactory, options) {
             }
             // Core MCP dispatch — shared between OAuth and static-auth paths.
             const dispatchMcpRequest = async () => {
-                if (options.stateless) {
-                    if (req.method !== "POST") {
-                        writeJsonRpcError(res, 405, "Only POST is supported in stateless mode");
+                if (options.stateless && req.method !== "POST") {
+                    reject(405, "Only POST is supported in stateless mode");
+                    return;
+                }
+                // The body is read *here*, once, under the 1 MiB streaming cap, and
+                // handed to the SDK pre-parsed on every path below — the SDK's own
+                // reader has no ceiling, so letting it read on any path would leave
+                // that path uncapped (#227). GET (SSE stream) and DELETE carry no body
+                // and the SDK never reads one for them.
+                let parsedBody;
+                if (req.method === "POST") {
+                    const read = await readJsonBody(req);
+                    if (read.kind === "invalid") {
+                        reject(400, "Parse error: Invalid JSON", JSON_RPC_PARSE_ERROR);
                         return;
                     }
+                    parsedBody = read.value;
+                }
+                if (options.stateless) {
+                    // No `sessionIdGenerator` = stateless mode (the SDK documents the
+                    // key as `undefined`; omitting it is the same and type-checks under
+                    // exactOptionalPropertyTypes).
                     const transport = new StreamableHTTPServerTransport({
-                        sessionIdGenerator: undefined,
                         enableJsonResponse: options.enableJsonResponse,
                     });
                     const server = createServerFactory();
@@ -446,27 +700,41 @@ export async function startHttpTransport(createServerFactory, options) {
                         void transport.close();
                         void server.close();
                     });
-                    await server.connect(transport);
-                    await transport.handleRequest(req, res);
+                    await server.connect(asTransport(transport));
+                    await transport.handleRequest(req, res, parsedBody);
                     return;
                 }
                 // Stateful mode: route by Mcp-Session-Id header
                 const sessionIdHeader = req.headers["mcp-session-id"];
                 const sessionId = Array.isArray(sessionIdHeader) ? sessionIdHeader[0] : sessionIdHeader;
-                if (sessionId && sessions.has(sessionId)) {
+                const identity = currentAuthIdentity();
+                if (sessionId) {
                     const entry = sessions.get(sessionId);
-                    entry.lastActivityAt = Date.now();
-                    await entry.transport.handleRequest(req, res);
-                    return;
+                    if (entry && entry.ownerIdentity === identity) {
+                        entry.lastActivityAt = Date.now();
+                        await entry.transport.handleRequest(req, res, parsedBody);
+                        return;
+                    }
+                    // Unknown session, or a session opened under another identity: one
+                    // answer for both, so the probe does not learn whether the id exists
+                    // (#232). A POST `initialize` carrying a stale id still opens a new
+                    // session below, as it always did.
+                    if (!(req.method === "POST" && isInitializeRequest(parsedBody))) {
+                        if (entry) {
+                            reqLogger.warn({ sessionId }, "Session ownership mismatch; answering as unknown session");
+                        }
+                        reject(404, "Session not found", -32001);
+                        return;
+                    }
                 }
                 if (req.method !== "POST") {
-                    writeJsonRpcError(res, 400, "Missing or invalid session ID");
+                    reject(400, "Missing or invalid session ID");
                     return;
                 }
-                // Parse body to detect initialization
-                const body = await readJsonBody(req);
+                // First request of a session must be `initialize`
+                const body = parsedBody;
                 if (!isInitializeRequest(body)) {
-                    writeJsonRpcError(res, 400, "First request must be an MCP initialize message");
+                    reject(400, "First request must be an MCP initialize message");
                     return;
                 }
                 // Cap concurrent sessions. Try a sweep first in case the ceiling is
@@ -475,7 +743,7 @@ export async function startHttpTransport(createServerFactory, options) {
                     await sweepIdleSessions();
                     if (sessions.size >= maxSessions) {
                         reqLogger.warn({ sessionCount: sessions.size, maxSessions }, "Session limit reached; rejecting new initialize");
-                        writeJsonRpcError(res, 503, "Server session limit reached; retry later");
+                        reject(503, "Server session limit reached; retry later");
                         return;
                     }
                 }
@@ -483,7 +751,7 @@ export async function startHttpTransport(createServerFactory, options) {
                     sessionIdGenerator: () => randomUUID(),
                     enableJsonResponse: options.enableJsonResponse,
                     onsessioninitialized: (id) => {
-                        sessions.set(id, { transport, server, lastActivityAt: Date.now() });
+                        sessions.set(id, { transport, server, lastActivityAt: Date.now(), ownerIdentity: identity });
                         reqLogger.info({ sessionId: id, sessionCount: sessions.size }, "MCP session initialized");
                     },
                     onsessionclosed: (id) => {
@@ -509,35 +777,41 @@ export async function startHttpTransport(createServerFactory, options) {
                     }
                 };
                 const server = createServerFactory();
-                await server.connect(transport);
+                await server.connect(asTransport(transport));
                 await transport.handleRequest(req, res, body);
             };
             if (options.staticAuth) {
                 // Static-auth mode: env-based JWT credentials configured at startup via
-                // initClient(). No Bearer token required from the MCP client.
-                await dispatchMcpRequest();
+                // initClient(). The MCP client authenticates with the shared API key
+                // when one is configured (#230) — never with a BoondManager token.
+                if (options.apiKey && !isApiKeyMatch(presentedApiKey(req), options.apiKey)) {
+                    res.setHeader("WWW-Authenticate", `Bearer realm="${resourceUrl}"`);
+                    reject(401, "Missing or invalid API key. Send `Authorization: Bearer <MCP_HTTP_API_KEY>` or `X-Api-Key: <MCP_HTTP_API_KEY>`.", -32001);
+                    return;
+                }
+                await runWithRequestContext({ corrId }, dispatchMcpRequest);
             }
             else {
                 // OAuth2 Bearer is mandatory on the MCP endpoint. The token is opaque
                 // to us — we forward it to BoondManager, which is authoritative.
                 const accessToken = extractBearerToken(req.headers["authorization"]);
                 if (!accessToken) {
-                    writeOAuthChallenge(res, 401, "Missing Bearer token. Authenticate against BoondManager and include `Authorization: Bearer <access_token>`.");
+                    challenge(401, "Missing Bearer token. Authenticate against BoondManager and include `Authorization: Bearer <access_token>`.");
+                    return;
+                }
+                if (options.validateToken && (await validateAccessToken(accessToken)) === "invalid") {
+                    reqLogger.info("Bearer rejected by BoondManager; answering 401 invalid_token");
+                    challenge(401, "BoondManager rejected the access token (expired or revoked). Re-authorize and retry.", "invalid_token");
                     return;
                 }
                 // Wrap in AsyncLocalStorage so boond-client's oauthContextAuth can pull
                 // the token out when issuing API calls.
-                await oauthContext.run({ accessToken }, dispatchMcpRequest);
+                await oauthContext.run({ accessToken }, () => runWithRequestContext({ corrId }, dispatchMcpRequest));
             }
         }
         catch (error) {
             if (error instanceof PayloadTooLargeError) {
-                if (!res.headersSent) {
-                    writeJsonRpcError(res, 413, "Request body too large");
-                }
-                else {
-                    res.end();
-                }
+                writePayloadTooLarge(res);
                 return;
             }
             reqLogger.error({ err: error }, "HTTP transport error");
@@ -548,7 +822,29 @@ export async function startHttpTransport(createServerFactory, options) {
                 res.end();
             }
         }
+    };
+    // `createServer` takes a sync listener: an async callback's rejection would
+    // be an unhandled promise, invisible to the client (issue #237). The handler
+    // catches everything it can above; this is the last net.
+    const httpServer = createServer((req, res) => {
+        void handleRequest(req, res).catch((error) => {
+            logger.error({ err: error }, "Unhandled HTTP transport error");
+            if (!res.headersSent) {
+                writeJsonRpcError(res, 500, "Internal server error");
+            }
+            else {
+                res.end();
+            }
+        });
     });
+    const timeouts = resolveServerTimeouts(options);
+    if (timeouts.coerced) {
+        logger.warn({ requested: options.headersTimeoutMs, applied: timeouts.headersTimeout, keepAlive: timeouts.keepAliveTimeout }, "MCP_HTTP_HEADERS_TIMEOUT_MS must exceed the keep-alive timeout; raised to keep-alive + 1 s");
+    }
+    httpServer.keepAliveTimeout = timeouts.keepAliveTimeout;
+    httpServer.headersTimeout = timeouts.headersTimeout;
+    httpServer.requestTimeout = timeouts.requestTimeout;
+    const shutdownTimeoutMs = options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
     await new Promise((resolve, reject) => {
         httpServer.once("error", reject);
         httpServer.listen(options.port, options.host, () => {
@@ -560,20 +856,54 @@ export async function startHttpTransport(createServerFactory, options) {
     // the kernel picks a free port and only server.address() knows which one.
     const bound = httpServer.address();
     const boundPort = bound && typeof bound === "object" ? bound.port : options.port;
-    return {
-        address: { host: options.host, port: boundPort, path: options.path },
-        sessionCount: () => sessions.size,
-        sweepIdleSessions,
-        close: async () => {
+    // Memoised so a second close() — a second SIGTERM, or a caller's cleanup
+    // racing the signal handler — waits on the same shutdown instead of calling
+    // `server.close()` on a closed server (ERR_SERVER_NOT_RUNNING, unhandled).
+    let closing;
+    const close = () => {
+        if (closing)
+            return closing;
+        closing = (async () => {
             if (sweepTimer)
                 clearInterval(sweepTimer);
             const entries = Array.from(sessions.values());
             sessions.clear();
             await Promise.all(entries.map((e) => destroySession(e)));
             await new Promise((resolve, reject) => {
-                httpServer.close((err) => (err ? reject(err) : resolve()));
+                // `server.close()` stops accepting, reaps idle keep-alive sockets once
+                // (Node's `httpServerPreClose` → `closeIdleConnections()`), and
+                // resolves when every remaining connection has ended. Two things
+                // never end on their own: an open SSE stream / a request stuck
+                // mid-headers (destroyed after the grace period), and a keep-alive
+                // socket that was still draining a body at that single reap — Node
+                // never re-checks it, and with a 65 s keep-alive it would hold the
+                // close for the whole grace period. So idle reaping is repeated until
+                // the server is closed.
+                const force = setTimeout(() => {
+                    logger.warn({ shutdownTimeoutMs }, "Shutdown grace period elapsed; destroying remaining connections");
+                    httpServer.closeAllConnections();
+                }, shutdownTimeoutMs);
+                force.unref();
+                const reapIdle = setInterval(() => httpServer.closeIdleConnections(), IDLE_REAP_INTERVAL_MS);
+                reapIdle.unref();
+                httpServer.close((err) => {
+                    clearTimeout(force);
+                    clearInterval(reapIdle);
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
             });
-        },
+        })();
+        return closing;
+    };
+    return {
+        address: { host: options.host, port: boundPort, path: options.path },
+        server: httpServer,
+        sessionCount: () => sessions.size,
+        sweepIdleSessions,
+        close,
     };
 }
 //# sourceMappingURL=http.js.map