hippo-memory 1.70.0 → 1.72.0

package/dist/server/auth.js

@@ -1,18 +1,15 @@
 // Bearer and loopback auth for the HTTP server.
-import { envRequireAuth } from '../util/env.js';
+import { envAllowKeylessLocal, envRequireAuth } from '../util/env.js';
 import { resolveTenantId } from '../store/tenant.js';
-import { log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { API_KEY_PREFIX, verifyApiKeyCached } from '../store/auth.js';
 import { ownerOrSubject } from '../api/index.js';
-import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER, MAX_ID_LEN } from '../util/http-util.js';
+import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER } from '../util/http-util.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { clientLimitKey } from './client-ip.js';
 import { keyCheckBounds } from './key-check-bounds.js';
 import { isJsonString } from '../util/json.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.
- */
+/** Recognises loopback remote addresses, including the IPv6-mapped '::ffff:127.0.0.1' Node reports on dual-stack sockets; anything else is remote. */
 export function isLoopback(remoteAddress) {
     if (!remoteAddress)
         return false;
@@ -29,21 +26,36 @@ const PROXY_HEADERS = [
     'forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'cf-connecting-ip', 'true-client-ip',
     'fly-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 proxyHeaderOf(req) {
+    return PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
+}
+/** A page in a browser on this machine: another site's request, or a hostile name resolved to loopback (DNS rebinding). */
+function isForeignPage(req) {
+    const host = req.headers.host;
+    return (host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req);
+}
+/** True only for a request made on this machine by its own user: a proxy and a browser page are loopback too, so the socket alone proves nothing. */
+export function isLocalCaller(req) {
+    return isLoopback(req.socket.remoteAddress) && proxyHeaderOf(req) === undefined && !isForeignPage(req);
+}
+// The throwing twin of isLocalCaller, for the no-key fallback: each refusal has its own status, and a proxied one is logged.
 function assertLocalCaller(req) {
     if (!isLoopback(req.socket.remoteAddress))
         throw new HttpError(401, 'auth required');
-    const proxyHeader = PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
+    const proxyHeader = proxyHeaderOf(req);
     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_...).');
         throw new HttpError(401, 'auth required');
     }
-    const host = req.headers.host;
-    if ((host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req)) {
+    if (isForeignPage(req)) {
         throw new HttpError(403, 'cross-site or non-local request refused; send an API key');
     }
 }
