mandala-computer-mcp 0.1.0

package/dist/http.js

@@ -0,0 +1,792 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
+import { BlockList, isIP } from 'node:net';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import express, {} from 'express';
+import { Api, MODEL_KEY_HEADER } from './api.js';
+import { createServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+/**
+ * A ceiling on live sessions.
+ *
+ * An initialize is cheap to send and expensive to serve — it builds a whole
+ * McpServer with every tool registered, plus a transport that then survives the
+ * TTL. The bearer cannot be checked without a round trip to the platform, so
+ * any string gets that far; without a cap, a loop of initializes is a memory
+ * exhaustion that costs the sender nothing.
+ */
+const DEFAULT_MAX_SESSIONS = 256;
+const DEFAULT_MAX_LARGE_BODY_PARSES = 4;
+const SMALL_BODY_BYTES = 256 * 1024;
+/**
+ * The addresses that mean "this machine only".
+ *
+ * `0.0.0.0` and `::` are deliberately absent: they bind every interface, which
+ * is an operator saying they want this reachable from elsewhere. Treating that
+ * as loopback would hand them a Host allowlist naming addresses their callers
+ * never send, and the deployment would answer 403 to everything.
+ *
+ * The whole of 127.0.0.0/8 is loopback, not only 127.0.0.1. Binding
+ * `127.0.0.2` used to skip the default Host check because the set named three
+ * spellings and nothing else on this machine.
+ *
+ * IPv4-mapped loopback — `::ffff:127.0.0.1`, and the bracketed spelling — is
+ * the same widening one notation further out. It is a v6 socket carrying a v4
+ * loopback address, Node will bind it, and it was falling through to "not
+ * loopback": no default Host allowlist, so DNS-rebinding protection silently
+ * off on a bind that is as local as `127.0.0.1` is.
+ *
+ * IPv6 loopback is the same hole one spelling further in. Node accepts
+ * `0:0:0:0:0:0:0:1` and `::0:1` and reports the bound address as `::1`, but
+ * `cfg.host` stays the operator's spelling — a string match on `::1` alone
+ * skipped the default Host allowlist and left DNS-rebinding protection off.
+ * Parsed as an address, every compression of all-zeros-then-one is loopback.
+ *
+ * A zone suffix (`%lo`) is dropped first, since it names an interface rather
+ * than an address.
+ */
+const LOOPBACK = new BlockList();
+LOOPBACK.addAddress('::1', 'ipv6');
+LOOPBACK.addSubnet('127.0.0.0', 8, 'ipv4');
+export function isLoopbackHost(host) {
+    let h = host.toLowerCase();
+    if (h.startsWith('[') && h.endsWith(']'))
+        h = h.slice(1, -1);
+    const zone = h.indexOf('%');
+    if (zone >= 0)
+        h = h.slice(0, zone);
+    if (h === 'localhost')
+        return true;
+    const version = isIP(h);
+    if (version === 4)
+        return LOOPBACK.check(h, 'ipv4');
+    if (version === 6)
+        return LOOPBACK.check(h, 'ipv6');
+    return false;
+}
+/**
+ * One operator-supplied allowlist entry, as the Host headers it should match.
+ *
+ * Bracket-aware, because that is the whole difficulty: a literal IPv6 address
+ * is full of colons and is only a `host:port` when the colon falls after the
+ * `]`. Three cases, and only the last is expanded:
+ *
+ * - already carries a port — left exactly as written. That operator has said
+ *   which port their callers use, and it need not be the one bound here.
+ * - a BARE IPv6 address, unbracketed. `::1` is not a legal Host header and
+ *   `::1` + `:3000` is `::1:3000`, which nothing can send — so it is BRACKETED
+ *   into the spellings a client actually sends, rather than left as a dead
+ *   entry that matches nothing. An operator who writes the address has said
+ *   which host they mean; the brackets are notation, not a second guess.
+ * - anything else — matched with and without the bound port.
+ */
+export function hostSpellings(host, port) {
+    if (host.startsWith('[')) {
+        // Already bracketed: with a port it is exactly what a client sends, and
+        // without one it still needs the ported spelling.
+        return /\]:\d+$/.test(host) ? [host] : [host, `${host}:${port}`];
+    }
+    // Unbracketed and full of colons is a v6 literal; one colon and digits is a
+    // name that already names its port.
+    if (/:\d+$/.test(host) && host.indexOf(':') === host.lastIndexOf(':'))
+        return [host];
+    if (host.includes(':'))
+        return [`[${host}]`, `[${host}]:${port}`];
+    return [host, `${host}:${port}`];
+}
+/**
+ * The Host/Origin refusal the SDK would have returned from handleRequest.
+ *
+ * Matched here so a DNS-rebinding initialize never reaches `createServer`.
+ * The SDK's check returns a 403 Response without throwing, so a refusal that
+ * ran after construction paid for every tool registration and never hit the
+ * catch that closes the transport (adversarial review, OPL-4314).
+ */
+function dnsRebindingRefusal(req, hosts, origins) {
+    if (!(hosts?.length || origins?.length))
+        return undefined;
+    if (hosts?.length) {
+        const hostHeader = req.header('host');
+        if (!hostHeader || !hosts.includes(hostHeader)) {
+            return `Invalid Host header: ${hostHeader}`;
+        }
+    }
+    if (origins?.length) {
+        const originHeader = req.header('origin');
+        if (originHeader && !origins.includes(originHeader)) {
+            return `Invalid Origin header: ${originHeader}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * The hosted install: one URL, and every caller brings their own key.
+ *
+ * The important property of this server is what it does NOT hold. There is no
+ * credential of its own, no store, and no state that outlives a session: a
+ * caller's `com_…` key arrives as their own bearer token, is used for their
+ * requests, and is never written down. What is kept is a digest of it, so that
+ * a later request on the same session can be shown to come from the same
+ * holder — a session id on its own is then not enough to drive somebody else's
+ * desktop, which it otherwise would be.
+ */
+export async function runHttp(cfg) {
+    // HTTP does not construct an Api until the first initialize, which made a
+    // bad MANDALA_BASE_URL look like a working bind and then fail that caller
+    // with a generic 500. Validate it before opening the listening socket, using
+    // the same constructor and therefore the same rules as every real session.
+    new Api('startup-validation-only', cfg.baseUrl);
+    const app = express();
+    // parseBody consumes every POST /mcp body. Every other route deliberately
+    // ignores request bodies, so put those requests in flowing mode immediately:
+    // leaving bytes unread can strand a keep-alive connection behind one wrong
+    // path or a GET/DELETE client that sent a body anyway.
+    app.use((req, _res, next) => {
+        if (req.method !== 'POST' || req.path !== '/mcp')
+            req.resume();
+        next();
+    });
+    const sessions = new Map();
+    // The port sessions are actually reachable on, which is not cfg.port when the
+    // operator asked for 0. Read when a transport is built rather than captured
+    // at construction, because the default Host allowlist below carries it and a
+    // list naming port 0 would match nothing a client could ever send.
+    let boundPort = cfg.port;
+    const ttl = cfg.sessionTtlMs ?? DEFAULT_TTL_MS;
+    const maxSessions = cfg.maxSessions ?? DEFAULT_MAX_SESSIONS;
+    const maxLargeBodyParses = cfg.maxLargeBodyParses ?? DEFAULT_MAX_LARGE_BODY_PARSES;
+    let largeBodyParses = 0;
+    // Tool callbacks inherit the request's lease even when a disconnected
+    // response lets transport.handleRequest() settle before the callback does.
+    const requestBodyLease = new AsyncLocalStorage();
+    // Initializes that have passed the cap check but have not yet reached
+    // `onsessioninitialized`. Counted, because the check and the map write are
+    // two awaits apart: without a reservation every concurrent initialize reads
+    // the same `sessions.size`, all of them pass, and the cap bounds nothing —
+    // which is the exact memory exhaustion it was put here to stop.
+    let pending = 0;
+    // Two parsers, chosen by whether this server has already checked who is
+    // asking.
+    //
+    // `express.json` buffers and parses the whole body before any route runs, so
+    // mounted globally at 80mb it spent that on a caller who had sent no key —
+    // free to send, expensive to serve, and nothing about it needed a
+    // credential. The large limit is what `write_file` needs, and `write_file`
+    // always arrives on an established session, so it is given to exactly that:
+    // a request naming a live session whose key digest matches the bearer it
+    // carried, which is the same test the POST route applies before doing
+    // anything. Everyone else — including an initialize, which is a few hundred
+    // bytes — gets the small one and a 413. Large parses are capped separately:
+    // initialize does not contact the platform, so an arbitrary bearer can still
+    // earn a matching digest and must not be able to start hundreds of concurrent
+    // 96 MiB allocations.
+    //
+    // Presence of an `Authorization` header is deliberately not the test. This
+    // server cannot check a `com_…` key without a round trip to the platform, so
+    // a header alone identifies nobody: `Bearer x` would buy the 80mb buffer as
+    // cheaply as sending nothing at all, and the limit would bound only the
+    // callers who had not thought about it. The digest proves continuity with a
+    // session holder, not that the platform accepted the key; the concurrency
+    // cap above is therefore still required.
+    //
+    // Which status a request ends at is unchanged as long as it stays under the
+    // limit, because the body is still parsed: a non-initialize with no session
+    // is still a 400, not a 401 about the key it also did not send.
+    // 96mb rather than 80: the limit exists for write_file, and it could not
+    // carry one. The platform caps a transfer at 64 MiB, base64 is four bytes for
+    // every three, and the JSON-RPC envelope is on top of that — 89,478,488
+    // characters of content against a limit of 83,886,080, so the largest file
+    // this server is documented to write was refused with a 413 by the very
+    // allowance that was raised for it. The real ceiling was about 59 MiB, which
+    // is not a number anybody would have found except by hitting it.
+    const fullBody = express.json({ limit: '96mb' });
+    const smallBody = express.json({ limit: '256kb' });
+    const parseBody = (req, res, next) => {
+        if (!wouldUseLargeParser(req, sessions))
+            return smallBody(req, res, next);
+        if (largeBodyParses >= maxLargeBodyParses) {
+            // Drain before answering so unread request bytes cannot be mistaken for
+            // the next request on a keep-alive connection. A peer that aborts the
+            // upload gets a closed response rather than a misleading reusable one.
+            const cleanup = () => {
+                req.off('end', drained);
+                req.off('aborted', failed);
+                req.off('error', failed);
+            };
+            const drained = () => {
+                cleanup();
+                if (!res.destroyed && !res.headersSent) {
+                    unavailable(res, `This server is already parsing its maximum of ${maxLargeBodyParses} large request bodies. Retry shortly.`);
+                }
+            };
+            const failed = () => {
+                cleanup();
+                res.destroy();
+            };
+            if (req.readableEnded)
+                drained();
+            else {
+                req.once('end', drained);
+                req.once('aborted', failed);
+                req.once('error', failed);
+                req.resume();
+            }
+            return;
+        }
+        largeBodyParses++;
+        let references = 1;
+        const drop = () => {
+            if (references <= 0)
+                return;
+            references--;
+            if (references === 0)
+                largeBodyParses--;
+        };
+        const lease = {
+            retain: () => {
+                if (references <= 0)
+                    return () => { };
+                references++;
+                let held = true;
+                return () => {
+                    if (!held)
+                        return;
+                    held = false;
+                    drop();
+                };
+            },
+            release: drop,
+        };
+        return fullBody(req, res, (err) => {
+            // A failed parse never reaches the route that normally releases this
+            // lease. A successful one keeps it for the route and tool lifetimes:
+            // req.body is the large allocation being bounded, and express.json
+            // finishing does not free it while asynchronous MCP work still uses it.
+            if (err)
+                lease.release();
+            else
+                res.locals.largeBodyLease = lease;
+            next(err);
+        });
+    };
+    const releaseLargeBody = (res) => {
+        const lease = res.locals.largeBodyLease;
+        delete res.locals.largeBodyLease;
+        lease?.release();
+    };
+    // Abandoned sessions are closed rather than left holding a transport. A
+    // client that goes away without a DELETE is the ordinary case, not the odd
+    // one — laptops sleep and tabs close.
+    //
+    // Inspected once a minute, or as often as the TTL if that is shorter — a
+    // sessionTtlMs of ten seconds that was only looked at every sixty is not the
+    // TTL the operator asked for.
+    const sweepMs = Math.min(60_000, Math.max(1_000, ttl));
+    const sweeper = setInterval(() => {
+        const cutoff = Date.now() - ttl;
+        for (const [id, live] of sessions) {
+            // Idle means nothing arriving AND nothing in flight. `lastSeen` is
+            // stamped when a request begins and again when it ends, so a single call
+            // that outlives the TTL — run_agent is minutes of clicking, and
+            // wait_for_computer takes a timeout_s of up to 900 — would otherwise be
+            // swept while it was still being served, closing the transport under an
+            // answer the caller had not received yet.
+            if (live.active === 0 && live.lastSeen < cutoff) {
+                sessions.delete(id);
+                void live.transport.close().catch(() => { });
+            }
+        }
+    }, sweepMs);
+    sweeper.unref();
+    /**
+     * Hold a session open for as long as one request is being served on it.
+     *
+     * Only for request/response traffic. The standing server-to-client stream is
+     * deliberately not counted: a conforming client opens `GET /mcp` once and
+     * holds it for the whole session, so counting it would make `active` never
+     * reach zero and no session would ever be swept — and the case the sweeper
+     * exists for, a laptop that slept and left the socket half-open, is exactly
+     * the one where `close` never fires to undo the count. The transport and its
+     * fully-registered server would sit on a `maxSessions` slot forever.
+     */
+    const beginActivity = (live) => {
+        live.active++;
+        live.lastSeen = Date.now();
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            live.active--;
+            live.lastSeen = Date.now();
+        };
+    };
+    const serving = async (live, handle) => {
+        const release = beginActivity(live);
+        try {
+            return await handle();
+        }
+        finally {
+            // The socket may close while the tool keeps running. Releasing on
+            // Response.close made the session look idle at that point, so a short
+            // TTL could sweep and close its transport underneath handleRequest.
+            // The work itself is the lifetime that matters.
+            release();
+        }
+    };
+    /** Stamp a session as heard from, without claiming anything is in flight. */
+    const touch = (live, res) => {
+        live.lastSeen = Date.now();
+        res.on('close', () => {
+            live.lastSeen = Date.now();
+        });
+    };
+    /**
+     * The Host headers a legitimate client sends, when nobody configured a list.
+     *
+     * A loopback bind is reached as `127.0.0.1:port`, `localhost:port` or
+     * `[::1]:port` depending on what was typed, and all three are this server; a
+     * name resolved to 127.0.0.1 by a page the user is visiting is not, and is
+     * exactly what the check exists to turn away.
+     *
+     * A non-loopback bind gets no default. The operator deliberately exposed this
+     * server and there is no way to guess the names it is legitimately reached
+     * by — inventing a list would break the deployment rather than protect it —
+     * so protection there stays opt-in, and startup says so.
+     */
+    function allowedHosts(portNow) {
+        // Lowercased to match the folded header — an operator who writes
+        // `Example.COM` means the same host the client sends as `example.com`.
+        //
+        // Expanded with and without the bound port, exactly as the loopback default
+        // below is, and for the same reason: the SDK's check is a whole-header
+        // `allowedHosts.includes(hostHeader)`, and a browser sends the port whenever
+        // it is not the scheme's default. An operator writing the obvious
+        // `MANDALA_ALLOWED_HOSTS=mcp.example.com` for a server bound on :3000 got a
+        // list that matched no header any direct client sends, so every request was
+        // answered 403 by the protection they had just turned on. See
+        // {@link hostSpellings} for which entries are expanded and which are not.
+        if (cfg.allowedHosts?.length) {
+            return [
+                ...new Set(cfg.allowedHosts.map((h) => h.toLowerCase()).flatMap((h) => hostSpellings(h, portNow))),
+            ];
+        }
+        if (!isLoopbackHost(cfg.host))
+            return undefined;
+        // `cfg.host` goes in as the spellings a client SENDS, which for a v6
+        // literal means bracketed. Widening isLoopbackHost to accept
+        // `::ffff:127.0.0.1` would otherwise have handed that bind a default
+        // allowlist naming only the bare form — so a client using the address it
+        // was given, `http://[::ffff:127.0.0.1]:port`, would be 403'd by
+        // protection that had not existed there before.
+        const bare = cfg.host.toLowerCase();
+        const own = bare.startsWith('[') || !bare.includes(':') ? [bare] : [`[${bare}]`];
+        const names = new Set(['127.0.0.1', 'localhost', '[::1]', ...own]);
+        return [...names].flatMap((h) => [`${h}:${portNow}`, h]);
+    }
+    const allowedOrigins = cfg.allowedOrigins?.map((origin) => origin.toLowerCase());
+    // Host names are case-insensitive, and the SDK's rebinding check is not: it
+    // is a plain `allowedHosts.includes(hostHeader)` against the header as sent,
+    // so a conformant client that says `Host: LOCALHOST:3000` is answered 403 by
+    // a list that contains `localhost:3000`. Nothing above can fix that from
+    // outside the SDK, but the header can be normalised to the one spelling the
+    // list is written in before it gets there. Safe to fold: RFC 3986 says the
+    // host is case-insensitive, and `new URL()` already lowercases it, which is
+    // why browsers and fetch never trip this and a hand-set header does.
+    //
+    // Folded in `rawHeaders`, not just `req.headers`. The transport is a wrapper
+    // over @hono/node-server, which rebuilds the web Request from
+    // `incoming.rawHeaders` and never looks at the parsed object Express hands
+    // around — so normalising only the latter changes nothing the check can see.
+    app.use((req, _res, next) => {
+        const raw = req.rawHeaders;
+        for (let i = 0; i < raw.length; i += 2) {
+            const name = raw[i].toLowerCase();
+            if (name === 'host' || name === 'origin')
+                raw[i + 1] = raw[i + 1].toLowerCase();
+        }
+        if (req.headers.host)
+            req.headers.host = req.headers.host.toLowerCase();
+        if (req.headers.origin)
+            req.headers.origin = req.headers.origin.toLowerCase();
+        next();
+    });
+    // Liveness is public; OCCUPANCY is not.
+    //
+    // `sessions` and `largeBodyParses` are the two caps this process enforces,
+    // and their current values are the two numbers somebody would want in order
+    // to time an exhaustion of either — how close the table is to 256, and
+    // whether all four parse slots are taken right now. Unauthenticated, on an
+    // exposed bind, that is a capacity oracle handed over on request.
+    //
+    // Kept where they are useful and cannot be read from outside: a loopback
+    // bind, where the only readers are on this machine, and an operator who has
+    // configured a Host allowlist, which is the deliberate act that says who may
+    // reach this server at all. Everywhere else the endpoint still answers, still
+    // says the server is alive, and simply does not count out loud.
+    const countsArePrivate = isLoopbackHost(cfg.host) || Boolean(cfg.allowedHosts?.length);
+    app.get('/healthz', (_req, res) => {
+        res.json({
+            ok: true,
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+            ...(countsArePrivate ? { sessions: sessions.size, largeBodyParses } : {}),
+        });
+    });
+    app.post('/mcp', parseBody, async (req, res) => {
+        const sessionId = req.header('mcp-session-id');
+        const key = bearer(req);
+        if (sessionId) {
+            try {
+                const live = sessions.get(sessionId);
+                if (!live)
+                    return notFound(res, 'Unknown session. Initialize a new one.', rpcId(req));
+                // The key is re-checked on every request, not only at initialize. A
+                // session id travels in a plain header and is the sort of thing that ends
+                // up in a proxy log; on its own it must not be a credential.
+                if (!key || !sameKey(live.keyDigest, key)) {
+                    return unauthorized(res, 'This session belongs to a different API key.', rpcId(req));
+                }
+                const lease = res.locals.largeBodyLease;
+                return await requestBodyLease.run(lease, () => serving(live, () => live.transport.handleRequest(req, res, req.body)));
+            }
+            finally {
+                // A verified session is the only request allowed through the large
+                // parser. Release the route's ownership here; a tool callback that
+                // outlives handleRequest retains its own reference through activity().
+                releaseLargeBody(res);
+            }
+        }
+        // Sessionless requests always use the small parser. This no-op keeps the
+        // ownership explicit if the parser policy changes later.
+        releaseLargeBody(res);
+        if (!isInitializeRequest(req.body)) {
+            return badRequest(res, 'No session id, and this is not an initialize request.', rpcId(req));
+        }
+        if (!key) {
+            return unauthorized(res, 'Send your Mandala API key as a bearer token: Authorization: Bearer com_…', rpcId(req));
+        }
+        // Host/Origin are already decided, and constructing the McpServer is the
+        // expensive part of an initialize. Checked here so a DNS-rebinding POST
+        // never pays that cost, never takes a pending slot, and is 403 even when
+        // the session cap is full — occupancy is not the answer to a Host the
+        // operator never served (adversarial review, OPL-4314).
+        const hosts = allowedHosts(boundPort);
+        const refused = dnsRebindingRefusal(req, hosts, allowedOrigins);
+        if (refused)
+            return rpcError(res, 403, -32000, refused);
+        // Swept sessions free their slot on the timer; this is the backstop for the
+        // case the timer cannot help with, which is arrivals faster than the TTL.
+        if (sessions.size + pending >= maxSessions) {
+            return unavailable(res, `This server is holding its maximum of ${maxSessions} sessions. Retry shortly.`, rpcId(req));
+        }
+        pending++;
+        // Released exactly once, whether the initialize lands in the map or throws
+        // on the way there. A reservation that leaked on the failure path would
+        // ratchet the cap down until the process restarted — every later initialize
+        // refused with 503 for the life of the process, which is the denial of
+        // service the counter was added to prevent, self-inflicted.
+        let reserved = true;
+        const release = () => {
+            if (reserved) {
+                reserved = false;
+                pending--;
+            }
+        };
+        // Everything from here to the map write is inside the reservation,
+        // constructors included: they are ordinary code that can throw, and Express
+        // turning that into a 500 is precisely the path that used to leak.
+        //
+        // `transport` is declared out here so the catch can reach it: the session
+        // is written to the map from inside handleRequest, so a throw after that
+        // point has something to clean up.
+        let transport;
+        let mcp;
+        let finishInitialize = () => { };
+        try {
+            const t = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                // On whenever there is a list to check against, which for a loopback
+                // bind is always — see `allowedHosts`. A browser cannot be stopped from
+                // resolving a name it controls to 127.0.0.1, so the Host header is the
+                // only thing separating the operator's own client from a page the user
+                // happened to open, and the MCP spec asks a locally-bound server to
+                // check it.
+                enableDnsRebindingProtection: Boolean(hosts?.length || allowedOrigins?.length),
+                allowedHosts: hosts,
+                allowedOrigins,
+                onsessioninitialized: (id) => {
+                    const live = {
+                        transport: t,
+                        keyDigest: digest(key),
+                        lastSeen: Date.now(),
+                        // Initialize is already in flight when the session first becomes
+                        // visible to the sweeper. Count it until handleRequest settles.
+                        active: 1,
+                    };
+                    sessions.set(id, live);
+                    let held = true;
+                    finishInitialize = () => {
+                        if (!held)
+                            return;
+                        held = false;
+                        live.active--;
+                        live.lastSeen = Date.now();
+                    };
+                    release();
+                },
+                onsessionclosed: (id) => {
+                    sessions.delete(id);
+                },
+            });
+            transport = t;
+            t.onclose = () => {
+                if (t.sessionId)
+                    sessions.delete(t.sessionId);
+            };
+            const server = createServer({
+                ...cfg,
+                apiKey: key,
+                activity: () => {
+                    const id = t.sessionId;
+                    const live = id ? sessions.get(id) : undefined;
+                    const finishActivity = live ? beginActivity(live) : () => { };
+                    const finishBody = requestBodyLease.getStore()?.retain();
+                    return () => {
+                        finishBody?.();
+                        finishActivity();
+                    };
+                },
+                // Per-caller, and deliberately with no fallback to cfg.modelKey: an
+                // operator who set MANDALA_MODEL_KEY for their own stdio use would
+                // otherwise be billed for every stranger's run here. Absent means
+                // run_agent is simply not offered to this session.
+                modelKey: req.header(MODEL_KEY_HEADER)?.trim() || undefined,
+                // Dropped for the same reason, one field further on. MANDALA_COMPUTER_ID
+                // is the operator's own machine, and spreading it into a stranger's
+                // session pre-binds their key to a computer on somebody else's account:
+                // every call until they run use_computer 404s, and the id of a machine
+                // that is not theirs is named back to them by way of explanation.
+                computerId: undefined,
+            });
+            mcp = server;
+            await server.connect(t);
+            const handled = await t.handleRequest(req, res, req.body);
+            // Any initialize that never reached `onsessioninitialized` has no map
+            // slot and nothing the sweeper will reap. The SDK's 403 used to take
+            // this path without throwing; other early returns still can.
+            if (!t.sessionId) {
+                void server.close().catch(() => { });
+                void t.close().catch(() => { });
+            }
+            return handled;
+        }
+        catch (err) {
+            // `onsessioninitialized` fires from inside handleRequest, so by the time
+            // anything past it throws the session is already in the map — holding a
+            // maxSessions slot and a key digest, under an id the client never learned
+            // and so can never DELETE. Left alone it sits there until the TTL sweep
+            // half an hour later, and enough of them ratchet the cap to zero.
+            if (transport?.sessionId)
+                sessions.delete(transport.sessionId);
+            if (mcp)
+                void mcp.close().catch(() => { });
+            else if (transport)
+                void transport.close().catch(() => { });
+            throw err;
+        }
+        finally {
+            finishInitialize();
+            release();
+        }
+    });
+    // The server-to-client stream, and session teardown. Both are addressed by
+    // session id alone in the protocol, so both re-check the key for the reason
+    // the POST does.
+    const bySession = async (req, res) => {
+        const sessionId = req.header('mcp-session-id');
+        const live = sessionId ? sessions.get(sessionId) : undefined;
+        if (!live)
+            return notFound(res, 'Unknown session.');
+        const key = bearer(req);
+        if (!key || !sameKey(live.keyDigest, key)) {
+            return unauthorized(res, 'This session belongs to a different API key.');
+        }
+        // The DELETE is a request and is held for; the GET is the notification
+        // stream and is only noted. See `serving`.
+        if (req.method === 'GET') {
+            touch(live, res);
+            return live.transport.handleRequest(req, res);
+        }
+        return serving(live, () => live.transport.handleRequest(req, res));
+    };
+    app.get('/mcp', bySession);
+    app.delete('/mcp', bySession);
+    // Express's default 404 is HTML. Keep every answer from this MCP-facing
+    // server in the JSON-RPC shape its clients can surface, even when the path
+    // itself was wrong.
+    app.use((req, res) => notFound(res, `Unknown path: ${req.method} ${req.path}. Use /mcp or /healthz.`, rpcId(req)));
+    // The last word on anything that threw, because Express's own last word is
+    // an HTML page.
+    //
+    // `finalhandler` renders the error — message, and outside NODE_ENV=production
+    // the whole stack, absolute paths and all — into the response body. Two
+    // things reach it here. A body-parser refusal is one: `express.json` throws
+    // `entity.too.large` past the limit and `entity.parse.failed` on malformed
+    // JSON, and neither is caught by a route, because neither ever reaches one.
+    // Anything a handler throws is the other. Both used to leave an MCP client
+    // holding markup it has no way to report to its user, and the too-large case
+    // in particular is now reachable by anyone who can open a socket, since the
+    // small limit is what an unidentified caller gets.
+    //
+    // Body-parser failures are answered with their own status and message: they
+    // describe the request the sender just made, and knowing it was too large or
+    // malformed is what lets them fix it. Everything else is a bug in this
+    // server, so it is logged here and the sender is told only that it happened
+    // — the stack is for the operator's terminal, not for the wire.
+    app.use((err, _req, res, next) => {
+        // Streaming answers are the ordinary case on /mcp, and once bytes are out
+        // the status line is long gone. Express's handler is the only thing that
+        // can destroy the socket at that point; ours would append JSON to an SSE
+        // stream.
+        if (res.headersSent)
+            return next(err);
+        const e = err;
+        // `type` is body-parser's marker, and its errors carry a status of their
+        // own. Anything else with a status did not come from parsing a body.
+        if (typeof e?.type === 'string' && typeof e.status === 'number') {
+            const message = e.type === 'entity.too.large'
+                ? tooLargeMessage(_req, sessions)
+                : typeof e.message === 'string'
+                    ? e.message
+                    : 'This request body could not be read.';
+            return rpcError(res, e.status, -32000, message, rpcId(_req));
+        }
+        console.error('mandala-computer-mcp: unhandled error serving a request', err);
+        return rpcError(res, 500, -32603, 'This server failed while serving the request.', rpcId(_req));
+    });
+    return new Promise((resolve, reject) => {
+        let listening = false;
+        const http = app.listen(cfg.port, cfg.host, () => {
+            listening = true;
+            // The bound port, not the requested one. `port()` deliberately accepts 0,
+            // which means "any free port" — and printing it back gives the operator
+            // http://127.0.0.1:0/mcp, a URL that cannot be used to reach the server
+            // they were just told was up.
+            const addr = http.address();
+            const bound = typeof addr === 'object' && addr ? addr.port : cfg.port;
+            boundPort = bound;
+            console.error(`mandala-computer-mcp on http://${cfg.host}:${bound}/mcp — callers authenticate with their own Mandala API key`);
+            // Said once, at the only moment anybody is reading. A bind that is not
+            // loopback cannot have its legitimate Host values guessed, so the check
+            // is off and the operator is the only one who can turn it on — and an
+            // exposed server with no Host check is reachable by any page that
+            // resolves its own name to this address.
+            if (!allowedHosts(bound)) {
+                console.error(`  no Host allowlist for ${cfg.host} — set MANDALA_ALLOWED_HOSTS to the name(s) this is served under to enable DNS-rebinding protection`);
+            }
+            else if (!cfg.allowedHosts?.length) {
+                // The other half of the same sentence, and the one that costs an
+                // operator a working install if it goes unsaid. A loopback bind gets a
+                // Host allowlist by default, which is right for the local case and
+                // wrong for the very common one where this sits behind nginx, Caddy or
+                // cloudflared: the proxy forwards `Host: mcp.example.com`, the check
+                // refuses it, and every request 403s with nothing in the log to say
+                // which header was the problem. Named here so the fix is one line
+                // rather than an afternoon.
+                console.error(`  answering only to Host: 127.0.0.1, localhost or [::1] (with or without :${bound}) — set MANDALA_ALLOWED_HOSTS if this is served under a name, e.g. behind a proxy`);
+            }
+            resolve(http);
+        });
+        // Without a listener, an 'error' event is rethrown as an uncaught
+        // exception — a stack trace for EADDRINUSE, the most ordinary operational
+        // failure there is, and a promise that never settles. Rejecting instead
+        // lets main()'s catch print the one sentence.
+        //
+        // Only while the bind is still pending, though. A server that is already
+        // up emits 'error' for things it goes on serving through, and tearing down
+        // the sweeper there would leave the session cap with nothing to reap
+        // against — every later caller refused, for a connection error minutes
+        // earlier that the reject could no longer report anyway.
+        http.on('error', (err) => {
+            if (listening) {
+                // Not rejected and not torn down, for the reasons above — but not
+                // discarded either. EMFILE on accept leaves a server that refuses every
+                // connection with nothing anywhere saying why, and the operator's only
+                // other clue is silence. Logged where the unhandled-error path already
+                // logs, so there is one place to look.
+                console.error('mandala-computer-mcp: server error after bind —', err);
+                return;
+            }
+            clearInterval(sweeper);
+            reject(err);
+        });
+        // Closing the server has to take the sessions with it, and has to do it on
+        // the way in. `close()` stops new connections and then waits for the ones
+        // already in flight, so a session holding an open server-to-client stream
+        // keeps it from ever completing — an embedding host that shuts this down
+        // would hang rather than exit. Doing this in the 'close' event instead
+        // would be too late by definition: that event cannot fire until the
+        // streams this needs to end are already gone.
+        const teardown = () => {
+            clearInterval(sweeper);
+            for (const live of sessions.values())
+                void live.transport.close().catch(() => { });
+            sessions.clear();
+        };
+        const closeServer = http.close.bind(http);
+        http.close = ((cb) => {
+            teardown();
+            return closeServer(cb);
+        });
+        http.on('close', teardown);
+    });
+}
+/**
+ * Whether this request is allowed through the 96mb parser.
+ *
+ * Shared with the 413 handler so a verified session that actually hit that
+ * ceiling is not told to initialize for 256KB.
+ */
+function wouldUseLargeParser(req, sessions) {
+    const id = req.header('mcp-session-id');
+    const live = id ? sessions.get(id) : undefined;
+    const key = bearer(req);
+    const verified = Boolean(live && key && sameKey(live.keyDigest, key));
+    const rawLength = req.header('content-length');
+    const mayBeLarge = rawLength === undefined || !/^\d+$/.test(rawLength) || Number(rawLength) > SMALL_BODY_BYTES;
+    return verified && mayBeLarge;
+}
+function tooLargeMessage(req, sessions) {
+    return wouldUseLargeParser(req, sessions)
+        ? 'Request body is too large. This established session accepts at most 96MB.'
+        : 'Request body is too large. Bodies above 256KB are accepted only on an established session, by a caller whose key matches it — initialize first, then send this there.';
+}
+function bearer(req) {
+    const auth = req.header('authorization') ?? '';
+    // RFC 7235 §2.1 makes the scheme case-insensitive, and a client that sends
+    // `bearer com_…` is sending a well-formed credential. Matching only the
+    // capitalised spelling answers it with a 401 whose message tells it to do
+    // the thing it just did.
+    const m = /^bearer[ \t]+/i.exec(auth);
+    return m ? auth.slice(m[0].length).trim() || undefined : undefined;
+}
+const digest = (key) => createHash('sha256').update(key).digest();
+/** Constant-time, because this comparison decides whether a session is yours. */
+function sameKey(expected, candidate) {
+    const actual = digest(candidate);
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+function rpcId(req) {
+    const id = req.body?.id;
+    return typeof id === 'string' || typeof id === 'number' || id === null ? id : null;
+}
+const rpcError = (res, status, code, message, id = null) => {
+    res.status(status).json({ jsonrpc: '2.0', error: { code, message }, id });
+};
+const badRequest = (res, m, id = null) => rpcError(res, 400, -32000, m, id);
+const unauthorized = (res, m, id = null) => rpcError(res, 401, -32001, m, id);
+const notFound = (res, m, id = null) => rpcError(res, 404, -32001, m, id);
+const unavailable = (res, m, id = null) => rpcError(res, 503, -32002, m, id);
+//# sourceMappingURL=http.js.map