shieldcortex 4.31.2 → 4.32.1

package/dist/database/migrations.js

@@ -23,7 +23,6 @@
  * databases that have only partially run them.
  */
 import { randomUUID } from 'crypto';
-import { seedDefaultFirewallRules } from './seed-firewall-rules.js';
 /**
  * Log unexpected errors from idempotent DDL operations (v4.26.0).
  *
@@ -473,13 +472,10 @@ export function runMigrations(database) {
         logIfUnexpectedDdlError(err, 'firewall_rules.built_in column add');
         // (pipeline handles missing column gracefully; this is informational)
     }
-    // Seed default built-in firewall rules on first init.
-    try {
-        seedDefaultFirewallRules(database);
-    }
-    catch {
-        // Seeder runs idempotently; failures here should never block startup.
-    }
+    // Built-in firewall rule seeding now lives in `initDatabase()` AFTER the
+    // schema is applied — `runMigrations()` returns early on fresh databases
+    // (no `memories` table), so a seed call here never fired for new installs.
+    // The init-level call is idempotent and covers both fresh and existing DBs.
     // Migration: session_events.content_hash + dedupe UNIQUE index (v4.17).
     // DBs created between the foundation commit and the importer commit have
     // session_events but no content_hash column. ALTER + idempotent index
@@ -654,4 +650,104 @@ export function runMigrations(database) {
             // Best-effort marker; the stderr line above carries the signal.
         }
     }
+    // Migration: control_state table (cross-process kill-switch / pause).
+    //
+    // Phase 2 hardening: the kill switch / pause mode used to live only in
+    // module-level memory, so a dashboard (API process) activation never reached
+    // the separate MCP server process. control_state is the single-row source of
+    // truth both processes read/write; api/control.ts persists to and refreshes
+    // from it. Existing DBs that predate the table get it here (schema.sql /
+    // inline-schema.ts cover fresh installs).
+    try {
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS control_state (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        mode TEXT NOT NULL DEFAULT 'active' CHECK (mode IN ('active','paused','kill_switch')),
+        meta_json TEXT,
+        updated_at TEXT NOT NULL
+      );
+    `);
+    }
+    catch (err) {
+        logIfUnexpectedDdlError(err, 'control_state');
+    }
+    // Migration: audit_aggregates table (Phase 8a — bound defence_audit growth).
+    //
+    // defence_audit grows on every pipeline run with no DELETE anywhere, so a busy
+    // agent eventually trips the 100MB hard block (init.ts MAX_DB_SIZE) and bricks
+    // its own memory store. Retention purges (src/defence/audit/retention.ts) now
+    // delete old rows — but getLifetimeStats() scans the whole table, so a naive
+    // purge would make lifetime totals silently undercount. This single-row
+    // cumulative aggregate is the rollup target: purges add the to-be-deleted
+    // rows' contributions here BEFORE deleting, and getLifetimeStats() returns
+    // aggregate + live so the numbers never go backwards.
+    try {
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS audit_aggregates (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        total_scans INTEGER NOT NULL DEFAULT 0,
+        threats_blocked INTEGER NOT NULL DEFAULT 0,
+        quarantined INTEGER NOT NULL DEFAULT 0,
+        memories_protected INTEGER NOT NULL DEFAULT 0,
+        credential_leaks INTEGER NOT NULL DEFAULT 0,
+        updated_at TEXT
+      );
+    `);
+    }
+    catch (err) {
+        logIfUnexpectedDdlError(err, 'audit_aggregates');
+    }
+    // Migration: Phase 10 — scope the memories_au FTS trigger to UPDATE OF the
+    // indexed columns only (title, content, tags).
+    //
+    // The trigger originally shipped as `AFTER UPDATE ON memories` with no `OF`
+    // column list, so it fired a full FTS5 external-content delete+reinsert on
+    // ANY column update. The hottest write path — accessMemory() bumping
+    // access_count / last_accessed / salience on every recalled memory, plus the
+    // 5-minute decay-score persistence — never touches indexed text, so each read
+    // was re-tokenising and rewriting the FTS index for nothing (write
+    // amplification + WAL churn + more surface for FTS drift).
+    //
+    // A `CREATE TRIGGER IF NOT EXISTS` alone CANNOT replace the existing unscoped
+    // trigger on an upgraded DB, so we DROP it first, then recreate with the
+    // scoped form. Fresh installs already get the scoped trigger from
+    // schema.sql / inline-schema.ts; this block only matters for existing DBs.
+    try {
+        database.exec('DROP TRIGGER IF EXISTS memories_au');
+        database.exec(`
+      CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE OF title, content, tags ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, title, content, tags)
+        VALUES('delete', old.id, old.title, old.content, old.tags);
+        INSERT INTO memories_fts(rowid, title, content, tags)
+        VALUES (new.id, new.title, new.content, new.tags);
+      END;
+    `);
+    }
+    catch (err) {
+        logIfUnexpectedDdlError(err, 'memories_au');
+    }
+    // Migration: Phase 14 — mcp_tool_hashes table (MCP tool-description drift /
+    // rug-pull detection). `shieldcortex mcp scan` stores a sha256 of each MCP
+    // server's advertised tool definition (name + description + inputSchema) and
+    // compares it on the next scan: a CHANGED hash for an already-seen tool is
+    // the classic rug-pull signal (a server silently altering an approved tool
+    // description). Mirrors the content-hash idempotency pattern used elsewhere
+    // (session_events.content_hash). Fresh installs get this from schema.sql /
+    // inline-schema.ts; this block only matters for existing DBs.
+    try {
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS mcp_tool_hashes (
+        server_name TEXT NOT NULL,
+        tool_name TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        first_seen TEXT,
+        last_seen TEXT,
+        last_changed TEXT,
+        PRIMARY KEY (server_name, tool_name)
+      );
+    `);
+    }
+    catch (err) {
+        logIfUnexpectedDdlError(err, 'mcp_tool_hashes');
+    }
 }

package/dist/database/schema.sql

@@ -65,7 +65,7 @@ CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
   VALUES('delete', old.id, old.title, old.content, old.tags);
 END;
 
-CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE OF title, content, tags ON memories BEGIN
   INSERT INTO memories_fts(memories_fts, rowid, title, content, tags)
   VALUES('delete', old.id, old.title, old.content, old.tags);
   INSERT INTO memories_fts(rowid, title, content, tags)
@@ -229,6 +229,21 @@ CREATE INDEX IF NOT EXISTS idx_audit_result ON defence_audit(firewall_result);
 CREATE INDEX IF NOT EXISTS idx_audit_source ON defence_audit(source_type);
 CREATE INDEX IF NOT EXISTS idx_audit_project ON defence_audit(project);
 
+-- Defence: cumulative audit aggregate (single row, id=1). Retention purges roll
+-- the to-be-deleted rows' lifetime-stat contributions into this row BEFORE
+-- deleting, so getLifetimeStats() = this aggregate + a scan of the (bounded)
+-- live defence_audit table. Without it, retention would make lifetime stats
+-- silently undercount after every purge.
+CREATE TABLE IF NOT EXISTS audit_aggregates (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  total_scans INTEGER NOT NULL DEFAULT 0,
+  threats_blocked INTEGER NOT NULL DEFAULT 0,
+  quarantined INTEGER NOT NULL DEFAULT 0,
+  memories_protected INTEGER NOT NULL DEFAULT 0,
+  credential_leaks INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT
+);
+
 -- Defence: Quarantine for blocked/suspicious memories pending review
 CREATE TABLE IF NOT EXISTS quarantine (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -345,6 +360,7 @@ CREATE TABLE IF NOT EXISTS firewall_rules (
 
 CREATE INDEX IF NOT EXISTS idx_firewall_rules_priority ON firewall_rules(priority);
 CREATE INDEX IF NOT EXISTS idx_firewall_rules_enabled ON firewall_rules(enabled);
+CREATE INDEX IF NOT EXISTS idx_firewall_rules_built_in ON firewall_rules(built_in);
 
 -- Rate limits (cross-process, persisted)
 CREATE TABLE IF NOT EXISTS rate_limits (
@@ -352,3 +368,25 @@ CREATE TABLE IF NOT EXISTS rate_limits (
   write_count INTEGER NOT NULL DEFAULT 1,
   window_start_ms INTEGER NOT NULL
 );
+
+-- Control state (single row, cross-process kill-switch / pause)
+CREATE TABLE IF NOT EXISTS control_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  mode TEXT NOT NULL DEFAULT 'active' CHECK (mode IN ('active','paused','kill_switch')),
+  meta_json TEXT,
+  updated_at TEXT NOT NULL
+);
+
+-- Phase 14: MCP tool-description hashes (drift / rug-pull detection).
+-- `shieldcortex mcp scan` stores a sha256 of each MCP server's advertised tool
+-- definition; a CHANGED hash on a re-scan flags a silently-altered (rug-pulled)
+-- tool description.
+CREATE TABLE IF NOT EXISTS mcp_tool_hashes (
+  server_name TEXT NOT NULL,
+  tool_name TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  first_seen TEXT,
+  last_seen TEXT,
+  last_changed TEXT,
+  PRIMARY KEY (server_name, tool_name)
+);

package/dist/defence/audit/queries.d.ts

@@ -76,8 +76,16 @@ export interface LifetimeStats {
     memoriesProtected: number;
 }
 /**
- * Get all-time aggregate stats from the defence_audit table.
- * Fast COUNT-only queries — no heavy computation.
+ * Get all-time aggregate stats.
+ *
+ * defence_audit is now retention-bounded (see src/defence/audit/retention.ts):
+ * old rows are periodically purged so the table can't grow until it bricks the
+ * DB at the 100MB hard limit. To keep these lifetime totals correct, every purge
+ * first rolls the to-be-deleted rows' contributions into the single-row
+ * `audit_aggregates` table. So the lifetime total is `aggregate + scan(live)` —
+ * the aggregate carries the purged history and the COUNT scan covers the
+ * (bounded) rows still on disk. This guarantees totals never go backwards after
+ * a purge. The credential LIKE scan is over a bounded table now, so it's fine.
  */
 export declare function getLifetimeStats(): LifetimeStats;
 /**

package/dist/defence/audit/queries.js

@@ -107,12 +107,20 @@ export function getAuditStats(timeRange, project) {
     };
 }
 /**
- * Get all-time aggregate stats from the defence_audit table.
- * Fast COUNT-only queries — no heavy computation.
+ * Get all-time aggregate stats.
+ *
+ * defence_audit is now retention-bounded (see src/defence/audit/retention.ts):
+ * old rows are periodically purged so the table can't grow until it bricks the
+ * DB at the 100MB hard limit. To keep these lifetime totals correct, every purge
+ * first rolls the to-be-deleted rows' contributions into the single-row
+ * `audit_aggregates` table. So the lifetime total is `aggregate + scan(live)` —
+ * the aggregate carries the purged history and the COUNT scan covers the
+ * (bounded) rows still on disk. This guarantees totals never go backwards after
+ * a purge. The credential LIKE scan is over a bounded table now, so it's fine.
  */
 export function getLifetimeStats() {
     const db = getDatabase();
-    // Counts by firewall result
+    // Counts by firewall result (live, retention-bounded rows)
     const counts = db.prepare(`
     SELECT firewall_result, COUNT(*) as cnt
     FROM defence_audit
@@ -137,7 +145,25 @@ export function getLifetimeStats() {
     FROM defence_audit
     WHERE LOWER(threat_indicators) LIKE '%credential%'
   `).get();
-    const credentialLeaks = credRow?.cnt ?? 0;
+    let credentialLeaks = credRow?.cnt ?? 0;
+    // Add the cumulative aggregate of all rows already purged by retention. The
+    // table may not exist on very old DBs mid-migration — treat absence as zero.
+    try {
+        const agg = db.prepare(`
+      SELECT total_scans, threats_blocked, quarantined, memories_protected, credential_leaks
+      FROM audit_aggregates WHERE id = 1
+    `).get();
+        if (agg) {
+            totalScans += agg.total_scans;
+            threatsBlocked += agg.threats_blocked;
+            quarantined += agg.quarantined;
+            memoriesProtected += agg.memories_protected;
+            credentialLeaks += agg.credential_leaks;
+        }
+    }
+    catch {
+        // No aggregate row / table yet — lifetime == live counts.
+    }
     return {
         totalScans,
         threatsBlocked,

package/dist/defence/audit/retention.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Audit retention + size-pressure valve (Phase 8a).
+ *
+ * `logAudit()` inserts a defence_audit row on EVERY pipeline run (including
+ * per-tool-response scans) and nothing ever deletes them — the table grows
+ * forever. The DB has a 100MB hard limit (init.ts MAX_DB_SIZE) that BLOCKS all
+ * writes once exceeded, and consolidation/vacuum can't shrink audit rows that
+ * are never deleted, so a busy agent bricks its own memory store with no
+ * recovery path.
+ *
+ * Retention alone would break lifetime stats: getLifetimeStats() scans the
+ * whole defence_audit table, so deleting old rows would make every lifetime
+ * total silently undercount after a purge. So retention is COUPLED with an
+ * aggregate rollup — before deleting, the to-be-deleted rows' stat
+ * contributions are folded into the single-row `audit_aggregates` table, and
+ * getLifetimeStats() returns `aggregate + scan(remaining)`. Totals never regress.
+ */
+/** Default age-based retention window. */
+export declare const DEFAULT_RETENTION_DAYS = 90;
+/**
+ * Hard ceiling on live defence_audit rows under size pressure. When the DB file
+ * crosses the warning threshold, the valve trims the oldest rows down to (at
+ * most) this many so audit growth can't carry the file to the 100MB block.
+ */
+export declare const AUDIT_PRESSURE_ROW_CAP = 100000;
+/**
+ * Age-based retention: roll the contributions of rows older than the cutoff into
+ * audit_aggregates, then DELETE them. Aggregate + delete run in one transaction
+ * so a crash can't drop rows without first banking their stats (which would make
+ * lifetime totals regress). Returns the number of rows deleted.
+ */
+export declare function purgeOldAuditEntries(retentionDays?: number): number;
+/**
+ * Size-pressure valve. Cheap to call: it first checks the DB file size and bails
+ * unless the file has crossed the warning threshold (reusing the codebase's
+ * existing 50MB WARN_DB_SIZE via checkDatabaseSize(), so we don't keep a second
+ * copy of the threshold). When over pressure, it trims the OLDEST audit rows
+ * down to a row cap — same aggregate-then-delete path as age retention — so
+ * audit growth can never carry the DB to the 100MB block.
+ *
+ * Thresholds are injectable for tests. Simulating a real 50MB file (and, on a
+ * `:memory:` DB, ANY measurable file size) is impractical, so passing
+ * `warnBytes` BYPASSES the file-size gate entirely and drives the row-cap trim
+ * directly; `maxRows` sets the cap. In production neither is passed and the gate
+ * uses the live file size vs WARN_DB_SIZE.
+ */
+export declare function purgeAuditUnderSizePressure(options?: {
+    warnBytes?: number;
+    maxRows?: number;
+}): number;

package/dist/defence/audit/retention.js

@@ -0,0 +1,161 @@
+/**
+ * Audit retention + size-pressure valve (Phase 8a).
+ *
+ * `logAudit()` inserts a defence_audit row on EVERY pipeline run (including
+ * per-tool-response scans) and nothing ever deletes them — the table grows
+ * forever. The DB has a 100MB hard limit (init.ts MAX_DB_SIZE) that BLOCKS all
+ * writes once exceeded, and consolidation/vacuum can't shrink audit rows that
+ * are never deleted, so a busy agent bricks its own memory store with no
+ * recovery path.
+ *
+ * Retention alone would break lifetime stats: getLifetimeStats() scans the
+ * whole defence_audit table, so deleting old rows would make every lifetime
+ * total silently undercount after a purge. So retention is COUPLED with an
+ * aggregate rollup — before deleting, the to-be-deleted rows' stat
+ * contributions are folded into the single-row `audit_aggregates` table, and
+ * getLifetimeStats() returns `aggregate + scan(remaining)`. Totals never regress.
+ */
+import { getDatabase, checkDatabaseSize } from '../../database/init.js';
+/** Default age-based retention window. */
+export const DEFAULT_RETENTION_DAYS = 90;
+/**
+ * Hard ceiling on live defence_audit rows under size pressure. When the DB file
+ * crosses the warning threshold, the valve trims the oldest rows down to (at
+ * most) this many so audit growth can't carry the file to the 100MB block.
+ */
+export const AUDIT_PRESSURE_ROW_CAP = 100_000;
+/**
+ * Compute the lifetime-stat contributions of a set of defence_audit rows
+ * identified by a WHERE clause + params. Mirrors getLifetimeStats's mapping
+ * EXACTLY (BLOCK→threats_blocked, QUARANTINE→quarantined, ALLOW→memories_protected,
+ * and the credential predicate is the same case-insensitive LIKE) so the
+ * aggregate + live split reproduces the pre-purge totals byte-for-byte.
+ */
+function computeDelta(where, params) {
+    const db = getDatabase();
+    const counts = db.prepare(`
+    SELECT firewall_result, COUNT(*) AS cnt
+    FROM defence_audit
+    WHERE ${where}
+    GROUP BY firewall_result
+  `).all(...params);
+    const delta = {
+        total_scans: 0,
+        threats_blocked: 0,
+        quarantined: 0,
+        memories_protected: 0,
+        credential_leaks: 0,
+    };
+    for (const row of counts) {
+        delta.total_scans += row.cnt;
+        if (row.firewall_result === 'BLOCK')
+            delta.threats_blocked += row.cnt;
+        else if (row.firewall_result === 'QUARANTINE')
+            delta.quarantined += row.cnt;
+        else if (row.firewall_result === 'ALLOW')
+            delta.memories_protected += row.cnt;
+    }
+    const credRow = db.prepare(`
+    SELECT COUNT(*) AS cnt
+    FROM defence_audit
+    WHERE (${where}) AND LOWER(threat_indicators) LIKE '%credential%'
+  `).get(...params);
+    delta.credential_leaks = credRow?.cnt ?? 0;
+    return delta;
+}
+/**
+ * Fold a delta into the single-row audit_aggregates (id=1) cumulative totals.
+ * UPSERT so the row is created on first purge and incremented thereafter.
+ */
+function rollIntoAggregate(delta) {
+    const db = getDatabase();
+    db.prepare(`
+    INSERT INTO audit_aggregates (
+      id, total_scans, threats_blocked, quarantined, memories_protected,
+      credential_leaks, updated_at
+    ) VALUES (1, @total_scans, @threats_blocked, @quarantined, @memories_protected, @credential_leaks, @updated_at)
+    ON CONFLICT(id) DO UPDATE SET
+      total_scans = total_scans + excluded.total_scans,
+      threats_blocked = threats_blocked + excluded.threats_blocked,
+      quarantined = quarantined + excluded.quarantined,
+      memories_protected = memories_protected + excluded.memories_protected,
+      credential_leaks = credential_leaks + excluded.credential_leaks,
+      updated_at = excluded.updated_at
+  `).run({
+        total_scans: delta.total_scans,
+        threats_blocked: delta.threats_blocked,
+        quarantined: delta.quarantined,
+        memories_protected: delta.memories_protected,
+        credential_leaks: delta.credential_leaks,
+        updated_at: new Date().toISOString(),
+    });
+}
+/**
+ * Age-based retention: roll the contributions of rows older than the cutoff into
+ * audit_aggregates, then DELETE them. Aggregate + delete run in one transaction
+ * so a crash can't drop rows without first banking their stats (which would make
+ * lifetime totals regress). Returns the number of rows deleted.
+ */
+export function purgeOldAuditEntries(retentionDays = DEFAULT_RETENTION_DAYS) {
+    const db = getDatabase();
+    const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000).toISOString();
+    return db.transaction(() => {
+        const where = 'timestamp < ?';
+        const params = [cutoff];
+        const delta = computeDelta(where, params);
+        if (delta.total_scans === 0)
+            return 0; // nothing to do; skip the aggregate write
+        rollIntoAggregate(delta);
+        const res = db.prepare(`DELETE FROM defence_audit WHERE ${where}`).run(...params);
+        return Number(res.changes ?? 0);
+    })();
+}
+/**
+ * Size-pressure valve. Cheap to call: it first checks the DB file size and bails
+ * unless the file has crossed the warning threshold (reusing the codebase's
+ * existing 50MB WARN_DB_SIZE via checkDatabaseSize(), so we don't keep a second
+ * copy of the threshold). When over pressure, it trims the OLDEST audit rows
+ * down to a row cap — same aggregate-then-delete path as age retention — so
+ * audit growth can never carry the DB to the 100MB block.
+ *
+ * Thresholds are injectable for tests. Simulating a real 50MB file (and, on a
+ * `:memory:` DB, ANY measurable file size) is impractical, so passing
+ * `warnBytes` BYPASSES the file-size gate entirely and drives the row-cap trim
+ * directly; `maxRows` sets the cap. In production neither is passed and the gate
+ * uses the live file size vs WARN_DB_SIZE.
+ */
+export function purgeAuditUnderSizePressure(options = {}) {
+    const db = getDatabase();
+    const maxRows = options.maxRows ?? AUDIT_PRESSURE_ROW_CAP;
+    // Size gate. In production: only proceed once the live DB file crosses the
+    // codebase's existing WARN_DB_SIZE (50MB), surfaced via checkDatabaseSize() —
+    // we reuse that rather than keep a second copy of the threshold. When tests
+    // inject `warnBytes`, the gate is bypassed (a `:memory:` DB has no measurable
+    // file size) so the row-cap path can be exercised directly.
+    if (options.warnBytes === undefined) {
+        if (!checkDatabaseSize().warning)
+            return 0;
+    }
+    return db.transaction(() => {
+        const total = db.prepare('SELECT COUNT(*) AS c FROM defence_audit').get().c;
+        if (total <= maxRows)
+            return 0;
+        // Trim down to the cap by deleting the OLDEST rows. Find the cutoff id: keep
+        // the newest `maxRows` by timestamp, purge everything older.
+        const cutoffRow = db.prepare(`
+      SELECT timestamp FROM defence_audit
+      ORDER BY timestamp DESC
+      LIMIT 1 OFFSET ?
+    `).get(maxRows);
+        if (!cutoffRow)
+            return 0;
+        const where = 'timestamp <= ?';
+        const params = [cutoffRow.timestamp];
+        const delta = computeDelta(where, params);
+        if (delta.total_scans === 0)
+            return 0;
+        rollIntoAggregate(delta);
+        const res = db.prepare(`DELETE FROM defence_audit WHERE ${where}`).run(...params);
+        return Number(res.changes ?? 0);
+    })();
+}

package/dist/defence/credential-leak/entropy.d.ts

@@ -39,3 +39,14 @@ export declare function extractHighEntropyTokens(content: string): Array<{
     entropy: number;
     confidence: number;
 }>;
+/**
+ * Allowlist of well-known PUBLIC identifier shapes that are NOT secrets and
+ * must never be flagged as credentials — by ANY detector (pattern OR entropy).
+ *
+ * Conservative on purpose: only the exact canonical shapes below are excluded,
+ * so real secrets (sk_live_..., random base64 tokens) still trip detection.
+ * The token is matched on its own boundaries (anchored), so a SHA-shaped
+ * substring of a longer secret is NOT what gets matched here — callers pass the
+ * isolated token.
+ */
+export declare function isWellKnownNonSecret(token: string): boolean;

package/dist/defence/credential-leak/entropy.js

@@ -80,10 +80,37 @@ export function extractHighEntropyTokens(content) {
     }
     return results;
 }
