hippo-memory 1.71.0 → 2.0.0

package/dist/server/client-ip.js

@@ -6,15 +6,15 @@ import { HttpError } from '../util/http-util.js';
 const IPV6_PREFIX_GROUPS = 4;
 /**
  * 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. */
+ * 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 function clientIpForRateLimit(req) {
     const socketIp = req.socket.remoteAddress ?? 'unknown';
     const header = envClientIpHeader();
     if (!header)
         return socketIp;
-    const trusted = trustedProxyList(envTrustedProxies());
-    if (trusted && !isTrustedProxy(trusted, socketIp))
+    const trust = proxyTrust(envTrustedProxies());
+    if (trust === undefined || (trust !== ANY_PEER && !isTrustedProxy(trust, socketIp)))
         return socketIp;
     const raw = req.headers[header];
     const hops = (Array.isArray(raw) ? raw.join(',') : raw ?? '')
@@ -22,20 +22,25 @@ export function clientIpForRateLimit(req) {
         .map((hop) => hop.trim())
         .filter((hop) => hop.length > 0);
     for (let i = hops.length - 1; i >= 0; i--) {
-        if (!trusted || !isTrustedProxy(trusted, hops[i]))
+        if (trust === ANY_PEER || !isTrustedProxy(trust, hops[i]))
             return hops[i];
     }
     return hops[0] ?? socketIp;
 }
+/** HIPPO_TRUSTED_PROXIES=*: every peer is the proxy, and the hop it appended is the client. */
+const ANY_PEER = '*';
 let trustedProxyCache;
-/** Parses HIPPO_TRUSTED_PROXIES once per distinct value; undefined when unset, so any peer may set the header. */
-function trustedProxyList(raw) {
-    if (!raw?.trim())
+/** Parses HIPPO_TRUSTED_PROXIES once per distinct value; undefined when unset, so no peer's header is read. */
+function proxyTrust(raw) {
+    const value = raw?.trim();
+    if (!value)
         return undefined;
-    if (trustedProxyCache?.raw === raw)
+    if (value === ANY_PEER)
+        return ANY_PEER;
+    if (trustedProxyCache?.raw === value)
         return trustedProxyCache.list;
     const list = new BlockList();
-    for (const entry of raw.split(',').map((e) => e.trim()).filter((e) => e.length > 0)) {
+    for (const entry of value.split(',').map((e) => e.trim()).filter((e) => e.length > 0)) {
         const [addr = '', prefix] = entry.split('/');
         const family = isIP(addr) === 6 ? 'ipv6' : 'ipv4';
         const bits = prefix === undefined ? undefined : Number(prefix);
@@ -49,19 +54,33 @@ function trustedProxyList(raw) {
         else
             list.addSubnet(addr, bits, family);
     }
-    trustedProxyCache = { raw, list };
+    trustedProxyCache = { raw: value, list };
     return list;
 }
-/** 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 function warnIfClientIpHeaderUnpinned() {
+/** 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 class UntrustedClientIpHeaderError extends Error {
+    header;
+    constructor(header) {
+        super(`hippo serve: HIPPO_CLIENT_IP_HEADER is ${header} but HIPPO_TRUSTED_PROXIES is unset, so no peer may set that header. ` +
+            "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, or to * when the proxy is the only peer that can reach this port.");
+        this.header = header;
+        this.name = 'UntrustedClientIpHeaderError';
+    }
+}
+/** Checked at boot: a client-IP header needs a trusted-proxy list, and `*` is said once, since it believes any peer. */
+export function assertClientIpHeaderPinned() {
     const header = envClientIpHeader();
-    if (!header || trustedProxyList(envTrustedProxies()))
+    if (!header)
         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. ` +
-        "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, so the header is read from the proxy alone.");
+    const trust = proxyTrust(envTrustedProxies());
+    if (trust === undefined)
+        throw new UntrustedClientIpHeaderError(header);
+    if (trust === ANY_PEER) {
+        log.warn(`serve: HIPPO_TRUSTED_PROXIES is *, so ${header} is read from any peer; keep the proxy the only route to this port.`);
+    }
 }
 /** 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);

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

@@ -1,3 +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

@@ -1,4 +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/mcp-http.js

@@ -1,28 +1,29 @@
 // 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;
 /** 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 remoteAddress, so clients sharing a key stay separable; 'noauth' covers loopback no-auth, which is single-host single-user. */
+ * 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: POST /mcp answers a JSON-RPC request synchronously; GET /mcp/stream is a keepalive-only SSE stream (`: ping` every 30s) in v1.
+// 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\-_.!~*'()%]+$/;
@@ -70,6 +71,7 @@ function mcpContextFor(ctx, clientKey, autoSleep, project) {
         clientKey,
         store: ctx.store,
         autoSleep,
+        autoSleepRunner: consolidateInChild,
     };
     if (project !== undefined)
         mcpCtx.project = project;
@@ -100,7 +102,8 @@ export async function handleMcpPost(req, res, opts) {
         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.
@@ -116,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. */
@@ -180,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/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 });
 }

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