hippo-memory 1.53.2 → 1.54.0

package/dist/api.d.ts

@@ -43,6 +43,8 @@ export interface Actor {
     role: 'admin' | 'member';
     /** EI2: restricted scopes a member key may read (auth.ts grantScope). Unused for admin actors. */
     scopes?: readonly string[];
+    /** An auth resolver vouched for this caller, so its admin role stops at its own tenant. */
+    viaAuthResolver?: true;
 }
 export interface Context {
     hippoRoot: string;
@@ -869,8 +871,8 @@ export interface AuthCreateResult {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Only an admin actor can mint (ForbiddenError otherwise), so a member key
- * can never create a key, least of all an admin one.
+ * Only an admin actor can mint (ForbiddenError otherwise), and a key never
+ * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
 export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
 /**

package/dist/api.js

@@ -6,7 +6,6 @@
  * (`hippo serve`, A1) call into this module so the business logic lives
  * in exactly one place.
  */
-import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, memoriesBackingObjects, } from './store.js';
 import { RejectedValueError } from './rejection.js';
@@ -18,7 +17,7 @@ import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineR
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
 import { createMemory, createSuccessor, applyOutcome, calculateStrength, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
-import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
+import { appendAuditEvent, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
 import { evalNow } from './ablation.js';
@@ -549,8 +548,7 @@ function recallFrom(ctx, opts, windowSize, all) {
             actor: ctx.actor.subject,
             op: 'recall',
             metadata: {
-                query_hash: createHash('sha256').update(opts.query).digest('hex').slice(0, 16),
-                query_length: opts.query.length,
+                ...auditQueryFields(opts.query),
                 results: rankedOut.length,
             },
         });
@@ -1348,16 +1346,19 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Only an admin actor can mint (ForbiddenError otherwise), so a member key
- * can never create a key, least of all an admin one.
+ * Only an admin actor can mint (ForbiddenError otherwise), and a key never
+ * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
 export function authCreate(ctx, opts) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can create API keys');
     }
+    if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
+        throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
+    }
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        const role = opts.role ?? 'admin';
+        const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
         const result = createApiKey(db, { tenantId: ctx.tenantId, label: opts.label, role });
         // v1.12.4: audit emit (closes the gap v1.12.3 CHANGELOG flagged as deferred).
         // Mirrors the auth_revoke pattern at authRevoke — same try/catch so audit
@@ -1408,10 +1409,10 @@ export function authRevoke(ctx, keyId) {
     }
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        // SAFETY: row's shape matches the three columns named in the SELECT
+        // SAFETY: row's shape matches the four columns named in the SELECT
         // above.
         const row = db
