tinyfish-mcp-lite 0.0.0-stage → 0.1.0

package/dist/core/upstream.js

@@ -0,0 +1,178 @@
+/**
+ * Single fetch call site for the upstream MCP endpoint.
+ *
+ * POSTs one JSON-RPC message per call with the auth + attribution headers and
+ * classifies the response by HTTP status and content type only — it never
+ * inspects methods, tool names, or result schemas. The upstream HTTP status is
+ * preserved on every variant so the transport adapter can pass it through
+ * (the hosted server answers JSON-RPC client errors as 400, server errors as
+ * 500, notifications as 204).
+ *
+ * Web-standard types only (fetch / Response / ReadableStream) — no node:http.
+ */
+import { VERSION } from "../version.js";
+import { isAbortError, UpstreamAbortedError, UpstreamAuthError, UpstreamProtocolError, UpstreamUnreachableError, } from "./errors.js";
+export class UpstreamClient {
+    url;
+    apiKey;
+    clientVersion;
+    fetchFn;
+    constructor(options) {
+        this.url = options.url;
+        this.apiKey = options.apiKey;
+        this.clientVersion = options.clientVersion ?? VERSION;
+        this.fetchFn = options.fetchFn ?? globalThis.fetch;
+    }
+    /** POST one JSON-RPC message upstream and classify the response. */
+    async post(message, options = {}) {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "X-API-Key": this.apiKey,
+            "X-TF-Request-Origin": "tinyfish-mcp",
+            "X-TF-Client-Name": "tinyfish-mcp",
+            "X-TF-Client-Version": this.clientVersion,
+        };
+        if (options.sessionId !== undefined && options.sessionId !== "") {
+            headers["Mcp-Session-Id"] = options.sessionId;
+        }
+        if (options.protocolVersion !== undefined && options.protocolVersion !== "") {
+            headers["MCP-Protocol-Version"] = options.protocolVersion;
+        }
+        let response;
+        try {
+            response = await this.fetchFn(this.url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(message),
+                signal: options.signal,
+            });
+        }
+        catch (err) {
+            throw toTransportError(err, this.url);
+        }
+        const status = response.status;
+        const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+        if (status === 204 || status === 205) {
+            return { kind: "empty", status };
+        }
+        if (contentType.startsWith("text/event-stream")) {
+            if (response.body === null) {
+                throw new UpstreamProtocolError("Upstream SSE response has no body", status);
+            }
+            return { kind: "sse", status, stream: response.body };
+        }
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (err) {
+            throw toTransportError(err, this.url);
+        }
+        if (text.length === 0) {
+            // A body-less 401/403 (e.g. a gateway/LB that strips bodies) is still an
+            // auth rejection — classify it BEFORE the generic empty return so the
+            // client gets the check-your-TINYFISH_API_KEY error, not a protocol one.
+            if (status === 401 || status === 403) {
+                throw new UpstreamAuthError(status, "");
+            }
+            return { kind: "empty", status };
+        }
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch (err) {
+            // A 401/403 whose body is not JSON at all is an auth rejection
+            // from an intermediary or a non-MCP error page — classified so the
+            // adapter can shape the check-your-TINYFISH_API_KEY error. Any other
+            // status with a non-JSON body stays a protocol violation.
+            if (status === 401 || status === 403) {
+                throw new UpstreamAuthError(status, text, { cause: err });
+            }
+            throw new UpstreamProtocolError(`Upstream returned non-JSON body (HTTP ${status}, content-type "${contentType}")`, status, { cause: err });
+        }
+        // A 401/403 with a JSON body that is NOT a JSON-RPC message (e.g.
+        // {"error":"unauthorized"}) is also an auth rejection — only a genuine
+        // JSON-RPC error body forwards verbatim, preserving upstream's HTTP
+        // status.
+        if ((status === 401 || status === 403) && !isJsonRpcMessage(body)) {
+            throw new UpstreamAuthError(status, text);
+        }
+        return {
+            kind: "json",
+            status,
+            sessionId: response.headers.get("mcp-session-id"),
+            body,
+            contentType: response.headers.get("content-type"),
+        };
+    }
+}
+/**
+ * A parsed body that is a JSON-RPC 2.0 message (forwardable verbatim): the
+ * version marker plus at least one of the members every JSON-RPC message
+ * carries (`result`/`error` for responses, `method` for requests and
+ * notifications). Quasi-JSON-RPC junk like {"jsonrpc":"2.0","message":"no"}
+ * fails the gate, so at 401/403 it shapes as the -32001 auth error instead of
+ * forwarding.
+ *
+ * BATCH ARRAYS are deliberately outside this gate: MCP forbids JSON-RPC
+ * batching and upstream does not support it, so a 401/403 whose body is a
+ * batch(-error) array shapes as -32001 with the raw body preserved in
+ * `data.upstreamBody` rather than forwarding verbatim.
+ */
+function isJsonRpcMessage(body) {
+    return (typeof body === "object" &&
+        body !== null &&
+        !Array.isArray(body) &&
+        body.jsonrpc === "2.0" &&
+        ("error" in body || "result" in body || "method" in body));
+}
+/**
+ * Map a fetch/stream failure to a typed transport error. Never includes the
+ * key. When `url` is given (the fetch call site knows it), the upstream host
+ * is attached so the error shaping can name it in the client-facing message.
+ */
+export function toTransportError(err, url) {
+    if (isAbortError(err)) {
+        return new UpstreamAbortedError("Upstream request aborted", { cause: err });
+    }
+    // Undici wraps network failures as "TypeError: fetch failed" with the real
+    // error (ECONNREFUSED, ENOTFOUND, TLS) on err.cause — surface that detail.
+    let detail = err instanceof Error ? err.message : String(err);
+    const cause = causeDetail(err);
+    if (cause !== undefined) {
+        detail += ` (${cause})`;
+    }
+    const error = new UpstreamUnreachableError(`Upstream unreachable: ${detail}`, { cause: err });
+    if (url !== undefined) {
+        try {
+            error.host = new URL(url).host;
+        }
+        catch {
+            // Malformed URL: leave host unset; the shaping falls back to a generic name.
+        }
+    }
+    return error;
+}
+/** Extract the errno code (or message) from an error's cause chain, if any. */
+function causeDetail(err) {
+    if (typeof err !== "object" || err === null || !("cause" in err))
+        return undefined;
+    const cause = err.cause;
+    if (typeof cause !== "object" || cause === null)
+        return undefined;
+    const code = cause.code;
+    if (typeof code === "string" && code.length > 0)
+        return code;
+    if (cause instanceof AggregateError) {
+        for (const inner of cause.errors) {
+            const innerCode = inner?.code;
+            if (typeof innerCode === "string" && innerCode.length > 0)
+                return innerCode;
+        }
+    }
+    if (cause instanceof Error && cause.message.length > 0)
+        return cause.message;
+    return undefined;
+}

