hippo-memory 1.59.0 → 1.61.0

package/dist/audit.d.ts

@@ -1,6 +1,7 @@
 import { type MemoryEntry } from './memory.js';
 import type { DatabaseSyncLike } from './db.js';
 import type { JsonObject } from './working-memory.js';
+import { type KeysetPosition } from './keyset.js';
 export type AuditSeverity = 'warning' | 'error';
 export interface AuditIssue {
     memoryId: string;
@@ -42,6 +43,8 @@ export interface QueryAuditOpts {
     op?: AuditOp;
     since?: string;
     limit?: number;
+    /** Resume after this row: the (ts, id) position the previous page ended on. */
+    after?: KeysetPosition;
 }
 export interface AuditEvent {
     id: number;

package/dist/audit.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { canAutoDelete } from './memory.js';
 import { log } from './log.js';
+import { keysetAfter } from './keyset.js';
 export const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
     'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',
@@ -274,11 +275,13 @@ export function queryAuditEvents(db, opts) {
         where.push('ts >= ?');
         params.push(opts.since);
     }
-    const limit = Math.max(1, Math.min(opts.limit ?? 100, 10000));
+    const after = keysetAfter('ts', 'id', opts.after);
+    // One past the route's 10000 cap: GET /v1/audit reads a row ahead to tell whether another page exists.
+    const limit = Math.max(1, Math.min(opts.limit ?? 100, 10001));
     // 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);
+        .prepare(`SELECT ${AUDIT_COLUMNS} FROM audit_log WHERE ${where.join(' AND ')}${after.sql} ORDER BY ts DESC, id DESC LIMIT ?`)
+        .all(...params, ...after.params, limit);
     return rows.map(rowToAuditEvent);
 }
 /**
@@ -330,6 +333,7 @@ function safeJsonParse(raw) {
         return v instanceof Object ? v : {};
     }
     catch {
+        // Malformed metadata reads as empty so the audit row itself stays listable.
         return {};
     }
 }

package/dist/auth.d.ts

@@ -1,7 +1,13 @@
-import type { DatabaseSyncLike } from './db.js';
+import { type DatabaseSyncLike } from './db.js';
+import { type KeysetPosition } from './keyset.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;
+/** Counts since process start, so a flood of bad tokens shows as scrypt work, not just as 401s. */
+export interface ApiKeyVerifyStats {
+    readonly storeLookups: number;
+    readonly scryptRuns: number;
+}
+export declare function apiKeyVerifyStats(): ApiKeyVerifyStats;
 export interface CreateApiKeyOpts {
     tenantId: string;
     label?: string;
@@ -22,7 +28,29 @@ export interface ValidateResult {
     /** EI2: scope grants for this key. Present only when valid=true. */
     scopes?: string[];
 }
+/** The identity a verified API key carries. */
+export interface VerifiedApiKey {
+    tenantId: string;
+    keyId: string;
+    role: 'admin' | 'member';
+    scopes: string[];
+}
 export declare function validateApiKey(db: DatabaseSyncLike, plaintext: string): ValidateResult;
+/** How long a verified key is trusted without a store read; also the ceiling on a revoke made by another process. */
+export declare const VERIFIED_KEY_TTL_MS = 60000;
+/** LRU of verified keys with an absolute TTL. Holds a SHA-256 of the token, never the token. */
+export declare class VerifiedKeyCache {
+    private readonly capacity;
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(capacity: number, ttlMs: number);
+    get size(): number;
+    get(hippoRoot: string, keyId: string, plaintext: string, now: number): VerifiedApiKey | undefined;
+    set(hippoRoot: string, keyId: string, plaintext: string, key: VerifiedApiKey, now: number): void;
+    delete(keyId: string): void;
+}
+/** Verify a bearer API key for `hippoRoot`; a cache hit skips both scrypt and the DB open. Null when invalid. */
+export declare function verifyApiKeyCached(hippoRoot: string, plaintext: string): VerifiedApiKey | null;
 export declare function revokeApiKey(db: DatabaseSyncLike, keyId: string): void;
 /** EI2: grant `keyId` read access to one restricted `scope`. Idempotent. */
 export declare function grantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
@@ -45,7 +73,20 @@ export interface ApiKeyListItem {
     /** EI2: restricted scopes this key may read. */
     scopes: string[];
 }
-export declare function listApiKeys(db: DatabaseSyncLike, opts: {
+export interface ListApiKeysOpts {
     active: boolean;
-}): ApiKeyListItem[];
+    /** Only this tenant's keys; omit for every tenant (the CLI's single-tenant view). */
+    tenantId?: string;
+    /** Resume after this row: the position the previous page ended on (key and id are both the row id). */
+    after?: KeysetPosition;
+    limit?: number;
+}
+/** A listed key plus its row id, the paging key the list item itself does not expose. */
+export interface ApiKeyListRow {
+    rowId: number;
+    key: ApiKeyListItem;
+}
+/** Keys newest first, with their row ids, filtered and limited in SQL. */
+export declare function listApiKeyRows(db: DatabaseSyncLike, opts: ListApiKeysOpts): ApiKeyListRow[];
+export declare function listApiKeys(db: DatabaseSyncLike, opts: ListApiKeysOpts): ApiKeyListItem[];
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -1,10 +1,13 @@
-import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import { createHash, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import { openHippoDb, closeHippoDb } from './db.js';
+import { keysetAfter } from './keyset.js';
 /** 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;
 const BASE32 = 'abcdefghijklmnopqrstuvwxyz234567';
+const MINTED_KEY_PATTERN = new RegExp(`^${API_KEY_PREFIX}[a-z2-7]{${ID_LEN}}\\.[a-z2-7]{${SECRET_LEN}}$`);
 function randBase32(n) {
     const bytes = randomBytes(n);
     let out = '';
@@ -18,18 +21,9 @@ function hashKey(plaintext) {
     const hash = scryptSync(plaintext, salt, SCRYPT_KEYLEN);
     return `scrypt$${salt.toString('hex')}$${hash.toString('hex')}`;
 }
-// Constant dummy hash precomputed once at module load. Used by validateApiKey
-// to pay the scrypt cost on the miss path (unknown / revoked / malformed key)
-// so the timing signal between hit and miss is reduced. The DB lookup branch
-// itself can still leak via cache effects — v0.40 follow-up: request-level
-// rate limit on /v1/* to bound key-id enumeration. Stored format identical to
-// real hashes: scrypt$saltHex$hashHex.
-const DUMMY_PLAINTEXT = 'hk_dummy_constant_padding_for_timing.dummy_secret_padding_for_timing_x';
-// Precomputed `hashKey(DUMMY_PLAINTEXT)`: computing it at module load put one scrypt on every CLI start.
-const DUMMY_HASH = 'scrypt$5b2117156f1ad78738fd8b6a5bace454$92e098fa28003b7c38ba8f1451bd8618260a4a3c5a64b87cc2b471567c0960e7';
-// Not a secret (it's padding, not a real key hash): exposed only so a test can pin its shape.
-export function _dummyHashForTests() {
-    return DUMMY_HASH;
+const verifyStats = { storeLookups: 0, scryptRuns: 0 };
+export function apiKeyVerifyStats() {
+    return { ...verifyStats };
 }
 function verifyKey(plaintext, stored) {
     const parts = stored.split('$');
@@ -37,6 +31,7 @@ function verifyKey(plaintext, stored) {
         return false;
     const salt = Buffer.from(parts[1], 'hex');
     const expected = Buffer.from(parts[2], 'hex');
+    verifyStats.scryptRuns++;
     const actual = scryptSync(plaintext, salt, expected.length);
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
@@ -52,49 +47,115 @@ export function createApiKey(db, opts) {
     db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role) VALUES (?, ?, ?, ?, ?, ?)`).run(keyId, hash, opts.tenantId, opts.label ?? null, new Date().toISOString(), opts.role ?? 'admin');
     return { keyId, plaintext };
 }
-export function validateApiKey(db, plaintext) {
-    const dot = plaintext.indexOf('.');
-    if (dot < 0) {
-        // Malformed input still pays the scrypt cost so caller cannot distinguish
-        // "no dot" from "unknown key_id" by timing.
-        verifyKey(DUMMY_PLAINTEXT, DUMMY_HASH);
-        return { valid: false };
-    }
-    const keyId = plaintext.slice(0, dot);
+/** One full check against the store: shape, row, revocation, then scrypt. Null for any failure. */
+function lookupApiKey(db, plaintext) {
+    if (!MINTED_KEY_PATTERN.test(plaintext))
+        return null;
+    const keyId = plaintext.slice(0, API_KEY_PREFIX.length + ID_LEN);
     // SAFETY: row comes from the SELECT above, which projects exactly
     // key_hash, tenant_id, revoked_at, role; `.get` returns undefined when no
     // row matches key_id.
     const row = db
         .prepare(`SELECT key_hash, tenant_id, revoked_at, role FROM api_keys WHERE key_id = ?`)
         .get(keyId);
-    // Always run verifyKey — on miss/revoked, against DUMMY_HASH so scrypt cost
-    // is paid. This reduces timing signal between hit and miss, but the DB
-    // lookup itself can still leak via cache effects. v0.40 follow-up: add
-    // request-level rate limit on /v1/* to bound enumeration.
-    const target = (row && !row.revoked_at) ? row.key_hash : DUMMY_HASH;
-    const matches = verifyKey(plaintext, target);
-    if (!row || row.revoked_at || !matches)
-        return { valid: false };
-    // v1.12.0: fail-safe to least privilege — only 'admin' is admitted as admin,
-    // anything else (including future schema drift, manual DB tampering inserting
-    // 'superuser', or a NULL slipped past the NOT NULL constraint) downgrades to
-    // 'member'. The migration constrains to 'admin' DEFAULT, but defense-in-depth.
+    // Ids are 120 random bits and not secret, so padding the miss path with scrypt hid nothing and let junk tokens burn CPU.
+    if (!row || row.revoked_at || !verifyKey(plaintext, row.key_hash))
+        return null;
+    // Fail-safe to least privilege: any role value but 'admin' reads as 'member'.
     const role = row.role === 'admin' ? 'admin' : 'member';
-    const scopes = listScopeGrants(db, keyId);
-    return { valid: true, tenantId: row.tenant_id, keyId, role, scopes };
+    return { tenantId: row.tenant_id, keyId, role, scopes: listScopeGrants(db, keyId) };
+}
+export function validateApiKey(db, plaintext) {
+    const key = lookupApiKey(db, plaintext);
+    return key ? { valid: true, ...key } : { valid: false };
+}
+/** How long a verified key is trusted without a store read; also the ceiling on a revoke made by another process. */
+export const VERIFIED_KEY_TTL_MS = 60_000;
+const VERIFIED_KEY_CACHE_CAP = 1_000;
+function secretDigest(plaintext) {
+    return createHash('sha256').update(plaintext).digest();
+}
+/** LRU of verified keys with an absolute TTL. Holds a SHA-256 of the token, never the token. */
+export class VerifiedKeyCache {
+    capacity;
+    ttlMs;
+    // Map iterates in insertion order, so re-inserting on a hit makes the first key the least recent.
+    entries = new Map();
+    constructor(capacity, ttlMs) {
+        this.capacity = capacity;
+        this.ttlMs = ttlMs;
+    }
+    get size() {
+        return this.entries.size;
+    }
+    get(hippoRoot, keyId, plaintext, now) {
+        const entry = this.entries.get(keyId);
+        if (!entry || entry.hippoRoot !== hippoRoot)
+            return undefined;
+        if (now >= entry.expiresAt) {
+            this.entries.delete(keyId);
+            return undefined;
+        }
+        // A wrong secret misses but leaves the entry, so a flood of bad guesses cannot evict a good key.
+        if (!timingSafeEqual(entry.digest, secretDigest(plaintext)))
+            return undefined;
+        this.entries.delete(keyId);
+        this.entries.set(keyId, entry);
+        return { ...entry.key, scopes: [...entry.key.scopes] };
+    }
+    set(hippoRoot, keyId, plaintext, key, now) {
+        this.entries.delete(keyId);
+        if (this.entries.size >= this.capacity) {
+            const oldest = this.entries.keys().next();
+            if (!oldest.done)
+                this.entries.delete(oldest.value);
+        }
+        const frozen = Object.freeze({ ...key, scopes: [...key.scopes] });
+        this.entries.set(keyId, { hippoRoot, digest: secretDigest(plaintext), key: frozen, expiresAt: now + this.ttlMs });
+    }
+    delete(keyId) {
+        this.entries.delete(keyId);
+    }
+}
+// SHORTCUT: per-process cache, so a revoke or scope change made by another process (the CLI) lands within VERIFIED_KEY_TTL_MS; a shared revocation epoch in the store if that is too slow.
+const verifiedKeys = new VerifiedKeyCache(VERIFIED_KEY_CACHE_CAP, VERIFIED_KEY_TTL_MS);
+/** Verify a bearer API key for `hippoRoot`; a cache hit skips both scrypt and the DB open. Null when invalid. */
+export function verifyApiKeyCached(hippoRoot, plaintext) {
+    if (!MINTED_KEY_PATTERN.test(plaintext))
+        return null;
+    const keyId = plaintext.slice(0, API_KEY_PREFIX.length + ID_LEN);
+    const hit = verifiedKeys.get(hippoRoot, keyId, plaintext, Date.now());
+    if (hit)
+        return hit;
+    verifyStats.storeLookups++;
+    const db = openHippoDb(hippoRoot);
+    let key;
+    try {
+        key = lookupApiKey(db, plaintext);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // Only successes are cached: caching misses would let junk tokens fill the cache and evict real keys.
+    if (key)
+        verifiedKeys.set(hippoRoot, keyId, plaintext, key, Date.now());
+    return key;
 }
 export function revokeApiKey(db, keyId) {
     db.prepare(`UPDATE api_keys SET revoked_at = ? WHERE key_id = ? AND revoked_at IS NULL`)
         .run(new Date().toISOString(), keyId);
+    verifiedKeys.delete(keyId);
 }
 /** EI2: grant `keyId` read access to one restricted `scope`. Idempotent. */
 export function grantScope(db, keyId, scope) {
     db.prepare(`INSERT INTO api_key_scope_grants (key_id, scope, granted_at) VALUES (?, ?, ?)
      ON CONFLICT(key_id, scope) DO NOTHING`).run(keyId, scope, new Date().toISOString());
+    verifiedKeys.delete(keyId);
 }
 /** EI2: revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */
 export function ungrantScope(db, keyId, scope) {
     db.prepare(`DELETE FROM api_key_scope_grants WHERE key_id = ? AND scope = ?`).run(keyId, scope);
+    verifiedKeys.delete(keyId);
 }
 /** EI2: every restricted scope `keyId` may read. */
 export function listScopeGrants(db, keyId) {
@@ -104,19 +165,35 @@ export function listScopeGrants(db, keyId) {
         .all(keyId);
     return rows.map((r) => r.scope);
 }
-export function listApiKeys(db, opts) {
-    const sql = opts.active
-        ? `SELECT key_id, tenant_id, label, created_at, revoked_at, role FROM api_keys WHERE revoked_at IS NULL ORDER BY id DESC`
-        : `SELECT key_id, tenant_id, label, created_at, revoked_at, role FROM api_keys ORDER BY id DESC`;
-    // SAFETY: rows come from one of the two SELECTs above, both of which
-    // project the same 6 columns (key_id, tenant_id, label, created_at,
-    // revoked_at, role) in the same order.
-    const rows = db.prepare(sql).all();
+/** Keys newest first, with their row ids, filtered and limited in SQL. */
+export function listApiKeyRows(db, opts) {
+    const where = ['1 = 1'];
+    const params = [];
+    if (opts.active)
+        where.push('revoked_at IS NULL');
+    if (opts.tenantId !== undefined) {
+        where.push('tenant_id = ?');
+        params.push(opts.tenantId);
+    }
+    const after = keysetAfter('id', 'id', opts.after);
+    params.push(...after.params);
+    const limitSql = opts.limit === undefined ? '' : ' LIMIT ?';
+    if (opts.limit !== undefined)
+        params.push(opts.limit);
+    const sql = `SELECT id, key_id, tenant_id, label, created_at, revoked_at, role FROM api_keys WHERE ${where.join(' AND ')}${after.sql} ORDER BY id DESC${limitSql}`;
+    // SAFETY: the SELECT above projects exactly these 7 columns, in this order.
+    const rows = db.prepare(sql).all(...params);
     return rows.map(r => ({
-        keyId: r.key_id, tenantId: r.tenant_id, label: r.label,
-        createdAt: r.created_at, revokedAt: r.revoked_at,
-        role: r.role === 'admin' ? 'admin' : 'member',
-        scopes: listScopeGrants(db, r.key_id),
+        rowId: r.id,
+        key: {
+            keyId: r.key_id, tenantId: r.tenant_id, label: r.label,
+            createdAt: r.created_at, revokedAt: r.revoked_at,
+            role: r.role === 'admin' ? 'admin' : 'member',
+            scopes: listScopeGrants(db, r.key_id),
+        },
     }));
 }
+export function listApiKeys(db, opts) {
+    return listApiKeyRows(db, opts).map(r => r.key);
+}
 //# sourceMappingURL=auth.js.map

package/dist/autolearn.js

@@ -4,10 +4,11 @@
  */
 import { execSync, execFileSync, spawn } from 'child_process';
 import { createMemory, Layer, DEFAULT_HALF_LIFE_DAYS } from './memory.js';
-import { loadAllEntries } from './store.js';
-import { textOverlap } from './search.js';
+import { loadAllEntries } from './store/entry-reads.js';
+import { textOverlap } from './tokenize.js';
 import { isContentWorthStoring } from './audit.js';
 import { redactSecretsStrict } from './secret-detect.js';
+import { log } from './log.js';
 /** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; no store is in reach, so `hippo watch` re-derives its half-life from the store's config. */
 export function captureError(exitCode, stderr, command, tenantId) {
     // Truncate to first 500 chars to avoid storing megabytes of build logs
@@ -154,7 +155,8 @@ export function isGitRepo(cwd) {
         });
         return raw.trim() === 'true';
     }
-    catch {
+    catch (err) {
+        log.debug(`autolearn: not a git repo: ${err instanceof Error ? err.message : String(err)}`);
         return false;
     }
 }
@@ -169,7 +171,8 @@ export function fetchGitLog(cwd, days) {
         ], { encoding: 'utf8', cwd, timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
         return raw;
     }
-    catch {
+    catch (err) {
+        log.debug(`autolearn: git log unavailable: ${err instanceof Error ? err.message : String(err)}`);
         return '';
     }
 }

package/dist/capture/command.d.ts

@@ -0,0 +1,33 @@
+import { type SessionTurn } from './transcript.js';
+export interface CaptureOptions {
+    source: 'stdin' | 'file' | 'last-session';
+    filePath?: string;
+    /** Explicit transcript path for `--last-session`. Without one, `stdinText`
+     * is used, then auto-discovery under `~/.claude/projects/` on a manual run. */
+    transcriptPath?: string;
+    /** Read from stdin by the caller (cli.ts), which owns the bounded wait.
+     * `stdinTimedOut` marks an empty read "unknown", not "no payload". */
+    stdinText?: string;
+    stdinTimedOut?: boolean;
+    sessionTurns?: readonly SessionTurn[];
+    /**
+     * Tee stdout/stderr to this log file while capture runs. Mirrors the
+     * pattern used by `hippo sleep --log-file` so the SessionEnd hook output
+     * (invisible during TUI teardown) can be surfaced via `hippo last-sleep`
+     * on the next session start. Appends rather than truncates — `hippo sleep`
+     * writes the same file first in the SessionEnd sequence.
+     */
+    logFile?: string;
+    dryRun: boolean;
+    global: boolean;
+    /**
+     * L9: tenant scope for the dedup read in `cmdCaptureCore`. When provided
+     * AND `global` is false, the dedup check only considers this tenant's
+     * existing memories. Undefined preserves pre-1.12.1 host-wide dedup
+     * behaviour. Ignored when `global: true` (global captures are host-wide).
+     */
+    tenantId?: string;
+    originProject?: string;
+}
+export declare function cmdCapture(hippoRoot: string, options: CaptureOptions): void;
+//# sourceMappingURL=command.d.ts.map