+/**
+ * Allowlist of well-known PUBLIC identifier shapes that are NOT secrets and
+ * must never be flagged as credentials — by ANY detector (pattern OR entropy).
+ *
+ * Conservative on purpose: only the exact canonical shapes below are excluded,
+ * so real secrets (sk_live_..., random base64 tokens) still trip detection.
+ * The token is matched on its own boundaries (anchored), so a SHA-shaped
+ * substring of a longer secret is NOT what gets matched here — callers pass the
+ * isolated token.
+ */
+export function isWellKnownNonSecret(token) {
+    const t = token.trim();
+    // Canonical UUID (any version), e.g. 550e8400-e29b-41d4-a716-446655440000.
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(t))
+        return true;
+    // Git commit SHA-1 (40 hex) and SHA-256 (64 hex) — public revision ids.
+    if (/^[0-9a-f]{40}$/i.test(t))
+        return true;
+    if (/^[0-9a-f]{64}$/i.test(t))
+        return true;
+    // Abbreviated git SHA (7–12 hex, the `git rev-parse --short` range).
+    if (/^[0-9a-f]{7,12}$/i.test(t))
+        return true;
+    return false;
+}
 /**
  * Heuristic filter to reduce false positives from entropy detection.
  */
 function isLikelyFalsePositive(token) {
+    if (isWellKnownNonSecret(token))
+        return true;
     // UUIDs — legitimate identifiers, not secrets
     if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(token))
         return true;

