hippo-memory 1.63.2 → 1.64.1

package/dist/raw-archive.js

@@ -1,5 +1,5 @@
 import { BadRequestError, NotFoundError } from './api-errors.js';
-import { isFtsAvailable } from './db.js';
+import { isFtsAvailable, withWriteScope } from './db.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
 function loadRawRow(db, id) {
@@ -60,16 +60,15 @@ function auditArchive(db, id, row, opts) {
  *
  * Snapshots the full row into `raw_archive`, flips `kind` to `'archived'` so the
  * append-only trigger lets the delete through, then deletes the row. All in one
- * SAVEPOINT so it can be nested inside an outer transaction (e.g. batchWriteAndDelete).
+ * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
  *
  * Throws if the row does not exist or is not `kind='raw'`.
  */
 export function archiveRawMemory(db, id, opts) {
     const row = loadRawRow(db, id);
-    // SAVEPOINT (not BEGIN) so this works whether or not we're already inside a
-    // transaction. SQLite refuses BEGIN within a transaction; SAVEPOINT nests safely.
-    db.exec('SAVEPOINT archive_raw');
-    try {
+    // A SAVEPOINT when already inside a transaction (e.g. batchWriteAndDelete), so a throw here
+    // rolls back only this archive.
+    withWriteScope(db, 'archive_raw', () => {
         moveRowToArchive(db, id, row, opts);
         auditArchive(db, id, row, opts);
         // Archiving a child under a level-2 summary marks the parent dirty, inside the
@@ -85,15 +84,6 @@ export function archiveRawMemory(db, id, opts) {
         if (opts.afterArchive) {
             opts.afterArchive(db, id);
         }
-        db.exec('RELEASE SAVEPOINT archive_raw');
-    }
-    catch (e) {
-        try {
-            db.exec('ROLLBACK TO SAVEPOINT archive_raw');
-            db.exec('RELEASE SAVEPOINT archive_raw');
-        }
-        catch { /* savepoint already discarded; keep the original error */ }
-        throw e;
-    }
+    });
 }
 //# sourceMappingURL=raw-archive.js.map

package/dist/recall-scope.d.ts

@@ -46,6 +46,20 @@ export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void
 export declare const PRIVATE_SCOPE_RE: RegExp;
 /** True when `scope` matches the `<source>:private:*` shape. */
 export declare function isPrivateScope(scope: string | null | undefined): boolean;
+export declare const PERSONAL_SCOPE_PREFIX = "personal:private:";
+export declare const PERSONAL_OWNER_MAX: number;
+/** True for a `personal:private:<owner>` scope, any case, so a case variant is never mistaken for a team scope. */
+export declare function isPersonalScope(scope: string | null | undefined): boolean;
+/** The caller's own personal scope, or null when it has no owner that can hold one. */
+export declare function personalScopeOf(actor: {
+    owner?: string;
+} | undefined): string | null;
+/** Refuses a client-sent `personal:` scope: only the server stamps one, from the caller's owner. */
+export declare function assertClientScope(scope: string | null | undefined): void;
+/** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
+export declare function canTouchScope(actor: {
+    owner?: string;
+}, scope: string | null): boolean;
 /**
  * Recall-side scope filter — the canonical JS half of the recall default-deny
  * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
@@ -53,14 +67,22 @@ export declare function isPrivateScope(scope: string | null | undefined): boolea
  * - When `requested` is set and non-empty: exact match required.
  * - When `requested` is undefined/empty: default-deny on any
  *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
- *   quarantine buckets. `null` and public scopes pass.
+ *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
  *
  * @internal Exported for test parity with
  * `RECALL_DEFAULT_DENY_SCOPES` (single-source-of-truth verification). NOT part
  * of the public API surface; not re-exported from `src/index.ts`. Subject to
  * change without semver bump.
  */
-export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined): boolean;
+export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
+export interface SqlFragment {
+    sql: string;
+    params: string[];
+}
+/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
+export declare function scopeAdmitSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
+/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
+export declare function touchableScopeSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
 /**
  * The CLI `--scope` variant of the recall filter (JS half of the
  * SQL 'default-deny-or-exact' mode in loadSearchRows).
@@ -76,7 +98,7 @@ export declare function passesScopeFilterForRecall(scope: string | null, request
  * a private scope or a quarantine bucket (`--scope unknown:legacy`). That is
  * deliberate owner access, identical in reach to api.recall's exact-match
  * for the same input; only NON-requested private/quarantine scopes stay
- * denied.
+ * denied. A named personal scope never unlocks: the CLI has no caller identity to check it against.
  */
 export declare function passesCliRecallScopeFilter(scope: string | null, requested: string | undefined): boolean;
 /**
@@ -93,12 +115,13 @@ export declare class ScopeForbiddenError extends ForbiddenError {
  * is the act that needs authorization.
  */
 export declare function isRestrictedScope(scope: string | null | undefined): boolean;
-/** The identity a scope check runs against: a role plus any scope grants. */
+/** The identity a scope check runs against: a role, any scope grants, and the person who owns the key. */
 export interface ScopeActor {
     role: 'admin' | 'member';
     scopes?: readonly string[];
+    owner?: string;
 }
-/** True when `actor` may read `scope`: admin always; member needs an exact grant on a restricted scope. */
+/** Personal rows answer to their owner alone: role, key grants and resolver scopes never open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
 export declare function canReadScope(actor: ScopeActor, scope: string): boolean;
 /** Authorize an explicitly requested scope before any read honours it (member scope grants). */
 export declare function assertScopeRequestAllowed(actor: ScopeActor, requested: string | undefined): void;

package/dist/recall-scope.js

@@ -5,7 +5,8 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
-import { ForbiddenError } from './api-errors.js';
+import { BadRequestError, ForbiddenError } from './api-errors.js';
+import { MAX_ID_LEN } from './http-util.js';
 /**
  * Literal scopes excluded from recall by default-deny when the
  * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
@@ -58,6 +59,32 @@ export function isPrivateScope(scope) {
         return false;
     return PRIVATE_SCOPE_RE.test(scope);
 }
+export const PERSONAL_SCOPE_PREFIX = 'personal:private:';
+// The scope must fit the 256-character scope caps, so the owner gets what the prefix leaves.
+export const PERSONAL_OWNER_MAX = MAX_ID_LEN - PERSONAL_SCOPE_PREFIX.length;
+/** True for a `personal:private:<owner>` scope, any case, so a case variant is never mistaken for a team scope. */
+export function isPersonalScope(scope) {
+    if (!isScopeString(scope))
+        return false;
+    return /^personal:private:/i.test(scope);
+}
+/** The caller's own personal scope, or null when it has no owner that can hold one. */
+export function personalScopeOf(actor) {
+    const owner = actor?.owner;
+    if (!owner || owner.length > PERSONAL_OWNER_MAX || /\p{Cc}/u.test(owner))
+        return null;
+    return `${PERSONAL_SCOPE_PREFIX}${owner}`;
+}
+/** Refuses a client-sent `personal:` scope: only the server stamps one, from the caller's owner. */
+export function assertClientScope(scope) {
+    if (isScopeString(scope) && /^personal:/i.test(scope)) {
+        throw new BadRequestError(`scope ${scope} is reserved: the server sets personal scopes itself`);
+    }
+}
+/** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
+export function canTouchScope(actor, scope) {
+    return !isPersonalScope(scope) || scope === personalScopeOf(actor);
+}
 /**
  * Recall-side scope filter — the canonical JS half of the recall default-deny
  * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
@@ -65,18 +92,34 @@ export function isPrivateScope(scope) {
  * - When `requested` is set and non-empty: exact match required.
  * - When `requested` is undefined/empty: default-deny on any
  *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
- *   quarantine buckets. `null` and public scopes pass.
+ *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
  *
  * @internal Exported for test parity with
  * `RECALL_DEFAULT_DENY_SCOPES` (single-source-of-truth verification). NOT part
  * of the public API surface; not re-exported from `src/index.ts`. Subject to
  * change without semver bump.
  */
-export function passesScopeFilterForRecall(scope, requested) {
+export function passesScopeFilterForRecall(scope, requested, ownScope) {
     if (requested !== undefined && requested !== '') {
         return scope === requested;
     }
-    return !isRestrictedScope(scope);
+    return !isRestrictedScope(scope) || (ownScope != null && scope === ownScope);
+}
+/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
+export function scopeAdmitSql(col, ownScope) {
+    const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
+    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${placeholders}) AND ${col}scope NOT LIKE '%:private:%')`;
+    if (ownScope == null)
+        return { sql: `(${admitted})`, params: [...RECALL_DEFAULT_DENY_SCOPES] };
+    // The own arm sits inside the outer parentheses so a caller's `AND ${sql}` cannot split it off.
+    return { sql: `(${admitted} OR ${col}scope = ?)`, params: [...RECALL_DEFAULT_DENY_SCOPES, ownScope] };
+}
+/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
+export function touchableScopeSql(col, ownScope) {
+    const notPersonal = `${col}scope IS NULL OR ${col}scope NOT LIKE '${PERSONAL_SCOPE_PREFIX}%'`;
+    if (ownScope == null)
+        return { sql: `(${notPersonal})`, params: [] };
+    return { sql: `(${notPersonal} OR ${col}scope = ?)`, params: [ownScope] };
 }
 /**
  * The CLI `--scope` variant of the recall filter (JS half of the
@@ -93,10 +136,10 @@ export function passesScopeFilterForRecall(scope, requested) {
  * a private scope or a quarantine bucket (`--scope unknown:legacy`). That is
  * deliberate owner access, identical in reach to api.recall's exact-match
  * for the same input; only NON-requested private/quarantine scopes stay
- * denied.
+ * denied. A named personal scope never unlocks: the CLI has no caller identity to check it against.
  */
 export function passesCliRecallScopeFilter(scope, requested) {
-    if (requested !== undefined && requested !== '' && scope === requested) {
+    if (requested !== undefined && requested !== '' && !isPersonalScope(requested) && scope === requested) {
         return true;
     }
     return passesScopeFilterForRecall(scope, undefined);
@@ -126,8 +169,10 @@ export function isRestrictedScope(scope) {
     // `:private:` anywhere, any case, matches the store's SQL default-deny (store/search-rows.ts) so JS never admits what SQL hides.
     return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
 }
-/** True when `actor` may read `scope`: admin always; member needs an exact grant on a restricted scope. */
+/** Personal rows answer to their owner alone: role, key grants and resolver scopes never open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
 export function canReadScope(actor, scope) {
+    if (isPersonalScope(scope))
+        return scope === personalScopeOf(actor);
     if (actor.role === 'admin')
         return true;
     if (!isRestrictedScope(scope))

package/dist/recall-trace.js

@@ -49,7 +49,7 @@ export function writeRecallTrace(db, input) {
     try {
         const queryHash = createHash('sha256').update(input.query).digest('hex').slice(0, 16);
         const ts = new Date().toISOString();
-        db.exec('BEGIN');
+        db.exec('BEGIN IMMEDIATE');
         try {
             const insertTrace = db.prepare(`
         INSERT INTO recall_traces (ts, tenant_id, session_id, pipeline, query_hash, query_length, result_count, explain_mode)

package/dist/reject-flow.d.ts

@@ -20,6 +20,8 @@ export interface RejectFlowOpts {
     memoryId?: string;
     /** Pre-emptive form: reject a value not currently stored (or already gone). */
     value?: string;
+    /** The caller's own personal scope: the only personal rows the sweep may remove. Unset (the CLI) skips every personal row. */
+    ownScope?: string;
 }
 export interface RejectFlowResult {
     digest: string;

package/dist/reject-flow.js

@@ -11,7 +11,9 @@
  * cli.ts and api.ts, so it introduces no cycle.
  */
 import { closeHippoDb } from './db.js';
+import { BadRequestError } from './api-errors.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
+import { isPersonalScope } from './recall-scope.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
 import { stampOriginProject } from './store/entry-row.js';
@@ -45,19 +47,28 @@ function assertRejectOpts(opts) {
 function contentToReject(db, opts) {
     if (opts.memoryId === undefined)
         return opts.value;
-    // SAFETY: row's shape matches the two columns named in the SELECT above.
+    // SAFETY: row's shape matches the three columns named in the SELECT above.
     const row = db
-        .prepare(`SELECT content, tenant_id FROM memories WHERE id = ?`)
+        .prepare(`SELECT content, tenant_id, scope FROM memories WHERE id = ?`)
         .get(opts.memoryId);
     if (!row || row.tenant_id !== opts.tenantId) {
         throw new Error(`memory not found: ${opts.memoryId}`);
     }
+    // A tombstone is tenant-wide, so one made from personal text would show its reason to everyone.
+    if (isPersonalScope(row.scope))
+        throw new BadRequestError("Personal memories can't be rejected. Use forget to remove it.");
     return row.content;
 }
+/** Every row but another person's personal one, which is outside the caller's recall and so outside its reject. */
+function inReach(opts, scope) {
+    return !isPersonalScope(scope) || scope === opts.ownScope;
+}
 function removeLiveRows(db, opts, holdsValue, removal) {
     const { removedIds, removedRawIds, successors } = removal;
     const merged = [];
     for (const row of selectAllEntries(db, opts.tenantId)) {
+        if (!inReach(opts, row.scope))
+            continue;
         if (!holdsValue(row.content)) {
             if (heldTexts(row).some(holdsValue))
                 merged.push(row);
@@ -93,10 +104,13 @@ function removeLiveRows(db, opts, holdsValue, removal) {
 // bring it back. They have no markdown mirror, so the post-commit
 // mirror purge below is a no-op for them; they join removedIds for the
 // audit trail and the caller's report.
-function removeDormantCopies(db, tenantId, digest, holdsValue, removal) {
+function removeDormantCopies(db, opts, digest, holdsValue, removal) {
+    const { tenantId } = opts;
     const { removedIds, dormantSuccessorIds } = removal;
-    removedIds.push(...purgeDormantByDigest(db, tenantId, digest));
+    removedIds.push(...purgeDormantByDigest(db, tenantId, digest, (scope) => inReach(opts, scope)));
     for (const dormant of listDormantSnapshots(db, tenantId)) {
+        if (!inReach(opts, dormant.entry.scope))
+            continue;
         const successor = mergedSuccessor(dormant.entry, holdsValue, new Set(removedIds));
         if (successor === undefined)
             continue;
@@ -157,7 +171,7 @@ export function rejectValue(opts) {
         const digest = rejectionDigest(content);
         const now = new Date().toISOString();
         const removal = { removedIds: [], removedRawIds: [], successors: [], dormantSuccessorIds: [] };
-        db.exec('BEGIN');
+        db.exec('BEGIN IMMEDIATE');
         try {
             insertRejectedValue(db, {
                 tenantId: opts.tenantId,
@@ -173,7 +187,7 @@ export function rejectValue(opts) {
             // memories is the escape if stores grow 100x; not needed now.
             const holdsValue = (text) => rejectionDigest(text) === digest;
             removeLiveRows(db, opts, holdsValue, removal);
-            removeDormantCopies(db, opts.tenantId, digest, holdsValue, removal);
+            removeDormantCopies(db, opts, digest, holdsValue, removal);
             auditRejectValue(db, opts, digest, removal.removedIds);
             db.exec('COMMIT');
         }

package/dist/secret-detect.js

@@ -44,12 +44,10 @@ const SECRET_PATTERNS = [
     // does.
     { name: 'sk-style-key', re: /\bsk-[A-Za-z0-9_-]{20,}\b/ },
     { name: 'sk-underscore-key', re: /\bsk_[A-Za-z0-9]+_[A-Za-z0-9_]{6,}\b/ },
-    // Generic assignment: api_key=..., password: ..., token = "..." where the
-    // value actually LOOKS like a credential: 12+ chars drawn only from
-    // token-safe characters AND containing at least one digit. Without both
-    // constraints this pattern flags ordinary code snippets and prose
-    // (`token = estimateTokens(...)`), silently hiding code-lesson memories from ambient context.
-    { name: 'secret-assignment', re: /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*['"]?(?=[A-Za-z0-9_\-+/]*\d)[A-Za-z0-9_\-+/=]{12,}/i },
+    // The value needs 12+ token-safe chars and a digit, or `token = estimateTokens(...)` and doc templates like user:password@ would hide code lessons from ambient context.
+    // Secret names end in the keyword (dbPassword, PGPASSWORD) and token_url does not, so the match opens there and scans no prefix; pwd and pass need a _ as OLDPWD and bypass are not secrets.
+    { name: 'secret-assignment', re: /(?:(?:api[_-]?key|access[_-]?key|private[_-]?key|secret|token|passw(?:or)?d|(?<=_)(?:pwd|pass))(?:[_-]?(?:key(?:[_-]?base)?|value|secret))?['"]?\s*(?::=?|=>?)\s*['"]?|(?<=--)password(?:=|\s+))(?=[A-Za-z0-9_\-+/]*\d)[A-Za-z0-9_\-+/=]{12,}/i },
+    { name: 'url-password', re: /(?<=[A-Za-z0-9]:\/\/)[^\s/:@?#]*:(?=[^\s/@?#]*\d)[^\s/@?#]+(?=@)/ },
 ];
 const KEYISH_CONTEXT_RE = /key|token|secret|credential|bearer|auth|password/i;
 const CO_OCCURRENCE_GUARDED = new Set(['sk-style-key', 'sk-underscore-key']);
@@ -58,6 +56,7 @@ const STRICT_ONLY_PATTERNS = [
     /\bbearer\s+[A-Za-z0-9._~+/-]{16,}=*/gi,
     /\bauthorization["']?\s*[:=]\s*["']?basic\s+[A-Za-z0-9+/]{8,}={0,2}/gi,
     /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*/g,
+    /(?<=[A-Za-z0-9]:\/\/)[^\s/:@?#]*:[^\s/@?#]+(?=@)/g,
 ];
 /**
  * Scan a memory's tags + content for secret material.
@@ -88,8 +87,8 @@ export function detectSecret(entry) {
 export function redactSecrets(text) {
     return redactText(text, false);
 }
-/** A domain's first label must open on a letter, so asset names like logo@2x.png and pins like react@18.2.0 stay. */
-const EMAIL = /\b[A-Za-z0-9._%+-]+@[A-Za-z][A-Za-z0-9-]*(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}\b/g;
+/** Only a run's first character starts a match, so a long run is scanned once; a domain's first label opens on a letter, so logo@2x.png and react@18.2.0 stay. */
+const EMAIL = /(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]{1,64}@[A-Za-z][A-Za-z0-9-]*(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}\b/g;
 /** Memories never hold a raw email address (AGENTS.md); phone numbers are left alone, as their patterns misfire on ids. */
 export function maskEmails(text) {
     return text.replace(EMAIL, '[email]');

package/dist/server/auth.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage } from 'node:http';
-import type { Context } from '../api.js';
-import type { ServeOpts } from './types.js';
+import { type Context } from '../api.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
@@ -27,13 +27,15 @@ type AuthHeader = {
     token: string;
 };
 export declare function readAuthHeader(req: IncomingMessage): AuthHeader;
-type AuthOpts = Pick<ServeOpts, 'hippoRoot' | 'authResolver' | 'authResolverTimeoutMs'>;
+type AuthOpts = Pick<ResolvedServeOpts, 'hippoRoot' | 'authResolver' | 'authResolverTimeoutMs' | 'store' | 'callerLimiter'> & Partial<Pick<ResolvedServeOpts, 'failedAuthLimiter'>>;
 /** Add-ons call this to refuse a subject that would collide with a built-in actor. */
 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. Opens
- * the DB only for an API-key-shaped Bearer token (or any Bearer token when no
+ * 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.
  */
 export declare function buildContextWithAuth(req: IncomingMessage, opts: AuthOpts): Promise<Context>;
@@ -44,7 +46,7 @@ export declare function buildContextWithAuth(req: IncomingMessage, opts: AuthOpt
  * envelope. Loopback no-auth still passes.
  */
 export declare function requireAuth(req: IncomingMessage, opts: AuthOpts): Promise<void>;
-/** Never rejects: an outage (5xx) skips one heartbeat tick, only a definite 4xx denial closes the stream. */
+/** 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'>;
 /** Gate for any action beyond the caller's own tenant: a tenant's admin, by key or resolver, is never a host admin. */
 export declare function assertCrossTenantAdmin(ctx: Context, what: string): void;

package/dist/server/auth.js

@@ -3,7 +3,9 @@ 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';
 /**
@@ -134,51 +136,105 @@ async function askResolver(resolver, token, deadlineMs) {
     return clean;
 }
 const DEFAULT_RESOLVER_DEADLINE_MS = 5000;
+/** Runs only before scrypt, so junk, unknown, revoked and expired tokens and a proven key's re-check never spend a colleague's budget. */
+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)))) {
+        throw new HttpError(429, 'too many key checks from this address', limiter.retryAfterSec);
+    }
+}
 /** Shared by buildContextWithAuth and requireAuth so the two cannot drift. */
-async function resolveBearer(token, opts) {
+async function resolveBearer(req, 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 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 = verifyApiKeyCached(opts.hippoRoot, token);
+    const key = await verifyApiKeyCached(opts.hippoRoot, token, opts.store, () => chargeScryptRun(req, opts));
     if (!key)
         throw new HttpError(401, 'invalid api key');
-    return { tenantId: key.tenantId, subject: `api_key:${key.keyId}`, role: key.role, scopes: key.scopes };
+    const id = { tenantId: key.tenantId, subject: `api_key:${key.keyId}`, role: key.role, scopes: key.scopes };
+    if (key.ownerSubject)
+        id.owner = key.ownerSubject;
+    return id;
 }
-/**
- * Build a per-request Context from the Authorization header and remote
- * address. Throws HttpError(401) for invalid / missing credentials. Opens
- * 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.
- */
-export async function buildContextWithAuth(req, opts) {
+/** The auth check without a charge: the bearer's identity, or null for the loopback fallback. */
+async function checkAuth(req, opts) {
     const auth = readAuthHeader(req);
     if (auth.kind === 'malformed') {
         throw new HttpError(401, 'invalid api key');
     }
-    if (auth.kind === 'bearer') {
-        const id = await resolveBearer(auth.token, opts);
-        const actor = { subject: id.subject, role: id.role, scopes: id.scopes };
-        if (id.viaAuthResolver)
-            actor.viaAuthResolver = true;
-        // Only the server's own tenant owns the host; any other tenant's admin key is a tenant admin.
-        else if (id.role === 'admin' && id.tenantId === resolveTenantId({}))
-            actor.hostAdmin = true;
-        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor };
-    }
-    // No Authorization header. Loopback-only fallback for a direct local caller (no proxy headers),
-    // unless HIPPO_REQUIRE_AUTH=1 forbids the local-CLI escape hatch.
+    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.
     if (envRequireAuth()) {
         throw new HttpError(401, 'auth required');
     }
     assertLocalCaller(req);
+    return null;
+}
+function bearerActor(id) {
+    const actor = { subject: id.subject, role: id.role, scopes: id.scopes };
+    if (id.owner !== undefined)
+        actor.owner = id.owner;
+    if (id.viaAuthResolver)
+        actor.viaAuthResolver = true;
+    // Only the server's own tenant owns the host; any other tenant's admin key is a tenant admin.
+    else if (id.role === 'admin' && id.tenantId === resolveTenantId({}))
+        actor.hostAdmin = true;
+    return actor;
+}
+/** 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;
+const CALLER_WARN_EVERY_MS = 60_000;
+const callerWarnedAt = new Map();
+function warnCallerLimited(req, key, tenantId, person) {
+    const now = Date.now();
+    const last = callerWarnedAt.get(key);
+    if (last !== undefined && now - last < CALLER_WARN_EVERY_MS)
+        return;
+    callerWarnedAt.delete(key);
+    if (callerWarnedAt.size >= LIMITER_MAX_KEYS) {
+        const oldest = callerWarnedAt.keys().next();
+        if (!oldest.done)
+            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) });
+}
+function chargeCaller(req, tenantId, actor, opts) {
+    const limiter = opts.callerLimiter;
+    if (!limiter)
+        return;
+    const person = ownerOrSubject(actor);
+    const key = `${tenantId}\u0000${person}`;
+    if (limiter.check(key))
+        return;
+    warnCallerLimited(req, 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.
+ */
+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);
+        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor, store: opts.store };
+    }
     // Loopback fallback is process-local, treat as admin.
     return {
         hippoRoot: opts.hippoRoot,
         tenantId: resolveTenantId({}),
         actor: { subject: 'localhost:cli', role: 'admin', hostAdmin: true },
+        store: opts.store,
     };
 }
 /**
@@ -188,27 +244,18 @@ export async function buildContextWithAuth(req, opts) {
  * envelope. Loopback no-auth still passes.
  */
 export async function requireAuth(req, opts) {
-    const auth = readAuthHeader(req);
-    if (auth.kind === 'malformed') {
-        throw new HttpError(401, 'invalid api key');
-    }
-    if (auth.kind === 'bearer') {
-        await resolveBearer(auth.token, opts);
-        return;
-    }
-    if (envRequireAuth()) {
-        throw new HttpError(401, 'auth required');
-    }
-    assertLocalCaller(req);
+    const id = await checkAuth(req, opts);
+    if (id !== null)
+        chargeCaller(req, id.tenantId, bearerActor(id), opts);
 }
-/** Never rejects: an outage (5xx) skips one heartbeat tick, only a definite 4xx denial closes the stream. */
+/** 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) {
     try {
-        await requireAuth(req, opts);
+        await checkAuth(req, opts);
         return 'ok';
     }
     catch (err) {
-        return err instanceof HttpError && err.status < 500 ? 'revoked' : 'unavailable';
+        return err instanceof HttpError && err.status < 500 && err.status !== 429 ? 'revoked' : 'unavailable';
     }
 }
 /** Gate for any action beyond the caller's own tenant: a tenant's admin, by key or resolver, is never a host admin. */

package/dist/server/client-ip.d.ts

@@ -21,5 +21,7 @@ import type { RateLimiter } from '../rate-limit.js';
  * the client sent, so they never pick the bucket.
  */
 export declare function clientIpForRateLimit(req: IncomingMessage): string;
+/** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
+export declare function subscriberKey(ip: string): string;
 export declare function enforceRateLimit(req: IncomingMessage, path: string, limiter?: RateLimiter): void;
 //# sourceMappingURL=client-ip.d.ts.map

package/dist/server/client-ip.js

@@ -67,6 +67,21 @@ function trustedProxyList(raw) {
     trustedProxyCache = { raw, list };
     return list;
 }
+/** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
+export function subscriberKey(ip) {
+    const bare = ip.split('%')[0];
+    if (bare.toLowerCase().startsWith('::ffff:') && isIP(bare.slice(7)) === 4)
+        return bare.slice(7);
+    if (isIP(bare) !== 6)
+        return ip;
+    const [head = '', tail] = bare.toLowerCase().split('::');
+    const left = head ? head.split(':') : [];
+    const right = tail ? tail.split(':') : [];
+    // A trailing dotted quad holds two groups; isIP has already checked the shape.
+    const rightGroups = right.length + (right.at(-1)?.includes('.') ? 1 : 0);
+    const groups = tail === undefined ? left : [...left, ...Array(8 - left.length - rightGroups).fill('0'), ...right];
+    return `${groups.slice(0, 4).map((g) => parseInt(g, 16).toString(16)).join(':')}::/64`;
+}
 function isTrustedProxy(list, ip) {
     const bare = ip.startsWith('::ffff:') && isIP(ip.slice(7)) === 4 ? ip.slice(7) : ip;
     const family = isIP(bare);
@@ -85,7 +100,7 @@ export function enforceRateLimit(req, path, limiter) {
     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');
+            throw new HttpError(429, 'rate limit exceeded', limiter.retryAfterSec);
         }
     }
 }

package/dist/server/mcp-http.d.ts

@@ -1,5 +1,11 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { ServeOpts } from './types.js';
-export declare function handleMcpPost(req: IncomingMessage, res: ServerResponse, opts: ServeOpts): Promise<void>;
-export declare function handleMcpStream(req: IncomingMessage, res: ServerResponse, opts: ServeOpts, streamSlots: Map<string, number>): Promise<void>;
+import type { Context } from '../api.js';
+import { type McpContext } from '../mcp/server.js';
+import type { CallerProject } from '../prompt-hook.js';
+import type { ResolvedServeOpts } from './types.js';
+/** On a shared store, the caller's project from X-Hippo-Project and the comma-separated X-Hippo-Project-Aliases; any other store ignores both. */
+export declare function callerProjectFromHeaders(req: IncomingMessage, hippoRoot: string): CallerProject | undefined;
+export declare function mcpContextFor(ctx: Context, clientKey: string, autoSleep: McpContext['autoSleep'], project?: CallerProject): McpContext;
+export declare function handleMcpPost(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts): Promise<void>;
+export declare function handleMcpStream(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts, streamSlots: Map<string, number>): Promise<void>;
 //# sourceMappingURL=mcp-http.d.ts.map