@panguard-ai/threat-cloud 1.4.1 → 1.5.5

package/dist/database.js

@@ -7,7 +7,7 @@
  * @module @panguard-ai/threat-cloud/database
  */
 import Database from 'better-sqlite3';
-import { createHmac, createHash } from 'node:crypto';
+import { createHmac, createHash, randomUUID } from 'node:crypto';
 import { runMigrations } from './migrations.js';
 import { AuditLogger } from './audit-logger.js';
 /**
@@ -24,6 +24,14 @@ export class ThreatCloudDB {
         this.initialize();
         this.audit = new AuditLogger(this.db);
     }
+    /**
+     * Escape hatch for callers that need direct DB access (e.g. modules
+     * defined outside this class that perform table-specific queries).
+     * Prefer adding a typed method here when the access pattern stabilises.
+     */
+    getRawDb() {
+        return this.db;
+    }
     /** Create tables if they don't exist / 建立資料表 */
     initialize() {
         this.db.exec(`
@@ -123,13 +131,83 @@ export class ThreatCloudDB {
       CREATE INDEX IF NOT EXISTS idx_usage_type ON usage_events(event_type);
       CREATE INDEX IF NOT EXISTS idx_usage_created ON usage_events(created_at);
 
+      CREATE TABLE IF NOT EXISTS telemetry_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_type TEXT NOT NULL,
+        platform TEXT NOT NULL DEFAULT 'unknown',
+        skill_count INTEGER NOT NULL DEFAULT 0,
+        finding_count INTEGER NOT NULL DEFAULT 0,
+        severity TEXT NOT NULL DEFAULT 'LOW',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_telemetry_type ON telemetry_events(event_type);
+      CREATE INDEX IF NOT EXISTS idx_telemetry_created ON telemetry_events(created_at);
+
+      CREATE TABLE IF NOT EXISTS telemetry_hourly_aggregates (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        hour_bucket TEXT NOT NULL,
+        event_type TEXT NOT NULL,
+        platform TEXT NOT NULL DEFAULT 'unknown',
+        event_count INTEGER NOT NULL DEFAULT 0,
+        total_findings INTEGER NOT NULL DEFAULT 0,
+        total_skills INTEGER NOT NULL DEFAULT 0,
+        avg_severity TEXT NOT NULL DEFAULT 'LOW',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_telemetry_hourly_unique
+        ON telemetry_hourly_aggregates(hour_bucket, event_type, platform);
+
+      CREATE TABLE IF NOT EXISTS activations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        client_id TEXT NOT NULL UNIQUE,
+        platform TEXT NOT NULL DEFAULT 'unknown',
+        os_type TEXT NOT NULL DEFAULT 'unknown',
+        panguard_version TEXT NOT NULL DEFAULT 'unknown',
+        node_version TEXT NOT NULL DEFAULT 'unknown',
+        activated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
       -- Migrations are handled by the numbered migration system in migrations.ts
+
+      -- Org/Device/Policy tables (migration v8, duplicated here as safety net
+      -- because CREATE TABLE IF NOT EXISTS is idempotent)
+      CREATE TABLE IF NOT EXISTS orgs (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        api_key_hash TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE TABLE IF NOT EXISTS devices (
+        id TEXT PRIMARY KEY,
+        org_id TEXT NOT NULL REFERENCES orgs(id),
+        hostname TEXT,
+        os_type TEXT,
+        agent_count INTEGER NOT NULL DEFAULT 0,
+        guard_version TEXT,
+        last_seen TEXT NOT NULL DEFAULT (datetime('now')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_devices_org ON devices(org_id);
+      CREATE INDEX IF NOT EXISTS idx_devices_last_seen ON devices(last_seen);
+      CREATE TABLE IF NOT EXISTS org_policies (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        org_id TEXT NOT NULL REFERENCES orgs(id),
+        category TEXT NOT NULL,
+        action TEXT NOT NULL CHECK(action IN ('allow', 'block')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(org_id, category)
+      );
     `);
         try {
-            runMigrations(this.db);
+            const applied = runMigrations(this.db);
+            if (applied > 0) {
+                console.log(`[threat-cloud] ${applied} migration(s) applied`);
+            }
         }
         catch (err) {
-            console.error('[threat-cloud] Migration failed (non-fatal):', err instanceof Error ? err.message : String(err));
+            console.error('[threat-cloud] MIGRATION FAILED:', err instanceof Error ? err.message : String(err));
+            // Re-throw — migrations failing means the DB is in a broken state
+            throw err;
         }
         this.db.exec(`
       CREATE INDEX IF NOT EXISTS idx_rules_category ON rules(category);
@@ -325,6 +403,19 @@ export class ThreatCloudDB {
     `);
         stmt.run(rule.ruleId, rule.ruleContent, rule.publishedAt, rule.source, category, severity, mitreTechniques, tags);
     }
+    /** Delete all rules with a given source. Returns number of deleted rows. */
+    deleteRulesBySource(source) {
+        const stmt = this.db.prepare('DELETE FROM rules WHERE source = ?');
+        const result = stmt.run(source);
+        return result.changes;
+    }
+    /** Delete rules by a list of rule IDs. Returns number of deleted rows. */
+    deleteRulesByIds(ruleIds) {
+        const placeholders = ruleIds.map(() => '?').join(',');
+        const stmt = this.db.prepare(`DELETE FROM rules WHERE rule_id IN (${placeholders})`);
+        const result = stmt.run(...ruleIds);
+        return result.changes;
+    }
     /** Fetch rules published after a given timestamp / 取得指定時間後發佈的規則 */
     getRulesSince(since, filters) {
         let sql = `SELECT rule_id as ruleId, rule_content as ruleContent, published_at as publishedAt, source,
@@ -440,9 +531,10 @@ export class ThreatCloudDB {
         const findingRows = this.db
             .prepare(`SELECT finding_summaries FROM skill_threats
          WHERE skill_name = ? AND finding_summaries IS NOT NULL
-         ORDER BY created_at DESC LIMIT 5`)
+         ORDER BY created_at DESC LIMIT 10`)
             .all(skillName);
         const findings = [];