package/dist/http/adapter.d.ts

@@ -0,0 +1,3 @@
+import { type ProxyCore } from "../core/proxy-core.js";
+import type { RequestHandler } from "./index.js";
+export declare function createMcpAdapter(core: ProxyCore): RequestHandler;

package/dist/http/adapter.js

@@ -0,0 +1,294 @@
+/**
+ * Per-request MCP wiring over the transport-agnostic proxy core.
+ *
+ * Session bridging: the local client re-sends
+ * whatever Mcp-Session-Id upstream issued, so the client-sent header IS the
+ * core localKey. For `initialize` — where no upstream id exists yet — a
+ * locally generated key seeds the session entry, and the core aliases that
+ * entry under the upstream-issued id once the response arrives. `Mcp-Session-Id`
+ * is echoed on JSON responses exactly when upstream echoed it (the core hands
+ * back the echoed value; null on SSE — upstream's SSE path sets no session
+ * header, and neither do we).
+ *
+ * Local-hop auth is server-holds-key: inbound Authorization headers are
+ * ignored — the only client headers that influence the upstream call are
+ * Mcp-Session-Id and MCP-Protocol-Version; the core builds every outbound
+ * header itself.
+ *
+ * Streaming: when upstream answers SSE, frames are relayed through
+ * the core's onEvent into an SSE response using the ORIGINAL `data:` payload
+ * string (byte-verbatim, no re-serialization). Each write is awaited
+ * (backpressure), a local client disconnect aborts the upstream fetch via a
+ * per-request AbortSignal (no orphaned upstream streams), and mid-stream
+ * failures are classified: local write failures are never labeled upstream.
+ */
+import { randomUUID } from "node:crypto";
+import { JsonRpcErrorCodes, LocalWriteError, ProxyCoreError, toJsonRpcError, toStreamErrorFrame, } from "../core/errors.js";
+import { requestIdOf } from "../core/proxy-core.js";
+import { log } from "../log.js";
+export function createMcpAdapter(core) {
+    return async (req, res) => {
+        const sessionId = headerValue(req, "mcp-session-id");
+        const protocolVersion = headerValue(req, "mcp-protocol-version");
+        const raw = await readBody(req);
+        let message;
+        try {
+            message = JSON.parse(raw.toString("utf8"));
+        }
+        catch {
+            // Local ParseError mirroring upstream's shape (client-error codes →
+            // HTTP 400; id -1 when no request id is known). The one case the proxy
+            // answers without forwarding — it cannot route what it cannot parse.
+            sendJson(res, 400, {
+                jsonrpc: "2.0",
+                error: { code: JsonRpcErrorCodes.ParseError, message: "Parse error: Invalid JSON" },
+                id: -1,
+            });
+            return;
+        }
+        try {
+            await route(core, res, message, sessionId, protocolVersion);
+        }
+        catch (err) {
+            // Every failure upstream never answered as JSON-RPC is shaped
+            // through the one function in core/errors.ts. Streamed requests handle
+            // their own mid-stream failures and only rethrow pre-stream ones, so
+            // headers are normally unsent here; the guard covers a write that died
+            // halfway through sending a response.
+            logFailure(err);
+            if (res.headersSent) {
+                res.end();
+                return;
+            }
+            const shaped = toJsonRpcError(err, requestIdOf(message));
+            sendJson(res, shaped.httpStatus, shaped.body);
+        }
+    };
+}
+async function route(core, res, message, sessionId, protocolVersion) {
+    // Notification (has method, no id): forward, answer 204 empty like upstream.
+    if (isNotification(message)) {
+        // localKey "" ⇒ the core sends no Mcp-Session-Id upstream (transparent
+        // for session-less notifications); a real client id replays verbatim.
+        await core.notify(sessionId ?? "", message, protocolVersion);
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const method = methodOf(message);
+    if (method === "initialize") {
+        // No upstream session exists yet: a generated localKey seeds the entry
+        // unless the client is re-initializing with a session id it already
+        // holds. The client-sent id (if any) is passed separately so the core
+        // replays it upstream (upstream adopts client-sent header ids) without
+        // ever sending an adapter-invented key.
+        const localKey = sessionId ?? randomUUID();
+        const response = await core.initialize(localKey, message, protocolVersion, sessionId);
+        sendProxyResponse(res, response);
+        return;
+    }
+    if (method === "tools/call") {
+        await relayPossiblyStreaming(core, sessionId ?? "", message, protocolVersion, res);
+        return;
+    }
+    // Everything else — ping, tools/list, resources/*, unknown methods, and
+    // shapeless bodies — forwards generically; upstream's status and body
+    // (including MethodNotFound / InvalidRequest errors) pass through verbatim.
+    // JSON-RPC BATCH ARRAYS land here too (methodOf/isNotification treat an
+    // array as shapeless): MCP forbids batching and upstream does not support
+    // it, so a batch is not special-cased anywhere — it forwards as-is and
+    // upstream answers its own InvalidRequest. Same story on the response side:
+    // upstream.ts's isJsonRpcMessage gate excludes arrays by design.
+    const response = await core.forward(sessionId ?? "", message, protocolVersion);
+    sendProxyResponse(res, response);
+}
+/**
+ * Log a shaped failure to stderr. Classified core errors log their (key-free)
+ * message; anything else is a local proxy bug and logs its full stack — the
+ * client only ever sees the generic InternalError message.
+ */
+function logFailure(err) {
+    if (err instanceof ProxyCoreError) {
+        log.warn(err.message);
+        return;
+    }
+    log.error(`proxy bug (client got a generic InternalError): ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+}
+/**
+ * tools/call may answer JSON or SSE; the adapter cannot know which until the
+ * core either emits an event (⇒ SSE) or resolves. The SSE response is opened
+ * lazily on the first relayed frame; the resolved final frame is appended and
+ * the stream closed. Each write is awaited (OnEvent may return a promise), so
+ * socket backpressure propagates into the core's frame loop.
+ *
+ * Client-disconnect abort: if the local socket closes before the response is
+ * finished ('close' with writableEnded false — 'close' alone also fires on
+ * normal completion), the per-request AbortSignal fires and the core aborts
+ * the upstream fetch. That surfaces as an UpstreamAbortedError rejection,
+ * absorbed here as an ordinary disconnect (nobody is left to answer).
+ *
+ * Note: an SSE stream that carried ONLY the final frame still relays as a
+ * plain JSON response (streaming never turned true). Real upstream always
+ * emits progress first; if it ever mattered, the final frame's rawBody is the
+ * verbatim payload either way.
+ */
+async function relayPossiblyStreaming(core, localKey, message, protocolVersion, res) {
+    let streaming = false;
+    // Last _meta.runId seen in a relayed progress frame — upstream names the
+    // run there so a mid-stream failure can hand the client a recovery handle.
+    let lastRunId;
+    const clientAbort = new AbortController();
+    const onClose = () => {
+        if (!res.writableEnded)
+            clientAbort.abort();
+    };
+    res.on("close", onClose);
+    const onEvent = async (event, rawData) => {
+        if (!streaming) {
+            streaming = true;
+            // Mirror upstream's SSE headers. Deliberately no Mcp-Session-Id:
+            // upstream's SSE path never sets one.
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache, no-transform",
+                Connection: "keep-alive",
+            });
+        }
+        lastRunId = runIdOf(event) ?? lastRunId;
+        await writeSseFrame(res, event, rawData);
+    };
+    try {
+        const response = await core.forwardStream(localKey, message, onEvent, protocolVersion, clientAbort.signal);
+        if (streaming) {
+            try {
+                await writeSseFrame(res, response.body, response.rawBody);
+            }
+            catch (err) {
+                // A final-frame write failure is a LOCAL socket condition, exactly
+                // like a progress-frame write failure inside onEvent — classify it the
+                // same way so it can never be mislabeled as an upstream stream failure.
+                throw new LocalWriteError(`Relaying the final SSE frame to the local client failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            res.end();
+            return;
+        }
+        // Plain JSON answer: written with upstream's status, body verbatim.
+        sendProxyResponse(res, response);
+    }
+    catch (err) {
+        if (clientAbort.signal.aborted) {
+            // The local client went away; the upstream fetch was aborted through the
+            // per-request signal. Not an upstream failure — log it as what it is.
+            log.warn("local client disconnected mid-tools/call; upstream request aborted");
+            res.destroy();
+            return;
+        }
+        if (err instanceof LocalWriteError) {
+            // Writing to the local client socket failed (client dying but 'close'
+            // not yet observed). Teardown already happened in the core (the throw
+            // exits the frame loop, canceling the upstream stream). Never labeled
+            // "Upstream unreachable".
+            log.warn(err.message);
+            res.destroy();
+            return;
+        }
+        if (streaming) {
+            // The stream broke after the local SSE response already started. Emit
+            // the final SSE-framed JSON-RPC error (-32000, "the run may still be
+            // executing", runId in data when seen) — never an unframed body into a
+            // started SSE stream. The log prefix names the actual culprit: a
+            // classified core error is an upstream-leg failure; anything else is a
+            // LOCAL proxy bug and must not be logged with an upstream-blaming label.
+            if (err instanceof ProxyCoreError) {
+                log.error(`upstream stream failed mid-relay: ${err.message}`);
+            }
+            else {
+                log.error(`proxy bug mid-stream (client got a framed InternalError): ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+            }
+            const errorFrame = toStreamErrorFrame(err, requestIdOf(message), lastRunId);
+            await writeSseFrame(res, errorFrame).catch(() => undefined);
+            res.end();
+            return;
+        }
+        // Pre-stream failures (headers not sent) rethrow to the shaping catch in
+        // the handler (toJsonRpcError → -32000/-32001/-32603 with an HTTP status).
+        throw err;
+    }
+    finally {
+        res.removeListener("close", onClose);
+    }
+}
+/** Extract `params._meta.runId` from a relayed progress notification, if present. */
+function runIdOf(event) {
+    if (typeof event !== "object" || event === null)
+        return undefined;
+    const params = event.params;
+    if (typeof params !== "object" || params === null)
+        return undefined;
+    const meta = params._meta;
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    const runId = meta.runId;
+    return typeof runId === "string" && runId.length > 0 ? runId : undefined;
+}
+/** Write upstream's status + JSON-RPC body verbatim; echo the session header. */
+function sendProxyResponse(res, response) {
+    // Copy upstream's Content-Type through; fall back for
+    // locally synthesized responses (e.g. an SSE final frame answered as JSON).
+    const headers = {
+        "Content-Type": response.contentType ?? "application/json",
+    };
+    if (response.sessionId !== null) {
+        headers["Mcp-Session-Id"] = response.sessionId;
+    }
+    sendJson(res, response.status, response.body, headers);
+}
+function sendJson(res, status, body, headers = { "Content-Type": "application/json" }) {
+    res.writeHead(status, headers);
+    res.end(JSON.stringify(body));
+}
+/**
+ * One SSE frame; resolves when the chunk is flushed. Relays the ORIGINAL
+ * upstream payload string when available (byte-verbatim);
+ * falls back to JSON.stringify for locally synthesized frames. A payload
+ * containing newlines (multi-line `data:` field) is re-split into one
+ * `data:` line per payload line, which reconstructs to identical bytes on the
+ * receiving parser.
+ */
+function writeSseFrame(res, message, rawData) {
+    const payload = rawData ?? JSON.stringify(message);
+    const frame = payload
+        .split("\n")
+        .map((line) => `data: ${line}`)
+        .join("\n");
+    return new Promise((resolve, reject) => {
+        res.write(`${frame}\n\n`, (err) => (err ? reject(err) : resolve()));
+    });
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/** Node folds duplicate headers into one comma-joined string; empty ⇒ absent. */
+function headerValue(req, name) {
+    const value = req.headers[name];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** JSON-RPC notification: an object with a method and no id key (upstream's rule). */
+function isNotification(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        !Array.isArray(message) &&
+        typeof message.method === "string" &&
+        !("id" in message));
+}
+function methodOf(message) {
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    const method = message.method;
+    return typeof method === "string" ? method : undefined;
+}

package/dist/http/index.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+/**
+ * Request handler contract for the HTTP layer. Handlers may be async: the
+ * server awaits the returned promise and converts a rejection into a 500
+ * JSON-RPC InternalError response (or just ends the response when headers are
+ * already out, e.g. mid-SSE), so async failures are never silently swallowed.
+ */
+export type RequestHandler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+/**
+ * Routing shell around the MCP adapter:
+ * - Origin allowlist first, before the body is touched: deny → 403 plain text.
+ * - GET /healthz → 200 "ok" (client debugging; kept trivial).
+ * - POST /mcp → the MCP handler; other methods on /mcp → 405 with Allow: POST
+ *   (mirrors upstream, where Next.js 405s methods the route does not export).
+ * - Everything else → 404.
+ */
+export declare function createAppHandler(mcpHandler: RequestHandler): RequestHandler;
+/**
+ * Starts an HTTP server bound to 127.0.0.1 (loopback only, never configurable).
+ * Resolves once listening; rejects with the bind error (e.g. EADDRINUSE) otherwise.
+ */
+export declare function startHttpServer(port: number, handler?: RequestHandler): Promise<Server>;

package/dist/http/index.js

@@ -0,0 +1,85 @@
+import { createServer } from "node:http";
+import { log } from "../log.js";
+import { checkOrigin } from "./origin.js";
+/** JSON-RPC InternalError, used for unhandled handler failures. */
+const INTERNAL_ERROR = -32603;
+const notFoundHandler = (_req, res) => {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found\n");
+};
+/**
+ * Routing shell around the MCP adapter:
+ * - Origin allowlist first, before the body is touched: deny → 403 plain text.
+ * - GET /healthz → 200 "ok" (client debugging; kept trivial).
+ * - POST /mcp → the MCP handler; other methods on /mcp → 405 with Allow: POST
+ *   (mirrors upstream, where Next.js 405s methods the route does not export).
+ * - Everything else → 404.
+ */
+export function createAppHandler(mcpHandler) {
+    return async (req, res) => {
+        if (!checkOrigin(req.headers.origin)) {
+            res.writeHead(403, { "Content-Type": "text/plain" });
+            res.end("Forbidden: Origin not allowed\n");
+            return;
+        }
+        const pathname = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+        if (pathname === "/mcp") {
+            if (req.method !== "POST") {
+                res.writeHead(405, { Allow: "POST" });
+                res.end();
+                return;
+            }
+            await mcpHandler(req, res);
+            return;
+        }
+        if (pathname === "/healthz" && req.method === "GET") {
+            res.writeHead(200, { "Content-Type": "text/plain" });
+            res.end("ok");
+            return;
+        }
+        notFoundHandler(req, res);
+    };
+}
+/**
+ * Starts an HTTP server bound to 127.0.0.1 (loopback only, never configurable).
+ * Resolves once listening; rejects with the bind error (e.g. EADDRINUSE) otherwise.
+ */
+export function startHttpServer(port, handler = notFoundHandler) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            void invokeSafely(handler, req, res);
+        });
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.removeListener("error", reject);
+            resolve(server);
+        });
+    });
+}
+/**
+ * Await the handler; turn sync throws and async rejections into a 500. The
+ * MCP adapter shapes every classified failure itself, so anything that
+ * reaches this catch is a local proxy bug: full stack to stderr, generic
+ * -32603 InternalError to the client.
+ */
+async function invokeSafely(handler, req, res) {
+    try {
+        await handler(req, res);
+    }
+    catch (err) {
+        // Core error messages never contain the API key, and the client-facing
+        // body is generic regardless — the key cannot leak.
+        log.error(`request failed: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+        if (!res.headersSent) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                jsonrpc: "2.0",
+                error: { code: INTERNAL_ERROR, message: "Internal error" },
+                id: null,
+            }));
+        }
+        else {
+            res.end();
+        }
+    }
+}

