hippo-memory 1.59.0 → 1.61.0

package/dist/server/auth.js

@@ -0,0 +1,221 @@
+// Bearer and loopback auth for the HTTP server.
+import { envRequireAuth } from '../env.js';
+import { resolveTenantId } from '../tenant.js';
+import { log } from '../log.js';
+import { API_KEY_PREFIX, verifyApiKeyCached } from '../auth.js';
+import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER } from '../http-util.js';
+import { requestIds } from './request.js';
+import { isJsonString } from './validation.js';
+/**
+ * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as
+ * '::ffff:127.0.0.1' on dual-stack sockets, so we accept that alongside
+ * the bare v4 and v6 loopbacks. Anything else is treated as remote.
+ */
+export function isLoopback(remoteAddress) {
+    if (!remoteAddress)
+        return false;
+    if (remoteAddress === '127.0.0.1')
+        return true;
+    if (remoteAddress === '::1')
+        return true;
+    if (remoteAddress === '::ffff:127.0.0.1')
+        return true;
+    return false;
+}
+// A proxy on this host (nginx, Caddy, cloudflared) connects from loopback, so these headers mean the caller is not local.
+const PROXY_HEADERS = [
+    'forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'cf-connecting-ip', 'true-client-ip',
+];
+// A browser on this machine is loopback too, so the no-key fallback also needs a local Host and a same-site caller.
+function assertLocalCaller(req) {
+    if (!isLoopback(req.socket.remoteAddress))
+        throw new HttpError(401, 'auth required');
+    const proxyHeader = PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
+    if (proxyHeader !== undefined) {
+        log.warn(`proxied loopback request refused: it carries ${proxyHeader}, so the no-key local fallback does not apply. ` +
+            'Send an API key (hippo auth create, then Authorization: Bearer hk_...).', { requestId: requestIds.get(req) });
+        throw new HttpError(401, 'auth required');
+    }
+    const host = req.headers.host;
+    if ((host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req)) {
+        throw new HttpError(403, 'cross-site or non-local request refused; send an API key');
+    }
+}
+export function readAuthHeader(req) {
+    const raw = req.headers['authorization'];
+    if (raw === undefined)
+        return { kind: 'absent' };
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (!isHeaderString(value) || value.length === 0) {
+        return { kind: 'malformed' };
+    }
+    const space = value.indexOf(' ');
+    if (space < 0)
+        return { kind: 'malformed' };
+    const scheme = value.slice(0, space);
+    const token = value.slice(space + 1).trim();
+    if (scheme.toLowerCase() !== 'bearer')
+        return { kind: 'malformed' };
+    if (token.length === 0)
+        return { kind: 'malformed' };
+    return { kind: 'bearer', token };
+}
+// Built-in actors are the bare names below or `<name>:<detail>`; a plain prefix would also reject `clinton@corp`.
+const RESERVED_ACTOR_NAMES = [
+    'api_key', 'localhost', 'cli', 'system', 'mcp', 'connector', 'sleep', 'post-compact', 'recall', 'agent-memories',
+];
+/** Add-ons call this to refuse a subject that would collide with a built-in actor. */
+export function isReservedActor(subject) {
+    const lower = subject.toLowerCase();
+    return RESERVED_ACTOR_NAMES.some((n) => lower === n || lower.startsWith(`${n}:`));
+}
+function hasControlChar(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x20 || c === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** Core owns the checks so a resolver cannot mint an actor that collides with a built-in one. */
+function sanitiseResolved(r) {
+    // Each field is read once: a getter on plugin code could answer differently the second time.
+    const { tenantId, subject, role, scopes } = r;
+    // A resolver is plugin code, so the runtime checks hold even though the static types say string.
+    if (!isJsonString(tenantId) || tenantId.trim().length === 0)
+        return null;
+    // Core reserves `__`-prefixed tenants (`__host__`, `__unroutable__`).
+    const tenant = tenantId.trim();
+    if (tenant.startsWith('__') || tenant.length > 256 || hasControlChar(tenant))
+        return null;
+    if (!isJsonString(subject) || subject.length < 1 || subject.length > 256)
+        return null;
+    // Padding would let "system " pass the reserved-name check yet read as `system` in an audit log.
+    if (hasControlChar(subject) || subject !== subject.trim())
+        return null;
+    if (isReservedActor(subject))
+        return null;
+    const clean = { tenantId: tenant, subject, role: role === 'admin' ? 'admin' : 'member' };
+    if (Array.isArray(scopes))
+        clean.scopes = scopes.filter((s) => isJsonString(s));
+    return clean;
+}
+function logResolverFailure(what, raw, token) {
+    // The plugin's message is logged, but never the token, even if the plugin echoed it.
+    log.error(`auth resolver ${what}: ${raw.split(token).join('[token]')}`);
+}
+/** 503 when upstream throws or misses the deadline, so a stream heartbeat can tell an outage from a revocation. */
+async function askResolver(resolver, token, deadlineMs) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no answer within ${deadlineMs} ms`)), deadlineMs);
+    });
+    let resolved;
+    try {
+        resolved = await Promise.race([(async () => resolver(token))(), deadline]);
+    }
+    catch (err) {
+        logResolverFailure('threw', err instanceof Error ? err.message : 'unknown error', token);
+        throw new HttpError(503, 'auth provider unavailable');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let clean = null;
+    try {
+        clean = resolved ? sanitiseResolved(resolved) : null;
+    }
+    catch (err) {
+        // A throwing getter is a resolver bug, not an outage, so it is a 401 like any malformed answer.
+        logResolverFailure('threw', err instanceof Error ? err.message : 'unknown error', token);
+    }
+    if (!clean)
+        throw new HttpError(401, 'invalid api key');
+    return clean;
+}
+const DEFAULT_RESOLVER_DEADLINE_MS = 5000;
+/** Shared by buildContextWithAuth and requireAuth so the two cannot drift. */
+async function resolveBearer(token, opts) {
+    // Routing by shape keeps key plaintext out of plugin code and stops a resolver overriding a key's identity.
+    if (opts.authResolver && !token.startsWith(API_KEY_PREFIX)) {
+        const t = opts.authResolverTimeoutMs;
+        const deadlineMs = t !== undefined && Number.isFinite(t) && t > 0 ? t : DEFAULT_RESOLVER_DEADLINE_MS;
+        return { ...(await askResolver(opts.authResolver, token, deadlineMs)), viaAuthResolver: true };
+    }
+    const key = verifyApiKeyCached(opts.hippoRoot, token);
+    if (!key)
+        throw new HttpError(401, 'invalid api key');
+    return { tenantId: key.tenantId, subject: `api_key:${key.keyId}`, role: key.role, scopes: key.scopes };
+}
+/**
+ * Build a per-request Context from the Authorization header and remote
+ * address. Throws HttpError(401) for invalid / missing credentials. Opens
+ * the DB only for an API-key-shaped Bearer token (or any Bearer token when no
+ * auth resolver is registered), so loopback no-auth requests stay cheap.
+ */
+export async function buildContextWithAuth(req, opts) {
+    const auth = readAuthHeader(req);
+    if (auth.kind === 'malformed') {
+        throw new HttpError(401, 'invalid api key');
+    }
+    if (auth.kind === 'bearer') {
+        const id = await resolveBearer(auth.token, opts);
+        const actor = { subject: id.subject, role: id.role, scopes: id.scopes };
+        if (id.viaAuthResolver)
+            actor.viaAuthResolver = true;
+        // Only the server's own tenant owns the host; any other tenant's admin key is a tenant admin.
+        else if (id.role === 'admin' && id.tenantId === resolveTenantId({}))
+            actor.hostAdmin = true;
+        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor };
+    }
+    // No Authorization header. Loopback-only fallback for a direct local caller (no proxy headers),
+    // unless HIPPO_REQUIRE_AUTH=1 forbids the local-CLI escape hatch.
+    if (envRequireAuth()) {
+        throw new HttpError(401, 'auth required');
+    }
+    assertLocalCaller(req);
+    // v1.12.0: loopback fallback is process-local, treat as admin.
+    return {
+        hippoRoot: opts.hippoRoot,
+        tenantId: resolveTenantId({}),
+        actor: { subject: 'localhost:cli', role: 'admin', hostAdmin: true },
+    };
+}
+/**
+ * Auth check for routes that do not need a tenant Context (e.g. MCP transport,
+ * which builds its own root resolution via findHippoRoot). Throws HttpError
+ * 401 the same way buildContextWithAuth does, but skips building the Context
+ * envelope. Loopback no-auth still passes.
+ */
+export async function requireAuth(req, opts) {
+    const auth = readAuthHeader(req);
+    if (auth.kind === 'malformed') {
+        throw new HttpError(401, 'invalid api key');
+    }
+    if (auth.kind === 'bearer') {
+        await resolveBearer(auth.token, opts);
+        return;
+    }
+    if (envRequireAuth()) {
+        throw new HttpError(401, 'auth required');
+    }
+    assertLocalCaller(req);
+}
+/** Never rejects: an outage (5xx) skips one heartbeat tick, only a definite 4xx denial closes the stream. */
+export async function heartbeatVerdict(req, opts) {
+    try {
+        await requireAuth(req, opts);
+        return 'ok';
+    }
+    catch (err) {
+        return err instanceof HttpError && err.status < 500 ? 'revoked' : 'unavailable';
+    }
+}
+/** Gate for any action beyond the caller's own tenant: a tenant's admin, by key or resolver, is never a host admin. */
+export function assertCrossTenantAdmin(ctx, what) {
+    if (ctx.actor.role !== 'admin')
+        throw new HttpError(403, `${what} requires admin role`);
+    if (!ctx.actor.hostAdmin)
+        throw new HttpError(403, `${what} requires a host admin`);
+}
+//# sourceMappingURL=auth.js.map

package/dist/server/client-ip.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage } from 'node:http';
+import type { RateLimiter } from '../rate-limit.js';
+/**
+ * Rate-limit key for a request. Defaults to the socket's remote address.
+ *
+ * Behind a TLS-terminating proxy (Fly, most PaaS ingress) every socket
+ * carries the proxy's address, so per-IP buckets collapse into one global
+ * bucket that unauthenticated traffic can drain before auth runs. Set
+ * HIPPO_CLIENT_IP_HEADER to the header the proxy stamps with the real
+ * client address (fly-client-ip on Fly, which the edge always overwrites)
+ * to key buckets per client instead.
+ *
+ * Only set this when a trusted proxy fronts EVERY request: a directly
+ * reachable server honoring the header would let clients mint a fresh
+ * bucket per request and bypass the limiter entirely.
+ *
+ * HIPPO_TRUSTED_PROXIES (comma-separated IPs or CIDRs) pins which peers count
+ * as that proxy: the header is read only when the socket peer is listed, and
+ * listed hops are skipped. In a comma-joined chain (X-Forwarded-For) the key is
+ * the rightmost hop no trusted proxy added; entries to its left are whatever
+ * the client sent, so they never pick the bucket.
+ */
+export declare function clientIpForRateLimit(req: IncomingMessage): string;
+export declare function enforceRateLimit(req: IncomingMessage, path: string, limiter?: RateLimiter): void;
+//# sourceMappingURL=client-ip.d.ts.map

package/dist/server/client-ip.js

@@ -0,0 +1,92 @@
+// Client IP keying and the per-IP rate limit for /v1 and /mcp.
+import { envClientIpHeader, envTrustedProxies } from '../env.js';
+import { BlockList, isIP } from 'node:net';
+import { log } from '../log.js';
+import { HttpError } from '../http-util.js';
+/**
+ * Rate-limit key for a request. Defaults to the socket's remote address.
+ *
+ * Behind a TLS-terminating proxy (Fly, most PaaS ingress) every socket
+ * carries the proxy's address, so per-IP buckets collapse into one global
+ * bucket that unauthenticated traffic can drain before auth runs. Set
+ * HIPPO_CLIENT_IP_HEADER to the header the proxy stamps with the real
+ * client address (fly-client-ip on Fly, which the edge always overwrites)
+ * to key buckets per client instead.
+ *
+ * Only set this when a trusted proxy fronts EVERY request: a directly
+ * reachable server honoring the header would let clients mint a fresh
+ * bucket per request and bypass the limiter entirely.
+ *
+ * HIPPO_TRUSTED_PROXIES (comma-separated IPs or CIDRs) pins which peers count
+ * as that proxy: the header is read only when the socket peer is listed, and
+ * listed hops are skipped. In a comma-joined chain (X-Forwarded-For) the key is
+ * the rightmost hop no trusted proxy added; entries to its left are whatever
+ * the client sent, so they never pick the bucket.
+ */
+export function clientIpForRateLimit(req) {
+    const socketIp = req.socket.remoteAddress ?? 'unknown';
+    const header = envClientIpHeader();
+    if (!header)
+        return socketIp;
+    const trusted = trustedProxyList(envTrustedProxies());
+    if (trusted && !isTrustedProxy(trusted, socketIp))
+        return socketIp;
+    const raw = req.headers[header];
+    const hops = (Array.isArray(raw) ? raw.join(',') : raw ?? '')
+        .split(',')
+        .map((hop) => hop.trim())
+        .filter((hop) => hop.length > 0);
+    for (let i = hops.length - 1; i >= 0; i--) {
+        if (!trusted || !isTrustedProxy(trusted, hops[i]))
+            return hops[i];
+    }
+    return hops[0] ?? socketIp;
+}
+let trustedProxyCache;
+/** Parses HIPPO_TRUSTED_PROXIES once per distinct value; undefined when unset, so any peer may set the header. */
+function trustedProxyList(raw) {
+    if (!raw?.trim())
+        return undefined;
+    if (trustedProxyCache?.raw === raw)
+        return trustedProxyCache.list;
+    const list = new BlockList();
+    for (const entry of raw.split(',').map((e) => e.trim()).filter((e) => e.length > 0)) {
+        const [addr = '', prefix] = entry.split('/');
+        const family = isIP(addr) === 6 ? 'ipv6' : 'ipv4';
+        const bits = prefix === undefined ? undefined : Number(prefix);
+        const maxBits = family === 'ipv6' ? 128 : 32;
+        if (isIP(addr) === 0 || (bits !== undefined && (!Number.isInteger(bits) || bits < 0 || bits > maxBits))) {
+            log.warn(`HIPPO_TRUSTED_PROXIES: ignoring '${entry}', not an IP address or CIDR`);
+            continue;
+        }
+        if (bits === undefined)
+            list.addAddress(addr, family);
+        else
+            list.addSubnet(addr, bits, family);
+    }
+    trustedProxyCache = { raw, list };
+    return list;
+}
+function isTrustedProxy(list, ip) {
+    const bare = ip.startsWith('::ffff:') && isIP(ip.slice(7)) === 4 ? ip.slice(7) : ip;
+    const family = isIP(bare);
+    return family !== 0 && list.check(bare, family === 6 ? 'ipv6' : 'ipv4');
+}
+export function enforceRateLimit(req, path, limiter) {
+    // E3: per-IP rate limit on /v1/* and /mcp* to bound api-key-id enumeration. /health
+    // (a liveness probe) and other paths are never throttled. A 429 thrown
+    // here lands in the createServer catch like any other HttpError.
+    //
+    // Keyed on the socket's remote address by default. Behind a TLS-terminating
+    // proxy every socket carries the proxy's address, collapsing the per-IP
+    // buckets into one global bucket that pre-auth traffic can drain; set
+    // HIPPO_CLIENT_IP_HEADER there so each real client gets its own bucket
+    // (see clientIpForRateLimit).
+    if (limiter && (path.startsWith('/v1/') || path === '/mcp' || path === '/mcp/stream')) {
+        const ip = clientIpForRateLimit(req);
+        if (!limiter.check(ip)) {
+            throw new HttpError(429, 'rate limit exceeded');
+        }
+    }
+}
+//# sourceMappingURL=client-ip.js.map

package/dist/server/cursor.d.ts

@@ -0,0 +1,23 @@
+import type { ServerResponse } from 'node:http';
+import type { KeysetPosition } from '../keyset.js';
+type CursorPart = 'string' | 'integer';
+/** Bare-array routes cannot grow a body field without breaking clients, so their next cursor rides this header. */
+export declare const NEXT_CURSOR_HEADER = "X-Next-Cursor";
+export declare function encodeCursor(pos: KeysetPosition): string;
+/** The position a `?cursor=` names, or undefined when the param is absent; anything this server did not mint is a 400. */
+export declare function parseCursor(raw: string | null, keyPart: CursorPart, idPart: CursorPart): KeysetPosition | undefined;
+export interface Page<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+/** Drops the one-row lookahead the query fetched past `limit` and names the next page's cursor, null on the last page. */
+export declare function pageOf<T>(rows: readonly T[], limit: number, positionOf: (row: T) => KeysetPosition): Page<T>;
+/** Rows ordered by (created_at DESC, id DESC): the decision, incident, process, policy, skill, brief, note and prediction tables. */
+export declare function byCreatedAt(row: {
+    createdAt: string;
+    id: number;
+}): KeysetPosition;
+/** Sets the next-page header on a bare-array response; absent means this was the last page. */
+export declare function setNextCursorHeader(res: ServerResponse, nextCursor: string | null): void;
+export {};
+//# sourceMappingURL=cursor.d.ts.map

package/dist/server/cursor.js

@@ -0,0 +1,58 @@
+import { HttpError } from '../http-util.js';
+import { isJsonNumber, isJsonString } from './validation.js';
+/** Bare-array routes cannot grow a body field without breaking clients, so their next cursor rides this header. */
+export const NEXT_CURSOR_HEADER = 'X-Next-Cursor';
+const MAX_CURSOR_CHARS = 1024;
+const CURSOR_RE = /^[A-Za-z0-9_-]+$/;
+export function encodeCursor(pos) {
+    return Buffer.from(JSON.stringify([pos.key, pos.id])).toString('base64url');
+}
+function decodeJson(raw) {
+    try {
+        const parsed = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+        return parsed;
+    }
+    catch (e) {
+        if (e instanceof SyntaxError)
+            return undefined;
+        throw e;
+    }
+}
+function isPart(value, part) {
+    if (part === 'string')
+        return isJsonString(value) && value.length > 0;
+    return isJsonNumber(value) && Number.isInteger(value);
+}
+function toPosition(parsed, keyPart, idPart) {
+    if (!Array.isArray(parsed) || parsed.length !== 2)
+        return undefined;
+    const [key, id] = parsed;
+    return isPart(key, keyPart) && isPart(id, idPart) ? { key, id } : undefined;
+}
+/** The position a `?cursor=` names, or undefined when the param is absent; anything this server did not mint is a 400. */
+export function parseCursor(raw, keyPart, idPart) {
+    if (raw === null)
+        return undefined;
+    const parsed = raw.length <= MAX_CURSOR_CHARS && CURSOR_RE.test(raw) ? decodeJson(raw) : undefined;
+    const pos = toPosition(parsed, keyPart, idPart);
+    if (!pos)
+        throw new HttpError(400, 'cursor is malformed; pass next_cursor from the previous page unchanged');
+    return pos;
+}
+/** Drops the one-row lookahead the query fetched past `limit` and names the next page's cursor, null on the last page. */
+export function pageOf(rows, limit, positionOf) {
+    if (rows.length <= limit)
+        return { items: [...rows], nextCursor: null };
+    const items = rows.slice(0, limit);
+    return { items, nextCursor: encodeCursor(positionOf(items[items.length - 1])) };
+}
+/** Rows ordered by (created_at DESC, id DESC): the decision, incident, process, policy, skill, brief, note and prediction tables. */
+export function byCreatedAt(row) {
+    return { key: row.createdAt, id: row.id };
+}
+/** Sets the next-page header on a bare-array response; absent means this was the last page. */
+export function setNextCursorHeader(res, nextCursor) {
+    if (nextCursor !== null)
+        res.setHeader(NEXT_CURSOR_HEADER, nextCursor);
+}
+//# sourceMappingURL=cursor.js.map

package/dist/server/lifecycle.d.ts

@@ -0,0 +1,7 @@
+import type { Server, ServerResponse } from 'node:http';
+/**
+ * Stop accepting, end streams at once (they never finish on their own), give other in-flight
+ * requests up to `drainMs`, then close whatever is left.
+ */
+export declare function drainAndClose(server: Server, inflight: ReadonlySet<ServerResponse>, drainMs: number): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/server/lifecycle.js

@@ -0,0 +1,29 @@
+import { log } from '../log.js';
+/**
+ * Stop accepting, end streams at once (they never finish on their own), give other in-flight
+ * requests up to `drainMs`, then close whatever is left.
+ */
+export async function drainAndClose(server, inflight, drainMs) {
+    const closed = new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    });
+    server.closeIdleConnections?.();
+    for (const res of inflight) {
+        if (res.headersSent && !res.writableEnded)
+            res.destroy();
+        else if (!res.headersSent)
+            res.setHeader('Connection', 'close');
+    }
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(true), drainMs);
+    });
+    const late = await Promise.race([closed.then(() => false), timedOut]);
+    clearTimeout(timer);
+    if (late) {
+        log.warn(`shutdown: ${inflight.size} request(s) still running after ${drainMs} ms; closing them`);
+        server.closeAllConnections?.();
+    }
+    await closed;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/server/mcp-http.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ServeOpts } from './types.js';
+export declare function handleMcpPost(req: IncomingMessage, res: ServerResponse, opts: ServeOpts): Promise<void>;
+export declare function handleMcpStream(req: IncomingMessage, res: ServerResponse, opts: ServeOpts, streamSlots: Map<string, number>): Promise<void>;
+//# sourceMappingURL=mcp-http.d.ts.map

package/dist/server/mcp-http.js

@@ -0,0 +1,199 @@
+// MCP over HTTP: POST /mcp and the GET /mcp/stream SSE keepalive.
+import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '../env.js';
+import { createHash } from 'node:crypto';
+import { handleMcpRequest, mcpErrorResponse } from '../mcp/server.js';
+import { HttpError, isJsonObjectRecord, readBody, sendJson } from '../http-util.js';
+import { buildContextWithAuth, heartbeatVerdict, readAuthHeader, requireAuth } from './auth.js';
+import { clientIpForRateLimit } from './client-ip.js';
+import { requestIds } from './request.js';
+import { isJsonString } from './validation.js';
+/**
+ * Build a per-client key for MCP state isolation under HTTP-MCP. Used by
+ * mcp/server.ts to scope `lastRecalledIds` to the calling client so two
+ * clients on the same tenant cannot poison each other's outcome feedback.
+ *
+ * Token is hashed (sha256, 16-hex-char prefix) so we never log or persist
+ * the raw bearer. Combined with remoteAddress so two clients sharing a key
+ * (e.g. on a shared Postman environment) are still separable in the common
+ * case. 'noauth' covers loopback no-auth and is acceptable because that
+ * path is single-host single-user.
+ */
+function buildMcpClientKey(req) {
+    const auth = readAuthHeader(req);
+    const tokenHash = auth.kind === 'bearer'
+        ? createHash('sha256').update(auth.token).digest('hex').slice(0, 16)
+        : 'noauth';
+    const addr = req.socket.remoteAddress ?? 'unknown';
+    return `http:${tokenHash}:${addr}`;
+}
+// ── MCP-over-HTTP/SSE transport (Task 11) ──
+//
+// Two routes implement an MCP HTTP transport alongside the stdio one. Both
+// dispatch to the same `handleMcpRequest` as the stdio loop in src/mcp/server.ts.
+//
+// POST /mcp        — Send a JSON-RPC request, get a JSON-RPC response synchronously
+//                    in the body. Content-type: application/json both ways.
+// GET  /mcp/stream — Open an SSE stream for server-initiated messages.
+//                    v1 simplification: this stream is keepalive-only. Clients
+//                    that need server-pushed notifications/progress will see
+//                    only `: ping` comments every 30s. All real responses come
+//                    back synchronously on POST /mcp. This matches the
+//                    "synchronous JSON in body" leg of the MCP HTTP spec and
+//                    is enough for `tools/list` / `tools/call` round-trips.
+//                    Server-initiated SSE messages will be wired in a later task.
+//
+// Auth: same as /v1/* — Bearer token validated via `requireAuth`, with the
+// loopback no-auth fallback. SSE check runs once at stream-open.
+export async function handleMcpPost(req, res, opts) {
+    // Build the same Context the /v1/* routes use so MCP tool calls inherit
+    // the server's bound hippoRoot and the auth-resolved tenantId / actor.
+    // Without this, executeTool would walk from cwd via findHippoRoot() and
+    // pull tenant from HIPPO_TENANT, dropping a valid Bearer for tenant B
+    // back to whatever the env says.
+    const ctx = await buildContextWithAuth(req, opts);
+    const raw = await readBody(req);
+    let mcpReq;
+    try {
+        mcpReq = JSON.parse(raw);
+    }
+    catch {
+        throw new HttpError(400, 'invalid JSON-RPC body');
+    }
+    if (!isJsonObjectRecord(mcpReq) || !isJsonString(mcpReq.method)) {
+        throw new HttpError(400, 'JSON-RPC body must include a method string');
+    }
+    // SAFETY: validated above as a plain JSON object carrying a string method;
+    // the remaining McpRequest wire fields (jsonrpc, id, params) are checked or
+    // safely defaulted inside handleMcpRequest's JSON-RPC dispatch.
+    const rpcReq = mcpReq;
+    let mcpRes;
+    try {
+        mcpRes = await handleMcpRequest(rpcReq, {
+            hippoRoot: ctx.hippoRoot,
+            tenantId: ctx.tenantId,
+            // v1.12.0: McpContext.actor stays string; extract subject at the boundary.
+            actor: ctx.actor.subject,
+            // The caller's real role: MCP tools must not run a member key as admin.
+            role: ctx.actor.role,
+            scopes: ctx.actor.scopes,
+            viaAuthResolver: ctx.actor.viaAuthResolver,
+            hostAdmin: ctx.actor.hostAdmin,
+            clientKey: buildMcpClientKey(req),
+        });
+    }
+    catch (err) {
+        mcpRes = mcpErrorResponse(rpcReq.id, err, requestIds.get(req));
+    }
+    if (mcpRes === null) {
+        // Notification — no body, 202 Accepted.
+        res.writeHead(202);
+        res.end();
+        return;
+    }
+    sendJson(res, 200, mcpRes);
+}
+// Each open stream holds a socket and a timer, so one key (or one IP when keyless) gets a bounded number.
+const DEFAULT_MAX_STREAMS_PER_CLIENT = 8;
+/** The bucket a stream counts against: a hash of the bearer token, else the client IP. */
+function streamSlotKey(req) {
+    const auth = readAuthHeader(req);
+    if (auth.kind === 'bearer')
+        return `key:${createHash('sha256').update(auth.token).digest('hex').slice(0, 16)}`;
+    return `ip:${clientIpForRateLimit(req)}`;
+}
+/** Takes a stream slot or throws 429; the slot is released once, when the response closes. */
+function acquireStreamSlot(req, res, slots) {
+    const max = envMcpSseMaxStreams() ?? DEFAULT_MAX_STREAMS_PER_CLIENT;
+    const key = streamSlotKey(req);
+    const open = slots.get(key) ?? 0;
+    if (open >= max)
+        throw new HttpError(429, `too many open streams for this client (limit ${max}); close one first`);
+    slots.set(key, open + 1);
+    res.once('close', () => {
+        const left = (slots.get(key) ?? 1) - 1;
+        if (left > 0)
+            slots.set(key, left);
+        else
+            slots.delete(key);
+    });
+}
+export async function handleMcpStream(req, res, opts, streamSlots) {
+    await requireAuth(req, opts);
+    // An async resolver can outlive the client; 'close' has already fired, so no timer may start.
+    if (req.destroyed || res.destroyed || req.socket.destroyed)
+        return;
+    acquireStreamSlot(req, res, streamSlots);
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+    });
+    // Initial ping so smoke tests can confirm the stream is live without
+    // waiting for the first keepalive interval.
+    res.write(': ping\n\n');
+    // v0.39 SSE hardening:
+    //   - Heartbeat re-validates the bearer (default 60s). If the key was
+    //     revoked or rotated, close the stream with reason='auth_revoked'.
+    //   - MCP_SSE_MAX_AGE_SEC (default 3600) caps stream lifetime; close
+    //     with reason='max_age_exceeded' when reached.
+    //   - MCP_SSE_HEARTBEAT_MS (default 60000) lets tests run with a short
+    //     interval without waiting a full minute.
+    const heartbeatMs = envMcpSseHeartbeatMs() ?? 60000;
+    const maxAgeMs = (envMcpSseMaxAgeSec() ?? 3600) * 1000;
+    const startedAt = Date.now();
+    let closed = false;
+    let checking = false;
+    const closeWith = (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        try {
+            res.write(`event: closed\ndata: ${JSON.stringify({ reason })}\n\n`);
+        }
+        catch { /* socket already gone */ }
+        try {
+            res.end();
+        }
+        catch { /* socket already gone */ }
+    };
+    const ping = setInterval(() => {
+        if (closed) {
+            clearInterval(ping);
+            return;
+        }
+        if (Date.now() - startedAt >= maxAgeMs) {
+            closeWith('max_age_exceeded');
+            clearInterval(ping);
+            return;
+        }
+        if (checking)
+            return;
+        checking = true;
+        void heartbeatVerdict(req, opts).then((verdict) => {
+            checking = false;
+            if (closed || verdict === 'unavailable')
+                return;
+            if (verdict === 'revoked') {
+                closeWith('auth_revoked');
+                clearInterval(ping);
+                return;
+            }
+            try {
+                res.write(': ping\n\n');
+            }
+            catch {
+                clearInterval(ping); // the client hung up; stop pinging a dead socket
+            }
+        });
+    }, heartbeatMs);
+    // Don't keep the event loop alive just for this timer — the server's
+    // listener already does that, and tests want the process to exit cleanly.
+    if (ping.unref instanceof Function)
+        ping.unref();
+    // res 'close' covers an early socket drop that req 'close' can miss.
+    res.on('close', () => {
+        closed = true;
+        clearInterval(ping);
+    });
+}
+//# sourceMappingURL=mcp-http.js.map