@spool-lab/core 0.4.12 → 0.5.0

package/dist/security/repo.d.ts

@@ -0,0 +1,190 @@
+import type Database from 'better-sqlite3';
+import type { SensitiveKind } from '@spool-lab/redact';
+import type { FindingRow, FindingState, OccurrenceBySession, RiskByCategoryRow, SessionWithFindingCounts } from './types.js';
+export interface FindingFilter {
+    sessionId?: number;
+    kind?: SensitiveKind;
+    /** Multi-select kinds. When non-empty takes precedence over `kind`.
+     *  Used by the Security page filter pills which support clicking
+     *  multiple chips to OR them together. */
+    kinds?: readonly SensitiveKind[];
+    state?: FindingState | 'any';
+    severity?: 'high' | 'low';
+    /** When true, info-tier kinds (absolute-path / ip / internal-host)
+     *  are excluded at the SQL layer. Needed by SessionCard fetches —
+     *  a session with 800+ absolute-path + a handful of api-keys would
+     *  otherwise have its non-info findings shoved off the first page
+     *  by `detected_at DESC` ordering, and the client-side info filter
+     *  has nothing left to render. Ignored when `kind` or `kinds`
+     *  explicitly includes an info kind. */
+    excludeInfo?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface SessionFindingFilter {
+    kind?: SensitiveKind;
+    kinds?: readonly SensitiveKind[];
+    state?: FindingState | 'any';
+    severity?: 'high' | 'low';
+    /** Free-text on session title. */
+    text?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface Page<T> {
+    rows: T[];
+    hasMore: boolean;
+}
+export interface FindingInput {
+    sessionId: number;
+    messageId: number | null;
+    kind: SensitiveKind;
+    valueHash: string;
+    confidence: number;
+    provider: string;
+    startOffset: number;
+    endOffset: number;
+    /** Allowlist hit at insert time → 'dismissed'; else 'active'. */
+    state: FindingState;
+}
+/** Insert a batch of findings. Caller wraps in a transaction. */
+export declare function insertFindings(db: Database.Database, rows: readonly FindingInput[]): void;
+/** Delete all non-purged rows for the providers being rescanned —
+ *  i.e. wipe the producer's previous output so the upcoming
+ *  `insertFindings` is the canonical truth.
+ *
+ *  Includes `state='dismissed'` deliberately: those rows are derived
+ *  state. The user's "ignore" decisions live in `allowlist_session`
+ *  and `allowlist_global` (preserved here), and the scan path
+ *  re-emits findings as `state='dismissed'` whenever it encounters a
+ *  hit that matches an allowlist row. Re-inserting also keeps
+ *  `findings.value_hash` aligned with the per-kind allowlist
+ *  preference (security.json `kindAllowlist`) — without this delete,
+ *  a mute → unmute cycle would accumulate phantom dismissed rows
+ *  (one set per cycle), inflating audit counts and breaking
+ *  `riskByCategory` totals over time.
+ *
+ *  Purged rows are the only state that's NOT producer-derived —
+ *  they correspond to destructive `messages.content_text` rewrites
+ *  the user explicitly approved. Preserving them is the audit
+ *  contract documented in the design doc. */
+export declare function deleteRefreshableFindings(db: Database.Database, sessionId: number, providers: readonly string[]): void;
+/** @deprecated Renamed to {@link deleteRefreshableFindings} after the
+ *  active-only filter was found to leak phantom dismissed rows
+ *  across mute→unmute cycles. Kept as a thin alias so callers
+ *  outside the repo don't break mid-stack. */
+export declare const deleteActiveFindings: typeof deleteRefreshableFindings;
+/** Recompute sessions.scan_finding_count + scan_high_count from the
+ *  findings table.
+ *
+ *  Counts EXCLUDE info-tier kinds (absolute-path, ip, internal-host).
+ *  Those are stored — useful for an opt-in "Show informational
+ *  signals" toggle — but they don't drive the Library row badge
+ *  because their pattern-only signal has too high a false-positive
+ *  rate to be meaningful at first glance. */
+export declare function updateSessionCounts(db: Database.Database, sessionId: number): void;
+export declare function setSessionScanProfile(db: Database.Database, sessionId: number, profile: string, completedAt: string): void;
+/** Set every session's scan_profile to NULL — used by "Rescan all" so
+ *  every session re-enqueues. */
+export declare function invalidateAllScanProfiles(db: Database.Database): number;
+/** Drop the scan profile for one session — used by the sync cascade
+ *  when a session's messages change after first scan. */
+export declare function invalidateSessionScanProfile(db: Database.Database, sessionId: number): void;
+/** Sessions whose stored profile doesn't structurally match
+ *  `currentProfile`. Used at boot for backfill enqueue. */
+export declare function listSessionsNeedingScan(db: Database.Database, currentProfile: string): number[];
+export declare function listFindings(db: Database.Database, filter: FindingFilter): FindingRow[];
+export declare function listFindingsPage(db: Database.Database, filter: FindingFilter): Page<FindingRow>;
+export declare function listSessionsWithFindings(db: Database.Database, filter: SessionFindingFilter): SessionWithFindingCounts[];
+export declare function listSessionsWithFindingsPage(db: Database.Database, filter: SessionFindingFilter): Page<SessionWithFindingCounts>;
+/** Total distinct sessions matching the same filter as
+ *  `listSessionsWithFindings` — used by the renderer to show
+ *  "涉及 N 个会话" without loading every page. Cheaper than the list
+ *  query: no SELECT projection, no GROUP BY, no ORDER BY. */
+export declare function countSessionsWithFindings(db: Database.Database, filter: SessionFindingFilter): number;
+/** Risk by category — one row per kind that has ≥ 1 active finding.
+ *  Drives the Watchtower-style panel on the Security page. */
+export declare function riskByCategory(db: Database.Database): RiskByCategoryRow[];
+/** Cross-session blast radius for one leaked value. Returns every
+ *  session that has ≥ 1 ACTIVE finding sharing the given
+ *  `(kind, valueHash)`, with the per-session occurrence count, project,
+ *  and most-recent detection time. Ordered most-recent-first.
+ *
+ *  Spool already collapses repeated occurrences of a value WITHIN a
+ *  session into one row (×N); this extends that view across the whole
+ *  archive so the user can see "this same key also leaked in 4 other
+ *  sessions". Dismissed/purged occurrences are excluded — they no
+ *  longer expose the value through search / AI / browse. */
+export declare function occurrencesByValueHash(db: Database.Database, kind: SensitiveKind, valueHash: string): OccurrenceBySession[];
+/** The most recent `scan_completed_at` across ALL sessions, regardless
+ *  of whether they currently have active findings. Drives the Security
+ *  page's "scanned X ago" label. Deriving it from the filtered,
+ *  paginated findings list undercounts: a session scanned + cleaned
+ *  (no active findings) drops off that list and stops contributing, so
+ *  the label could read older than the true last scan. Returns null
+ *  when nothing has been scanned yet. */
+export declare function lastScanCompletedAt(db: Database.Database): string | null;
+/** Read the live raw value for one finding. Used by the UI's review
+ *  panel and the Purge confirm dialog. Returns null when the finding
+ *  no longer points at a valid message (race against session
+ *  deletion) or has been purged (offsets now point at the mask). */
+export declare function getFindingValue(db: Database.Database, findingId: number): string | null;
+/** Bulk version of `getFindingValue` — one SQL query for N finding
+ *  ids instead of N round-trips. Caller fans the result map back out
+ *  by id; missing keys are treated as `null` (purged / vanished). */
+export declare function getFindingValues(db: Database.Database, findingIds: readonly number[]): Record<number, string | null>;
+export interface AllowlistSnapshot {
+    /** (kind|value_hash) keys for this session. */
+    session: Set<string>;
+    /** (kind|value_hash) keys, global scope. */
+    global: Set<string>;
+}
+export declare function getAllowlists(db: Database.Database, sessionId: number): AllowlistSnapshot;
+export declare function isAllowlisted(allow: AllowlistSnapshot, kind: SensitiveKind, valueHash: string): boolean;
+export declare function addAllowlistSession(db: Database.Database, sessionId: number, kind: SensitiveKind, valueHash: string): void;
+export declare function addAllowlistGlobal(db: Database.Database, kind: SensitiveKind, valueHash: string): void;
+export declare function removeAllowlistSession(db: Database.Database, sessionId: number, kind: SensitiveKind, valueHash: string): void;
+export declare function removeAllowlistGlobal(db: Database.Database, kind: SensitiveKind, valueHash: string): void;
+export interface AllowlistEntryRow {
+    scope: 'session' | 'global';
+    kind: SensitiveKind;
+    valueHash: string;
+    createdAt: string;
+    /** Session row context — null for global entries. */
+    sessionUuid: string | null;
+    sessionTitle: string | null;
+    /** The live plaintext value, reconstructed at read time from a
+     *  matching non-purged finding's message text (NOT stored on the
+     *  allowlist row). Null when no such finding survives — the source
+     *  message was purged, the finding was deleted, or the session is
+     *  gone — in which case the UI falls back to the kind label alone. */
+    value: string | null;
+}
+/** All allowlist rows from both tables, joined with the originating
+ *  session metadata. Drives the Settings → Security pane's "Manage…"
+ *  modal so the user can review and revoke past decisions.
+ *
+ *  Each entry's display value is reconstructed live from a matching
+ *  finding's message text — the same plaintext the findings view
+ *  shows (blurred). Nothing is persisted on the allowlist row. */
+export declare function listAllowlistEntries(db: Database.Database): AllowlistEntryRow[];
+/** Total allowlist rows across both scopes. A cheap header badge —
+ *  two `SELECT COUNT(*)` summed, no per-row value reconstruction.
+ *  Use this instead of `listAllowlistEntries().length` for counts. */
+export declare function countAllowlistEntries(db: Database.Database): number;
+/** Flip a finding to 'dismissed' and, depending on scope, write the
+ *  allowlist entry so future rescans honor the decision. Caller
+ *  wraps in a transaction. */
+export declare function dismissFinding(db: Database.Database, findingId: number, scope: 'session' | 'global', recomputeCounts?: boolean): number | null;
+/** Batch variant of {@link dismissFinding}. Dismisses many findings in a
+ *  single transaction — one allowlist write + one `updateSessionCounts`
+ *  per affected session instead of N parallel IPC round-trips, each of
+ *  which recomputes counts. Mirrors the bulk-purge pattern
+ *  (`purgeFindings`). Returns the distinct session ids touched, in
+ *  first-seen order, so the IPC layer can emit one change event per
+ *  session. Unknown ids are skipped. */
+export declare function dismissFindings(db: Database.Database, findingIds: readonly number[], scope: 'session' | 'global'): number[];
+/** Re-activate a dismissed finding and remove the allowlist entry
+ *  that pinned it (both scopes, since UI doesn't always know which). */
+export declare function undismissFinding(db: Database.Database, findingId: number): number | null;
+//# sourceMappingURL=repo.d.ts.map

package/dist/security/repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/security/repo.ts"],"names":[],"mappings":"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"}