-            .prepare(`SELECT key_id, tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
+            .prepare(`SELECT key_id, tenant_id, revoked_at, role FROM api_keys WHERE key_id = ?`)
             .get(keyId);
         if (!row) {
             throw new Error(`Unknown key_id: ${keyId}`);
@@ -1420,6 +1421,9 @@ export function authRevoke(ctx, keyId) {
         if (row.tenant_id !== ctx.tenantId) {
             throw new Error(`Unknown key_id: ${keyId}`);
         }
+        if (ctx.actor.viaAuthResolver && row.role === 'admin') {
+            throw new ForbiddenError('An auth resolver admin cannot revoke an admin key, which outranks it');
+        }
         let revokedAt;
         let alreadyRevoked = false;
         if (row.revoked_at) {
@@ -1930,7 +1934,7 @@ export async function getContext(ctx, opts = {}) {
         // 'recall' op emitted by api.recall for parity). pinnedOnly + '*' fallback
         // never hit the search engines, so they don't emit (matches cmdContext).
         const ctxRecallMetadata = {
-            query: query.slice(0, 200),
+            ...auditQueryFields(query),
             results: selectedItems.length,
             mode: 'context',
         };

package/dist/audit.d.ts

@@ -27,6 +27,11 @@ export interface AppendAuditOpts {
     targetId?: string;
     metadata?: unknown;
 }
+export type AuditQueryFields = {
+    query_hash: string;
+    query_length: number;
+};
+export declare function auditQueryFields(query: string): AuditQueryFields;
 export declare function appendAuditEvent(db: DatabaseSyncLike, opts: AppendAuditOpts): void;
 export interface QueryAuditOpts {
     tenantId: string;
@@ -44,4 +49,18 @@ export interface AuditEvent {
     metadata: JsonObject;
 }
 export declare function queryAuditEvents(db: DatabaseSyncLike, opts: QueryAuditOpts): AuditEvent[];
+export interface ListAuditAfterOpts {
+    /** Last id already consumed; 0 starts from the beginning. */
+    afterId: number;
+    /** Clamped to 1..10000; default 1000. */
+    limit?: number;
+    /** Omit for every tenant (deployment-wide export). */
+    tenantId?: string;
+}
+/**
+ * Cursor read: events with id > afterId, ascending by id. Ids are AUTOINCREMENT
+ * and never reused, but deletes (retention prune) leave gaps, so resume from
+ * the last id returned, never from a count.
+ */
+export declare function listAuditEventsAfter(db: DatabaseSyncLike, opts: ListAuditAfterOpts): AuditEvent[];
 //# sourceMappingURL=audit.d.ts.map

package/dist/audit.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { canAutoDelete } from './memory.js';
 export const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
@@ -240,6 +241,12 @@ function isBigIntValue(value) {
 function bigintSafeReplacer(_key, value) {
     return isBigIntValue(value) ? value.toString() : value;
 }
+export function auditQueryFields(query) {
+    return {
+        query_hash: createHash('sha256').update(query).digest('hex').slice(0, 16),
+        query_length: query.length,
+    };
+}
 export function appendAuditEvent(db, opts) {
     db.prepare(`INSERT INTO audit_log (ts, tenant_id, actor, op, target_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), opts.tenantId, opts.actor, opts.op, opts.targetId ?? null, JSON.stringify(opts.metadata ?? {}, bigintSafeReplacer));
 }
@@ -255,13 +262,40 @@ export function queryAuditEvents(db, opts) {
         params.push(opts.since);
     }
     const limit = Math.max(1, Math.min(opts.limit ?? 100, 10000));
