@proof-holdings/mcp-server 1.0.0 → 1.2.0

package/dist/remote.d.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Remote entrypoint: the Proof MCP server over Streamable HTTP (`h-mcp-remote`, SC-3 + SC-4).
+ *
+ * Deployed as its own service, NOT as a route inside the existing backend. The reason is
+ * structural rather than stylistic: `src/cluster.ts` forks one worker per CPU and round-robins
+ * between them, while a Streamable HTTP session lives in the memory of ONE process. Mounting this
+ * on the clustered backend would lose sessions by default, not in an edge case. The deployment
+ * therefore pins requests to a replica by the REPLICA PREFIX this server puts in every session id
+ * it mints (`<replica>.<uuid>`); see `replicaId` below for why hashing the id itself cannot work,
+ * and `k8s/mcp-remote/nginx-mcp.conf` for the routing that consumes the prefix. That routing is
+ * deliberately NOT in the base nginx configmap — see that directory's README for the ingress it
+ * would otherwise take down, and `src/__tests__/drift/mcp-remote-deployment.test.ts`, which asserts
+ * the base stays free of it.
+ *
+ * ANONYMOUS FIRST, KEYED ON REQUEST (`h-mcp-oauth-remote-wiring`). Every connection starts with the
+ * keyless surface and the ability to log in through the normal flows; a client that has been
+ * through the OAuth ceremony (`h-mcp-oauth-server`) presents the API key it was granted, and this
+ * server reads it from the `Authorization` header ONLY. A `?api_key=` query parameter is never
+ * read: a token in a URL is copied into proxy logs and `Referer`, and the standard clients all send
+ * a header. The token is resolved ONCE, at open, by self-inspection (`GET /api/v1/me/api-key`) —
+ * purely so the refusal is legible; nothing is cached from it, and the key travels to the backend
+ * on every call, which is what makes a revocation take effect immediately rather than at session
+ * TTL. Where the 401 lands is a measurement, not a preference: on the TOOL CALL that needs an
+ * account, because a 401 on `initialize` reached the human as a connection timeout and cost the
+ * anonymous connection entirely (`docs/mcp-oauth-client-probe.md`).
+ *
+ * Each connection needs its OWN `HttpClient` for two reasons now: `captureSetCookie` writes a login
+ * session onto the instance, and the API key of one connection must never be reachable from
+ * another. The boundary between keyless and keyed tools lives in `./authBoundary.js`.
+ */
+import { type Server } from 'node:http';
+import { HttpClient } from './http.js';
+export interface RemoteServerOptions {
+    baseUrl: string;
+    /** Maximum concurrent MCP sessions. Each one registers the full tool set, so this is a memory bound. */
+    maxSessions?: number;
+    /** Idle time after which a session is closed and dropped. */
+    sessionTtlMs?: number;
+    sweepIntervalMs?: number;
+    /**
+     * Which replica this process is. It is PREFIXED to every session id it mints, and the proxy
+     * routes on that prefix.
+     *
+     * This is not decoration, it is the only thing that makes sticky routing possible. Hashing the
+     * session id — the obvious reading of "sticky by mcp-session-id" — cannot work: the replica is
+     * chosen when the connection OPENS, and at that moment no session id exists yet, so the hash of
+     * the id minted afterwards lands wherever it lands. Measured on a two-replica nginx stand, that
+     * arrangement sent 45 of 60 follow-up requests to a replica that had never heard of the session.
+     * Carrying the replica in the id turns the routing decision into a lookup instead of a guess.
+     */
+    replicaId?: string;
+}
+export interface RemoteServer {
+    httpServer: Server;
+    sessionCount(): number;
+    /** Test seam: the live per-session HTTP clients, to assert they are distinct instances. */
+    debugClients(): HttpClient[];
+    close(): Promise<void>;
+}
+/**
+ * Ceiling on the burst, expressed FLEET-WIDE because the bucket it spends is fleet-wide.
+ *
+ * The burst below is sized off `maxSessions`, which is per replica — and the bucket it lands in is
+ * `ipRateLimit(300, 60, 'me')` keyed on the pod's egress IP, i.e. shared by every replica. So the
+ * figure that matters is `replicas × burst`, and stating the burst per replica beside a rate stated
+ * fleet-wide is how those two drift apart: at `replicas: 3` and the default cap, an unbounded burst
+ * is 300 — the entire minute's bucket, spent at exactly the moment those sessions also begin their
+ * ordinary `/me/*` calls through it. `src/__tests__/drift/mcp-remote-deployment.test.ts` derives
+ * `replicas × min(MCP_MAX_SESSIONS, RESOLVE_BURST_CEILING)` — the EFFECTIVE burst, not this
+ * constant alone — against the backend's own literal, so SCALING THE FLEET reddens it instead of
+ * surfacing as 429s in production. Raising THIS constant is caught elsewhere and deliberately so:
+ * while the manifest cap sits at or below the ceiling, the effective burst does not move, and the
+ * unit case in `mcp/__tests__/remote.test.ts` that runs a cap ABOVE the ceiling is what holds it.
+ */
+export declare const RESOLVE_BURST_CEILING = 100;
+/**
+ * A token bucket over the self-inspection above. Process-local on purpose: what it protects is this
+ * process's own outbound channel, and a shared counter would need a store this service does not
+ * have and must not grow for a defensive bound.
+ *
+ * Exported for its own test. The arithmetic below has a failure mode no HTTP-level case can reach
+ * cheaply — a clock that steps BACKWARDS — and the previous version's clock seam was a default
+ * parameter on an unexported function, i.e. unreachable from a test even in principle. That is the
+ * same shape `positiveIntEnv` above was fixed for once already.
+ */
+export declare function createResolveBudget(maxSessions: number, now?: () => number): {
+    /** True when a self-inspection may be sent; consumes one token. */
+    take(): boolean;
+};
+/**
+ * The replica's own index: `MCP_REPLICA_ID` if set, otherwise the ordinal a StatefulSet puts at the
+ * end of the pod hostname (`mcp-remote-1` → `1`). Falls back to `0` for a single process, which is
+ * what the stdio-style local run and the tests get.
+ */
+/**
+ * Reads a positive-integer setting, falling back to the built-in default on anything else.
+ *
+ * A typo must not disable the bound it configures. `Number('abc')` is NaN, and both
+ * `size >= NaN` and `lastSeen < NaN` are false — so an unparseable value would fail OPEN on exactly
+ * the two limits this server relies on, with the pod still passing every probe. INTEGER rather than
+ * merely finite-and-positive, because `MCP_SESSION_TTL_MS=0.5` would sweep every session on the
+ * first tick and `MCP_MAX_SESSIONS=0.5` would silently mean one.
+ *
+ * Exported and at module scope so it can be tested — the previous version was a closure inside the
+ * entrypoint guard, unreachable from a test even in principle, which left the fix one edit wide.
+ */
+export declare function positiveIntEnv(name: string, env?: NodeJS.ProcessEnv): number | undefined;
+export declare function resolveReplicaId(explicit?: string, hostname?: string): string;
+export declare function createRemoteServer(options: RemoteServerOptions): RemoteServer;
+//# sourceMappingURL=remote.d.ts.map

package/dist/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAiBjG,OAAO,EAAY,UAAU,EAAE,MAAM,WAAW,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,IAAI,MAAM,CAAC;IACvB,2FAA2F;IAC3F,YAAY,IAAI,UAAU,EAAE,CAAC;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA6RD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAkBzC;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,MAAgC;IAMhG,mEAAmE;YAC3D,OAAO;EAclB;AAoGD;;;;GAIG;AACH;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAarG;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAI5F;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA0T7E"}