hippo-memory 1.70.0 → 1.72.0

package/dist/server/client-ip.js

@@ -5,25 +5,9 @@ import { log } from '../util/log.js';
 import { HttpError } from '../util/http-util.js';
 const IPV6_PREFIX_GROUPS = 4;
 /**
- * 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 function clientIpForRateLimit(req) {
     const socketIp = req.socket.remoteAddress ?? 'unknown';
     const header = envClientIpHeader();
@@ -73,11 +57,12 @@ export function warnIfClientIpHeaderUnpinned() {
     const header = envClientIpHeader();
     if (!header || trustedProxyList(envTrustedProxies()))
         return;
-    log.warn(`serve: HIPPO_CLIENT_IP_HEADER is ${header} and HIPPO_TRUSTED_PROXIES is unset, so any caller that reaches this port without passing the proxy can send that header and pick its own rate-limit bucket. ` +
+    log.warn(`serve: HIPPO_CLIENT_IP_HEADER is ${header} and HIPPO_TRUSTED_PROXIES is unset, so any caller that reaches this port ` +
+        `without passing the proxy can send that header and pick its own rate-limit bucket. ` +
         "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, so the header is read from the proxy alone.");
 }
 /** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
-export function subscriberKey(ip) {
+function subscriberKey(ip) {
     const bare = ip.split('%')[0];
     if (bare.toLowerCase().startsWith('::ffff:') && isIP(bare.slice(7)) === 4)
         return bare.slice(7);
@@ -101,15 +86,8 @@ function isTrustedProxy(list, ip) {
     return family !== 0 && list.check(bare, family === 6 ? 'ipv6' : 'ipv4');
 }
 export function enforceRateLimit(req, path, limiter) {
-    // 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).
+    // Per-IP rate limit on /v1/* and /mcp* to bound api-key-id enumeration; /health and other paths are never throttled, and a 429 lands in the createServer
+    // catch. Keyed per clientIpForRateLimit (set HIPPO_CLIENT_IP_HEADER behind a TLS-terminating proxy, or all clients share one bucket).
     if (limiter && (path.startsWith('/v1/') || path === '/mcp' || path === '/mcp/stream')) {
         if (!limiter.check(clientLimitKey(req))) {
             throw new HttpError(429, 'rate limit exceeded', limiter.retryAfterSec);

package/dist/server/deadline.d.ts

@@ -4,8 +4,6 @@ import { RequestDeadline } from '../util/request-scope.js';
 export declare function handlerDeadlineCount(): number;
 /** Whether `res` was answered at its deadline, so whatever its handler does later has no caller. */
 export declare function isAbandoned(res: ServerResponse): boolean;
-/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
-export declare function requestDeadlineMs(): number;
 /** The deadline of `req`, for every /v1 and /mcp route but the two exempt ones. */
 export declare function requestDeadlineFor(req: IncomingMessage): RequestDeadline | undefined;
 /** Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the store knows what became of a write. */

package/dist/server/deadline.js

@@ -1,6 +1,4 @@
-import { envRequestDeadlineMs } from '../util/env.js';
-import { RequestDeadline } from '../util/request-scope.js';
-const DEFAULT_REQUEST_DEADLINE_MS = 120_000;
+import { RequestDeadline, requestDeadlineMs } from '../util/request-scope.js';
 // Each has a deadline of its own kind: sleep stops its child process, and the stream is meant to stay open.
 const EXEMPT = new Set(['POST /v1/sleep', 'GET /mcp/stream']);
 const abandoned = new WeakSet();