-    // SAFETY: the SELECT above names exactly these six columns in this order, so the
-    // row shape matches this assertion.
+    // SAFETY: AUDIT_COLUMNS names exactly the AuditRow columns, in this order.
+    const rows = db
+        .prepare(`SELECT ${AUDIT_COLUMNS} FROM audit_log WHERE ${where.join(' AND ')} ORDER BY ts DESC, id DESC LIMIT ?`)
+        .all(...params, limit);
+    return rows.map(rowToAuditEvent);
+}
+/**
+ * Cursor read: events with id > afterId, ascending by id. Ids are AUTOINCREMENT
+ * and never reused, but deletes (retention prune) leave gaps, so resume from
+ * the last id returned, never from a count.
+ */
+export function listAuditEventsAfter(db, opts) {
+    if (!Number.isInteger(opts.afterId) || opts.afterId < 0) {
+        throw new RangeError('afterId must be a non-negative integer');
+    }
+    if (opts.limit !== undefined && !Number.isInteger(opts.limit)) {
+        throw new RangeError('limit must be an integer');
+    }
+    const where = ['id > ?'];
+    const params = [opts.afterId];
+    if (opts.tenantId !== undefined) {
+        where.push('+tenant_id = ?');
+        params.push(opts.tenantId);
+    }
+    const limit = Math.max(1, Math.min(opts.limit ?? 1000, 10000));
+    // SAFETY: AUDIT_COLUMNS names exactly the AuditRow columns, in this order.
     const rows = db
-        .prepare(`SELECT id, ts, tenant_id, actor, op, target_id, metadata_json
-       FROM audit_log WHERE ${where.join(' AND ')} ORDER BY ts DESC, id DESC LIMIT ?`)
+        .prepare(`SELECT ${AUDIT_COLUMNS} FROM audit_log WHERE ${where.join(' AND ')} ORDER BY id ASC LIMIT ?`)
         .all(...params, limit);
-    return rows.map((r) => ({
+    return rows.map(rowToAuditEvent);
+}
+const AUDIT_COLUMNS = 'id, ts, tenant_id, actor, op, target_id, metadata_json';
+function rowToAuditEvent(r) {
+    return {
         id: r.id,
         ts: r.ts,
         tenantId: r.tenant_id,
@@ -271,7 +305,7 @@ export function queryAuditEvents(db, opts) {
         op: r.op,
         targetId: r.target_id,
         metadata: safeJsonParse(r.metadata_json),
-    }));
+    };
 }
 function safeJsonParse(raw) {
     try {

package/dist/auth.d.ts

@@ -1,4 +1,6 @@
 import type { DatabaseSyncLike } from './db.js';
+/** Every minted API key starts with this, so the server can route a bearer token by shape. */
+export declare const API_KEY_PREFIX = "hk_";
 export declare function _dummyHashForTests(): string;
 export interface CreateApiKeyOpts {
     tenantId: string;

package/dist/auth.js

@@ -1,5 +1,6 @@
 import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
-const KEY_PREFIX = 'hk_';
+/** Every minted API key starts with this, so the server can route a bearer token by shape. */
+export const API_KEY_PREFIX = 'hk_';
 const ID_LEN = 24; // base32 chars after prefix
 const SECRET_LEN = 32; // base32 chars after dot
 const SCRYPT_KEYLEN = 32;
@@ -40,7 +41,7 @@ function verifyKey(plaintext, stored) {
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
 export function createApiKey(db, opts) {
-    const keyId = `${KEY_PREFIX}${randBase32(ID_LEN)}`;
+    const keyId = `${API_KEY_PREFIX}${randBase32(ID_LEN)}`;
     const secret = randBase32(SECRET_LEN);
     const plaintext = `${keyId}.${secret}`;
     const hash = hashKey(plaintext);

package/dist/cli.js

@@ -81,7 +81,7 @@ import { importChatGPT, importClaude, importCursor, importGenericFile, importMar
 import { cmdCapture, cmdPreCompact, cmdPostCompact, resolveLastSessionTranscript, truncateCodePointSafe, sanitizeLogMessage, transcriptWorkingState } from './capture.js';
 import { COMPACTION_DB_WAIT_MS, replayCompactionsAt } from './compaction-record.js';
 import { readStdinBounded } from './stdin.js';
-import { auditMemories, appendAuditEvent, AUDIT_OPS, } from './audit.js';
+import { auditMemories, appendAuditEvent, auditQueryFields, AUDIT_OPS, } from './audit.js';
 import { listApiKeys, revokeApiKey } from './auth.js';
 import { buildProvenanceCoverage } from './provenance-coverage.js';
 import { buildCorrectionLatency } from './correction-latency.js';
@@ -1853,10 +1853,7 @@ async function cmdRecall(hippoRoot, query, flags) {
     }
     else if (process.env.HIPPO_ANCHORING !== 'off') {
         // SHA-256/16 per the recall-audit convention; hashQueryText is FNV-1a and brute-forceable on short queries.
-        emitCliAudit(hippoRoot, 'recall_anchor_skipped_no_session', undefined, {
-            query_hash: createHash('sha256').update(query).digest('hex').slice(0, 16),
-            query_length: query.length,
-        });
+        emitCliAudit(hippoRoot, 'recall_anchor_skipped_no_session', undefined, auditQueryFields(query));
     }
     if (cmdAnchoringHint?.reason === 'memory_dominance') {
         emitCliAudit(hippoRoot, 'recall_anchor_detected_memory_dominance', cmdAnchoringHint.memoryId, {
@@ -1878,7 +1875,7 @@ async function cmdRecall(hippoRoot, query, flags) {
     }
     // A5 audit: one 'recall' event per query, before the early-empty return, in every participating store.
     const recallMetadata = {
-        query: query.slice(0, 200),
+        ...auditQueryFields(query),
         results: results.length,
     };
     emitCliAudit(hippoRoot, 'recall', undefined, recallMetadata);

package/dist/index.d.ts

@@ -21,4 +21,6 @@ export { importChatGPT, importClaude, importCursor, importGenericFile, importMar
 export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
 export { computeSalience, SalienceDecision, SalienceResult, SalienceOptions, } from './salience.js';
 export { computeAmbientState, renderAmbientSummary, formatAmbientVector, AmbientState, } from './ambient.js';
+export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, type AuditEvent, type AuditOp, type QueryAuditOpts, type ListAuditAfterOpts, } from './audit.js';
+export { openHippoDb, openHippoDbReadOnly, closeHippoDb, type DatabaseSyncLike } from './db.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -34,4 +34,6 @@ export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buil
 export { computeSalience, } from './salience.js';
 // Pineal gland: ambient state vector
 export { computeAmbientState, renderAmbientSummary, formatAmbientVector, } from './ambient.js';
+export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, } from './audit.js';
+export { openHippoDb, openHippoDbReadOnly, closeHippoDb } from './db.js';
 //# sourceMappingURL=index.js.map

package/dist/mcp/server.d.ts

@@ -50,6 +50,7 @@ export interface McpContext {
     role?: 'admin' | 'member';
     /** EI2: scope grants for the HTTP-MCP caller's key. Absent for stdio (admin, needs none). */
     scopes?: readonly string[];
+    viaAuthResolver?: true;
     /**
      * Per-client key for state isolation under HTTP-MCP. For stdio: 'stdio-${pid}'
      * (one process = one client). For HTTP-SSE / HTTP MCP: hash(bearer + remoteAddr)

package/dist/mcp/server.js

@@ -25,9 +25,8 @@ import { recall as apiRecall, remember as apiRemember, outcome as apiOutcome, dr
 import { assertScopeRequestAllowed } from '../recall-scope.js';
 import { resolveProjectIdentity, classifyOriginProject, findHippoStoreDir } from '../project-identity.js';
 import { computePredictionBaserate } from '../predictions.js';
-import { appendAuditEvent } from '../audit.js';
+import { appendAuditEvent, auditQueryFields } from '../audit.js';
 import { RejectedValueError } from '../rejection.js';
-import { createHash } from 'node:crypto';
 import { detectAnchoring, hashQueryText, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from '../recall-history.js';
 import { detectAvailabilityBias } from '../availability.js';
 // v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map
@@ -58,7 +57,10 @@ export function findHippoRoot(cwd = process.cwd(), opts) {
  * a member key never acts as admin through MCP.
  */
 function mcpActor(ctx) {
-    return { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
+    const actor = { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
+    if (ctx?.viaAuthResolver)
+        actor.viaAuthResolver = true;
+    return actor;
 }
 // MCP stdio transport spec: messages are newline-delimited JSON-RPC, no embedded newlines.
 // https://modelcontextprotocol.io/specification/.../basic/transports#stdio
@@ -738,10 +740,7 @@ async function executeTool(name, args, ctx) {
                             actor: ctx?.actor ?? 'mcp',
                             op: 'recall_anchor_skipped_no_session',
                             targetId: undefined,
-                            metadata: {
-                                query_hash: createHash('sha256').update(query).digest('hex').slice(0, 16),
-                                query_length: query.length,
-                            },
+                            metadata: auditQueryFields(query),
                         });
                     }
                     finally {

package/dist/server.d.ts

@@ -11,8 +11,22 @@ export interface ServerHandle {
      *  flow outside tests. */
     server?: import('node:http').Server;
 }
+/** Identity an {@link AuthResolver} vouches for. The core sanitises it before use. */
+export interface ResolvedBearer {
+    tenantId: string;
+    subject: string;
+    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys) that outlive IdP deprovisioning. */
+    role: 'admin' | 'member';
+    scopes?: readonly string[];
+}
+/** Sole judge of non-`hk_` bearer tokens: null is a 401; a throw or missed deadline is a 503, so throw only when upstream is down. */
+export type AuthResolver = (token: string) => ResolvedBearer | null | Promise<ResolvedBearer | null>;
 export interface ServeOpts {
     hippoRoot: string;
+    /** Runs on every request and SSE heartbeat, so keep it cache-backed; API keys never reach it. */
+    authResolver?: AuthResolver;
+    /** Deadline for one authResolver call; defaults to 5000 ms. */
+    authResolverTimeoutMs?: number;
     port?: number;
     host?: string;
     /** Stop and exit on SIGINT/SIGTERM. Only `hippo serve` owns the process, so only it sets this. */