package/dist/defence/credential-leak/index.js

@@ -7,7 +7,7 @@
  * variable patterns, and high-entropy string heuristics.
  */
 import { ALL_CREDENTIAL_PATTERNS, } from './patterns.js';
-import { extractHighEntropyTokens } from './entropy.js';
+import { extractHighEntropyTokens, isWellKnownNonSecret } from './entropy.js';
 export const DEFAULT_CREDENTIAL_CONFIG = {
     enabled: true,
     blockOnCritical: true,
@@ -49,6 +49,27 @@ function isAllowlisted(value, allowlist) {
     }
     return false;
 }
+/**
+ * Expand a match span to the full contiguous identifier token it sits in, then
+ * test it against the well-known-non-secret allowlist (git SHA / UUID).
+ *
+ * Generic hex patterns (e.g. the 32-hex "Azure" rule) match a SUBSTRING of a
+ * 40-hex commit SHA, so checking only the captured value misses it — we must
+ * look at the surrounding contiguous run. The token boundary is the usual
+ * credential alphabet ([A-Za-z0-9-]); we deliberately do NOT cross `/`, `+`,
+ * `=` etc. so a real base64 secret that merely contains a hex-looking run is
+ * not whitelisted.
+ */
+function matchIsWellKnownNonSecret(content, start, end) {
+    const tokenChar = /[A-Za-z0-9-]/;
+    let s = start;
+    let e = end;
+    while (s > 0 && tokenChar.test(content[s - 1]))
+        s--;
+    while (e < content.length && tokenChar.test(content[e]))
+        e++;
+    return isWellKnownNonSecret(content.slice(s, e));
+}
 // ── Scanner ──
 /**
  * Scan content for credential leaks.
@@ -88,6 +109,11 @@ export function scanForCredentials(content, config) {
             const end = start + fullMatch.length;
             if (matchedRanges.some(r => start >= r.start && end <= r.end))
                 continue;
+            // Skip well-known PUBLIC identifiers (git SHA / UUID). Generic hex rules
+            // match a substring of these, so expand to the full token before testing
+            // (Phase 17 A5).
+            if (matchIsWellKnownNonSecret(content, start, end))
+                continue;
             const action = actionForSeverity(pattern.severity, cfg);
             const redacted = redactMatch(secretValue, pattern.type);
             findings.push({

package/dist/defence/credential-leak/patterns.d.ts

@@ -23,3 +23,12 @@ export declare const PRIVATE_KEY_PATTERNS: CredentialPattern[];
 export declare const CONNECTION_STRING_PATTERNS: CredentialPattern[];
 export declare const ENV_SECRET_PATTERNS: CredentialPattern[];
 export declare const ALL_CREDENTIAL_PATTERNS: CredentialPattern[];
+/**
+ * Fetch specific credential pattern SOURCES by name from the single source of
+ * truth. Lets other detectors (e.g. fragmentation entity extraction) reuse the
+ * canonical token regexes instead of maintaining their own divergent copies —
+ * WITHOUT pulling in the broad/low-confidence heuristics, so detection scope is
+ * unchanged. Throws on an unknown name so a rename can never silently drop a
+ * provider.
+ */
+export declare function getCredentialRegexesByName(names: string[]): RegExp[];

