hippo-memory 1.70.0 → 1.71.0

package/dist/search/multihop.js

@@ -34,9 +34,8 @@ export function multihopSearch(query, entries, options = {}) {
             merged.set(r.entry.id, r);
         }
     }
-    // PLAIN stable score sort on purpose -- pass1/pass2 inputs are
-    // deterministically ordered (search() carries the content tail), stability
-    // inherits that, and ties keep pass-1 results ahead of pass-2 follow-ups.
+    // PLAIN stable score sort on purpose: pass1/pass2 inputs are already deterministically ordered (search() carries the content tail),
+    // stability inherits that, and ties keep pass-1 results ahead of pass-2 follow-ups.
     return fit([...merged.values()].sort((a, b) => compareScoresDesc(a.score, b.score)));
 }
 //# sourceMappingURL=multihop.js.map

package/dist/search/path-context.d.ts

@@ -1,24 +1,11 @@
-/**
- * Extract meaningful path segments from a directory path.
- * Returns tags like ['path:src', 'path:api', 'path:my-project'].
- * Filters out noise (node_modules, .git, Users, home dirs, drive letters).
- */
+/** Extracts meaningful path segments from a directory as tags like ['path:src', 'path:my-project']; filters noise (node_modules, .git, Users, home dirs,
+ * drive letters). */
 export declare function extractPathTags(dirPath: string): string[];
-/**
- * Compute path overlap score between two sets of path tags.
- * Returns 0..1 where 1 = perfect match.
- * Normalizes by the MORE SPECIFIC side (the larger of the two tag sets),
- * so a memory carrying only a bare/generic path tag can no longer score a
- * full 1.0 against a deeply-nested cwd just because its own tiny tag set
- * is fully contained in the query's — genericity is no longer rewarded.
- */
+/** Path overlap score in 0..1 (1 = perfect match), normalized by the MORE SPECIFIC side (the larger tag set),
+ * so a bare/generic path tag cannot score 1.0 against a deeply nested cwd just because its tiny tag set is contained in the query's. */
 export declare function pathOverlapScore(memoryPathTags: string[], currentPathTags: string[]): number;
 /** Weight applied to path overlap score when computing the recall boost multiplier. */
 export declare const PATH_BOOST_WEIGHT = 0.3;
-/**
- * Multiplier applied to a composite recall score for path locality.
- * Filters the memory's tags to path:* itself so call sites cannot drift.
- * Returns 1.0..1.3.
- */
+/** Multiplier (1.0..1.3) applied to a composite recall score for path locality; filters the memory's tags to path:* itself so call sites cannot drift. */
 export declare function pathBoostMultiplier(memoryTags: string[], currentPathTags: string[]): number;
 //# sourceMappingURL=path-context.d.ts.map

package/dist/search/path-context.js

@@ -1,10 +1,7 @@
 // Keeps the last meaningful segments, the most specific ones.
 const PATH_SEGMENTS_KEPT = 4;