package/dist/http/origin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pure Origin-header allowlist check — the anti-DNS-rebinding / anti-CSRF
+ * control for the loopback server. Evaluated before the request body is read;
+ * on deny the caller answers 403 without touching the body.
+ *
+ * Policy:
+ * - Absent Origin → allow (non-browser clients: curl, MCP SDKs, inspectors).
+ * - http/https origins on `127.0.0.1` or `localhost` → allow, any port
+ *   (any port variant of loopback is fine, so no `port` parameter exists).
+ * - Everything else → deny, including the literal "null" Origin (sandboxed
+ *   iframes, file://), IPv6 `[::1]` (the server binds IPv4 loopback only),
+ *   and anything that does not parse as a URL.
+ */
+export declare function checkOrigin(originHeader: string | undefined): boolean;

package/dist/http/origin.js

@@ -0,0 +1,27 @@
+/**
+ * Pure Origin-header allowlist check — the anti-DNS-rebinding / anti-CSRF
+ * control for the loopback server. Evaluated before the request body is read;
+ * on deny the caller answers 403 without touching the body.
+ *
+ * Policy:
+ * - Absent Origin → allow (non-browser clients: curl, MCP SDKs, inspectors).
+ * - http/https origins on `127.0.0.1` or `localhost` → allow, any port
+ *   (any port variant of loopback is fine, so no `port` parameter exists).
+ * - Everything else → deny, including the literal "null" Origin (sandboxed
+ *   iframes, file://), IPv6 `[::1]` (the server binds IPv4 loopback only),
+ *   and anything that does not parse as a URL.
+ */
+export function checkOrigin(originHeader) {
+    if (originHeader === undefined)
+        return true;
+    let origin;
+    try {
+        origin = new URL(originHeader);
+    }
+    catch {
+        return false;
+    }
+    if (origin.protocol !== "http:" && origin.protocol !== "https:")
+        return false;
+    return origin.hostname === "127.0.0.1" || origin.hostname === "localhost";
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};