hippo-memory 1.72.0 → 2.1.0

package/dist/server/auth.js

@@ -1,6 +1,8 @@
 // Bearer and loopback auth for the HTTP server.
-import { envAllowKeylessLocal, envRequireAuth } from '../util/env.js';
+import { envAllowKeylessLocal, envKeylessLocalRole, envRequireAuth } from '../util/env.js';
+import { loadConfig } from '../core/config.js';
 import { resolveTenantId } from '../store/tenant.js';
+import { sqliteReach } from '../store/sqlite/store.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { API_KEY_PREFIX, verifyApiKeyCached } from '../store/auth.js';
 import { ownerOrSubject } from '../api/index.js';
@@ -9,38 +11,40 @@ 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';
-/** 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;
-    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.
+import { MINUTE_MS } from '../util/time.js';
+import { isLoopbackAddress } from '../util/net.js';
+/** Kept under its old name because src/server.ts publishes it. */
+export const isLoopback = isLoopbackAddress;
+// 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',
+    'forwarded',
+    'x-forwarded-for',
+    'x-forwarded-host',
+    'x-forwarded-proto',
+    'x-real-ip',
+    'cf-connecting-ip',
+    'true-client-ip',
     'fly-client-ip',
 ];
 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). */
+/** 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. */
+/** 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);
+    return isLoopbackAddress(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.
+// 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))
+    if (!isLoopbackAddress(req.socket.remoteAddress))
         throw new HttpError(401, 'auth required');
     const proxyHeader = proxyHeaderOf(req);
     if (proxyHeader !== undefined) {
@@ -52,10 +56,11 @@ function assertLocalCaller(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. */
+/** 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.';
+    '"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)
@@ -149,7 +154,8 @@ async function askResolver(resolver, token, deadlineMs) {
     return clean;
 }
 const DEFAULT_RESOLVER_DEADLINE_MS = 5000;
-/** Runs only before scrypt, so junk, unknown, revoked and expired tokens and a proven key's re-check never spend a colleague's budget. */
+/** Runs only before scrypt, so junk, unknown, revoked and expired
+ * tokens and a proven key's re-check never spend a colleague's budget. */
 function chargeScryptRun(req, opts) {
     const limiter = opts.failedAuthLimiter;
     // Reserving rather than peeking bounds scrypt runs exactly, even when concurrent misses await a slow store.
@@ -164,17 +170,24 @@ async function resolveBearer(req, token, opts) {
         const t = opts.authResolverTimeoutMs;
         const deadlineMs = t !== undefined && Number.isFinite(t) && t > 0 ? t : DEFAULT_RESOLVER_DEADLINE_MS;
         const clean = await askResolver(opts.authResolver, token, deadlineMs);
-        return { ...clean, viaAuthResolver: true, owner: clean.subject }; // a resolver vouches for a person, never names one
+        // A resolver vouches for a person, never names one.
+        return { ...clean, viaAuthResolver: true, owner: clean.subject };
     }
     const key = await verifyApiKeyCached(token, opts.store, (keyId, derive) => {
-        // The key's own bucket first, so a flood on one key id ends at its five tries and leaves the address's budget to the callers who share it.
+        // The key's own bucket first, so a flood on one key id ends at its five tries and leaves the address's budget to
+        // the callers who share it.
         keyChecks.admit(keyId, clientLimitKey(req));
         chargeScryptRun(req, opts);
         return keyChecks.run(derive);
     });
     if (!key)
         throw new HttpError(401, 'invalid api key');
-    const id = { tenantId: key.tenantId, subject: `api_key:${key.keyId}`, role: key.role, scopes: key.scopes };
+    const id = {
+        tenantId: key.tenantId,
+        subject: `api_key:${key.keyId}`,
+        role: key.role,
+        scopes: key.scopes,
+    };
     if (key.ownerSubject)
         id.owner = key.ownerSubject;
     return id;
@@ -213,7 +226,7 @@ function bearerActor(id) {
 export const LIMITER_MAX_KEYS = 10_000;
 // One for the process, as the thread pool its derivations run on is.
 const keyChecks = keyCheckBounds(LIMITER_MAX_KEYS);
-const CALLER_WARN_EVERY_MS = 60_000;
+const CALLER_WARN_EVERY_MS = MINUTE_MS;
 const callerWarnedAt = new Map();
 function warnCallerLimited(key, tenantId, person) {
     const now = Date.now();
@@ -240,8 +253,8 @@ function chargeCaller(tenantId, actor, opts) {
     warnCallerLimited(key, tenantId, person);
     throw new HttpError(429, 'rate limit exceeded for this caller', limiter.retryAfterSec);
 }
-/** 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. */
+/** Builds a per-request Context from the Authorization header and remote address; throws HttpError(401) on bad ones.
+ * Reads the store only for an API-key-shaped Bearer (or any Bearer with no resolver), so keyless calls stay cheap. */
 export async function buildContextWithAuth(req, opts) {
     const id = await checkAuth(req, opts);
     const ctx = contextFor(id, opts);
@@ -249,29 +262,46 @@ export async function buildContextWithAuth(req, opts) {
         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. */
+/** 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);
 }
+/** The keyless local caller: any process on this machine can reach
+ * loopback, so it is a member unless the operator names admin. */
+function keylessLocalActor(opts) {
+    const role = opts.keylessLocalRole ?? envKeylessLocalRole();
+    return role === 'admin'
+        ? { subject: 'localhost:cli', role: 'admin', hostAdmin: true }
+        : { subject: 'localhost:cli', role: 'member' };
+}
 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.
+    // Per request, never cached at serve: the global store can be created while the server runs.
+    const reach = sqliteReach(opts.hippoRoot, opts.store);
+    // loadConfig caches by file mtime, so each request still sees an edit made while the server runs.
+    const config = loadConfig(opts.hippoRoot);
+    if (id !== null) {
+        const actor = bearerActor(id);
+        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor, store: opts.store, reach, config };
+    }
     return {
         hippoRoot: opts.hippoRoot,
         tenantId: resolveTenantId({}),
-        actor: { subject: 'localhost:cli', role: 'admin', hostAdmin: true },
+        actor: keylessLocalActor(opts),
         store: opts.store,
+        reach,
+        config,
     };
 }
-/** 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. */
+/** 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)
         chargeCaller(id.tenantId, bearerActor(id), opts);
 }
-/** Never rejects or charges a caller bucket: an outage (5xx) or a throttle (429) skips one tick; only a definite 4xx denial closes the stream. */
+/** Never rejects or charges a caller bucket: an outage (5xx) or a throttle (429) skips one tick; only a definite 4xx
+ * denial closes the stream. */
 export async function heartbeatVerdict(req, opts) {
     try {
         await checkAuth(req, opts);

package/dist/server/boot.d.ts

@@ -1,5 +1,8 @@
 import type { ServeOpts, ServerHandle } from './types.js';
-/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses non-loopback hosts unless HIPPO_REQUIRE_AUTH=1.
+/**
+ * Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless
+ * HIPPO_REQUIRE_AUTH=1 and
+ * either `tls` or allowCleartext is given, and refuses HIPPO_CLIENT_IP_HEADER without HIPPO_TRUSTED_PROXIES.
  * 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,20 +1,21 @@
-import { envPort, envRequireAuth, envV1Rps } from '../util/env.js';
+import { envAllowCleartext, envCallerRps, envPort, envRequireAuth, envV1Rps } from '../util/env.js';
 import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.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 { hasGroup } from '../store/index.js';
+import { isStoreBusy } from '../api/busy.js';
+import { createStoreHolder, offLoopFor, outsideRouteBlock, } 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';
 import { PACKAGE_VERSION } from '../util/version.js';
+import { MINUTE_MS } from '../util/time.js';
 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 { 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 { isLocalCaller, LIMITER_MAX_KEYS } from './auth.js';
-import { enforceRateLimit, warnIfClientIpHeaderUnpinned } from './client-ip.js';
+import { assertClientIpHeaderPinned, enforceRateLimit } from './client-ip.js';
 import { answerAtDeadline, handlerDeadlineCount, isAbandoned, requestDeadlineFor } from './deadline.js';
 import { DEFAULT_SHUTDOWN_DRAIN_MS, drainAndClose, setKeepAliveTimeouts, shutdownBoundMs } from './lifecycle.js';
 import { readyProbeFor } from './ready.js';
@@ -22,8 +23,8 @@ 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 { accessRouteOf, logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError } from './request.js';
-import { createListener, warnIfCleartext } from './tls.js';
+import { accessRouteOf, logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError, } from './request.js';
+import { assertTlsOrCleartextAllowed, createListener } from './tls.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
@@ -31,7 +32,8 @@ import { dispatchAddonRoute, dispatchPublicJson, dispatchV1Route } from './route
 function isAddressInfo(a) {
     return a !== null && typeof a !== 'string';
 }
-// Pinned at module load, bumped with package.json on releases; reading package.json synchronously here would couple the daemon to its install path,
+// 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']);
@@ -41,7 +43,8 @@ async function handleRequest(req, res, opts, options) {
     // Node's URL parser collapses them and they slip past the route table.
     rejectEncodedSlash(req.url ?? '/');
     const { method, path, query } = parseRequest(req);
-    // An older core ignores X-Hippo-Project, so every /mcp reply, a 429 or 401 too, tells the client this one filters by it.
+    // An older core ignores X-Hippo-Project, so every /mcp reply, a 429 or 401 too, tells the client this one filters by
+    // it.
     if (path === '/mcp')
         res.setHeader(MCP_PROJECT_SCOPED_HEADER, '1');
     if (method === 'GET' && path === '/health') {
@@ -56,19 +59,22 @@ async function handleRequest(req, res, opts, options) {
     }
     enforceRateLimit(req, path, limiter);
     const routeRequest = { req, res, opts, query };
-    if (await runWithRequestStores(() => dispatchScopedRoute(routeRequest, method, path), { busyWaitMs: SERVER_DB_WAIT_MS }))
+    if (await dispatchScopedRoute(routeRequest, method, path))
         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.
+    // The request scope (the server's lock wait) is kept by the heartbeat timer after it closes, so the key check and
+    // every heartbeat wait that long. 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 });
+        await handleMcpStream(req, res, opts, streamSlots);
         return;
     }
     res.writeHead(404, JSON_HEADERS);
     res.end(JSON.stringify({ error: 'not found' }));
 }
-/** 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. */
+/**
+ * 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;
@@ -86,8 +92,10 @@ async function dispatchScopedRoute(r, method, path) {
     return false;
 }
 function sendHealth(req, res, startedAt) {
-    // 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.
+    // 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,
@@ -127,7 +135,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 and unlinks a stale 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) {
@@ -135,53 +144,64 @@ async function assertNoLiveServer(hippoRoot) {
             `Stop that server before starting another on the same hippoRoot.`);
     }
 }
-// SHORTCUT: buckets live in this process and reset on restart or LRU eviction; move them to the store if serve ever runs as several processes.
+// SHORTCUT: buckets live in this process and reset on restart or LRU eviction; move them to the store if serve ever
+// runs as several processes.
 function limiterFor({ ratePerSec, burst }) {
-    return createRateLimiter({ ratePerSec, burst, idleEvictMs: 60000, maxKeys: LIMITER_MAX_KEYS });
+    return createRateLimiter({ ratePerSec, burst, idleEvictMs: MINUTE_MS, maxKeys: LIMITER_MAX_KEYS });
 }
 function bootRateLimiter(perAddress) {
     if (perAddress === 'off')
         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 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;
+    // 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 typo must not switch the limit off, so only an explicit 0 does.
+    const raw = envV1Rps();
+    const v1Rps = raw === undefined ? 20 : Number(raw);
+    if (!Number.isFinite(v1Rps) || v1Rps < 0) {
+        throw new Error(`HIPPO_V1_RPS must be a number of at least 0 (0 turns the per-address limit off), not '${raw}'`);
+    }
+    return v1Rps > 0 ? limiterFor({ ratePerSec: v1Rps, burst: v1Rps * 2 }) : undefined;
 }
 const DEFAULT_FAILED_AUTH = { ratePerSec: 20, burst: 40 };
 function assertRateLimitSpec(name, { ratePerSec, burst }) {
-    if (!Number.isFinite(ratePerSec) || ratePerSec <= 0)
+    if (!Number.isFinite(ratePerSec) || ratePerSec <= 0) {
         throw new Error(`rateLimits.${name}.ratePerSec must be a finite number above 0`);
-    if (!Number.isFinite(burst) || burst < 1)
+    }
+    if (!Number.isFinite(burst) || burst < 1) {
         throw new Error(`rateLimits.${name}.burst must be a finite number of at least 1`);
+    }
+}
+const DEFAULT_CALLER_RPS = 20;
+/**
+ * The per-caller spec when serve() names none: HIPPO_CALLER_RPS (0 is off), else 20 per second with a burst of twice
+ * that.
+ */
+function defaultCallerSpec() {
+    const raw = envCallerRps();
+    const rps = raw === undefined ? DEFAULT_CALLER_RPS : Number(raw);
+    // A typo must not switch the limit off, so only an explicit 0 does.
+    if (!Number.isFinite(rps) || rps < 0) {
+        throw new Error(`HIPPO_CALLER_RPS must be a number of at least 0 (0 turns the per-caller limit off), not '${raw}'`);
+    }
+    return rps === 0 ? 'off' : { ratePerSec: rps, burst: Math.max(1, rps * 2) };
 }
 /** Refuses a bad spec at boot, since a NaN or zero rate would otherwise turn a bucket off or refuse every request. */
 function bootLimiters(rateLimits) {
-    const { perCaller, perAddress, failedAuthPerAddress = DEFAULT_FAILED_AUTH } = rateLimits ?? {};
-    if (perCaller !== undefined)
+    const { perCaller = defaultCallerSpec(), perAddress, failedAuthPerAddress = DEFAULT_FAILED_AUTH } = rateLimits ?? {};
+    if (perCaller !== 'off')
         assertRateLimitSpec('perCaller', perCaller);
     if (perAddress !== undefined && perAddress !== 'off')
         assertRateLimitSpec('perAddress', perAddress);
     assertRateLimitSpec('failedAuthPerAddress', failedAuthPerAddress);
-    warnIfClientIpHeaderUnpinned();
+    assertClientIpHeaderPinned();
     return {
         perAddress: bootRateLimiter(perAddress),
-        callerLimiter: perCaller === undefined ? undefined : limiterFor(perCaller),
+        callerLimiter: perCaller === 'off' ? undefined : limiterFor(perCaller),
         failedAuthLimiter: limiterFor(failedAuthPerAddress),
     };
 }
-function createStoreHolder(hippoRoot, store) {
-    if (store.kind !== 'sqlite') {
-        log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
-        return { hold: () => { }, afterResponse: () => { }, release: async () => { } };
-    }
-    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) {
-    return resolver && ((token) => outsideSqliteOffLoop(() => resolver(token)));
-}
 function replyWithFailure(req, res, err, requestId) {
     const mapped = replyFor(err);
     logRequestFailure(req, err, mapped.status);
@@ -192,10 +212,12 @@ function replyWithFailure(req, res, err, requestId) {
         catch { /* socket already gone */ }
         return;
     }
-    if (isStoreBusy(err))
+    if (isStoreBusy(err)) {
         res.setHeader('Retry-After', '1');
-    else if (err instanceof HttpError && err.retryAfterSec !== undefined)
+    }
+    else if (err instanceof HttpError && err.retryAfterSec !== undefined) {
         res.setHeader('Retry-After', String(err.retryAfterSec));
+    }
     if (mapped.status === 500) {
         // The id lets an operator find the logged cause without the client seeing internal text.
         sendJson(res, 500, { error: mapped.message, requestId });
@@ -210,29 +232,43 @@ function replyWithFailure(req, res, err, requestId) {
         sendJson(res, 504, { error: err.message, code: err.code, requestId });
         return;
     }
-    // readBody hit its cap or deadline, so close once the 413 or 408 is out rather than drain what the client keeps sending.
-    if (err instanceof BodyTooLargeError || err instanceof BodyTimeoutError)
+    // readBody hit its cap or deadline, so close once the 413 or 408 is out rather than drain what the client keeps
+    // sending.
+    if (err instanceof BodyTooLargeError || err instanceof BodyTimeoutError) {
         res.once('finish', () => closeAfterReply(req));
+    }
     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 this line is the only trace of the failure. The path and the error text can hold caller data, so it carries neither.
+// 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 };
+    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.
+// 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.
+// 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) });
+    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 {
@@ -244,14 +280,19 @@ function replyOrClose(req, res, err, requestId) {
         res.destroy();
     }
 }
-/** Runs `handle` under the request's id and deadline; a failure becomes the reply, unless the deadline has already answered. */
+/**
+ * Runs `handle` under the request's id and deadline; a failure becomes the reply, unless the deadline has already
+ * answered.
+ */
 function answerRequest(req, res, handle, slowWarnMs) {
     const requestId = openRequest(req, res, slowWarnMs);
     const deadline = requestDeadlineFor(req);
+    const abort = deadline ? new AbortController() : undefined;
     // Inside the scope, so the failure reply's log line carries the id too.
     runWithRequestId(requestId, () => {
-        if (deadline)
-            answerAtDeadline(res, deadline, () => replyOrClose(req, res, new DeadlineExceededError(HANDLER_LATE), requestId));
+        if (deadline) {
+            answerAtDeadline(res, deadline, () => replyOrClose(req, res, new DeadlineExceededError(HANDLER_LATE), requestId), () => abort?.abort(new DeadlineExceededError(HANDLER_LATE)));
+        }
         handle().then(() => {
             if (isAbandoned(res))
                 logLateFinish(req, requestId);
@@ -263,7 +304,7 @@ function answerRequest(req, res, handle, slowWarnMs) {
             else
                 logLateFailure(req, err, requestId);
         });
-    }, deadline);
+    }, deadline, abort?.signal);
 }
 function listenOn(server, port, host) {
     return new Promise((resolve, reject) => {
@@ -287,7 +328,10 @@ function exitOnSignalOrCrash(stop, drainMs) {
     installSignalHandlers('serve', shutdown);
     installCrashHandlers('serve', shutdown);
 }
-/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses non-loopback hosts unless HIPPO_REQUIRE_AUTH=1.
+/**
+ * Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless
+ * HIPPO_REQUIRE_AUTH=1 and
+ * either `tls` or allowCleartext is given, and refuses HIPPO_CLIENT_IP_HEADER without HIPPO_TRUSTED_PROXIES.
  * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export async function serve(opts) {
     const host = opts.host ?? DEFAULT_SERVER_HOST;
@@ -296,15 +340,17 @@ export async function serve(opts) {
     const publicJsonBodies = assertPublicJson(opts.publicJson ?? {});
     const limiters = bootLimiters(opts.rateLimits);
     assertBindable(host);
+    assertTlsOrCleartextAllowed(host, opts.tls, LOOPBACK_HOSTS, opts.allowCleartext ?? envAllowCleartext());
     await assertNoLiveServer(opts.hippoRoot);
-    // 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
+    // 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();
     const served = servedOptsFor(opts, routes, publicJsonBodies, limiters);
     // A store other than hippo.db is a team's central server, so its folder's config.json must not decide shared-ness.
-    if (served.store.kind !== 'sqlite')
+    if (!hasGroup(served.store, 'localFiles'))
         markSharedStore(opts.hippoRoot);
     const holder = createStoreHolder(opts.hippoRoot, served.store);
     const inflight = new Set();
@@ -330,27 +376,29 @@ export async function serve(opts) {
 }
 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;
 }
 function servedOptsFor(opts, routes, publicJsonBodies, { callerLimiter, failedAuthLimiter }) {
+    const store = opts.store ?? workerSqliteStore(opts.hippoRoot);
     return {
-        ...opts, routes, publicJsonBodies, store: opts.store ?? workerSqliteStore(opts.hippoRoot), callerLimiter, failedAuthLimiter,
+        ...opts,
+        routes,
+        publicJsonBodies,
+        store,
+        offLoop: offLoopFor(store),
+        callerLimiter,
+        failedAuthLimiter,
         authResolver: outsideRouteBlock(opts.authResolver),
     };
 }
 function acceptingServer(served, holder, inflight, options) {
-    const { kind } = served.store;
     return createListener(served.tls, (req, res) => {
         res.once('finish', holder.afterResponse);
         inflight.add(res);
         res.once('close', () => inflight.delete(res));
-        const run = () => handleRequest(req, res, served, options);
-        // A missed port under another store would otherwise create and write a hippo.db that store never reads.
-        answerRequest(req, res, () => (kind === 'sqlite' ? run() : withSqliteBlocked(kind, run)), served.slowRequestWarnMs);
+        answerRequest(req, res, () => holder.runRequest(() => handleRequest(req, res, served, options)), served.slowRequestWarnMs);
     });
 }
 async function listenAndDescribe(server, port, host, tls) {
@@ -362,11 +410,11 @@ async function listenAndDescribe(server, port, host, tls) {
     const addressInfo = address;
     const actualPort = addressInfo.port;
     const url = `${tls ? 'https' : 'http'}://${host.includes(':') ? `[${host}]` : host}:${actualPort}`;
-    warnIfCleartext(host, tls, LOOPBACK_HOSTS);
     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 rewritten it, and an unconditional unlink 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 ?? DEFAULT_SHUTDOWN_DRAIN_MS);
 }

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

@@ -1,12 +1,24 @@
 import type { IncomingMessage } from 'node:http';
 import type { RateLimiter } from './rate-limit.js';
 /**
- * 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. */
+ * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated
+ * traffic can drain.
+ * HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) is read only from a peer in HIPPO_TRUSTED_PROXIES (IPs or CIDRs, or `*`
+ * for any peer),
+ * so a caller that reaches the port past the proxy cannot pick its own bucket. 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;
+/**
+ * serve() refused HIPPO_CLIENT_IP_HEADER with no HIPPO_TRUSTED_PROXIES: the header would be read from no one, so the
+ * setting is a mistake.
+ */
+export declare class UntrustedClientIpHeaderError extends Error {
+    readonly header: string;
+    constructor(header: string);
+}
+/** Checked at boot: a client-IP header needs a trusted-proxy list, and `*` is said once, since it believes any peer. */
+export declare function assertClientIpHeaderPinned(): void;
 /** 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;