-/**
- * Extract meaningful path segments from a directory path.
- * Returns tags like ['path:src', 'path:api', 'path:my-project'].
- * Filters out noise (node_modules, .git, Users, home dirs, drive letters).
- */
+/** Extracts meaningful path segments from a directory as tags like ['path:src', 'path:my-project']; filters noise (node_modules, .git, Users, home dirs,
+ * drive letters). */
 export function extractPathTags(dirPath) {
     const normalized = dirPath.replace(/\\/g, '/');
     const segments = normalized.split('/').filter(Boolean);
@@ -19,14 +16,8 @@ export function extractPathTags(dirPath) {
         .slice(-PATH_SEGMENTS_KEPT)
         .map(s => `path:${s.toLowerCase()}`);
 }
-/**
- * Compute path overlap score between two sets of path tags.
- * Returns 0..1 where 1 = perfect match.
- * Normalizes by the MORE SPECIFIC side (the larger of the two tag sets),
- * so a memory carrying only a bare/generic path tag can no longer score a
- * full 1.0 against a deeply-nested cwd just because its own tiny tag set
- * is fully contained in the query's — genericity is no longer rewarded.
- */
+/** Path overlap score in 0..1 (1 = perfect match), normalized by the MORE SPECIFIC side (the larger tag set),
+ * so a bare/generic path tag cannot score 1.0 against a deeply nested cwd just because its tiny tag set is contained in the query's. */
 export function pathOverlapScore(memoryPathTags, currentPathTags) {
     if (memoryPathTags.length === 0 || currentPathTags.length === 0)
         return 0;
@@ -38,11 +29,7 @@ export function pathOverlapScore(memoryPathTags, currentPathTags) {
 }
 /** Weight applied to path overlap score when computing the recall boost multiplier. */
 export const PATH_BOOST_WEIGHT = 0.3;
-/**
- * Multiplier applied to a composite recall score for path locality.
- * Filters the memory's tags to path:* itself so call sites cannot drift.
- * Returns 1.0..1.3.
- */
+/** Multiplier (1.0..1.3) applied to a composite recall score for path locality; filters the memory's tags to path:* itself so call sites cannot drift. */
 export function pathBoostMultiplier(memoryTags, currentPathTags) {
     const memPathTags = memoryTags.filter(t => t.startsWith('path:'));
     return 1.0 + pathOverlapScore(memPathTags, currentPathTags) * PATH_BOOST_WEIGHT;

package/dist/search/physics-search.js

@@ -1,7 +1,8 @@
 import { calculateStrength } from '../core/memory.js';
 import { estimateTokens } from '../util/token-text.js';
 import { evalNow, isRecallBoostAblated } from '../core/ablation.js';
-import { indexedModel, indexNeedsRebuild } from '../store/embeddings/index.js';
+import { indexNeedsRebuild } from '../store/embeddings/index.js';
+import { indexedModel } from '../store/vector-index.js';
 import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
 import { physicsScore as computePhysicsScores, computeMass } from '../core/physics.js';
 import { DEFAULT_PHYSICS_CONFIG } from '../core/physics-config.js';
@@ -14,7 +15,7 @@ import { addDagFields, ageInDays } from './breakdown.js';
 import { fitBudget } from './finalize.js';
 import { hybridSearch } from './hybrid.js';
 import { currentEntries } from './as-of.js';
-import { requireVectorReads, vectorCandidatesOutside } from './vector.js';
+import { embedQueryBy, requireVectorReads, startQueryEmbedDeadline, vectorCandidatesOutside } from './vector.js';
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 /** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
 export async function physicsSearch(query, entries, options = {}) {
@@ -28,27 +29,29 @@ export async function physicsSearch(query, entries, options = {}) {
         return hybridSearch(query, entries, options);
     const root = options.hippoRoot;
     const store = options.store ?? sqliteStore(root);
-    const queryVector = await physicsQueryVector(query, root, store, options.queryEmbedding);
+    // Shared with every hybrid ranking below, so a provider that stalls here is not waited on a second time.
+    const queryEmbedDeadline = startQueryEmbedDeadline();
+    const queryVector = await physicsQueryVector(query, root, store, queryEmbedDeadline, options.queryEmbedding);
     if (!queryVector)
-        return hybridSearch(query, entries, options);
+        return hybridSearch(query, entries, { ...options, queryEmbedDeadline });
     // Checked here too, since a caller's own query vector skips the check inside physicsQueryVector.
     const reads = requireVectorReads(store);
     const pool = currentEntries(await withVectorCandidates(reads, entries, queryVector, options.vectorCandidates), options);
     const physicsMap = await loadCandidateParticles(reads, pool);
     if (!physicsMap)
-        return hybridSearch(query, pool, options);
+        return hybridSearch(query, pool, { ...options, queryEmbedDeadline });
     const pools = splitByParticle(pool, physicsMap, queryVector, now);
     const config = options.physicsConfig ?? DEFAULT_PHYSICS_CONFIG;
     const physicsResults = scorePhysicsPool(pools, queryVector, config, scoring);
     const classicResults = pools.classic.length > 0
-        ? await hybridSearch(query, pools.classic, { ...options, vectorCandidates: undefined, budget: Infinity, explain })
+        ? await hybridSearch(query, pools.classic, { ...options, queryEmbedDeadline, vectorCandidates: undefined, budget: Infinity, explain })
         : [];
     const merged = mergeScorePools(physicsResults, classicResults);
     merged.sort(compareScoredResults);
     return fitBudget(merged, options.budget ?? DEFAULT_RECALL_BUDGET, options.minResults ?? 1, options.cost);
 }
 /** The caller's vector, else the provider's; null sends the caller to hybridSearch. */
-async function physicsQueryVector(query, root, store, given) {
+async function physicsQueryVector(query, root, store, deadline, given) {
     if (given && given.length > 0)
         return given;
     // Physics scores against particle positions, not the stored vector index, so a pruned index must not block it.
@@ -58,7 +61,7 @@ async function physicsQueryVector(query, root, store, given) {
             return null;
         if (indexNeedsRebuild(indexedModel(await requireVectorReads(store).embeddingIndexState()), provider.id))
             return null;
-        const [vec] = await provider.embed([query], 'query');
+        const vec = await embedQueryBy(deadline, provider, query);
         return vec && vec.length > 0 ? vec : null;
     }
     catch (err) {

package/dist/search/rrf.d.ts

@@ -1,43 +1,15 @@
-/**
- * Reciprocal Rank Fusion (Cormack, Clarke, and Buettcher 2009).
- *
- * Fuses N ranked candidate lists into a single ordering by summing
- * weighted 1/(k + rank) contributions per candidate. The constant K is
- * the canonical 60 from the original paper and the value already in use
- * across hippo's `hybridSearch`. Do NOT tune K without an
- * explicit cross-corpus eval — it is calibrated against IR benchmarks
- * and works robustly across BM25/dense/cross-encoder rank-list shapes.
- *
- * Generic over the candidate id type so this helper can be shared by
- * `src/search.ts::hybridSearch` (T = number, idx into MemoryEntry[]) and
- * the LongMemEval hybrid retrieve benchmark (T = string, session_id).
- *
- * Behaviour MUST stay byte-identical to the inline implementation that
- * lived in `src/search.ts:354-374` before extraction (commit ab6c5eb).
- * The `tests/rrf.test.ts` suite is the contract.
- */
+/** 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 is
-     * `max(rankedLists.map(l => l.length)) + 1` — the convention used in
-     * the pre-extraction `hybridSearch` code (`entries.length + 1`).
-     */
+    /** 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;
 }
-/**
- * Fuse N ranked lists into a single Map of candidate id -> RRF score.
- *
- * @param rankedLists  Each inner array is candidates in descending-score order.
- *                     Element at index 0 is rank 1; index 1 is rank 2; etc.
- * @param weights      Per-list weights. weights.length === rankedLists.length.
- *                     Weights are summed without normalisation — pass {0.5, 0.5}
- *                     for symmetric fusion or {0.2, 0.8} for asymmetric.
- * @param options      Optional k override + absentRank override.
- * @returns            Map from candidate id to fused RRF score. Sort descending
- *                     by value to get the fused ordering.
- */
+/** 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

@@ -1,34 +1,9 @@
-/**
- * Reciprocal Rank Fusion (Cormack, Clarke, and Buettcher 2009).
- *
- * Fuses N ranked candidate lists into a single ordering by summing
- * weighted 1/(k + rank) contributions per candidate. The constant K is
- * the canonical 60 from the original paper and the value already in use
- * across hippo's `hybridSearch`. Do NOT tune K without an
- * explicit cross-corpus eval — it is calibrated against IR benchmarks
- * and works robustly across BM25/dense/cross-encoder rank-list shapes.
- *
- * Generic over the candidate id type so this helper can be shared by
- * `src/search.ts::hybridSearch` (T = number, idx into MemoryEntry[]) and
- * the LongMemEval hybrid retrieve benchmark (T = string, session_id).
- *
- * Behaviour MUST stay byte-identical to the inline implementation that
- * lived in `src/search.ts:354-374` before extraction (commit ab6c5eb).
- * The `tests/rrf.test.ts` suite is the contract.
- */
+/** 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;
-/**
- * Fuse N ranked lists into a single Map of candidate id -> RRF score.
- *
- * @param rankedLists  Each inner array is candidates in descending-score order.
- *                     Element at index 0 is rank 1; index 1 is rank 2; etc.
- * @param weights      Per-list weights. weights.length === rankedLists.length.
- *                     Weights are summed without normalisation — pass {0.5, 0.5}
- *                     for symmetric fusion or {0.2, 0.8} for asymmetric.
- * @param options      Optional k override + absentRank override.
- * @returns            Map from candidate id to fused RRF score. Sort descending
- *                     by value to get the fused ordering.
- */
+/** 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})`);

package/dist/search/vector.d.ts

@@ -1,5 +1,6 @@
 import type { MemoryEntry } from '../core/memory.js';
 import type { VectorCandidateSpec } from '../store/search-rows.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). */
@@ -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 { cosineOf, indexedModel, indexNeedsRebuild } from '../store/embeddings/index.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)}`);
@@ -61,8 +87,12 @@ async function fillVectorArm(arm, query, root, options) {
     // 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;
@@ -79,8 +109,8 @@ 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++) {

package/dist/server/auth.d.ts

@@ -1,23 +1,12 @@
 import type { IncomingMessage } from 'node:http';
 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,5 +1,5 @@
 // Bearer and loopback auth for the HTTP server.
-import { envRequireAuth } from '../util/env.js';
+import { envAllowKeylessLocal, envRequireAuth } from '../util/env.js';
 import { resolveTenantId } from '../store/tenant.js';
 import { log } from '../util/log.js';
 import { API_KEY_PREFIX, verifyApiKeyCached } from '../store/auth.js';
@@ -8,11 +8,7 @@ import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER, MAX_ID_LE
 import { clientLimitKey } from './client-ip.js';
 import { keyCheckBounds } from './key-check-bounds.js';
 import { isJsonString } from '../util/json.js';
-/**
- * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as
- * '::ffff:127.0.0.1' on dual-stack sockets, so we accept that alongside
- * the bare v4 and v6 loopbacks. Anything else is treated as remote.
- */
+/** Recognises loopback remote addresses, including the IPv6-mapped '::ffff:127.0.0.1' Node reports on dual-stack sockets; anything else is remote. */
 export function isLoopback(remoteAddress) {
     if (!remoteAddress)
         return false;
@@ -29,21 +25,36 @@ const PROXY_HEADERS = [
     'forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'cf-connecting-ip', 'true-client-ip',
     'fly-client-ip',
 ];
-// A browser on this machine is loopback too, so the no-key fallback also needs a local Host and a same-site caller.
+function proxyHeaderOf(req) {
+    return PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
+}
+/** A page in a browser on this machine: another site's request, or a hostile name resolved to loopback (DNS rebinding). */
+function isForeignPage(req) {
+    const host = req.headers.host;
+    return (host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req);
+}
+/** True only for a request made on this machine by its own user: a proxy and a browser page are loopback too, so the socket alone proves nothing. */
+export function isLocalCaller(req) {
+    return isLoopback(req.socket.remoteAddress) && proxyHeaderOf(req) === undefined && !isForeignPage(req);
+}
+// The throwing twin of isLocalCaller, for the no-key fallback: each refusal has its own status, and a proxied one is logged.
 function assertLocalCaller(req) {
     if (!isLoopback(req.socket.remoteAddress))
         throw new HttpError(401, 'auth required');
-    const proxyHeader = PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
+    const proxyHeader = proxyHeaderOf(req);
     if (proxyHeader !== undefined) {
         log.warn(`proxied loopback request refused: it carries ${proxyHeader}, so the no-key local fallback does not apply. ` +
             'Send an API key (hippo auth create, then Authorization: Bearer hk_...).');
         throw new HttpError(401, 'auth required');
     }
-    const host = req.headers.host;
-    if ((host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req)) {
+    if (isForeignPage(req)) {
         throw new HttpError(403, 'cross-site or non-local request refused; send an API key');
     }
 }
+/** The 401 a keyless request from this machine gets by default; it names both fixes, since an upgrade is where most people meet it. */
+const KEY_REQUIRED_MESSAGE = 'auth required: this server takes no request without an API key. Mint one with `hippo auth create` and send it as ' +
+    '"Authorization: Bearer <key>" (the hippo CLI reads HIPPO_API_KEY), or start the server with HIPPO_ALLOW_KEYLESS_LOCAL=1 ' +
+    'to let requests from this machine in without a key.';
 export function readAuthHeader(req) {
     const raw = req.headers['authorization'];
     if (raw === undefined)
@@ -167,7 +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') {
@@ -175,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;
 }
@@ -224,12 +239,8 @@ function chargeCaller(tenantId, actor, opts) {
     warnCallerLimited(key, tenantId, person);
     throw new HttpError(429, 'rate limit exceeded for this caller', limiter.retryAfterSec);
 }
-/**
- * Build a per-request Context from the Authorization header and remote
- * address. Throws HttpError(401) for invalid / missing credentials. Reads
- * the store only for an API-key-shaped Bearer token (or any Bearer token when no
- * auth resolver is registered), so loopback no-auth requests stay cheap.
- */
+/** Builds a per-request Context from the Authorization header and remote address; throws HttpError(401) for invalid or missing credentials.
+ * Reads the store only for an API-key-shaped Bearer (or any Bearer when no auth resolver is registered), so keyless local requests stay cheap. */
 export async function buildContextWithAuth(req, opts) {
     const id = await checkAuth(req, opts);
     if (id !== null) {
@@ -237,7 +248,7 @@ export async function buildContextWithAuth(req, 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({}),
@@ -245,12 +256,8 @@ export async function buildContextWithAuth(req, opts) {
         store: opts.store,
     };
 }
-/**
- * Auth check for routes that do not need a tenant Context (e.g. MCP transport,
- * which builds its own root resolution via findHippoRoot). Throws HttpError
- * 401 the same way buildContextWithAuth does, but skips building the Context
- * envelope. Loopback no-auth still passes.
- */
+/** Auth check for routes that need no tenant Context (e.g. the MCP transport, which resolves its own root): throws HttpError 401 like buildContextWithAuth.
+ * A keyless local request passes only under HIPPO_ALLOW_KEYLESS_LOCAL=1. */
 export async function requireAuth(req, opts) {
     const id = await checkAuth(req, opts);
     if (id !== null)

package/dist/server/boot.d.ts

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