hippo-memory 1.69.0 → 1.71.0

package/dist/search/rerank.js

@@ -1,4 +1,5 @@
-import { cosineSimilarity } from '../embeddings.js';
+import { cosineOf } from '../store/embeddings/index.js';
+const DEFAULT_RERANK_TOP_K = 50;
 // MMR is O(K^2) cosine ops; candidates below this window never survive budget filtering anyway.
 const MMR_CANDIDATE_CAP = 100;
 /** MMR: repeatedly picks the candidate maximising lambda * relevance - (1 - lambda) * max(cos(cand, picked)).
@@ -39,7 +40,7 @@ function maxSimilarityToPicked(vi, picked, embeddingIndex) {
         const vp = embeddingIndex[p.entry.id];
         if (!vp || vp.length !== vi.length)
             continue;
-        const sim = Math.max(0, cosineSimilarity(vi, vp));
+        const sim = Math.max(0, cosineOf(vi, vp));
         if (sim > maxSim)
             maxSim = sim;
     }
@@ -63,7 +64,7 @@ export function applyMmrWindow(scored, embeddingIndex, lambda, explain) {
 }
 /** Runs the reranker over the top `topK` (default 50) and stamps pre and post ranks; see src/rerankers/types.ts. */
 export async function applyReranker(query, ordered, reranker, rerankerOptions) {
-    const topK = rerankerOptions?.topK ?? 50;
+    const topK = rerankerOptions?.topK ?? DEFAULT_RERANK_TOP_K;
     const head = ordered.slice(0, topK).map((r, i) => ({ ...r, preRerankRank: i + 1 }));
     const tail = ordered.slice(topK);
     const reranked = await reranker(query, head, { ...rerankerOptions, topK });

package/dist/search/rrf.d.ts

@@ -0,0 +1,15 @@
+/** Reciprocal Rank Fusion (Cormack, Clarke and Buettcher 2009): fuses N ranked lists by summing weighted 1/(k + rank) per candidate. K is the standard 60,
+ * the value hybridSearch already uses; do NOT tune it without a cross-corpus eval. Generic over the id type (hybridSearch uses number, the LongMemEval
+ * benchmark string). Behaviour MUST stay byte-identical to the inline hybridSearch code it replaced; tests/rrf.test.ts is the contract. */
+export declare const RRF_K = 60;
+export interface RrfFuseOptions {
+    /** Smoothing constant. Default RRF_K = 60. */
+    k?: number;
+    /** Rank assigned to candidates absent from a list; default `max(rankedLists.map(l => l.length)) + 1`, the convention hybridSearch used (`entries.length +
+     * 1`). */
+    absentRank?: number;
+}
+/** Fuses N ranked lists (each in descending-score order; index 0 is rank 1) into a Map of candidate id -> RRF score; sort by value descending for the fused
+ * order. `weights` has one entry per list and is summed without normalisation; `options` overrides k and absentRank. */
+export declare function rrfFuse<T>(rankedLists: ReadonlyArray<ReadonlyArray<T>>, weights: ReadonlyArray<number>, options?: RrfFuseOptions): Map<T, number>;
+//# sourceMappingURL=rrf.d.ts.map

package/dist/search/rrf.js

@@ -0,0 +1,36 @@
+/** Reciprocal Rank Fusion (Cormack, Clarke and Buettcher 2009): fuses N ranked lists by summing weighted 1/(k + rank) per candidate. K is the standard 60,
+ * the value hybridSearch already uses; do NOT tune it without a cross-corpus eval. Generic over the id type (hybridSearch uses number, the LongMemEval
+ * benchmark string). Behaviour MUST stay byte-identical to the inline hybridSearch code it replaced; tests/rrf.test.ts is the contract. */
+export const RRF_K = 60;
+/** Fuses N ranked lists (each in descending-score order; index 0 is rank 1) into a Map of candidate id -> RRF score; sort by value descending for the fused
+ * order. `weights` has one entry per list and is summed without normalisation; `options` overrides k and absentRank. */
+export function rrfFuse(rankedLists, weights, options) {
+    if (rankedLists.length !== weights.length) {
+        throw new Error(`rrfFuse: rankedLists.length (${rankedLists.length}) must match weights.length (${weights.length})`);
+    }
+    const k = options?.k ?? RRF_K;
+    const defaultAbsentRank = rankedLists.reduce((m, l) => Math.max(m, l.length), 0) + 1;
+    const absentRank = options?.absentRank ?? defaultAbsentRank;
+    const rankMaps = rankedLists.map((list) => {
+        const m = new Map();
+        for (let i = 0; i < list.length; i++) {
+            m.set(list[i], i + 1); // 1-indexed rank
+        }
+        return m;
+    });
+    const allCandidates = new Set();
+    for (const list of rankedLists)
+        for (const c of list)
+            allCandidates.add(c);
+    const scores = new Map();
+    for (const c of allCandidates) {
+        let score = 0;
+        for (let i = 0; i < rankMaps.length; i++) {
+            const rank = rankMaps[i].get(c) ?? absentRank;
+            score += weights[i] / (k + rank);
+        }
+        scores.set(c, score);
+    }
+    return scores;
+}
+//# sourceMappingURL=rrf.js.map

package/dist/search/temporal.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 export type TemporalDirection = 'recent' | 'oldest' | null;
 export declare function detectTemporalDirection(query: string): TemporalDirection;
 export interface TemporalRange {

package/dist/search/temporal.js

@@ -22,6 +22,9 @@ export function computeTemporalRange(entries) {
     }
     return { minTime, maxTime };
 }
+// A temporal cue scales rank linearly across the pool time range, from the floor to floor + span.
+const TEMPORAL_BOOST_FLOOR = 0.8;
+const TEMPORAL_BOOST_SPAN = 0.4;
 export function temporalBoost(entry, direction, range) {
     if (!direction)
         return 1.0;
@@ -31,10 +34,10 @@ export function temporalBoost(entry, direction, range) {
     const entryTime = new Date(entry.created).getTime();
     const normalized = (entryTime - range.minTime) / span;
     if (direction === 'recent') {
-        return 0.8 + 0.4 * normalized;
+        return TEMPORAL_BOOST_FLOOR + TEMPORAL_BOOST_SPAN * normalized;
     }
     else {
-        return 0.8 + 0.4 * (1 - normalized);
+        return TEMPORAL_BOOST_FLOOR + TEMPORAL_BOOST_SPAN * (1 - normalized);
     }
 }
 /** The query's temporal cue and, only when there is one, the pool's time range. */

package/dist/search/vector.d.ts

@@ -1,6 +1,7 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { VectorCandidateSpec } from '../store/search-rows.js';
-import { type HippoStore, type VectorReads } from '../store-port.js';
+import { type EmbeddingProvider } from '../store/embeddings/provider.js';
+import { type HippoStore, type VectorReads } from '../store/index.js';
 import { type CurrentnessOptions } from './as-of.js';
 /** hybridSearch's vector arm: which rows it may add, plus the caller's JS admission rules (exact private regex, entry filters). */
 export type HybridVectorCandidates = VectorCandidateSpec & {
@@ -11,7 +12,7 @@ export interface VectorArm {
     entries: MemoryEntry[];
     addedRows: boolean;
     useEmbeddings: boolean;
-    embeddingIndex: Record<string, number[]>;
+    embeddingIndex: Record<string, ArrayLike<number>>;
     queryVector: number[];
 }
 export interface VectorArmOptions extends CurrentnessOptions {
@@ -19,7 +20,13 @@ export interface VectorArmOptions extends CurrentnessOptions {
     vectorCandidates?: HybridVectorCandidates;
     /** Where vectors are read; hippo.db under `hippoRoot` when unset. */
     store?: HippoStore;
+    /** The deadline a caller already started for this recall's query embedding; a fresh budget when unset. */
+    queryEmbedDeadline?: AbortSignal;
 }
+/** One deadline for every query embedding a recall makes, so two stores or a physics fallback share the budget. */
+export declare function startQueryEmbedDeadline(): AbortSignal;
+/** The query's vector, or null when an API provider outlasts `deadline`; any other provider failure throws as before. */
+export declare function embedQueryBy(deadline: AbortSignal, provider: EmbeddingProvider, query: string): Promise<number[] | null>;
 /** The store's vector reads; a store without them answers 501, as any unported path does. */
 export declare function requireVectorReads(store: HippoStore): VectorReads;
 /** The nearest admitted rows not already in `entries`. */

package/dist/search/vector.js

@@ -1,10 +1,36 @@
-import { cosineSimilarity, indexedModel, indexNeedsRebuild } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { rethrowIfSqliteBlocked } from '../db.js';
-import { log } from '../log.js';
-import { requireGroup, sqliteStore } from '../store-port.js';
-import { redactSecretsStrict } from '../secret-detect.js';
+import { cosineOf, indexNeedsRebuild } from '../store/embeddings/index.js';
+import { indexedModel } from '../store/vector-index.js';
+import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { errorMessage, log } from '../util/log.js';
+import { envQueryEmbedTimeoutMs } from '../util/env.js';
+import { requireGroup, sqliteStore } from '../store/index.js';
+import { redactSecretsStrict } from '../util/secret-detect.js';
 import { currentEntries } from './as-of.js';
+// Jev's default budget (rerankers/jev.ts): each is one off-box call that a recall waits on.
+const QUERY_EMBED_BUDGET_MS = 5_000;
+/** How long one recall waits for its query vector, retries included; HIPPO_QUERY_EMBED_TIMEOUT_MS overrides the default. */
+function queryEmbedBudgetMs() {
+    return envQueryEmbedTimeoutMs() ?? QUERY_EMBED_BUDGET_MS;
+}
+/** One deadline for every query embedding a recall makes, so two stores or a physics fallback share the budget. */
+export function startQueryEmbedDeadline() {
+    return AbortSignal.timeout(queryEmbedBudgetMs());
+}
+/** The query's vector, or null when an API provider outlasts `deadline`; any other provider failure throws as before. */
+export async function embedQueryBy(deadline, provider, query) {
+    // No signal stops an in-process model, so the local provider is not held to the deadline.
+    if (provider.kind === 'local')
+        return (await provider.embed([query], 'query'))[0] ?? [];
+    try {
+        return (await provider.embed([query], 'query', { signal: deadline }))[0] ?? [];
+    }
+    catch (err) {
+        if (deadline.aborted)
+            return null;
+        throw err;
+    }
+}
 // Search runs on every hook prompt, so one line per reason per process says why vectors went unused without flooding stderr.
 function warnBm25Fallback(reason, detail) {
     log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
@@ -23,7 +49,9 @@ export function requireVectorReads(store) {
 /** The nearest admitted rows not already in `entries`. */
 export async function vectorCandidatesOutside(reads, entries, queryVector, spec) {
     const inPool = new Set(entries.map((e) => e.id));
-    return (await reads.nearestEntries(queryVector, spec)).filter((e) => !inPool.has(e.id) && (spec.admit?.(e) ?? true));
+    // The port takes data alone: `admit` is this side's rule, and a function cannot be sent to a store on another thread.
+    const { admit, ...stored } = spec;
+    return (await reads.nearestEntries(queryVector, stored)).filter((e) => !inPool.has(e.id) && (admit?.(e) ?? true));
 }
 /** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
 export async function resolveVectorArm(query, entries, options) {
@@ -35,10 +63,14 @@ export async function resolveVectorArm(query, entries, options) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        warnBm25Fallback('error', err instanceof Error ? err.message : String(err));
+        warnBm25Fallback('error', errorMessage(err));
     }
     return arm;
 }
+// Views when the store has them, so a search copies no vector; the number[] copies score the same.
+async function storedVectorsOf(store, reads, ids) {
+    return store.vectorViews ? store.vectorViews.storedVectorViews(ids) : reads.storedVectors(ids);
+}
 async function fillVectorArm(arm, query, root, options) {
     const provider = resolveEmbeddingProvider(root);
     if (!provider.isAvailable())
@@ -51,12 +83,16 @@ async function fillVectorArm(arm, query, root, options) {
         return;
     }
     const spec = options.vectorCandidates;
-    const vectors = await reads.storedVectors(arm.entries.map((e) => e.id));
+    const vectors = await storedVectorsOf(store, reads, arm.entries.map((e) => e.id));
     // Only spend a (possibly paid, off-box) query embedding when there is a stored vector this search can use.
     if (vectors.size === 0 && !(spec !== undefined && index.hasVectors))
         return;
-    const [vec] = await provider.embed([query], 'query');
-    arm.queryVector = vec ?? [];
+    const vec = await embedQueryBy(options.queryEmbedDeadline ?? startQueryEmbedDeadline(), provider, query);
+    if (vec === null) {
+        warnBm25Fallback('query-embed-budget', `the ${provider.kind} embedding provider gave no query vector within ${queryEmbedBudgetMs()} ms`);
+        return;
+    }
+    arm.queryVector = vec;
     if (arm.queryVector.length === 0) {
         warnBm25Fallback('empty-query-vector', 'the embedding provider returned no vector for the query');
         return;
@@ -65,7 +101,7 @@ async function fillVectorArm(arm, query, root, options) {
     if (added.length > 0) {
         arm.addedRows = true;
         arm.entries = currentEntries([...arm.entries, ...added], options);
-        for (const [id, v] of await reads.storedVectors(added.map((e) => e.id)))
+        for (const [id, v] of await storedVectorsOf(store, reads, added.map((e) => e.id)))
             vectors.set(id, v);
     }
     arm.embeddingIndex = Object.fromEntries(vectors);
@@ -73,14 +109,14 @@ async function fillVectorArm(arm, query, root, options) {
 }
 export function denseScores(arm) {
     const n = arm.entries.length;
-    const cosine = new Array(n).fill(0);
-    const hadVec = new Array(n).fill(false);
+    const cosine = Array(n).fill(0);
+    const hadVec = Array(n).fill(false);
     if (!arm.useEmbeddings)
         return { cosine, hadVec };
     for (let i = 0; i < n; i++) {
         const cached = arm.embeddingIndex[arm.entries[i].id];
         hadVec[i] = Boolean(cached && arm.queryVector.length > 0);
-        cosine[i] = hadVec[i] ? Math.max(0, cosineSimilarity(arm.queryVector, cached)) : 0;
+        cosine[i] = hadVec[i] ? Math.max(0, cosineOf(arm.queryVector, cached)) : 0;
     }
     return { cosine, hadVec };
 }

package/dist/server/auth.d.ts

@@ -1,23 +1,12 @@
 import type { IncomingMessage } from 'node:http';
-import { type Context } from '../api.js';
+import { type Context } from '../api/index.js';
 import type { ResolvedServeOpts } from './types.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 declare function isLoopback(remoteAddress: string | undefined): boolean;
-/**
- * Read the Authorization header in a case-insensitive way and pull the
- * bearer token out. Returns:
- *   - { kind: 'absent' } when no Authorization header is present
- *   - { kind: 'malformed' } when the header is set but not 'Bearer <token>'
- *   - { kind: 'bearer', token } when a non-empty bearer token is present
- *
- * The header NAME is case-insensitive (Node lowercases all header names on
- * IncomingMessage.headers); the SCHEME ('Bearer') is also matched
- * case-insensitively per RFC 6750.
- */
+/** 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 declare function isLocalCaller(req: IncomingMessage): boolean;
+/** Reads the Authorization header case-insensitively (name and RFC 6750 'Bearer' scheme): { kind: 'absent' }, { kind: 'malformed' } (set but not 'Bearer
+ * <token>'), or { kind: 'bearer', token } for a non-empty token. */
 type AuthHeader = {
     kind: 'absent';
 } | {
@@ -32,19 +21,11 @@ type AuthOpts = Pick<ResolvedServeOpts, 'hippoRoot' | 'authResolver' | 'authReso
 export declare function isReservedActor(subject: string): boolean;
 /** Key cap for every serve() bucket, shared by the warn map so it never tracks more callers than the buckets do. */
 export declare const LIMITER_MAX_KEYS = 10000;
-/**
- * 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 declare function buildContextWithAuth(req: IncomingMessage, opts: AuthOpts): Promise<Context>;
-/**
- * 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 declare function requireAuth(req: IncomingMessage, opts: AuthOpts): Promise<void>;
 /** 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 declare function heartbeatVerdict(req: IncomingMessage, opts: AuthOpts): Promise<'ok' | 'revoked' | 'unavailable'>;

package/dist/server/auth.js

@@ -1,18 +1,14 @@
 // Bearer and loopback auth for the HTTP server.
-import { envRequireAuth } from '../env.js';
-import { resolveTenantId } from '../tenant.js';
-import { log } from '../log.js';
-import { API_KEY_PREFIX, verifyApiKeyCached } from '../auth.js';
-import { ownerOrSubject } from '../api.js';
-import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER, MAX_ID_LEN } from '../http-util.js';
-import { clientIpForRateLimit, subscriberKey } from './client-ip.js';
-import { requestIds } from './request.js';
-import { isJsonString } from '../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.
- */
+import { envAllowKeylessLocal, envRequireAuth } from '../util/env.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { 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 { 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;
@@ -27,22 +23,38 @@ export function isLoopback(remoteAddress) {
 // 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',
+    '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_...).', { requestId: requestIds.get(req) });
+            '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)
@@ -140,7 +152,7 @@ const DEFAULT_RESOLVER_DEADLINE_MS = 5000;
 function chargeScryptRun(req, opts) {
     const limiter = opts.failedAuthLimiter;
     // Reserving rather than peeking bounds scrypt runs exactly, even when concurrent misses await a slow store.
-    if (limiter && !limiter.check(subscriberKey(clientIpForRateLimit(req)))) {
+    if (limiter && !limiter.check(clientLimitKey(req))) {
         throw new HttpError(429, 'too many key checks from this address', limiter.retryAfterSec);
     }
 }
@@ -153,7 +165,12 @@ async function resolveBearer(req, token, opts) {
         const clean = await askResolver(opts.authResolver, token, deadlineMs);
         return { ...clean, viaAuthResolver: true, owner: clean.subject }; // a resolver vouches for a person, never names one
     }
-    const key = await verifyApiKeyCached(opts.hippoRoot, token, opts.store, () => chargeScryptRun(req, opts));
+    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.
+        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 };
@@ -161,7 +178,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') {
@@ -169,10 +186,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;
 }
@@ -189,9 +210,11 @@ function bearerActor(id) {
 }
 /** Key cap for every serve() bucket, shared by the warn map so it never tracks more callers than the buckets do. */
 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 callerWarnedAt = new Map();
-function warnCallerLimited(req, key, tenantId, person) {
+function warnCallerLimited(key, tenantId, person) {
     const now = Date.now();
     const last = callerWarnedAt.get(key);
     if (last !== undefined && now - last < CALLER_WARN_EVERY_MS)
@@ -203,9 +226,9 @@ function warnCallerLimited(req, key, tenantId, person) {
             callerWarnedAt.delete(oldest.value);
     }
     callerWarnedAt.set(key, now);
-    log.warn('caller over its rate limit; its further 429s this minute are not logged', { tenant: tenantId, person, requestId: requestIds.get(req) });
+    log.warn('caller over its rate limit; its further 429s this minute are not logged', { tenant: tenantId, person });
 }
-function chargeCaller(req, tenantId, actor, opts) {
+function chargeCaller(tenantId, actor, opts) {
     const limiter = opts.callerLimiter;
     if (!limiter)
         return;
@@ -213,23 +236,19 @@ function chargeCaller(req, tenantId, actor, opts) {
     const key = `${tenantId}\u0000${person}`;
     if (limiter.check(key))
         return;
-    warnCallerLimited(req, key, tenantId, person);
+    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(req, id.tenantId, actor, opts);
+        chargeCaller(id.tenantId, actor, opts);
         return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor, store: opts.store };
     }
-    // Loopback fallback is process-local, treat as admin.
+    // 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({}),
@@ -237,16 +256,12 @@ 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)
-        chargeCaller(req, id.tenantId, bearerActor(id), opts);
+        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. */
 export async function heartbeatVerdict(req, opts) {

package/dist/server/boot.d.ts

@@ -0,0 +1,5 @@
+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.
+ * 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