+/** The 401 a keyless request from this machine gets by default; it names both fixes, since an upgrade is where most people meet it. */
+const KEY_REQUIRED_MESSAGE = 'auth required: this server takes no request without an API key. Mint one with `hippo auth create` and send it as ' +
+    '"Authorization: Bearer <key>" (the hippo CLI reads HIPPO_API_KEY), or start the server with HIPPO_ALLOW_KEYLESS_LOCAL=1 ' +
+    'to let requests from this machine in without a key.';
 export function readAuthHeader(req) {
     const raw = req.headers['authorization'];
     if (raw === undefined)
@@ -167,7 +179,7 @@ async function resolveBearer(req, token, opts) {
         id.owner = key.ownerSubject;
     return id;
 }
-/** The auth check without a charge: the bearer's identity, or null for the loopback fallback. */
+/** The auth check without a charge: the bearer's identity, or null for the keyless local fallback. */
 async function checkAuth(req, opts) {
     const auth = readAuthHeader(req);
     if (auth.kind === 'malformed') {
@@ -175,10 +187,14 @@ async function checkAuth(req, opts) {
     }
     if (auth.kind === 'bearer')
         return resolveBearer(req, auth.token, opts);
-    // No Authorization header: the loopback fallback, unless HIPPO_REQUIRE_AUTH=1 forbids the local-CLI escape hatch.
+    // No Authorization header. HIPPO_REQUIRE_AUTH=1 is checked first, so a deployment that sets both stays closed.
     if (envRequireAuth()) {
         throw new HttpError(401, 'auth required');
     }
+    if (!envAllowKeylessLocal()) {
+        // Only this machine's own user is told how to switch the key off; a proxied caller or a page learns nothing.
+        throw new HttpError(401, isLocalCaller(req) ? KEY_REQUIRED_MESSAGE : 'auth required');
+    }
     assertLocalCaller(req);
     return null;
 }
@@ -224,20 +240,23 @@ function chargeCaller(tenantId, actor, opts) {
     warnCallerLimited(key, tenantId, person);
     throw new HttpError(429, 'rate limit exceeded for this caller', limiter.retryAfterSec);
 }
-/**
- * Build a per-request Context from the Authorization header and remote
- * address. Throws HttpError(401) for invalid / missing credentials. Reads
- * the store 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.
- */
+/** Builds a per-request Context from the Authorization header and remote address; throws HttpError(401) for invalid or missing credentials.
+ * Reads the store only for an API-key-shaped Bearer (or any Bearer when no auth resolver is registered), so keyless local requests stay cheap. */
 export async function buildContextWithAuth(req, opts) {
     const id = await checkAuth(req, opts);
-    if (id !== null) {
-        const actor = bearerActor(id);
-        chargeCaller(id.tenantId, actor, opts);
-        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor, store: opts.store };
-    }
-    // Loopback fallback is process-local, treat as admin.
+    const ctx = contextFor(id, opts);
+    if (id !== null)
+        chargeCaller(id.tenantId, ctx.actor, opts);
+    return ctx;
+}
+/** The auth check again, uncharged, for a handler that authenticated with requireAuth before a slow body read and must re-check right before it acts. */
+export async function recheckContextWithAuth(req, opts) {
+    return contextFor(await checkAuth(req, opts), opts);
+}
+function contextFor(id, opts) {
+    if (id !== null)
+        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor: bearerActor(id), store: opts.store };
+    // The keyless local fallback (HIPPO_ALLOW_KEYLESS_LOCAL=1) is this machine's own user, so it is host admin.
     return {
         hippoRoot: opts.hippoRoot,
         tenantId: resolveTenantId({}),
@@ -245,12 +264,8 @@ export async function buildContextWithAuth(req, opts) {
         store: opts.store,
     };
 }
-/**
- * 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.
- */
+/** Auth check for routes that need no tenant Context (e.g. the MCP transport, which resolves its own root): throws HttpError 401 like buildContextWithAuth.
+ * A keyless local request passes only under HIPPO_ALLOW_KEYLESS_LOCAL=1. */
 export async function requireAuth(req, opts) {
     const id = await checkAuth(req, opts);
     if (id !== null)
@@ -263,6 +278,8 @@ export async function heartbeatVerdict(req, opts) {
         return 'ok';
     }
     catch (err) {
+        if (!(err instanceof HttpError))
+            log.error(`heartbeat auth check failed: ${errorMessage(err)}`, errorFields(err));
         return err instanceof HttpError && err.status < 500 && err.status !== 429 ? 'revoked' : 'unavailable';
     }
 }

package/dist/server/boot.d.ts

@@ -1,24 +1,5 @@
 import type { ServeOpts, ServerHandle } from './types.js';
-/**
- * Boot the HTTP daemon on host:port and write the pidfile under hippoRoot.
- *
- * Refuses non-loopback hosts at boot unless
- * HIPPO_REQUIRE_AUTH=1 is set. The auth middleware (buildContextWithAuth /
- * requireAuth) has shipped and every route checks it except GET /health
- * (public by design for platform health checks) and the two connector
- * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing
- * secrets and 404 when those secrets are unset, and any publicJson GET path. But the loopback
- * no-auth fallback inside buildContextWithAuth still admits unauthenticated
- * requests from a loopback remote address (unless they carry Forwarded,
- * X-Forwarded-For/-Host/-Proto, X-Real-IP, Cf-Connecting-Ip, True-Client-Ip or Fly-Client-Ip, which mark a same-host proxy and get
- * a 401 like any keyless remote request), so binding to a non-loopback host
- * is only safe once that fallback is disabled with HIPPO_REQUIRE_AUTH=1,
- * which forces every request (loopback or not) through Bearer-token
- * validation. Without that env var set, a non-loopback bind would expose the
- * DB to the network with no auth, so we fail fast instead.
- *
- * Use port: 0 in tests to bind to an ephemeral port and read the actual
- * port back via server.address() after listen.
- */
+/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses non-loopback hosts unless HIPPO_REQUIRE_AUTH=1.
+ * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export declare function serve(opts: ServeOpts): Promise<ServerHandle>;
 //# sourceMappingURL=boot.d.ts.map

package/dist/server/boot.js

@@ -1,9 +1,8 @@
 import { envPort, envRequireAuth, envV1Rps } from '../util/env.js';
-import { existsSync } from 'node:fs';
 import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.js';
-import { closeHippoDb, getHippoDbPath, isStoreBusy, openHippoDb, outsideRequestStores, outsideSqliteOffLoop, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from '../db/index.js';
-import { startWalCheckpointer } from '../db/wal-checkpointer.js';
-import { requireGroup } from '../store/index.js';
+import { outsideSqliteOffLoop, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from '../db/index.js';
+import { isStoreBusy } from '../store/sqlite/busy.js';
+import { holdSqliteConnection } from '../store/sqlite/held-connection.js';
 import { workerSqliteStore } from '../store/sqlite/worker-store.js';
 import { markSharedStore } from '../core/config.js';
 import { auditWriteFailureCount } from '../store/audit.js';
@@ -12,30 +11,28 @@ import { errorFields, errorMessage, log } from '../util/log.js';
 import { runWithRequestId } from '../util/request-scope.js';
 import { createRateLimiter } from './rate-limit.js';
 import { RecallContractError } from '../api/index.js';
-import { handleSlackEventsWebhook } from '../connectors/slack/webhook.js';
-import { handleGitHubEventsWebhook } from '../connectors/github/webhook.js';
-import { bodyDeadlineMs, BodyTimeoutError, BodyTooLargeError, closeAfterReply, DeadlineExceededError, HttpError, JSON_HEADERS, sendJson } from '../util/http-util.js';
+import { BodyTimeoutError, BodyTooLargeError, closeAfterReply, DeadlineExceededError, HttpError, JSON_HEADERS, sendJson } from '../util/http-util.js';
 import { workerCounts } from '../store/sqlite/executor-counts.js';
-import { isLoopback, LIMITER_MAX_KEYS } from './auth.js';
+import { isLocalCaller, LIMITER_MAX_KEYS } from './auth.js';
 import { enforceRateLimit, warnIfClientIpHeaderUnpinned } from './client-ip.js';
 import { answerAtDeadline, handlerDeadlineCount, isAbandoned, requestDeadlineFor } from './deadline.js';
-import { drainAndClose } from './lifecycle.js';
+import { DEFAULT_SHUTDOWN_DRAIN_MS, drainAndClose, setKeepAliveTimeouts, shutdownBoundMs } from './lifecycle.js';
 import { readyProbeFor } from './ready.js';
-import { installCrashHandlers } from '../util/crash-handlers.js';
+import { DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT } from './defaults.js';
+import { installCrashHandlers, installSignalHandlers } from '../util/crash-handlers.js';
 import { handleMcpPost, handleMcpStream } from './mcp-http.js';
 import { MCP_PROJECT_SCOPED_HEADER } from '../core/project-identity.js';
-import { logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError } from './request.js';
+import { accessRouteOf, logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError } from './request.js';
 import { createListener, warnIfCleartext } from './tls.js';
-import { assertAddonRoutes, assertPublicJson, dispatchAddonRoute, dispatchPublicJson, dispatchV1Route, isPublicRoute } from './route-table.js';
+import { assertAddonRoutes, assertPublicJson } from './route-checks.js';
+import { dispatchAddonRoute, dispatchPublicJson, dispatchV1Route } from './route-table.js';
 // server.address() returns AddressInfo once a TCP socket is bound; null before
 // listening, a string only for pipe/unix-socket listeners (never used here).
 function isAddressInfo(a) {
     return a !== null && typeof a !== 'string';
 }
-// Pinned at module load. Bumped alongside package.json on releases. The
-// HTTP /health response uses this; reading package.json synchronously here
-// would couple the daemon to its on-disk install path, which we want to
-// avoid for tests that mkdtemp a hippoRoot.
+// Pinned at module load, bumped with package.json on releases; reading package.json synchronously here would couple the daemon to its install path,
+// which tests that mkdtemp a hippoRoot avoid.
 const VERSION = PACKAGE_VERSION;
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
 async function handleRequest(req, res, opts, options) {
@@ -61,7 +58,8 @@ async function handleRequest(req, res, opts, options) {
     const routeRequest = { req, res, opts, query };
     if (await runWithRequestStores(() => dispatchScopedRoute(routeRequest, method, path), { busyWaitMs: SERVER_DB_WAIT_MS }))
         return;
-    // A scope of its own, which the heartbeat timer keeps after it closes, so the key check and every heartbeat wait the server's lock wait. Store-ready: the stream only authenticates, through the port.
+    // A scope of its own, which the heartbeat timer keeps after it closes, so the key check and every
+    // heartbeat wait the server's lock wait. Store-ready: the stream only authenticates, through the port.
     if (method === 'GET' && path === '/mcp/stream') {
         noteAccess(req, { route: path });
         await runWithRequestStores(() => handleMcpStream(req, res, opts, streamSlots), { busyWaitMs: SERVER_DB_WAIT_MS });
@@ -70,13 +68,7 @@ async function handleRequest(req, res, opts, options) {
     res.writeHead(404, JSON_HEADERS);
     res.end(JSON.stringify({ error: 'not found' }));
 }
-const WEBHOOK_GROUPS = ['entryWrites', 'connectorWrites', 'connectorEvents'];
-/** A store missing a group a delivery writes through refuses the webhook up front, so no delivery is acknowledged and then half stored. */
-function requireWebhookGroups(store) {
-    for (const group of WEBHOOK_GROUPS)
-        requireGroup(store, group);
-}
-/** Every route that runs inside a request scope, so it opens each store once: the /v1 table, public JSON, add-on routes, the webhooks and POST /mcp. */
+/** Every route that runs inside a request scope, so it opens each store once: the /v1 table with the webhooks, public JSON, add-on routes and POST /mcp. */
 async function dispatchScopedRoute(r, method, path) {
     if (await dispatchV1Route(r, method, path))
         return true;
@@ -85,26 +77,6 @@ async function dispatchScopedRoute(r, method, path) {
     if (await dispatchAddonRoute(r, method, path))
         return true;
     const { req, res, opts } = r;
-    if (method === 'POST' && path === '/v1/connectors/slack/events') {
-        noteAccess(req, { route: path });
-        // Bearer auth deliberately skipped: this route is in PUBLIC_ROUTES and authenticates via the Slack HMAC signature.
-        if (!isPublicRoute(method, path)) {
-            // Defensive: PUBLIC_ROUTES drift would land here. Fail closed.
-            throw new HttpError(401, 'auth required');
-        }
-        requireWebhookGroups(opts.store);
-        await handleSlackEventsWebhook({ req, res, opts }, opts.store);
-        return true;
-    }
-    if (method === 'POST' && path === '/v1/connectors/github/events') {
-        noteAccess(req, { route: path });
-        if (!isPublicRoute(method, path)) {
-            throw new HttpError(401, 'auth required');
-        }
-        requireWebhookGroups(opts.store);
-        await handleGitHubEventsWebhook({ req, res, opts }, opts.store);
-        return true;
-    }
     // Store-ready: under another store the MCP layer lists and runs only the tools ported to the port.
     if (method === 'POST' && path === '/mcp') {
         noteAccess(req, { route: path });
@@ -114,11 +86,9 @@ async function dispatchScopedRoute(r, method, path) {
     return false;
 }
 function sendHealth(req, res, startedAt) {
-    // Loopback callers (detectServer's stale-pidfile probe reads version and
-    // pid) get the full body. Non-loopback callers get liveness only: the
-    // version string would fingerprint the build for the public internet and
-    // the pid is noise. Platform health checks only need the 200.
-    if (isLoopback(req.socket.remoteAddress)) {
+    // A caller on this machine (detectServer's probe reads version and pid) gets the full body; anyone else, even a proxied caller or a browser page on loopback,
+    // gets liveness only: the version would fingerprint the build and the pid is noise. Platform health checks only need the 200.
+    if (isLocalCaller(req)) {
         sendJson(res, 200, {
             ok: true,
             version: VERSION,
@@ -135,7 +105,8 @@ function sendHealth(req, res, startedAt) {
         sendJson(res, 200, { ok: true });
     }
 }
-/** Readiness: one cheap read on the served store under the server's lock wait. /health stays liveness only, so a probe can tell a store that does not answer from a dead process. */
+/** Readiness: one cheap read on the served store under the server's lock wait. /health stays
+ * liveness only, so a probe can tell a store that does not answer from a dead process. */
 async function sendReady(res, store) {
     const { readiness } = store;
     if (readiness === undefined) {
@@ -156,10 +127,8 @@ function assertBindable(host) {
     }
 }
 async function assertNoLiveServer(hippoRoot) {
-    // Refuse to start if a live hippo server already serves this hippoRoot.
-    // detectServer probes the recorded /health — a stale pidfile is unlinked and
-    // ignored, but a live peer means a concurrent `hippo serve` would race for
-    // the port and clobber the pidfile.
+    // Refuse to start if a live hippo server already serves this hippoRoot (detectServer probes the recorded /health and unlinks a stale pidfile):
+    // a concurrent `hippo serve` would race for the port and clobber the pidfile.
     const existing = await detectServer(hippoRoot);
     if (existing) {
         throw new Error(`hippo serve: already running on port ${existing.port} (pid ${existing.pid}). ` +
@@ -175,10 +144,8 @@ function bootRateLimiter(perAddress) {
         return undefined;
     if (perAddress !== undefined)
         return limiterFor(perAddress);
-    // Per-IP rate limiter for /v1/* and /mcp*. Built here (not at module scope) so
-    // HIPPO_V1_RPS is read at boot, matching HIPPO_PORT above and letting a test
-    // set the rate before serve(). A non-positive or non-finite value disables
-    // limiting (the opt-out knob).
+    // Per-IP rate limiter for /v1/* and /mcp*, built here (not at module scope) so HIPPO_V1_RPS is read at boot and a test can set it before serve().
+    // A non-positive or non-finite value disables limiting (the opt-out knob).
     const v1Rps = Number(envV1Rps() ?? 20);
     return Number.isFinite(v1Rps) && v1Rps > 0 ? limiterFor({ ratePerSec: v1Rps, burst: v1Rps * 2 }) : undefined;
 }
@@ -209,39 +176,7 @@ function createStoreHolder(hippoRoot, store) {
         log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
         return { hold: () => { }, afterResponse: () => { }, release: async () => { } };
     }
-    // Handlers open and close their own connections; while this one is held, none of those closes is SQLite's last,
-    // which checkpoints and deletes the WAL. It opens only once the store exists, so serving never creates one.
-    let heldDb;
-    let checkpointer;
-    let stopHolding = false;
-    const hold = () => {
-        if (heldDb || stopHolding || !existsSync(getHippoDbPath(hippoRoot)))
-            return;
-        try {
-            // The 'finish' listener can fire inside a request scope, which would close this connection with the request,
-            // and inside the block of a `loop: 'off'` route, which would refuse the open.
-            // The server's lock wait: this open runs on the event loop, where SQLite's 5 s default and the 30 s journal-mode retry would stall every request.
-            heldDb = outsideSqliteOffLoop(() => outsideRequestStores(() => openHippoDb(hippoRoot, { busyWaitMs: SERVER_DB_WAIT_MS })));
-            checkpointer = startWalCheckpointer(getHippoDbPath(hippoRoot));
-        }
-        catch (err) {
-            stopHolding = true;
-            log.warn(`serve: could not hold a store connection; requests still work, only slower: ${errorMessage(err)}`);
-        }
-    };
-    const afterResponse = () => {
-        hold();
-        checkpointer?.noteResponse();
-    };
-    const release = async () => {
-        stopHolding = true;
-        // The worker's connection closes first, so the held one is SQLite's last and its close checkpoints and deletes the WAL.
-        await checkpointer?.stop();
-        if (heldDb)
-            closeHippoDb(heldDb);
-        heldDb = undefined;
-    };
-    return { hold, afterResponse, release };
+    return holdSqliteConnection(hippoRoot);
 }
 // A plugin's resolver may read hippo.db through this package's synchronous functions, so it runs outside the block of a `loop: 'off'` route.
 function outsideRouteBlock(resolver) {
@@ -281,9 +216,23 @@ function replyWithFailure(req, res, err, requestId) {
     sendError(res, mapped.status, mapped.message);
 }
 const HANDLER_LATE = 'the request did not finish by its deadline and was abandoned; a write it started may or may not be saved';
-// The caller already has its 504, so a second reply would be written into a finished response.
-function logLateFailure(req, err) {
-    log.debug(`${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} ended after its deadline reply: ${errorMessage(err)}`);
+// The caller already has its 504, so this line is the only trace of the failure. The path and the error text can hold caller data, so it carries neither.
+function logLateFailure(req, err, requestId) {
+    const fields = { requestId, method: req.method ?? 'GET', route: accessRouteOf(req), failureStatus: replyFor(err).status };
+    log.warn('request failed after its deadline reply', { ...fields, errorClass: errorFields(err).errorClass });
+}
+// A handler that ends after the 504 finds the response finished, so sending its own reply throws this: its work ran to the end.
+function isDroppedLateReply(err) {
+    return err instanceof Error && 'code' in err && err.code === 'ERR_HTTP_HEADERS_SENT';
+}
+/** A GET only reads; every other method this server routes can write. */
+const isRead = (method) => method === 'GET';
+// A read that ends late changed nothing. A write that ends late ran to its end after its caller was told it may not have been saved.
+function logLateFinish(req, requestId) {
+    const method = req.method ?? 'GET';
+    if (isRead(method))
+        return;
+    log.info('request finished after its deadline reply; its own reply was dropped', { requestId, method, route: accessRouteOf(req) });
 }
 function replyOrClose(req, res, err, requestId) {
     try {
@@ -291,7 +240,7 @@ function replyOrClose(req, res, err, requestId) {
     }
     catch (replyErr) {
         // A throw here would be an unhandled rejection, which stops the daemon for every caller.
-        log.error(`serve: failure reply not sent, socket closed: ${errorMessage(replyErr)}`);
+        log.error(`serve: failure reply not sent, socket closed: ${errorMessage(replyErr)}`, errorFields(replyErr));
         res.destroy();
     }
 }
@@ -303,24 +252,19 @@ function answerRequest(req, res, handle, slowWarnMs) {
     runWithRequestId(requestId, () => {
         if (deadline)
             answerAtDeadline(res, deadline, () => replyOrClose(req, res, new DeadlineExceededError(HANDLER_LATE), requestId));
-        handle().catch((err) => {
+        handle().then(() => {
             if (isAbandoned(res))
-                logLateFailure(req, err);
-            else
+                logLateFinish(req, requestId);
+        }, (err) => {
+            if (!isAbandoned(res))
                 replyOrClose(req, res, err, requestId);
+            else if (isDroppedLateReply(err))
+                logLateFinish(req, requestId);
+            else
+                logLateFailure(req, err, requestId);
         });
     }, deadline);
 }
-// Node's own default, named so the three socket deadlines read together. It times the request arriving, never the handler, so a 10 minute sleep is not cut.
-const REQUEST_RECEIVE_TIMEOUT_MS = 300_000;
-function setKeepAliveTimeouts(server) {
-    // The default 5s keepAliveTimeout closes idle sockets just as clients reuse them (ECONNRESET).
-    // headersTimeout must stay ABOVE keepAliveTimeout + keepAliveTimeoutBuffer (1s), or it closes idle reused sockets itself.
-    server.keepAliveTimeout = 65_000;
-    server.headersTimeout = 70_000;
-    // Never below what a raised body deadline allows, or Node's bare 408 would come before the route's own.
-    server.requestTimeout = Math.max(REQUEST_RECEIVE_TIMEOUT_MS, server.headersTimeout + bodyDeadlineMs());
-}
 function listenOn(server, port, host) {
     return new Promise((resolve, reject) => {
         const onError = (err) => {
@@ -338,57 +282,23 @@ function listenOn(server, port, host) {
         server.listen(port, host);
     });
 }
-function installSignalHandlers(stop) {
-    let shuttingDown = false;
-    const gracefulShutdown = async (signal) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        log.warn(`received ${signal}, shutting down`);
-        try {
-            await stop();
-            process.exit(0);
-        }
-        catch (err) {
-            log.error(`error during stop: ${errorMessage(err)}`, errorFields(err));
-            process.exit(1);
-        }
-    };
-    process.once('SIGTERM', () => { void gracefulShutdown('SIGTERM'); });
-    process.once('SIGINT', () => { void gracefulShutdown('SIGINT'); });
+function exitOnSignalOrCrash(stop, drainMs) {
+    const shutdown = { run: stop, boundMs: shutdownBoundMs(drainMs) };
+    installSignalHandlers('serve', shutdown);
+    installCrashHandlers('serve', shutdown);
 }
-/**
- * Boot the HTTP daemon on host:port and write the pidfile under hippoRoot.
- *
- * Refuses non-loopback hosts at boot unless
- * HIPPO_REQUIRE_AUTH=1 is set. The auth middleware (buildContextWithAuth /
- * requireAuth) has shipped and every route checks it except GET /health
- * (public by design for platform health checks) and the two connector
- * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing
- * secrets and 404 when those secrets are unset, and any publicJson GET path. But the loopback
- * no-auth fallback inside buildContextWithAuth still admits unauthenticated
- * requests from a loopback remote address (unless they carry Forwarded,
- * X-Forwarded-For/-Host/-Proto, X-Real-IP, Cf-Connecting-Ip, True-Client-Ip or Fly-Client-Ip, which mark a same-host proxy and get
- * a 401 like any keyless remote request), so binding to a non-loopback host
- * is only safe once that fallback is disabled with HIPPO_REQUIRE_AUTH=1,
- * which forces every request (loopback or not) through Bearer-token
- * validation. Without that env var set, a non-loopback bind would expose the
- * DB to the network with no auth, so we fail fast instead.
- *
- * Use port: 0 in tests to bind to an ephemeral port and read the actual
- * port back via server.address() after listen.
- */
+/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses non-loopback hosts unless HIPPO_REQUIRE_AUTH=1.
+ * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export async function serve(opts) {
-    const host = opts.host ?? '127.0.0.1';
-    const requestedPort = opts.port ?? Number(envPort() ?? 6789);
+    const host = opts.host ?? DEFAULT_SERVER_HOST;
+    const requestedPort = opts.port ?? Number(envPort() ?? DEFAULT_SERVER_PORT);
     const routes = frozenAddonRoutes(opts.routes);
     const publicJsonBodies = assertPublicJson(opts.publicJson ?? {});
     const limiters = bootLimiters(opts.rateLimits);
     assertBindable(host);
     await assertNoLiveServer(opts.hippoRoot);
-    // The server's start time. Single source of truth: it is returned by every
-    // GET /health response and (below) written into the pidfile, so detectServer
-    // can match the two and prove a pid-reusing impostor is not the real server.
+    // Single source of truth for the start time: returned by GET /health and written into the pidfile, so detectServer can prove a pid-reusing impostor is not
+    // this server.
     const startedAt = new Date().toISOString();
     // Open /mcp/stream count per client key, so the cap is per server rather than per process.
     const streamSlots = new Map();
@@ -414,15 +324,15 @@ export async function serve(opts) {
             await served.store.close();
         await holder.release();
     };
-    if (opts.handleSignals) {
-        installSignalHandlers(stop);
-        installCrashHandlers('serve', stop);
-    }
+    if (opts.handleSignals)
+        exitOnSignalOrCrash(stop, opts.shutdownDrainMs ?? DEFAULT_SHUTDOWN_DRAIN_MS);
     return { port: actualPort, url, stop, server };
 }
 function frozenAddonRoutes(addonRoutes) {
     // A frozen copy, so a route the caller adds or renames after boot never skips the check below.
-    const routes = Object.freeze((addonRoutes ?? []).map(({ path, handler, storeReady }) => Object.freeze(storeReady === undefined ? { path, handler } : { path, handler, storeReady })));
+    const routes = Object.freeze((addonRoutes ?? []).map(({ path, handler, storeReady }) => Object.freeze(storeReady === undefined
+        ? { path, handler }
+        : { path, handler, storeReady })));
     assertAddonRoutes(routes);
     return routes;
 }
@@ -456,10 +366,8 @@ async function listenAndDescribe(server, port, host, tls) {
     return { port: actualPort, url };
 }
 async function stopListening(opts, server, inflight, startedAt) {
-    // Remove the pidfile only if it still names this server. A newer server
-    // may have started on this hippoRoot and rewritten the pidfile; an
-    // unconditional unlink here would orphan it.
+    // Remove the pidfile only if it still names this server: a newer server may have rewritten it, and an unconditional unlink would orphan it.
     removePidfileIfOwned(opts.hippoRoot, { pid: process.pid, startedAt });
-    await drainAndClose(server, inflight, opts.shutdownDrainMs ?? 5000);
+    await drainAndClose(server, inflight, opts.shutdownDrainMs ?? DEFAULT_SHUTDOWN_DRAIN_MS);
 }
 //# sourceMappingURL=boot.js.map

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

@@ -1,30 +1,12 @@
 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.
- */
+ * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated traffic can drain.
+ * Set HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) only when a trusted proxy fronts EVERY request, or clients could mint a fresh bucket per request.
+ * HIPPO_TRUSTED_PROXIES (IPs or CIDRs) pins which peers count as that proxy; in a comma-joined chain the key is the rightmost hop no trusted proxy added. */
 export declare function clientIpForRateLimit(req: IncomingMessage): string;
 /** Said once at boot: with no proxy list, a caller that reaches the port without the proxy picks its own bucket by sending the header. */
 export declare function warnIfClientIpHeaderUnpinned(): void;
-/** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
-export declare function subscriberKey(ip: string): string;
 /** The one key every per-address limit and slot count uses, so rotating inside a /64 never buys a fresh bucket. */
 export declare function clientLimitKey(req: IncomingMessage): string;
 export declare function enforceRateLimit(req: IncomingMessage, path: string, limiter?: RateLimiter): void;