hippo-memory 1.53.2 → 1.55.0

package/dist/server.js

@@ -8,7 +8,7 @@ import { resolveTenantId } from './tenant.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { updateStats } from './store.js';
 import { buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, hashQueryText, } from './recall-history.js';
-import { appendAuditEvent, AUDIT_OPS } from './audit.js';
+import { appendAuditEvent, auditQueryFields, AUDIT_OPS } from './audit.js';
 // v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map
 // for the HTTP pipeline. Separate from CLI/MCP rings per plan v3 (per-
 // pipeline rings; no IPC). HTTP is the only caller that threads its
@@ -21,7 +21,7 @@ export function __resetSessionRecallHistoryHttp() {
     sessionRecallHistoryHttp.clear();
 }
 import { PACKAGE_VERSION } from './version.js';
-import { validateApiKey } from './auth.js';
+import { API_KEY_PREFIX, validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
 import { remember, retrieve, RecallContractError, ForbiddenError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, recordTokens, quarantineList, quarantineApprove, quarantineReject, } from './api.js';
 import { buildGraphModel } from './graph-view.js';
@@ -393,37 +393,119 @@ export function clientIpForRateLimit(req) {
     }
     return req.socket.remoteAddress ?? 'unknown';
 }
+// Built-in actors are the bare names below or `<name>:<detail>`; a plain prefix would also reject `clinton@corp`.
+const RESERVED_ACTOR_NAMES = [
+    'api_key', 'localhost', 'cli', 'system', 'mcp', 'connector', 'sleep', 'post-compact', 'recall', 'agent-memories',
+];
+function hasControlChar(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x20 || c === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** Core owns the checks so a resolver cannot mint an actor that collides with a built-in one. */
+function sanitiseResolved(r) {
+    // Each field is read once: a getter on plugin code could answer differently the second time.
+    const { tenantId, subject, role, scopes } = r;
+    // A resolver is plugin code, so the runtime checks hold even though the static types say string.
+    if (!isJsonString(tenantId) || tenantId.trim().length === 0)
+        return null;
+    // Core reserves `__`-prefixed tenants (`__host__`, `__unroutable__`).
+    const tenant = tenantId.trim();
+    if (tenant.startsWith('__') || tenant.length > 256 || hasControlChar(tenant))
+        return null;
+    if (!isJsonString(subject) || subject.length < 1 || subject.length > 256)
+        return null;
+    // Padding would let "system " pass the reserved-name check yet read as `system` in an audit log.
+    if (hasControlChar(subject) || subject !== subject.trim())
+        return null;
+    const lower = subject.toLowerCase();
+    if (RESERVED_ACTOR_NAMES.some((n) => lower === n || lower.startsWith(`${n}:`)))
+        return null;
+    const clean = { tenantId: tenant, subject, role: role === 'admin' ? 'admin' : 'member' };
+    if (Array.isArray(scopes))
+        clean.scopes = scopes.filter((s) => isJsonString(s));
+    return clean;
+}
+function logResolverFailure(what, raw, token) {
+    // The plugin's message is logged, but never the token, even if the plugin echoed it.
+    const msg = raw.split(token).join('[token]').replace(/[\r\n]/g, ' ');
+    process.stderr.write(`[hippo] auth resolver ${what}: ${msg}\n`);
+}
+/** 503 when upstream throws or misses the deadline, so a stream heartbeat can tell an outage from a revocation. */
+async function askResolver(resolver, token, deadlineMs) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no answer within ${deadlineMs} ms`)), deadlineMs);
+    });
+    let resolved;
+    try {
+        resolved = await Promise.race([(async () => resolver(token))(), deadline]);
+    }
+    catch (err) {
+        logResolverFailure('threw', err instanceof Error ? err.message : 'unknown error', token);
+        throw new HttpError(503, 'auth provider unavailable');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let clean = null;
+    try {
+        clean = resolved ? sanitiseResolved(resolved) : null;
+    }
+    catch (err) {
+        // A throwing getter is a resolver bug, not an outage, so it is a 401 like any malformed answer.
+        logResolverFailure('threw', err instanceof Error ? err.message : 'unknown error', token);
+    }
+    if (!clean)
+        throw new HttpError(401, 'invalid api key');
+    return clean;
+}
+const DEFAULT_RESOLVER_DEADLINE_MS = 5000;
+/** Shared by buildContextWithAuth and requireAuth so the two cannot drift. */
+async function resolveBearer(token, opts) {
+    // Routing by shape keeps key plaintext out of plugin code and stops a resolver overriding a key's identity.
+    if (opts.authResolver && !token.startsWith(API_KEY_PREFIX)) {
+        const t = opts.authResolverTimeoutMs;
+        const deadlineMs = t !== undefined && Number.isFinite(t) && t > 0 ? t : DEFAULT_RESOLVER_DEADLINE_MS;
+        return { ...(await askResolver(opts.authResolver, token, deadlineMs)), viaAuthResolver: true };
+    }
+    const db = openHippoDb(opts.hippoRoot);
+    try {
+        const result = validateApiKey(db, token);
+        if (!result.valid || !result.tenantId || !result.keyId || !result.role) {
+            throw new HttpError(401, 'invalid api key');
+        }
+        return {
+            tenantId: result.tenantId,
+            subject: `api_key:${result.keyId}`,
+            role: result.role,
+            scopes: result.scopes,
+        };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /**
  * Build a per-request Context from the Authorization header and remote
  * address. Throws HttpError(401) for invalid / missing credentials. Opens
- * the DB only when a Bearer token is present so loopback no-auth requests
- * stay cheap.
+ * the DB 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.
  */
-function buildContextWithAuth(req, hippoRoot) {
+async function buildContextWithAuth(req, opts) {
     const auth = readAuthHeader(req);
     if (auth.kind === 'malformed') {
         throw new HttpError(401, 'invalid api key');
     }
     if (auth.kind === 'bearer') {
-        const db = openHippoDb(hippoRoot);
-        try {
-            const result = validateApiKey(db, auth.token);
-            if (!result.valid || !result.tenantId || !result.keyId || !result.role) {
-                throw new HttpError(401, 'invalid api key');
-            }
-            return {
-                hippoRoot,
-                tenantId: result.tenantId,
-                actor: {
-                    subject: `api_key:${result.keyId}`,
-                    role: result.role,
-                    scopes: result.scopes,
-                },
-            };
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        const id = await resolveBearer(auth.token, opts);
+        const actor = { subject: id.subject, role: id.role, scopes: id.scopes };
+        if (id.viaAuthResolver)
+            actor.viaAuthResolver = true;
+        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor };
     }
     // No Authorization header. Loopback-only fallback, unless explicitly
     // disabled via HIPPO_REQUIRE_AUTH=1 (used by the bearer-lockdown test
@@ -434,7 +516,7 @@ function buildContextWithAuth(req, hippoRoot) {
     assertLocalCaller(req);
     // v1.12.0: loopback fallback is process-local, treat as admin.
     return {
-        hippoRoot,
+        hippoRoot: opts.hippoRoot,
         tenantId: resolveTenantId({}),
         actor: { subject: 'localhost:cli', role: 'admin' },
     };
@@ -445,22 +527,13 @@ function buildContextWithAuth(req, hippoRoot) {
  * 401 the same way buildContextWithAuth does, but skips building the Context
  * envelope. Loopback no-auth still passes.
  */
-function requireAuth(req, hippoRoot) {
+async function requireAuth(req, opts) {
     const auth = readAuthHeader(req);
     if (auth.kind === 'malformed') {
         throw new HttpError(401, 'invalid api key');
     }
     if (auth.kind === 'bearer') {
-        const db = openHippoDb(hippoRoot);
-        try {
-            const result = validateApiKey(db, auth.token);
-            if (!result.valid) {
-                throw new HttpError(401, 'invalid api key');
-            }
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        await resolveBearer(auth.token, opts);
         return;
     }
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
@@ -468,6 +541,23 @@ function requireAuth(req, hippoRoot) {
     }
     assertLocalCaller(req);
 }
+/** Never rejects: an outage (5xx) skips one heartbeat tick, only a definite 4xx denial closes the stream. */
+async function heartbeatVerdict(req, opts) {
+    try {
+        await requireAuth(req, opts);
+        return 'ok';
+    }
+    catch (err) {
+        return err instanceof HttpError && err.status < 500 ? 'revoked' : 'unavailable';
+    }
+}
+/** Gate for any action beyond the caller's own tenant: a resolver admin is a customer's tenant admin, never a host admin. */
+function assertCrossTenantAdmin(ctx, what) {
+    if (ctx.actor.role !== 'admin')
+        throw new HttpError(403, `${what} requires admin role`);
+    if (ctx.actor.viaAuthResolver)
+        throw new HttpError(403, `${what} requires an API-key admin`);
+}
 function getString(obj, key) {
     const v = obj[key];
     return isJsonString(v) ? v : undefined;
@@ -542,8 +632,8 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         return;
     }
-    // E3: per-IP rate limit on /v1/* to bound api-key-id enumeration. /health
-    // (a liveness probe) and non-/v1 paths are never throttled. A 429 thrown
+    // E3: 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
@@ -551,7 +641,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     // 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).
-    if (limiter && path.startsWith('/v1/')) {
+    if (limiter && (path.startsWith('/v1/') || path === '/mcp' || path === '/mcp/stream')) {
         const ip = clientIpForRateLimit(req);
         if (!limiter.check(ip)) {
             throw new HttpError(429, 'rate limit exceeded');
@@ -568,7 +658,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (kindRaw !== undefined && !isSetMember(VALID_KINDS, kindRaw)) {
             throw new HttpError(400, `invalid kind: ${kindRaw}`);
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = remember(ctx, {
             content,
             kind: kindRaw,
@@ -589,7 +679,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             throw new HttpError(400, `entity exceeds the ${MAX_ENTITY_NAME_LEN}-character cap`);
         }
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const model = buildGraphModel(ctx.hippoRoot, ctx.tenantId, {
             entity: entityRaw ?? undefined,
             limit,
@@ -662,7 +752,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         // serialized RecallResult. Mirrors the include_continuity convention.
         const explainRaw = query.get('explain');
         const explain = explainRaw === '1' || explainRaw === 'true';
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         // v0.33 / J1 — HTTP per-pipeline anchoring detector. HTTP threads its
         // ring snapshot via opts.recallHistory so api.recall's own
         // anchoringHint compute path activates. Unlike CLI (which computes
@@ -701,10 +791,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                         actor: ctx.actor.subject,
                         op: 'recall_anchor_skipped_no_session',
                         targetId: undefined,
-                        metadata: {
-                            query_hash: createHash('sha256').update(q).digest('hex').slice(0, 16),
-                            query_length: q.length,
-                        },
+                        metadata: auditQueryFields(q),
                     });
                 }
                 finally {
@@ -786,7 +873,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             : (sumOlderRaw === '1' || sumOlderRaw === 'true');
         const scopeQ = query.get('scope');
         const scope = scopeQ !== null && scopeQ.length > 0 ? scopeQ : undefined;
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const assembleExtra = {};
         if (budget !== undefined)
             assembleExtra.budget = budget;
@@ -831,7 +918,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             depth = parsed;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const drillExtra = {};
         if (limit !== undefined)
             drillExtra.limit = limit;
@@ -860,7 +947,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (!reason) {
             throw new HttpError(400, 'reason is required');
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = archiveRaw(ctx, archiveMatch.id, reason);
         sendJson(res, 200, result);
         return;
@@ -873,7 +960,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (!content) {
             throw new HttpError(400, 'content is required');
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = supersede(ctx, supersedeMatch.id, content);
         sendJson(res, 200, result);
         return;
@@ -881,7 +968,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const promoteMatch = matchPath('/v1/memories/:id/promote', path);
     if (method === 'POST' && promoteMatch) {
         validateIdSegment(promoteMatch.id, 'memory id');
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = promote(ctx, promoteMatch.id);
         sendJson(res, 200, result);
         return;
@@ -889,7 +976,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const idMatch = matchPath('/v1/memories/:id', path);
     if (method === 'DELETE' && idMatch) {
         validateIdSegment(idMatch.id, 'memory id');
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = forget(ctx, idMatch.id);
         sendJson(res, 200, result);
         return;
@@ -925,7 +1012,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             ids = idsRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         if (ids !== undefined) {
             const { applied } = outcome(ctx, ids, good);
             sendJson(res, 200, { applied });
@@ -987,7 +1074,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         // the project it serves.
         const crossProjectRaw = query.get('cross_project');
         const crossProject = crossProjectRaw === '1' || crossProjectRaw === 'true';
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = await getContext(ctx, {
             q,
             budget,
@@ -1027,10 +1114,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         // any Bearer-authed caller now carries an explicit role from the api_keys
         // row). When non-loopback serving lands, this gate is the actual auth
         // boundary on host-wide sleep.
-        const sleepCtx = buildContextWithAuth(req, opts.hippoRoot);
-        if (sleepCtx.actor.role !== 'admin') {
-            throw new HttpError(403, '/v1/sleep requires admin role');
-        }
+        const sleepCtx = await buildContextWithAuth(req, opts);
+        // Sleep consolidates every tenant under hippoRoot, so it is a cross-tenant action.
+        assertCrossTenantAdmin(sleepCtx, '/v1/sleep');
         const body = await parseJsonBody(req);
         const dryRunRaw = body['dry_run'];
         if (dryRunRaw !== undefined && !isJsonBoolean(dryRunRaw)) {
@@ -1072,7 +1158,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         // bound to the caller's authenticated tenant (ctx.tenantId, resolved
         // from the Bearer token). Forwarding body.tenantId here would let
         // tenant A mint a key for tenant B — see authCreate doc comment.
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = authCreate(ctx, {
             label: labelRaw,
             role,
@@ -1094,7 +1180,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             else
                 throw new HttpError(400, "active must be 'true' or 'false'");
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = authList(ctx, { active });
         sendJson(res, 200, result);
         return;
@@ -1105,14 +1191,14 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const keyMatch = matchPath('/v1/auth/keys/:keyId', path);
     if (method === 'DELETE' && keyMatch) {
         validateIdSegment(keyMatch.keyId, 'key id');
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const result = authRevoke(ctx, keyMatch.keyId);
         sendJson(res, 200, result);
         return;
     }
     // GET /v1/quarantine?status=: CD5 review queue. quarantineList carries no role gate itself, so it's checked here.
     if (method === 'GET' && path === '/v1/quarantine') {
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         if (ctx.actor.role !== 'admin') {
             throw new HttpError(403, '/v1/quarantine requires admin role');
         }
@@ -1131,7 +1217,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const quarantineApproveMatch = matchPath('/v1/quarantine/:id/approve', path);
     if (method === 'POST' && quarantineApproveMatch) {
         validateIdSegment(quarantineApproveMatch.id, 'memory id');
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             quarantineApprove(ctx, quarantineApproveMatch.id);
             sendJson(res, 200, { approved: quarantineApproveMatch.id });
@@ -1150,7 +1236,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const quarantineRejectMatch = matchPath('/v1/quarantine/:id/reject', path);
     if (method === 'POST' && quarantineRejectMatch) {
         validateIdSegment(quarantineRejectMatch.id, 'memory id');
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             quarantineReject(ctx, quarantineRejectMatch.id);
             sendJson(res, 200, { rejected: quarantineRejectMatch.id });
@@ -1195,13 +1281,12 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             limit = parsed;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         // ?tenant=<t> reads another tenant (e.g. '__host__' for consolidate rows); admin only.
         const tenantOverride = query.get('tenant');
         const crossTenant = tenantOverride !== null && tenantOverride !== '' && tenantOverride !== ctx.tenantId;
-        if (crossTenant && ctx.actor.role !== 'admin') {
-            throw new HttpError(403, '/v1/audit?tenant= for another tenant requires admin role');
-        }
+        if (crossTenant)
+            assertCrossTenantAdmin(ctx, '/v1/audit?tenant= for another tenant');
         const effectiveCtx = crossTenant ? { ...ctx, tenantId: tenantOverride } : ctx;
         const result = auditList(effectiveCtx, { op, since, limit });
         sendJson(res, 200, result);
@@ -1252,7 +1337,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             targetDateValue = targetDate;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const prediction = savePrediction(opts.hippoRoot, ctx.tenantId, {
             classTag,
             claimText: claim,
@@ -1267,7 +1352,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const classTag = query.get('class') ?? undefined;
         const status = query.get('status') ?? 'all';
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         let predictions;
         if (status === 'all') {
             if (classTag) {
@@ -1310,7 +1395,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (classTag.length > 256) {
             throw new HttpError(400, 'class exceeds 256-character cap');
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const baserate = computePredictionBaserate(opts.hippoRoot, ctx.tenantId, classTag, ctx.actor.subject);
         sendJson(res, 200, { baserate });
         return;
@@ -1318,7 +1403,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const predictionByIdMatch = path.match(/^\/v1\/predictions\/(\d+)$/);
     if (method === 'GET' && predictionByIdMatch) {
         const id = parseInt(predictionByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const prediction = loadPredictionById(opts.hippoRoot, ctx.tenantId, id);
         if (!prediction) {
             throw new HttpError(404, `prediction ${id} not found`);
@@ -1353,7 +1438,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             closureNote = note;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const prediction = closePrediction(opts.hippoRoot, ctx.tenantId, id, {
                 closureState: state,
@@ -1409,7 +1494,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             supersedesDecisionId = supRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const decision = saveDecision(opts.hippoRoot, ctx.tenantId, {
                 decisionText: text,
@@ -1430,7 +1515,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'GET' && path === '/v1/decisions') {
         const status = query.get('status') ?? 'all';
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         let decisions;
         if (status === 'all') {
             decisions = loadDecisions(opts.hippoRoot, ctx.tenantId, { limit });
@@ -1469,7 +1554,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             context = contextRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const decision = saveDecision(opts.hippoRoot, ctx.tenantId, {
                 decisionText: text,
@@ -1493,7 +1578,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const decisionCloseMatch = path.match(/^\/v1\/decisions\/(\d+)\/close$/);
     if (method === 'POST' && decisionCloseMatch) {
         const id = parseInt(decisionCloseMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const decision = closeDecision(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
             sendJson(res, 200, { decision });
@@ -1513,7 +1598,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const decisionByIdMatch = path.match(/^\/v1\/decisions\/(\d+)$/);
     if (method === 'GET' && decisionByIdMatch) {
         const id = parseInt(decisionByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const decision = loadDecisionById(opts.hippoRoot, ctx.tenantId, id);
         if (!decision) {
             throw new HttpError(404, `decision ${id} not found`);
@@ -1567,7 +1652,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             linkedMemoryIds = linkedRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const incident = saveIncident(opts.hippoRoot, ctx.tenantId, {
                 incidentText: text,
@@ -1588,7 +1673,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'GET' && path === '/v1/incidents') {
         const status = query.get('status') ?? 'all';
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         let incidents;
         if (status === 'all') {
             incidents = loadIncidents(opts.hippoRoot, ctx.tenantId, { limit });
@@ -1616,7 +1701,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (resolutionText.length > 4096) {
             throw new HttpError(400, 'resolutionText exceeds 4096-character cap');
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const incident = resolveIncident(opts.hippoRoot, ctx.tenantId, id, resolutionText, ctx.actor.subject);
             sendJson(res, 200, { incident });
@@ -1636,7 +1721,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const incidentCloseMatch = path.match(/^\/v1\/incidents\/(\d+)\/close$/);
     if (method === 'POST' && incidentCloseMatch) {
         const id = parseInt(incidentCloseMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const incident = closeIncident(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
             sendJson(res, 200, { incident });
@@ -1656,7 +1741,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const incidentByIdMatch = path.match(/^\/v1\/incidents\/(\d+)$/);
     if (method === 'GET' && incidentByIdMatch) {
         const id = parseInt(incidentByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const incident = loadIncidentById(opts.hippoRoot, ctx.tenantId, id);
         if (!incident) {
             throw new HttpError(404, `incident ${id} not found`);
@@ -1696,7 +1781,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             description = descriptionRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const process = saveProcess(opts.hippoRoot, ctx.tenantId, {
             processName,
             steps,
@@ -1708,7 +1793,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'GET' && path === '/v1/processes') {
         const status = query.get('status') ?? 'all';
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         let processes;
         if (status === 'all') {
             processes = loadProcesses(opts.hippoRoot, ctx.tenantId, { limit });
@@ -1755,7 +1840,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             description = descRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         // A supersession is a new version of the SAME process: reuse the
         // predecessor's name. 404 if the target does not exist; saveProcess's
         // in-SAVEPOINT preflight is the authoritative active-state check (409).
@@ -1788,7 +1873,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const processCloseMatch = path.match(/^\/v1\/processes\/(\d+)\/close$/);
     if (method === 'POST' && processCloseMatch) {
         const id = parseInt(processCloseMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const process = closeProcess(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
             sendJson(res, 200, { process });
@@ -1808,7 +1893,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const processByIdMatch = path.match(/^\/v1\/processes\/(\d+)$/);
     if (method === 'GET' && processByIdMatch) {
         const id = parseInt(processByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const process = loadProcessById(opts.hippoRoot, ctx.tenantId, id);
         if (!process) {
             throw new HttpError(404, `process ${id} not found`);
@@ -1843,7 +1928,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         const validFrom = optionalDateField(body['validFrom'], 'validFrom');
         const validTo = optionalDateField(body['validTo'], 'validTo');
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
                 policyName,
@@ -1862,7 +1947,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'GET' && path === '/v1/policies') {
         const status = query.get('status') ?? 'all';
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         let policies;
         if (status === 'all') {
             policies = loadPolicies(opts.hippoRoot, ctx.tenantId, { limit });
@@ -1887,7 +1972,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             throw new HttpError(400, 'date is required (ISO-8601 valid-time)');
         }
         const name = query.get('name') ?? undefined;
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const policies = loadPoliciesAsOf(opts.hippoRoot, ctx.tenantId, date, { name });
             sendJson(res, 200, { policies });
@@ -1921,7 +2006,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             changeSummary = changeRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const existing = loadPolicyById(opts.hippoRoot, ctx.tenantId, id);
         if (!existing) {
             throw new HttpError(404, `policy ${id} not found`);
@@ -1953,7 +2038,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const policyCloseMatch = path.match(/^\/v1\/policies\/(\d+)\/close$/);
     if (method === 'POST' && policyCloseMatch) {
         const id = parseInt(policyCloseMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const policy = closePolicy(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
             sendJson(res, 200, { policy });
@@ -1973,7 +2058,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const policyByIdMatch = path.match(/^\/v1\/policies\/(\d+)$/);
     if (method === 'GET' && policyByIdMatch) {
         const id = parseInt(policyByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const policy = loadPolicyById(opts.hippoRoot, ctx.tenantId, id);
         if (!policy) {
             throw new HttpError(404, `policy ${id} not found`);
@@ -2020,7 +2105,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             trigger = triggerRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
                 skillName,
@@ -2038,7 +2123,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'GET' && path === '/v1/skills') {
         const status = query.get('status') ?? 'all';
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         let skills;
         if (status === 'all') {
             skills = loadSkills(opts.hippoRoot, ctx.tenantId, { limit });
@@ -2058,7 +2143,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     // The export renderer: must precede the /:id GET (literal 'export' is
     // non-numeric so the /(\d+)/ route would not match it, but order it first).
     if (method === 'GET' && path === '/v1/skills/export') {
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const markdown = exportSkills(opts.hippoRoot, ctx.tenantId);
         sendJson(res, 200, { markdown });
         return;
@@ -2096,7 +2181,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             changeSummary = changeRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const existing = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
         if (!existing) {
             throw new HttpError(404, `skill ${id} not found`);
@@ -2126,7 +2211,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const skillCloseMatch = path.match(/^\/v1\/skills\/(\d+)\/close$/);
     if (method === 'POST' && skillCloseMatch) {
         const id = parseInt(skillCloseMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const skill = closeSkill(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
             sendJson(res, 200, { skill });
@@ -2146,7 +2231,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const skillByIdMatch = path.match(/^\/v1\/skills\/(\d+)$/);
     if (method === 'GET' && skillByIdMatch) {
         const id = parseInt(skillByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const skill = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
         if (!skill) {
             throw new HttpError(404, `skill ${id} not found`);
@@ -2180,7 +2265,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (summary.length > 8192) {
             throw new HttpError(400, 'summary exceeds 8192-character cap');
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
                 repo,
@@ -2198,7 +2283,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const status = query.get('status') ?? 'all';
         const repoFilter = query.get('repo');
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const listOpts = { limit };
         if (repoFilter !== null && repoFilter.trim().length > 0) {
             listOpts.repo = repoFilter.trim();
@@ -2225,7 +2310,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             throw new HttpError(400, 'repo exceeds 256-character cap');
         }
         const dryRun = body['dryRun'] === true;
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             if (dryRun) {
                 const { markdown, receiptCount } = assembleBriefFromReceipts(opts.hippoRoot, ctx.tenantId, repo);
@@ -2273,7 +2358,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             changeSummary = changeRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const existing = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
         if (!existing) {
             throw new HttpError(404, `project brief ${id} not found`);
@@ -2302,7 +2387,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const briefCloseMatch = path.match(/^\/v1\/project-briefs\/(\d+)\/close$/);
     if (method === 'POST' && briefCloseMatch) {
         const id = parseInt(briefCloseMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const brief = closeProjectBrief(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
             sendJson(res, 200, { brief });
@@ -2322,7 +2407,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const briefByIdMatch = path.match(/^\/v1\/project-briefs\/(\d+)$/);
     if (method === 'GET' && briefByIdMatch) {
         const id = parseInt(briefByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const brief = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
         if (!brief) {
             throw new HttpError(404, `project brief ${id} not found`);
@@ -2354,7 +2439,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (note.length > 8192) {
             throw new HttpError(400, 'note exceeds 8192-character cap');
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const customerNote = saveCustomerNote(opts.hippoRoot, ctx.tenantId, {
                 customer,
@@ -2372,7 +2457,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const status = query.get('status') ?? 'all';
         const customerFilter = query.get('customer');
         const limit = parseListLimit(query.get('limit'));
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const listOpts = { limit };
         if (customerFilter !== null && customerFilter.trim().length > 0) {
             listOpts.customer = customerFilter.trim();
@@ -2409,7 +2494,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             }
             changeSummary = changeRaw;
         }
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const existing = loadCustomerNoteById(opts.hippoRoot, ctx.tenantId, id);
         if (!existing) {
             throw new HttpError(404, `customer note ${id} not found`);
@@ -2438,7 +2523,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const noteCloseMatch = path.match(/^\/v1\/customer-notes\/(\d+)\/close$/);
     if (method === 'POST' && noteCloseMatch) {
         const id = parseInt(noteCloseMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         try {
             const customerNote = closeCustomerNote(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
             sendJson(res, 200, { note: customerNote });
@@ -2458,7 +2543,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     const noteByIdMatch = path.match(/^\/v1\/customer-notes\/(\d+)$/);
     if (method === 'GET' && noteByIdMatch) {
         const id = parseInt(noteByIdMatch[1], 10);
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const customerNote = loadCustomerNoteById(opts.hippoRoot, ctx.tenantId, id);
         if (!customerNote) {
             throw new HttpError(404, `customer note ${id} not found`);
@@ -2998,7 +3083,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         // 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.
-        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const ctx = await buildContextWithAuth(req, opts);
         const raw = await readBody(req);
         let mcpReq;
         try {
@@ -3024,6 +3109,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 // The caller's real role: MCP tools must not run a member key as admin.
                 role: ctx.actor.role,
                 scopes: ctx.actor.scopes,
+                viaAuthResolver: ctx.actor.viaAuthResolver,
                 clientKey: buildMcpClientKey(req),
             });
         }
@@ -3044,7 +3130,10 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         return;
     }
     if (method === 'GET' && path === '/mcp/stream') {
-        requireAuth(req, opts.hippoRoot);
+        await requireAuth(req, opts);
+        // An async resolver can outlive the client; 'close' has already fired, so no timer may start.
+        if (req.destroyed || res.destroyed || req.socket.destroyed)
+            return;
         res.writeHead(200, {
             'content-type': 'text/event-stream',
             'cache-control': 'no-cache',
@@ -3064,6 +3153,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const maxAgeMs = (parseInt(process.env.MCP_SSE_MAX_AGE_SEC ?? '3600', 10) || 3600) * 1000;
         const startedAt = Date.now();
         let closed = false;
+        let checking = false;
         const closeWith = (reason) => {
             if (closed)
                 return;
@@ -3087,26 +3177,35 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 clearInterval(ping);
                 return;
             }
-            try {
-                requireAuth(req, opts.hippoRoot);
-            }
-            catch {
-                closeWith('auth_revoked');
-                clearInterval(ping);
+            if (checking)
                 return;
-            }
-            try {
-                res.write(': ping\n\n');
-            }
-            catch {
-                clearInterval(ping);
-            }
+            checking = true;
+            void heartbeatVerdict(req, opts).then((verdict) => {
+                checking = false;
+                if (closed || verdict === 'unavailable')
+                    return;
+                if (verdict === 'revoked') {
+                    closeWith('auth_revoked');
+                    clearInterval(ping);
+                    return;
+                }
+                try {
+                    res.write(': ping\n\n');
+                }
+                catch {
+                    clearInterval(ping);
+                }
+            });
         }, heartbeatMs);
         // Don't keep the event loop alive just for this timer — the server's
         // listener already does that, and tests want the process to exit cleanly.
         if (ping.unref instanceof Function)
             ping.unref();
-        req.on('close', () => clearInterval(ping));
+        // res 'close' covers an early socket drop that req 'close' can miss.
+        res.on('close', () => {
+            closed = true;
+            clearInterval(ping);
+        });
         return;
     }
     res.writeHead(404, JSON_HEADERS);
@@ -3152,7 +3251,7 @@ export async function serve(opts) {
     // GET /health response and (below) written into the pidfile, so detectServer
     // can match the two and prove a pid-reusing impostor is not the real server.
     const startedAt = new Date().toISOString();
-    // E3: per-IP rate limiter for /v1/*. Built here (not at module scope) so
+    // E3: per-IP rate limiter for /v1/* and /mcp*. Built here (not at module scope) so
     // HIPPO_V1_RPS is read at boot, matching HIPPO_PORT above and letting a test
     // set the rate before serve(). A non-positive or non-finite value disables
     // limiting (the opt-out knob).