package/dist/defence/credential-leak/patterns.js

@@ -357,3 +357,24 @@ export const ALL_CREDENTIAL_PATTERNS = [
     ...GENERIC_SECRET_PATTERNS,
     ...ENV_SECRET_PATTERNS,
 ];
+// ── Single Source of Truth — pattern lookup by name (Phase 17 C3) ──
+/** Index of every credential pattern by its `name`, for cross-module reuse. */
+const PATTERNS_BY_NAME = new Map(ALL_CREDENTIAL_PATTERNS.map((p) => [p.name, p]));
+/**
+ * Fetch specific credential pattern SOURCES by name from the single source of
+ * truth. Lets other detectors (e.g. fragmentation entity extraction) reuse the
+ * canonical token regexes instead of maintaining their own divergent copies —
+ * WITHOUT pulling in the broad/low-confidence heuristics, so detection scope is
+ * unchanged. Throws on an unknown name so a rename can never silently drop a
+ * provider.
+ */
+export function getCredentialRegexesByName(names) {
+    return names.map((name) => {
+        const pattern = PATTERNS_BY_NAME.get(name);
+        if (!pattern) {
+            throw new Error(`Unknown credential pattern name: "${name}"`);
+        }
+        // Fresh RegExp so callers don't share lastIndex state with the source.
+        return new RegExp(pattern.regex.source, pattern.regex.flags);
+    });
+}