@@ -13,10 +11,6 @@ export function handlerDeadlineCount() {
 export function isAbandoned(res) {
     return abandoned.has(res);
 }
-/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
-export function requestDeadlineMs() {
-    return envRequestDeadlineMs() ?? DEFAULT_REQUEST_DEADLINE_MS;
-}
 /** The deadline of `req`, for every /v1 and /mcp route but the two exempt ones. */
 export function requestDeadlineFor(req) {
     const ms = requestDeadlineMs();

package/dist/server/defaults.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_SERVER_PORT = 6789;
+export declare const DEFAULT_SERVER_HOST = "127.0.0.1";
+export declare const DEFAULT_DASHBOARD_PORT = 3333;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/server/defaults.js

@@ -0,0 +1,5 @@
+// `hippo serve` reads these without loading the server, so the CLI and serve() cannot disagree on a default.
+export const DEFAULT_SERVER_PORT = 6789;
+export const DEFAULT_SERVER_HOST = '127.0.0.1';
+export const DEFAULT_DASHBOARD_PORT = 3333;
+//# sourceMappingURL=defaults.js.map

package/dist/server/key-check-bounds.d.ts

@@ -1,5 +1,6 @@
 export interface KeyCheckBounds {
-    /** Throws the 429 a refused key check answers, before any derivation: no room left to wait (Retry-After 1), or `address` has spent its tries on `keyId` (Retry-After 12). */
+    /** Throws the 429 a refused key check answers, before any derivation: no room left to
+     * wait (Retry-After 1), or `address` has spent its tries on `keyId` (Retry-After 12). */
     admit(keyId: string, address: string): void;
     /** Runs `derive` now or once a slot frees; `admit` in the same tick keeps the queue within its cap. */
     run<T>(derive: () => Promise<T>): Promise<T>;

package/dist/server/lifecycle.d.ts

@@ -1,7 +1,8 @@
 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 setKeepAliveTimeouts(server: Server): void;
+export declare const DEFAULT_SHUTDOWN_DRAIN_MS = 5000;
+/** How long a signal or crash shutdown may run before the process is ended without it. */
+export declare function shutdownBoundMs(drainMs: number): number;
+/** Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to `drainMs`, then closes what 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

@@ -1,8 +1,23 @@
+import { bodyDeadlineMs } from '../util/http-util.js';
 import { log } from '../util/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.
- */
+// 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;
+export 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());
+}
+export const DEFAULT_SHUTDOWN_DRAIN_MS = 5000;
+// Past the request drain, a stop only waits for each store thread to end its statement and close: seconds at most, so longer means a thread that will not end.
+const STORE_CLOSE_GRACE_MS = 10_000;
+/** How long a signal or crash shutdown may run before the process is ended without it. */
+export function shutdownBoundMs(drainMs) {
+    return drainMs + STORE_CLOSE_GRACE_MS;
+}
+/** Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to `drainMs`, then closes what is left. */
 export async function drainAndClose(server, inflight, drainMs) {
     const closed = new Promise((resolve, reject) => {
         server.close((err) => (err ? reject(err) : resolve()));

package/dist/server/mcp-http.js

@@ -1,54 +1,30 @@
 // MCP over HTTP: POST /mcp and the GET /mcp/stream SSE keepalive.
 import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '../util/env.js';
-import { createHash } from 'node:crypto';
 import { isSharedStore } from '../core/config.js';
 import { handleMcpRequest, mcpErrorResponse } from '../mcp/server.js';
 import { HttpError, readBody, sendJson } from '../util/http-util.js';
+import { log } from '../util/log.js';
 import { assertCallerProject } from '../core/project-identity.js';
 import { buildContextWithAuth, heartbeatVerdict, readAuthHeader, requireAuth } from './auth.js';
-import { clientLimitKey, subscriberKey } from './client-ip.js';
+import { clientLimitKey } from './client-ip.js';
 import { noteAccess } from './request.js';
 import { isJsonString, isJsonObject } from '../util/json.js';
-import { FINGERPRINT_HEX_CHARS } from '../util/token-text.js';
-const DEFAULT_SSE_HEARTBEAT_MS = 60000;
+import { blockHash } from '../util/token-text.js';
+import { consolidateInChild } from './sleep-offload.js';
+const DEFAULT_SSE_HEARTBEAT_MS = 60_000;
 const DEFAULT_SSE_MAX_AGE_SEC = 3600;
-/**
- * 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.
- */
+/** Per-client key for MCP state isolation under HTTP-MCP (scopes `lastRecalledIds`): sha256 of the token (16 hex chars, so the raw bearer is never logged)
+ * plus the client address the rate limiter keys on, so clients sharing a key stay separable behind a trusted proxy too; 'noauth' covers loopback no-auth. */
 function buildMcpClientKey(req) {
     const auth = readAuthHeader(req);
     const tokenHash = auth.kind === 'bearer'
-        ? createHash('sha256').update(auth.token).digest('hex').slice(0, FINGERPRINT_HEX_CHARS)
+        ? blockHash(auth.token)
         : 'noauth';
-    const addr = subscriberKey(req.socket.remoteAddress ?? 'unknown');
-    return `http:${tokenHash}:${addr}`;
+    return `http:${tokenHash}:${clientLimitKey(req)}`;
 }
-// ── MCP-over-HTTP/SSE transport ──
-//
-// 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.
+// MCP-over-HTTP/SSE: POST /mcp answers a JSON-RPC request synchronously; GET /mcp/stream is a keepalive-only SSE stream
+// (`: ping` every DEFAULT_SSE_HEARTBEAT_MS, 60 s) in v1.
+// Both dispatch to handleMcpRequest as stdio does. Auth matches /v1/* (Bearer via `requireAuth`, loopback fallback); SSE is checked once at stream-open.
 // Percent-encoded by the client, so any lowercase Unicode name fits a Latin-1 header.
 const HEADER_PIECE = /^[A-Za-z0-9\-_.!~*'()%]+$/;
 function decodeHeaderPiece(raw, header) {
@@ -95,17 +71,15 @@ function mcpContextFor(ctx, clientKey, autoSleep, project) {
         clientKey,
         store: ctx.store,
         autoSleep,
+        autoSleepRunner: consolidateInChild,
     };
     if (project !== undefined)
         mcpCtx.project = project;
     return mcpCtx;
 }
 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.
+    // Same Context the /v1/* routes use, so MCP tool calls inherit the bound hippoRoot and the auth-resolved tenantId/actor; otherwise executeTool would walk
+    // from cwd and read HIPPO_TENANT, dropping a valid Bearer for tenant B to the env's tenant.
     const ctx = await buildContextWithAuth(req, opts);
     noteAccess(req, { tenant: ctx.tenantId });
     const project = callerProjectFromHeaders(req, ctx.hippoRoot);
@@ -120,16 +94,16 @@ export async function handleMcpPost(req, res, opts) {
     if (!isJsonObject(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.
+    // SAFETY: validated above as a plain JSON object with a string method; the other McpRequest wire fields (jsonrpc, id, params) are checked or defaulted in
+    // handleMcpRequest.
     const rpcReq = mcpReq;
     let mcpRes;
     try {
         mcpRes = await handleMcpRequest(rpcReq, mcpContextFor(ctx, buildMcpClientKey(req), opts.autoSleep, project));
     }
     catch (err) {
-        mcpRes = mcpErrorResponse(rpcReq.id, err);
+        const tool = rpcReq.params?.name;
+        mcpRes = mcpErrorResponse(rpcReq.id, err, undefined, isJsonString(tool) ? `${rpcReq.method} ${tool.slice(0, 128)}` : rpcReq.method);
     }
     if (mcpRes === null) {
         // Notification — no body, 202 Accepted.
@@ -145,7 +119,7 @@ const DEFAULT_MAX_STREAMS_PER_CLIENT = 8;
 function streamSlotKey(req) {
     const auth = readAuthHeader(req);
     if (auth.kind === 'bearer')
-        return `key:${createHash('sha256').update(auth.token).digest('hex').slice(0, FINGERPRINT_HEX_CHARS)}`;
+        return `key:${blockHash(auth.token)}`;
     return `ip:${clientLimitKey(req)}`;
 }
 /** Takes a stream slot or throws 429; the slot is released once, when the response closes. */
@@ -178,13 +152,8 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
     // Initial ping so smoke tests can confirm the stream is live without
     // waiting for the first keepalive interval.
     res.write(': ping\n\n');
-    // 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.
+    // SSE hardening: the heartbeat re-validates the bearer (MCP_SSE_HEARTBEAT_MS, default 60000) and closes with 'auth_revoked' if the key was revoked or
+    // rotated; MCP_SSE_MAX_AGE_SEC (default 3600) caps stream lifetime and closes with 'max_age_exceeded'.
     keepStreamAlive(req, res, opts);
 }
 function keepStreamAlive(req, res, opts) {
@@ -214,6 +183,8 @@ function keepStreamAlive(req, res, opts) {
         checking = true;
         void heartbeatVerdict(req, opts).then((verdict) => {
             checking = false;
+            if (!closed && verdict === 'unavailable')
+                log.warn('heartbeat tick skipped: auth check unavailable');
             if (closed || verdict === 'unavailable')
                 return;
             if (verdict === 'revoked') {

package/dist/server/rate-limit.d.ts

@@ -1,16 +1,7 @@
-/**
- * Per-key token-bucket rate limiter for inbound /v1/* requests.
- *
- * Bounds api-key-id enumeration: a
- * client that drains its bucket is denied until it refills. Dependency-free
- * and unit-testable in isolation via the injectable `now`.
- */
+/** Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the injectable `now` makes it
+ * unit-testable. */
 export interface RateLimiter {
-    /**
-     * Consume one token for `key`. Returns true if the request is allowed,
-     * false if the key's bucket is exhausted. `now` (epoch ms) is injectable
-     * for deterministic tests.
-     */
+    /** Consume one token for `key`: true if allowed, false if the bucket is exhausted; `now` (epoch ms) is injectable for deterministic tests. */
     check(key: string, now?: number): boolean;
     readonly retryAfterSec: number;
 }
@@ -24,11 +15,7 @@ export interface RateLimiterOpts {
     /** Hard cap on tracked keys; the least-recently-used key is evicted on overflow. */
     maxKeys: number;
 }
-/**
- * Build a token-bucket limiter. Memory is bounded two ways: a sweep (throttled
- * to once per `idleEvictMs`) drops idle buckets, and a hard `maxKeys` cap evicts
- * the least-recently-used key, so a client rotating source addresses cannot
- * grow the map without bound between sweeps.
- */
+/** Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys` cap evicts the least-recently-used
+ * key, so a client rotating source addresses cannot grow the map without bound. */
 export declare function createRateLimiter(opts: RateLimiterOpts): RateLimiter;
 //# sourceMappingURL=rate-limit.d.ts.map

package/dist/server/rate-limit.js

@@ -1,16 +1,7 @@
-/**
- * Per-key token-bucket rate limiter for inbound /v1/* requests.
- *
- * Bounds api-key-id enumeration: a
- * client that drains its bucket is denied until it refills. Dependency-free
- * and unit-testable in isolation via the injectable `now`.
- */
-/**
- * Build a token-bucket limiter. Memory is bounded two ways: a sweep (throttled
- * to once per `idleEvictMs`) drops idle buckets, and a hard `maxKeys` cap evicts
- * the least-recently-used key, so a client rotating source addresses cannot
- * grow the map without bound between sweeps.
- */
+/** Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the injectable `now` makes it
+ * unit-testable. */
+/** Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys` cap evicts the least-recently-used
+ * key, so a client rotating source addresses cannot grow the map without bound. */
 export function createRateLimiter(opts) {
     const { ratePerSec, burst, idleEvictMs, maxKeys } = opts;
     const buckets = new Map();

package/dist/server/request.d.ts

@@ -13,6 +13,8 @@ interface AccessNote {
 }
 /** Names the matched route (the table's pattern, never the path sent) or the caller's tenant for the request's access line. */
 export declare function noteAccess(req: IncomingMessage, note: AccessNote): void;
+/** The route name the request's access line carries, for a line about the same request logged after its reply. */
+export declare function accessRouteOf(req: IncomingMessage): string;
 /** The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the access line. */
 export declare function openRequest(req: IncomingMessage, res: ServerResponse, slowWarnMs?: number): string;
 export declare function sendError(res: ServerResponse, status: number, message: string): void;
@@ -23,14 +25,8 @@ interface ParsedRoute {
 }
 export declare function parseRequest(req: IncomingMessage): ParsedRoute;
 export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-/**
- * Reject URL-encoded slashes in path segments BEFORE the URL parser decodes
- * them — otherwise `%2F` becomes `/`, path-split runs, and the route either
- * silently 404s or matches the wrong template.
- *
- * Only the PATHNAME is scanned (split on the first `?`), so recall queries
- * containing URLs like `?q=https%3A%2F%2Fexample.com` are not rejected.
- */
+/** Rejects URL-encoded slashes in path segments BEFORE the URL parser decodes them (`%2F` would become `/` and 404 or match the wrong template).
+ * Only the PATHNAME is scanned, so recall queries like `?q=https%3A%2F%2Fexample.com` are not rejected. */
 export declare function rejectEncodedSlash(rawUrl: string): void;
 export {};
 //# sourceMappingURL=request.d.ts.map

package/dist/server/request.js

@@ -1,7 +1,9 @@
 import { randomUUID } from 'node:crypto';
-import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db/index.js';
+import { STORE_BUSY_MESSAGE } from '../store/port.js';
+import { isStoreBusy } from '../store/sqlite/busy.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
-import { HttpError, mapApiError, sendJson } from '../util/http-util.js';
+import { mapApiError } from '../api/error-reply.js';
+import { HttpError, sendJson } from '../util/http-util.js';
 // The caller's id lands in a response header and in logs, so only a short plain token is echoed back.
 const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 /** The caller's `X-Request-Id` when it is a short plain token, else a fresh UUID. */
@@ -18,6 +20,9 @@ export function logRequestFailure(req, err, status) {
         log.warn(line, { status });
     else if (status >= 500 && status !== 501)
         log.error(line, { status, ...errorFields(err) });
+    // A failed login is the one 4xx an operator needs by default; the id (never the credential) is stamped from the request scope.
+    else if (status === 401 || status === 403)
+        log.warn(line, { status });
     else
         log.info(line, { status });
 }
@@ -27,7 +32,8 @@ export function replyFor(err) {
 }
 // Above the 30 s body deadline and the 5 s resolver deadline, so a request those govern is answered before it is called slow.
 const SLOW_REQUEST_WARN_MS = 60_000;
-/** Logs one warn when `res` has sent nothing after `afterMs`. It never ends the request or touches the reply; the timer goes when the reply finishes or the socket closes. */
+/** Logs one warn when `res` has sent nothing after `afterMs`. It never ends the request
+ * or touches the reply; the timer goes when the reply finishes or the socket closes. */
 function watchSlowRequest(req, res, requestId, afterMs = SLOW_REQUEST_WARN_MS) {
     const startedAt = Date.now();
     const timer = setTimeout(() => {
@@ -51,6 +57,10 @@ export function noteAccess(req, note) {
     if (held)
         Object.assign(held, note);
 }
+/** The route name the request's access line carries, for a line about the same request logged after its reply. */
+export function accessRouteOf(req) {
+    return accessNotes.get(req)?.route ?? UNMATCHED_ROUTE;
+}
 /** One info line per finished request. A path id and a query string can both hold caller data, so the line carries neither. */
 function logAccessWhenFinished(req, res, requestId) {
     const note = {};
@@ -97,14 +107,7 @@ export function parseRequest(req) {
         query: url.searchParams,
     };
 }
-/**
- * Lightweight pattern matcher for /v1/memories/:id/<action>. Avoids pulling
- * in a router dependency for the half-dozen patterns we actually use.
- *
- * Returns null if `path` does not match `pattern`. Otherwise returns an object
- * mapping each :param name to its value. Path segments are exact-matched
- * except for parameter slots.
- */
+/** Pattern matcher for /v1/memories/:id/<action> (no router dependency); null if `path` does not match, else each :param name mapped to its value. */
 function decodePathSegment(segment) {
     try {
         return decodeURIComponent(segment);
@@ -135,14 +138,8 @@ export function matchPath(pattern, path) {
     }
     return params;
 }
-/**
- * Reject URL-encoded slashes in path segments BEFORE the URL parser decodes
- * them — otherwise `%2F` becomes `/`, path-split runs, and the route either
- * silently 404s or matches the wrong template.
- *
- * Only the PATHNAME is scanned (split on the first `?`), so recall queries
- * containing URLs like `?q=https%3A%2F%2Fexample.com` are not rejected.
- */
+/** Rejects URL-encoded slashes in path segments BEFORE the URL parser decodes them (`%2F` would become `/` and 404 or match the wrong template).
+ * Only the PATHNAME is scanned, so recall queries like `?q=https%3A%2F%2Fexample.com` are not rejected. */
 export function rejectEncodedSlash(rawUrl) {
     const queryIdx = rawUrl.indexOf('?');
     const pathname = queryIdx === -1 ? rawUrl : rawUrl.slice(0, queryIdx);

package/dist/server/route-checks.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue } from '../util/json.js';
+import type { AddonRoute } from './types.js';
+/** Boot-time check: an add-on path must be plain, unique and not one core serves, so no add-on shadows a core route or hides from dispatch. */
+export declare function assertAddonRoutes(routes: readonly AddonRoute[]): void;
+/** Boot-time check and serialization: a public path that a core GET route serves would open that route to anyone. */
+export declare function assertPublicJson(publicJson: Readonly<Record<string, JsonValue>>): ReadonlyMap<string, string>;
+//# sourceMappingURL=route-checks.d.ts.map

package/dist/server/route-checks.js

@@ -0,0 +1,42 @@
+import { V1_ROUTES, routeMatches } from './route-table.js';
+const PLAIN_SEGMENT_RE = /^[A-Za-z0-9._~-]+$/;
+function isPlainV1Path(path) {
+    return path.startsWith('/v1/') && new URL(path, 'http://h').pathname === path
+        && path.slice('/v1/'.length).split('/').every((segment) => PLAIN_SEGMENT_RE.test(segment));
+}
+// A plain path never holds a `%`, so matchPath cannot throw here.
+function isCorePath(method, path) {
+    return V1_ROUTES.some((route) => routeMatches(route, method, path) !== null);
+}
+/** Boot-time check: an add-on path must be plain, unique and not one core serves, so no add-on shadows a core route or hides from dispatch. */
+export function assertAddonRoutes(routes) {
+    const seen = new Set();
+    for (const { path } of routes) {
+        if (!isPlainV1Path(path))
+            throw new Error(`add-on route '${path}' is not a plain /v1/ path (segments use A-Z a-z 0-9 . _ ~ -)`);
+        if (seen.has(path))
+            throw new Error(`add-on route '${path}' is registered twice`);
+        if (isCorePath('POST', path))
+            throw new Error(`add-on route '${path}' is already served by core`);
+        seen.add(path);
+    }
+}
+const PUBLIC_JSON_MAX_BYTES = 64 * 1024;
+/** Boot-time check and serialization: a public path that a core GET route serves would open that route to anyone. */
+export function assertPublicJson(publicJson) {
+    const bodies = new Map();
+    for (const [path, value] of Object.entries(publicJson)) {
+        if (!isPlainV1Path(path))
+            throw new Error(`public JSON path '${path}' is not a plain /v1/ path (segments use A-Z a-z 0-9 . _ ~ -)`);
+        if (isCorePath('GET', path))
+            throw new Error(`public JSON path '${path}' is already served by core`);
+        const text = JSON.stringify(value);
+        if (text === undefined)
+            throw new Error(`public JSON at '${path}' is not JSON`);
+        if (Buffer.byteLength(text) > PUBLIC_JSON_MAX_BYTES)
+            throw new Error(`public JSON at '${path}' is over 64 KiB`);
+        bodies.set(path, text);
+    }
+    return bodies;
+}
+//# sourceMappingURL=route-checks.js.map

package/dist/server/route-table.d.ts

@@ -1,15 +1,16 @@
-import type { AddonRoute, ResolvedServeOpts, RouteRequest } from './types.js';
-import type { JsonValue } from '../util/json.js';
-export declare function isPublicRoute(method: string, path: string): boolean;
+import type { Route, RouteRequest } from './types.js';
+/** The /v1 routes in dispatch order; the first entry whose method and path match handles the request. Each row's `auth` is what the
+ *  dispatch gate proves before its handler runs, so a handler never checks the caller itself. */
+export declare const V1_ROUTES: readonly Route[];
+/** The route's run for this request, gate first, or null when method or path differ. The matcher runs before the method check,
+ *  as the inline route blocks did, so a malformed `%` escape still throws from matchPath on any method. */
+export declare function routeMatches(route: Route, method: string, path: string): ((r: RouteRequest) => Promise<void>) | null;
+/** The route as the access line names it; a regex route reads as its pattern would, so no line carries a caller's id. */
+export declare function routeLabel(route: Route): string;
 /** Run the first /v1 route whose method and path match. */
 export declare function dispatchV1Route(r: RouteRequest, method: string, path: string): Promise<boolean>;
-/** Boot-time check: an add-on path must be plain, unique and not one core serves, so no add-on shadows a core route or hides from dispatch. */
-export declare function assertAddonRoutes(routes: readonly AddonRoute[]): void;
-/** Boot-time check and serialization: a public path that a core GET route serves would open that route to anyone. */
-export declare function assertPublicJson(publicJson: Readonly<Record<string, JsonValue>>): ReadonlyMap<string, string>;
 /** Core authenticates and parses before the handler runs, so an add-on route gets the same 401, 400 and 501 as a core one. */
 export declare function dispatchAddonRoute({ req, res, opts }: RouteRequest, method: string, path: string): Promise<boolean>;
 /** No auth, body read or store access, so a caller with no key gets it under any store. */
 export declare function dispatchPublicJson({ req, res, opts }: RouteRequest, method: string, path: string): boolean;
-export declare function assertSqliteStore(opts: ResolvedServeOpts): void;
 //# sourceMappingURL=route-table.d.ts.map