+        const ruleIdSet = new Set();
         for (const fr of findingRows) {
             try {
                 const parsed = JSON.parse(fr.finding_summaries);
@@ -450,6 +542,9 @@ export class ThreatCloudDB {
                     if (f.title && !findings.includes(f.title)) {
                         findings.push(f.title);
                     }
+                    if (f.id && f.id.startsWith('ATR-')) {
+                        ruleIdSet.add(f.id);
+                    }
                 }
             }
             catch {
@@ -461,8 +556,19 @@ export class ThreatCloudDB {
             avgRiskScore: row?.avg_score ?? 0,
             maxRiskLevel: row?.max_level ?? 'LOW',
             findings: findings.slice(0, 10),
+            atrRuleIds: [...ruleIdSet],
         };
     }
+    /** Fetch rule content by IDs. Returns the YAML detection patterns for crystallization. */
+    getRuleContentByIds(ruleIds) {
+        if (ruleIds.length === 0)
+            return [];
+        const placeholders = ruleIds.map(() => '?').join(',');
+        const rows = this.db
+            .prepare(`SELECT rule_id, rule_content FROM rules WHERE rule_id IN (${placeholders})`)
+            .all(...ruleIds);
+        return rows.map((r) => ({ ruleId: r.rule_id, ruleContent: r.rule_content }));
+    }
     /** Check if an ATR proposal already exists for a pattern hash */
     hasATRProposal(patternHash) {
         const row = this.db
@@ -476,6 +582,75 @@ export class ThreatCloudDB {
             .prepare('SELECT client_id, confirmations FROM atr_proposals WHERE pattern_hash = ? LIMIT 1')
             .get(patternHash);
     }
+    // -------------------------------------------------------------------------
+    // Payload fingerprint dedup — avoids paying Anthropic API for duplicate
+    // garak prompts. Typical hit rate is 90%+ on public corpora.
+    // 提示詞指紋去重 — 避免為重複的 garak 提示付 Anthropic API 錢。
+    // -------------------------------------------------------------------------
+    /**
+     * Look up a previously-judged payload fingerprint. Caller should call this
+     * BEFORE invoking the LLM drafter; on hit, skip the Anthropic call entirely
+     * and reuse the cached verdict.
+     *
+     * 查詢先前已判斷過的 payload fingerprint。呼叫端應在叫用 LLM drafter 之前查
+     * 這個表;命中時直接跳過 Anthropic 呼叫,回覆之前的結果。
+     */
+    getPayloadFingerprint(fingerprint) {
+        const row = this.db
+            .prepare(`SELECT result, rule_id, pattern_hash, hit_count
+         FROM payload_fingerprints WHERE fingerprint = ? LIMIT 1`)
+            .get(fingerprint);
+        if (!row)
+            return null;
+        const result = row.result;
+        return {
+            result,
+            ruleId: row.rule_id,
+            patternHash: row.pattern_hash,
+            hitCount: row.hit_count,
+        };
+    }
+    /**
+     * Insert or bump a payload fingerprint verdict. UPSERT by fingerprint:
+     * - First time: insert with hit_count=1
+     * - Repeat: increment hit_count, refresh last_seen_at
+     *
+     * 新增或累計 payload fingerprint 判斷結果。
+     */
+    recordPayloadFingerprint(fingerprint, result, details) {
+        this.db
+            .prepare(`INSERT INTO payload_fingerprints
+           (fingerprint, result, rule_id, pattern_hash, first_seen_at, last_seen_at, hit_count)
+         VALUES (?, ?, ?, ?, datetime('now'), datetime('now'), 1)
+         ON CONFLICT(fingerprint) DO UPDATE SET
+           hit_count = hit_count + 1,
+           last_seen_at = datetime('now')`)
+            .run(fingerprint, result, details?.ruleId ?? null, details?.patternHash ?? null);
+    }
+    /**
+     * Stats for the fingerprint cache. Surfaced in admin dashboard so you can
+     * see the hit rate and confirm the cost-saving is real.
+     * 指紋快取統計。供 admin dashboard 顯示命中率,確認省錢有效。
+     */
+    getPayloadFingerprintStats() {
+        const totals = this.db
+            .prepare(`SELECT
+           COUNT(*) as total,
+           COALESCE(SUM(CASE WHEN result='novel' THEN 1 ELSE 0 END), 0) as novel,
+           COALESCE(SUM(CASE WHEN result='duplicate' THEN 1 ELSE 0 END), 0) as duplicate,
+           COALESCE(SUM(CASE WHEN result='rejected' THEN 1 ELSE 0 END), 0) as rejected,
+           COALESCE(SUM(hit_count), 0) as total_hits
+         FROM payload_fingerprints`)
+            .get();
+        return {
+            total: totals.total,
+            novel: totals.novel,
+            duplicate: totals.duplicate,
+            rejected: totals.rejected,
+            totalHits: totals.total_hits,
+            cacheHits: Math.max(0, totals.total_hits - totals.total),
+        };
+    }
     /** Get recent skill threats / 取得最近技能威脅 */
     getSkillThreats(limit = 50) {
         return this.db
@@ -484,42 +659,156 @@ export class ThreatCloudDB {
     }
     /** Get proposal statistics / 取得提案統計 */
     getProposalStats() {
-        const pending = this.db
-            .prepare("SELECT COUNT(*) as count FROM atr_proposals WHERE status = 'pending'")
-            .get().count;
-        const confirmed = this.db
-            .prepare("SELECT COUNT(*) as count FROM atr_proposals WHERE status = 'confirmed'")
-            .get().count;
-        const rejected = this.db
-            .prepare("SELECT COUNT(*) as count FROM atr_proposals WHERE status = 'rejected'")
-            .get().count;
+        const countByStatus = (status) => this.db
+            .prepare('SELECT COUNT(*) as count FROM atr_proposals WHERE status = ?')
+            .get(status).count;
         const total = this.db.prepare('SELECT COUNT(*) as count FROM atr_proposals').get().count;
-        return { pending, confirmed, rejected, total };
+        return {
+            pending: countByStatus('pending'),
+            confirmed: countByStatus('confirmed'),
+            canary: countByStatus('canary'),
+            quarantined: countByStatus('quarantined'),
+            rejected: countByStatus('rejected'),
+            total,
+        };
     }
     /** Get threat statistics / 取得威脅統計 */
     // ---------------------------------------------------------------------------
     // Usage Events
     // ---------------------------------------------------------------------------
     recordUsageEvent(eventType, source, metadata) {
-        this.db.prepare('INSERT INTO usage_events (event_type, source, metadata) VALUES (?, ?, ?)').run(eventType, source, metadata ? JSON.stringify(metadata) : null);
+        this.db
+            .prepare('INSERT INTO usage_events (event_type, source, metadata) VALUES (?, ?, ?)')
+            .run(eventType, source, metadata ? JSON.stringify(metadata) : null);
     }
     getUsageStats() {
-        const totalScans = this.db.prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type IN ('scan', 'cli_scan')").get().count;
-        const scansToday = this.db.prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type = 'scan' AND created_at > datetime('now', '-1 day')").get().count;
-        const scansThisWeek = this.db.prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type = 'scan' AND created_at > datetime('now', '-7 days')").get().count;
-        const sourceRows = this.db.prepare("SELECT source, COUNT(*) as count FROM usage_events WHERE event_type = 'scan' GROUP BY source").all();
+        const totalScans = this.db
+            .prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type IN ('scan', 'cli_scan')")
+            .get().count;
+        const scansToday = this.db
+            .prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type = 'scan' AND created_at > datetime('now', '-1 day')")
+            .get().count;
+        const scansThisWeek = this.db
+            .prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type = 'scan' AND created_at > datetime('now', '-7 days')")
+            .get().count;
+        const sourceRows = this.db
+            .prepare("SELECT source, COUNT(*) as count FROM usage_events WHERE event_type = 'scan' GROUP BY source")
+            .all();
         const scansBySource = {};
         for (const r of sourceRows)
             scansBySource[r.source] = r.count;
-        const cliInstalls = this.db.prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type = 'cli_install'").get().count;
-        const dailyTrend = this.db.prepare("SELECT date(created_at) as date, COUNT(*) as count FROM usage_events WHERE event_type = 'scan' AND created_at > datetime('now', '-30 days') GROUP BY date(created_at) ORDER BY date").all();
+        const cliInstalls = this.db
+            .prepare("SELECT COUNT(*) as count FROM usage_events WHERE event_type = 'cli_install'")
+            .get().count;
+        const dailyTrend = this.db
+            .prepare("SELECT date(created_at) as date, COUNT(*) as count FROM usage_events WHERE event_type = 'scan' AND created_at > datetime('now', '-30 days') GROUP BY date(created_at) ORDER BY date")
+            .all();
         return { totalScans, scansToday, scansThisWeek, scansBySource, cliInstalls, dailyTrend };
     }
+    // ---------------------------------------------------------------------------
+    // Telemetry Events
+    // ---------------------------------------------------------------------------
+    /** Record a telemetry event / 記錄遙測事件 */
+    recordTelemetryEvent(event) {
+        this.db
+            .prepare('INSERT INTO telemetry_events (event_type, platform, skill_count, finding_count, severity) VALUES (?, ?, ?, ?, ?)')
+            .run(event.eventType, event.platform, event.skillCount, event.findingCount, event.severity);
+    }
+    /** Get telemetry stats merging raw events + hourly aggregates / 取得遙測統計 */
+    getTelemetryStats() {
+        // Raw events (last 24h — anything older is aggregated)
+        const rawTotal = this.db.prepare('SELECT COUNT(*) as count FROM telemetry_events').get().count;
+        const aggTotal = this.db
+            .prepare('SELECT COALESCE(SUM(event_count), 0) as count FROM telemetry_hourly_aggregates')
+            .get().count;
+        const eventsToday = this.db
+            .prepare("SELECT COUNT(*) as count FROM telemetry_events WHERE created_at > datetime('now', '-1 day')")
+            .get().count;
+        // By event type (raw)
+        const rawByType = this.db
+            .prepare('SELECT event_type, COUNT(*) as count FROM telemetry_events GROUP BY event_type')
+            .all();
+        const aggByType = this.db
+            .prepare('SELECT event_type, SUM(event_count) as count FROM telemetry_hourly_aggregates GROUP BY event_type')
+            .all();
+        const byEventType = {};
+        for (const r of rawByType)
+            byEventType[r.event_type] = (byEventType[r.event_type] ?? 0) + r.count;
+        for (const r of aggByType)
+            byEventType[r.event_type] = (byEventType[r.event_type] ?? 0) + r.count;
+        // By platform (raw)
+        const rawByPlatform = this.db
+            .prepare('SELECT platform, COUNT(*) as count FROM telemetry_events GROUP BY platform')
+            .all();
+        const aggByPlatform = this.db
+            .prepare('SELECT platform, SUM(event_count) as count FROM telemetry_hourly_aggregates GROUP BY platform')
+            .all();
+        const byPlatform = {};
+        for (const r of rawByPlatform)
+            byPlatform[r.platform] = (byPlatform[r.platform] ?? 0) + r.count;
+        for (const r of aggByPlatform)
+            byPlatform[r.platform] = (byPlatform[r.platform] ?? 0) + r.count;
+        // Avg finding count (raw only — aggregates don't track individual)
+        const avgRow = this.db
+            .prepare('SELECT AVG(finding_count) as avg FROM telemetry_events')
+            .get();
+        return {
+            totalEvents: rawTotal + aggTotal,
+            eventsToday,
+            byEventType,
+            byPlatform,
+            avgFindingCount: avgRow.avg ?? 0,
+        };
+    }
+    /** Aggregate raw telemetry events into hourly buckets, then delete old raw events / 彙總遙測事件 */
+    cleanupTelemetryEvents() {
+        // Step 1: Aggregate events older than 24h into hourly buckets
+        this.db.exec(`
+      INSERT INTO telemetry_hourly_aggregates (hour_bucket, event_type, platform, event_count, total_findings, total_skills, avg_severity)
+      SELECT
+        strftime('%Y-%m-%dT%H:00:00', created_at) as hour_bucket,
+        event_type,
+        platform,
+        COUNT(*) as event_count,
+        SUM(finding_count) as total_findings,
+        SUM(skill_count) as total_skills,
+        CASE
+          WHEN MAX(CASE severity WHEN 'CRITICAL' THEN 4 WHEN 'HIGH' THEN 3 WHEN 'MEDIUM' THEN 2 WHEN 'LOW' THEN 1 ELSE 0 END) >= 4 THEN 'CRITICAL'
+          WHEN MAX(CASE severity WHEN 'CRITICAL' THEN 4 WHEN 'HIGH' THEN 3 WHEN 'MEDIUM' THEN 2 WHEN 'LOW' THEN 1 ELSE 0 END) >= 3 THEN 'HIGH'
+          WHEN MAX(CASE severity WHEN 'CRITICAL' THEN 4 WHEN 'HIGH' THEN 3 WHEN 'MEDIUM' THEN 2 WHEN 'LOW' THEN 1 ELSE 0 END) >= 2 THEN 'MEDIUM'
+          ELSE 'LOW'
+        END as avg_severity
+      FROM telemetry_events
+      WHERE created_at < datetime('now', '-24 hours')
+      GROUP BY hour_bucket, event_type, platform
+      ON CONFLICT(hour_bucket, event_type, platform) DO UPDATE SET
+        event_count = event_count + excluded.event_count,
+        total_findings = total_findings + excluded.total_findings,
+        total_skills = total_skills + excluded.total_skills
+    `);
+        // Step 2: Delete raw events older than 24h
+        const result = this.db
+            .prepare("DELETE FROM telemetry_events WHERE created_at < datetime('now', '-24 hours')")
+            .run();
+        return result.changes;
+    }
     clearAllRules() {
-        const rulesDeleted = (this.db.prepare('DELETE FROM rules').run()).changes;
-        const proposalsDeleted = (this.db.prepare('DELETE FROM atr_proposals').run()).changes;
+        const rulesDeleted = this.db.prepare('DELETE FROM rules').run().changes;
+        const proposalsDeleted = this.db.prepare('DELETE FROM atr_proposals').run().changes;
         return rulesDeleted + proposalsDeleted;
     }
+    /** Get current schema version for health diagnostics */
+    getSchemaVersion() {
+        try {
+            const row = this.db
+                .prepare('SELECT version FROM schema_version ORDER BY version DESC LIMIT 1')
+                .get();
+            return row?.version ?? -1;
+        }
+        catch {
+            return -1;
+        }
+    }
     getStats() {
         const totalThreats = this.db.prepare('SELECT COUNT(*) as count FROM threats').get().count;
         const totalRules = this.db.prepare('SELECT COUNT(*) as count FROM rules').get().count;
@@ -589,7 +878,7 @@ export class ThreatCloudDB {
             .prepare(`
         SELECT pattern_hash as ruleId, rule_content as ruleContent, updated_at as publishedAt, 'atr-community' as source
         FROM atr_proposals
-        WHERE (status = 'confirmed' OR status = 'promoted') ${since ? 'AND updated_at > ?' : ''}
+        WHERE status = 'promoted' ${since ? 'AND updated_at > ?' : ''}
         ORDER BY updated_at ASC
       `)
             .all(...sinceParams);
@@ -657,15 +946,17 @@ export class ThreatCloudDB {
     }
     /** Promote proposals to rules based on community consensus and/or LLM approval / 推廣提案為規則 */
     promoteConfirmedProposals() {
-        // Path 1: LLM approved (any status with approved verdict)
-        // Path 2: Community consensus (3+ confirmations, NO LLM required)
+        // Path 1: LLM approved via self-review (JSON verdict with "approved":true)
+        // Path 2: Community consensus (3+ confirmations, no LLM required)
         //   — This ensures the flywheel works even without ANTHROPIC_API_KEY
-        // Path 3: LLM approved + community confirmed (highest confidence)
+        // Path 3: Admin manually approved via dashboard
+        //   (status='approved' set by admin-approve endpoint; verdict stored as
+        //    literal 'admin-approved' or a similar opaque marker — not JSON)
         const proposals = this.db
             .prepare(`
       SELECT pattern_hash, rule_content, llm_review_verdict, confirmations, status
       FROM atr_proposals
-      WHERE status IN ('confirmed', 'pending')
+      WHERE status IN ('confirmed', 'pending', 'approved')
         AND status != 'rejected'
         AND (
           -- Path 1: LLM approved
@@ -673,10 +964,16 @@ export class ThreatCloudDB {
           OR
           -- Path 2: Community consensus (3+ confirmations, even without LLM)
           (confirmations >= 3)
+          OR
+          -- Path 3: Admin dashboard approval (status promoted to 'approved'
+          -- by a human reviewer; the verdict field may be a plain marker
+          -- like 'admin-approved' rather than a JSON blob, so trust the
+          -- status column)
+          (status = 'approved')
         )
     `)
             .all();
-        let promoted = 0;
+        let moved = 0;
         for (const proposal of proposals) {
             // If LLM reviewed, check it's approved (don't promote LLM-rejected proposals)
             if (proposal.llm_review_verdict) {
@@ -689,6 +986,83 @@ export class ThreatCloudDB {
                     // Unparseable verdict — allow community consensus to override
                 }
             }
+            // Move to canary staging instead of direct promotion
+            this.db
+                .prepare(`
+        UPDATE atr_proposals
+        SET status = 'canary', canary_started_at = datetime('now'), updated_at = datetime('now')
+        WHERE pattern_hash = ?
+      `)
+                .run(proposal.pattern_hash);
+            moved++;
+        }
+        return moved;
+    }
+    /**
+     * Self-heal: find proposals that are status='promoted' but have no
+     * corresponding rule in the rules table, and re-upsert them. This
+     * handles historical bugs where promoteCanaryRules set the status but
+     * the upsertRule call failed silently (e.g., during a prior schema or
+     * constraint mismatch). Idempotent — safe to run every promotion cycle.
+     * Returns the number of rules restored.
+     */
+    healOrphanedPromotedProposals() {
+        const orphans = this.db
+            .prepare(`
+        SELECT p.pattern_hash, p.rule_content, p.updated_at
+        FROM atr_proposals p
+        LEFT JOIN rules r ON r.rule_id = p.pattern_hash
+        WHERE p.status = 'promoted' AND r.rule_id IS NULL
+      `)
+            .all();
+        let healed = 0;
+        for (const o of orphans) {
+            try {
+                this.upsertRule({
+                    ruleId: o.pattern_hash,
+                    ruleContent: o.rule_content,
+                    publishedAt: o.updated_at || new Date().toISOString(),
+                    source: 'atr-community',
+                });
+                healed++;
+            }
+            catch {
+                /* skip individual errors — next cycle will retry */
+            }
+        }
+        return healed;
+    }
+    /** Canary period in milliseconds (24 hours) / Canary 觀察期（24 小時） */
+    static CANARY_PERIOD_MS = 24 * 60 * 60 * 1000;
+    /**
+     * Promote canary rules that have survived the 24-hour observation period
+     * without negative feedback. Quarantine rules with negative feedback.
+     * 推廣存活 24 小時且無負面回饋的 canary 規則。隔離有負面回饋的規則。
+     */
+    promoteCanaryRules() {
+        const canaryProposals = this.db
+            .prepare(`
+        SELECT pattern_hash, rule_content, canary_started_at
+        FROM atr_proposals
+        WHERE status = 'canary'
+          AND canary_started_at IS NOT NULL
+      `)
+            .all();
+        let promoted = 0;
+        let quarantined = 0;
+        for (const proposal of canaryProposals) {
+            const negativeFeedback = this.getNegativeFeedbackCount(proposal.pattern_hash);
+            if (negativeFeedback >= 3) {
+                // Too much negative feedback — quarantine
+                this.quarantineProposal(proposal.pattern_hash);
+                quarantined++;
+                continue;
+            }
+            const elapsed = Date.now() - new Date(proposal.canary_started_at + 'Z').getTime();
+            if (elapsed < ThreatCloudDB.CANARY_PERIOD_MS) {
+                continue; // Still in canary period
+            }
+            // Survived canary period — promote to rule
             this.upsertRule({
                 ruleId: proposal.pattern_hash,
                 ruleContent: proposal.rule_content,
@@ -696,14 +1070,34 @@ export class ThreatCloudDB {
                 source: 'atr-community',
             });
             this.db
-                .prepare(`
-        UPDATE atr_proposals SET status = 'promoted', updated_at = datetime('now')
-        WHERE pattern_hash = ?
-      `)
+                .prepare(`UPDATE atr_proposals SET status = 'promoted', updated_at = datetime('now')
+           WHERE pattern_hash = ?`)
                 .run(proposal.pattern_hash);
             promoted++;
         }
-        return promoted;
+        return { promoted, quarantined };
+    }
+    /** Get count of negative feedback for a rule / 取得規則負面回饋數 */
+    getNegativeFeedbackCount(ruleId) {
+        return this.db
+            .prepare('SELECT COUNT(*) as count FROM atr_feedback WHERE rule_id = ? AND is_true_positive = 0')
+            .get(ruleId).count;
+    }
+    /** Quarantine a proposal / 隔離提案 */
+    quarantineProposal(patternHash) {
+        this.db
+            .prepare(`UPDATE atr_proposals SET status = 'quarantined', updated_at = datetime('now')
+         WHERE pattern_hash = ?`)
+            .run(patternHash);
+    }
+    /** Get canary rules (for 10% client sampling) / 取得 canary 規則（供 10% 客戶端抽樣） */
+    getCanaryATRRules() {
+        return this.db
+            .prepare(`SELECT pattern_hash as ruleId, rule_content as ruleContent, canary_started_at as publishedAt, 'atr-canary' as source
+         FROM atr_proposals
+         WHERE status = 'canary'
+         ORDER BY canary_started_at ASC`)
+            .all();
     }
     /** Reject an ATR proposal / 拒絕 ATR 提案 */
     rejectATRProposal(patternHash) {
@@ -722,17 +1116,21 @@ export class ThreatCloudDB {
         if (!proposal)
             return false;
         // Update proposal status
-        this.db.prepare(`
+        this.db
+            .prepare(`
       UPDATE atr_proposals SET status = 'approved', llm_review_verdict = 'admin-approved', updated_at = datetime('now')
       WHERE pattern_hash = ?
-    `).run(patternHash);
+    `)
+            .run(patternHash);
         // Insert as confirmed rule
         const ruleId = `ATR-2026-DRAFT-${patternHash.slice(0, 8)}`;
         try {
-            this.db.prepare(`
+            this.db
+                .prepare(`
         INSERT OR IGNORE INTO rules (rule_id, rule_content, source, category, severity)
         VALUES (?, ?, 'atr-community', 'skill-compromise', 'high')
-      `).run(ruleId, proposal.rule_content);
+      `)
+                .run(ruleId, proposal.rule_content);
         }
         catch {
             // Rule may already exist
@@ -742,9 +1140,11 @@ export class ThreatCloudDB {
     /** Admin: remove a skill from whitelist */
     removeFromWhitelist(skillName) {
         const normalized = skillName.toLowerCase().trim().replace(/\s+/g, '-');
-        const result = this.db.prepare(`
+        const result = this.db
+            .prepare(`
       DELETE FROM skill_whitelist WHERE normalized_name = ?
-    `).run(normalized);
+    `)
+            .run(normalized);
         return result.changes > 0;
     }
     /** Admin: manually add a skill to blacklist via skill_threats */
@@ -752,27 +1152,33 @@ export class ThreatCloudDB {
         const hash = createHash('sha256').update(skillName).digest('hex').slice(0, 16);
         // Insert 3 threat reports to trigger blacklist threshold
         for (let i = 0; i < 3; i++) {
-            this.db.prepare(`
+            this.db
+                .prepare(`
         INSERT INTO skill_threats (skill_hash, skill_name, risk_score, risk_level, finding_summaries, client_id)
         VALUES (?, ?, 100, 'CRITICAL', ?, ?)
-      `).run(hash, skillName, reason, `admin-${i}`);
+      `)
+                .run(hash, skillName, reason, `admin-${i}`);
         }
     }
     /** Admin: remove a skill from blacklist by clearing its threat reports */
     removeFromBlacklist(skillHash) {
-        const result = this.db.prepare(`
+        const result = this.db
+            .prepare(`
       DELETE FROM skill_threats WHERE skill_hash = ?
-    `).run(skillHash);
+    `)
+            .run(skillHash);
         return result.changes > 0;
     }
     /** Get all whitelist entries (including unconfirmed, for admin) */
     getAllWhitelistEntries() {
-        return this.db.prepare(`
+        return this.db
+            .prepare(`
       SELECT skill_name, normalized_name, fingerprint_hash, confirmations, status,
              first_reported, last_reported
       FROM skill_whitelist
       ORDER BY first_reported DESC
-    `).all();
+    `)
+            .all();
     }
     /** Get rules by source type, optionally filtered by date / 依來源取得規則 */
     getRulesBySource(source, since) {
@@ -813,36 +1219,57 @@ export class ThreatCloudDB {
             .run(skillName, normalized, fingerprintHash ?? null);
     }
     /** Get confirmed community whitelist / 取得社群白名單 */
-    getSkillWhitelist() {
+    getSkillWhitelist(since) {
+        if (since) {
+            return this.db
+                .prepare(`SELECT skill_name as name, fingerprint_hash as hash, confirmations
+           FROM skill_whitelist
+           WHERE status = 'confirmed' AND last_reported > ?
+           ORDER BY last_reported DESC`)
+                .all(since);
+        }
         return this.db
-            .prepare(`
-      SELECT skill_name as name, fingerprint_hash as hash, confirmations
-      FROM skill_whitelist
-      WHERE status = 'confirmed'
-      ORDER BY confirmations DESC
-    `)
+            .prepare(`SELECT skill_name as name, fingerprint_hash as hash, confirmations
+         FROM skill_whitelist
+         WHERE status = 'confirmed'
+         ORDER BY confirmations DESC`)
             .all();
     }
     /**
      * Get skill blacklist: skills reported by 3+ distinct clients with avg risk >= 70
      * 取得技能黑名單：3+ 不同客戶端回報且平均風險 >= 70 的技能
      */
-    getSkillBlacklist(minReports = 3, minAvgRisk = 70) {
+    getSkillBlacklist(minReports = 3, minAvgRisk = 70, since) {
+        if (since) {
+            // Incremental: only entries with new reports since the given timestamp
+            return this.db
+                .prepare(`SELECT
+            skill_hash as skillHash,
+            skill_name as skillName,
+            ROUND(AVG(risk_score)) as avgRiskScore,
+            MAX(risk_level) as maxRiskLevel,
+            COUNT(DISTINCT COALESCE(client_id, 'anonymous')) as reportCount,
+            MIN(created_at) as firstReported,
+            MAX(created_at) as lastReported
+          FROM skill_threats
+          GROUP BY skill_hash
+          HAVING reportCount >= ? AND AVG(risk_score) >= ? AND MAX(created_at) > ?
+          ORDER BY lastReported DESC`)
+                .all(minReports, minAvgRisk, since);
+        }
         return this.db
-            .prepare(`
-      SELECT
-        skill_hash as skillHash,
-        skill_name as skillName,
-        ROUND(AVG(risk_score)) as avgRiskScore,
-        MAX(risk_level) as maxRiskLevel,
-        COUNT(DISTINCT COALESCE(client_id, 'anonymous')) as reportCount,
-        MIN(created_at) as firstReported,
-        MAX(created_at) as lastReported
-      FROM skill_threats
-      GROUP BY skill_hash
-      HAVING reportCount >= ? AND AVG(risk_score) >= ?
-      ORDER BY avgRiskScore DESC
-    `)
+            .prepare(`SELECT
+          skill_hash as skillHash,
+          skill_name as skillName,
+          ROUND(AVG(risk_score)) as avgRiskScore,
+          MAX(risk_level) as maxRiskLevel,
+          COUNT(DISTINCT COALESCE(client_id, 'anonymous')) as reportCount,
+          MIN(created_at) as firstReported,
+          MAX(created_at) as lastReported
+        FROM skill_threats
+        GROUP BY skill_hash
+        HAVING reportCount >= ? AND AVG(risk_score) >= ?
+        ORDER BY avgRiskScore DESC`)
             .all(minReports, minAvgRisk);
     }
     /** Backfill classification for rules with NULL category / 回填缺少分類的規則 */
@@ -868,17 +1295,21 @@ export class ThreatCloudDB {
      * 取得尚未被 LLM 審查的待處理提案（用於重試）
      */
     getUnreviewedProposals(limit = 5) {
+        // Retry pending proposals that either (a) have never been reviewed, or
+        // (b) previously hit a transient error (rate limit, timeout, network).
+        // A legitimate `approved: false` verdict is NOT retried — that's a terminal
+        // rejection and handled by rejectATRProposal() in the reviewer; leaving it
+        // in the retry pool would loop forever and waste LLM API quota.
         return this.db
             .prepare(`SELECT pattern_hash as patternHash, rule_content as ruleContent
          FROM atr_proposals
          WHERE status = 'pending'
            AND (llm_review_verdict IS NULL
-                OR llm_review_verdict LIKE '%"approved":false%'
-                OR llm_review_verdict LIKE '%failed%'
-                OR llm_review_verdict LIKE '%error%'
+                OR llm_review_verdict LIKE '%LLM review failed%'
                 OR llm_review_verdict LIKE '%rate_limit%'
                 OR llm_review_verdict LIKE '%429%'
-                OR llm_review_verdict LIKE '%timed out%')
+                OR llm_review_verdict LIKE '%timed out%'
+                OR llm_review_verdict LIKE '%503%')
          ORDER BY created_at ASC
          LIMIT ?`)
             .all(limit);
@@ -890,6 +1321,34 @@ export class ThreatCloudDB {
          VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
             .run(event.source, event.skillsScanned, event.findingsCount, event.confirmedMalicious, event.highlySuspicious, event.generalSuspicious, event.cleanCount, event.deviceHash ?? null);
     }
+    /** Record a one-time activation event / 記錄一次性啟動事件 */
+    recordActivation(activation) {
+        try {
+            this.db
+                .prepare(`INSERT OR IGNORE INTO activations (client_id, platform, os_type, panguard_version, node_version)
+           VALUES (?, ?, ?, ?, ?)`)
+                .run(activation.clientId, activation.platform, activation.osType, activation.panguardVersion, activation.nodeVersion);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Get activation stats / 取得啟動統計 */
+    getActivationStats() {
+        const total = this.db.prepare(`SELECT COUNT(*) as count FROM activations`).get().count;
+        const byPlatform = this.db
+            .prepare(`SELECT platform, COUNT(*) as count FROM activations GROUP BY platform ORDER BY count DESC`)
+            .all();
+        const byOs = this.db
+            .prepare(`SELECT os_type as osType, COUNT(*) as count FROM activations GROUP BY os_type ORDER BY count DESC`)
+            .all();
+        const recent = this.db
+            .prepare(`SELECT activated_at as activatedAt, platform, os_type as osType, panguard_version as panguardVersion
+         FROM activations ORDER BY activated_at DESC LIMIT 20`)
+            .all();
+        return { total, byPlatform, byOs, recent };
+    }
     /** Get contributor leaderboard (hashed IDs, no PII) / 取得貢獻者排行榜 */
     getContributorLeaderboard(limit = 20) {
         // Hash client_id with SHA-256 for privacy
@@ -973,11 +1432,17 @@ export class ThreatCloudDB {
         const atrRulesCount = this.db
             .prepare(`SELECT COUNT(*) as count FROM rules WHERE source IN ('atr', 'atr-community')`)
             .get().count;
+        // Whitelist count
+        const whitelistCount = this.db.prepare(`SELECT COUNT(*) as count FROM skill_whitelist`).get().count;
+        // Blacklist count (uses aggregated skill_threats view, same as getSkillBlacklist)
+        const blacklistCount = this.getSkillBlacklist().length;
         return {
             totalSkillsScanned: totals.totalSkills,
             totalAgentsProtected: agentsProtected,
             totalThreatsDetected: totals.totalFindings,
             totalAtrRules: atrRulesCount,
+            whitelistedSkills: whitelistCount,
+            blacklistedSkills: blacklistCount,
             sources: {
                 bulk: { skills: bulk.skills, findings: bulk.findings },
                 cli: { skills: cli.skills, findings: cli.findings, devices: cli.devices },
@@ -986,6 +1451,238 @@ export class ThreatCloudDB {
             lastUpdated: new Date().toISOString(),
         };
     }
+    // ── Verdict Cache / 判定快取 ──────────────────────────────────
+    /** Look up a cached verdict by content hash. Returns null if miss or expired. */
+    getVerdictCache(contentHash) {
+        const row = this.db
+            .prepare(`SELECT content_hash, skill_name, verdict, scanned_at, scan_count
+         FROM verdict_cache
+         WHERE content_hash = ? AND expires_at > datetime('now')`)
+            .get(contentHash);
+        if (!row)
+            return null;
+        // Increment scan_count on cache hit
+        this.db
+            .prepare(`UPDATE verdict_cache SET scan_count = scan_count + 1 WHERE content_hash = ?`)
+            .run(contentHash);
+        return {
+            contentHash: row.content_hash,
+            skillName: row.skill_name,
+            verdict: row.verdict,
+            scannedAt: row.scanned_at,
+            scanCount: row.scan_count + 1,
+        };
+    }
+    /** Insert or replace a verdict cache entry with 30-day TTL. */
+    insertVerdictCache(entry) {
+        this.db
+            .prepare(`INSERT OR REPLACE INTO verdict_cache (content_hash, skill_name, verdict, scanned_at, expires_at, scan_count)
+         VALUES (?, ?, ?, datetime('now'), datetime('now', '+30 days'), 1)`)
+            .run(entry.contentHash, entry.skillName, entry.verdict);
+    }
+    /** Delete a specific cache entry. Returns true if a row was deleted. */
+    invalidateVerdictCache(contentHash) {
+        const result = this.db
+            .prepare(`DELETE FROM verdict_cache WHERE content_hash = ?`)
+            .run(contentHash);
+        return result.changes > 0;
+    }
+    /** Purge all expired cache entries. Returns count deleted. */
+    purgeExpiredVerdictCache() {
+        const result = this.db
+            .prepare(`DELETE FROM verdict_cache WHERE expires_at <= datetime('now')`)
+            .run();
+        return result.changes;
+    }
+    // ── Skill Hash History / 技能雜湊歷史 ────────────────────────
+    /** Get the latest (non-superseded) hash entry for a skill. */
+    getLatestSkillHash(skillName) {
+        const row = this.db
+            .prepare(`SELECT content_hash, scan_verdict
+         FROM skill_hash_history
+         WHERE skill_name = ? AND superseded_by IS NULL
+         ORDER BY last_seen DESC
+         LIMIT 1`)
+            .get(skillName);
+        if (!row)
+            return null;
+        return { contentHash: row.content_hash, scanVerdict: row.scan_verdict };
+    }
+    /** Record a skill hash observation. Creates or updates last_seen. */
+    recordSkillHash(entry) {
+        this.db
+            .prepare(`INSERT INTO skill_hash_history (skill_name, content_hash, scan_verdict, rug_pull_flag)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(skill_name, content_hash) DO UPDATE SET
+           last_seen = datetime('now'),
+           scan_verdict = COALESCE(excluded.scan_verdict, scan_verdict)`)
+            .run(entry.skillName, entry.contentHash, entry.scanVerdict ?? null, entry.rugPullFlag ? 1 : 0);
+    }
+    /** Mark a previous hash as superseded by a new hash. */
+    markSkillHashSuperseded(skillName, oldHash, newHash) {
+        this.db
+            .prepare(`UPDATE skill_hash_history
+         SET superseded_by = ?
+         WHERE skill_name = ? AND content_hash = ?`)
+            .run(newHash, skillName, oldHash);
+    }
+    /** Get full hash history for a skill (audit trail). */
+    getSkillHashHistory(skillName) {
+        const rows = this.db
+            .prepare(`SELECT content_hash, first_seen, last_seen, scan_verdict, superseded_by, rug_pull_flag
+         FROM skill_hash_history
+         WHERE skill_name = ?
+         ORDER BY first_seen ASC`)
+            .all(skillName);
+        return rows.map((r) => ({
+            contentHash: r.content_hash,
+            firstSeen: r.first_seen,
+            lastSeen: r.last_seen,
+            scanVerdict: r.scan_verdict,
+            supersededBy: r.superseded_by,
+            rugPullFlag: r.rug_pull_flag === 1,
+        }));
+    }
+    // ─── Org / Device / Policy (Threat Model #1, #6) ───────────────
+    /** Create an organization / 建立組織 */
+    createOrg(id, name) {
+        this.db.prepare('INSERT OR IGNORE INTO orgs (id, name) VALUES (?, ?)').run(id, name);
+    }
+    /** Get org by ID / 取得組織 */
+    getOrg(id) {
+        return this.db.prepare('SELECT * FROM orgs WHERE id = ?').get(id);
+    }
+    /** Upsert device heartbeat / 更新裝置心跳
+     *  Threat Model: Fleet view (#6 Scope Escalation — org-level visibility) */
+    upsertDevice(data) {
+        this.db
+            .prepare(`INSERT INTO devices (id, org_id, hostname, os_type, agent_count, guard_version, last_seen)
+         VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+         ON CONFLICT(id) DO UPDATE SET
+           org_id = excluded.org_id,
+           hostname = COALESCE(excluded.hostname, devices.hostname),
+           os_type = COALESCE(excluded.os_type, devices.os_type),
+           agent_count = excluded.agent_count,
+           guard_version = COALESCE(excluded.guard_version, devices.guard_version),
+           last_seen = datetime('now')`)
+            .run(data.deviceId, data.orgId, data.hostname ?? null, data.osType ?? null, data.agentCount ?? 0, data.guardVersion ?? null);
+    }
+    /** List devices for an org / 列出組織下的裝置
+     *  Threat Model: Fleet view (#6) */
+    getDevicesByOrg(orgId, limit = 100, offset = 0) {
+        return this.db
+            .prepare('SELECT id, hostname, os_type, agent_count, guard_version, last_seen, created_at FROM devices WHERE org_id = ? ORDER BY last_seen DESC LIMIT ? OFFSET ?')
+            .all(orgId, limit, offset);
+    }
+    /** Get device count for an org / 取得組織裝置數 */
+    getDeviceCount(orgId) {
+        return this.db.prepare('SELECT COUNT(*) as count FROM devices WHERE org_id = ?').get(orgId).count;
+    }
+    /** Set org policy / 設定組織策略
+     *  Threat Model: Policy engine (#1 Supply Chain, #6 Scope Escalation) */
+    setOrgPolicy(orgId, category, action) {
+        this.db
+            .prepare(`INSERT INTO org_policies (org_id, category, action)
+         VALUES (?, ?, ?)
+         ON CONFLICT(org_id, category) DO UPDATE SET action = excluded.action`)
+            .run(orgId, category, action);
+    }
+    /** Get org policies / 取得組織策略 */
+    getOrgPolicies(orgId) {
+        return this.db
+            .prepare('SELECT category, action, created_at FROM org_policies WHERE org_id = ? ORDER BY category')
+            .all(orgId);
+    }
+    /** Delete org policy / 刪除組織策略 */
+    deleteOrgPolicy(orgId, category) {
+        const result = this.db
+            .prepare('DELETE FROM org_policies WHERE org_id = ? AND category = ?')
+            .run(orgId, category);
+        return result.changes > 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Client Keys / 客戶端金鑰
+    // ---------------------------------------------------------------------------
+    /** Register a new client key. Returns the raw key (only time it's visible). */
+    registerClientKey(clientId, ipAddress) {
+        // Limit to 5 active keys per clientId to prevent DB flooding
+        const existing = this.db
+            .prepare('SELECT COUNT(*) as cnt FROM client_keys WHERE client_id = ? AND revoked = 0')
+            .get(clientId);
+        if (existing.cnt >= 5) {
+            // Revoke oldest key to make room
+            this.db
+                .prepare(`UPDATE client_keys SET revoked = 1, revoked_at = datetime('now')
+           WHERE id = (SELECT id FROM client_keys WHERE client_id = ? AND revoked = 0 ORDER BY created_at ASC LIMIT 1)`)
+                .run(clientId);
+        }
+        const clientKey = randomUUID();
+        const hash = createHash('sha256').update(clientKey).digest('hex');
+        this.db
+            .prepare('INSERT INTO client_keys (client_id, client_key_hash, ip_address) VALUES (?, ?, ?)')
+            .run(clientId, hash, ipAddress);
+        return { clientKey };
+    }
+    /** Validate a raw client key. Updates last_used_at on success. */
+    validateClientKey(rawKey) {
+        const hash = createHash('sha256').update(rawKey).digest('hex');
+        const row = this.db
+            .prepare('SELECT id FROM client_keys WHERE client_key_hash = ? AND revoked = 0')
+            .get(hash);
+        if (!row)
+            return false;
+        this.db
+            .prepare("UPDATE client_keys SET last_used_at = datetime('now') WHERE id = ?")
+            .run(row.id);
+        return true;
+    }
+    /**
+     * Look up role + clientId for a raw client key. Returns null if invalid/revoked.
+     * Does NOT update last_used_at (caller should use validateClientKey for that).
+     * Used by L5 partner-sync endpoints to enforce role-based access.
+     */
+    getClientKeyInfo(rawKey) {
+        const hash = createHash('sha256').update(rawKey).digest('hex');
+        const row = this.db
+            .prepare('SELECT client_id as clientId, COALESCE(key_role, ?) as role FROM client_keys WHERE client_key_hash = ? AND revoked = 0')
+            .get('guard', hash);
+        return row ?? null;
+    }
+    /**
+     * Issue a partner key. Partner keys are manually issued by admin and can
+     * access L5 live-sync endpoints (e.g. /api/atr-rules/live). Returns the
+     * raw key once — caller must store it securely.
+     */
+    registerPartnerKey(partnerName, issuedBy) {
+        const clientId = `partner:${partnerName}`;
+        const clientKey = randomUUID();
+        const hash = createHash('sha256').update(clientKey).digest('hex');
+        this.db
+            .prepare('INSERT INTO client_keys (client_id, client_key_hash, ip_address, key_role) VALUES (?, ?, ?, ?)')
+            .run(clientId, hash, `issued-by:${issuedBy}`, 'partner');
+        return { clientKey };
+    }
+    /** Revoke all keys for a client. Returns number of keys revoked. */
+    revokeClientKey(clientId) {
+        const result = this.db
+            .prepare("UPDATE client_keys SET revoked = 1, revoked_at = datetime('now') WHERE client_id = ? AND revoked = 0")
+            .run(clientId);
+        return result.changes;
+    }
+    /** List client keys (admin). Never returns raw keys. */
+    listClientKeys(limit = 50, offset = 0) {
+        const rows = this.db
+            .prepare('SELECT id, client_id, created_at, last_used_at, revoked, ip_address FROM client_keys ORDER BY created_at DESC LIMIT ? OFFSET ?')
+            .all(limit, offset);
+        return rows.map((r) => ({
+            id: r.id,
+            clientId: r.client_id,
+            createdAt: r.created_at,
+            lastUsedAt: r.last_used_at,
+            revoked: r.revoked === 1,
+            ipAddress: r.ip_address,
+        }));
+    }
     /** Close the database / 關閉資料庫 */
     close() {
         this.db.close();