package/dist/defence/custom-patterns/store.js

@@ -2,6 +2,13 @@
  * SQLite CRUD for custom injection patterns (Pro feature).
  */
 import { getDatabase } from '../../database/init.js';
+import { createRequire } from 'module';
+// safe-regex2 is require()d lazily (it may not be installed) behind a
+// try/catch fallback. Under real Node ESM a bare require() throws
+// ReferenceError, which the catch would swallow — quietly downgrading the
+// ReDoS check to the weaker heuristic. createRequire() gives us a working
+// require here.
+const require = createRequire(import.meta.url);
 const MAX_PATTERNS = 50;
 const MAX_REGEX_LENGTH = 500;
 /**
@@ -23,7 +30,7 @@ export function validateRegex(pattern) {
     }
     // ReDoS check via safe-regex2
     try {
-        // Dynamic import fallback — safe-regex2 may not be installed
+        // Load the CommonJS safe-regex2 via createRequire (it may not be installed)
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const safe = require('safe-regex2');
         if (!safe(pattern)) {

package/dist/defence/custom-rules/store.d.ts

@@ -36,3 +36,21 @@ export declare function deleteFirewallRule(id: number): boolean;
  * Get all enabled rules sorted by priority (used by the defence pipeline).
  */
 export declare function getEnabledFirewallRules(): FirewallRule[];
+/**
+ * Evaluate a single firewall rule against candidate text(s), honouring the
+ * rule's `condition_type`. This is the single source of truth for rule
+ * matching — the defence pipeline calls it for every enabled rule.
+ *
+ * - `keyword`: case-insensitive LITERAL substring match. Regex metacharacters
+ *   in the value (`a.b`, `x+y`) are treated literally, not as a pattern.
+ * - `domain`: the value is matched as a host/domain. It matches when the value
+ *   appears as a hostname (or a suffix of one, so `evil.com` matches
+ *   `api.evil.com`) anywhere in the text, including inside a URL.
+ * - `regex` (and any unknown type): compiled as a case-insensitive RegExp.
+ *   Invalid patterns never match (returns false) rather than throwing.
+ *
+ * `condition_value` is assumed to have already been vetted by safe-regex2 at
+ * creation time for regex rules (see createFirewallRule callers); we still
+ * guard compilation here so a malformed stored value can't crash the pipeline.
+ */
+export declare function ruleMatches(rule: Pick<FirewallRule, 'condition_type' | 'condition_value'>, ...texts: Array<string | undefined | null>): boolean;