@panguard-ai/threat-cloud 1.4.2 → 1.5.5

package/dist/server.js

@@ -9,6 +9,7 @@
  * - GET  /api/stats                  Get threat statistics
  * - POST /api/atr-proposals          Submit or confirm ATR rule proposal
  * - POST /api/atr-feedback           Submit feedback on ATR rule
+ * - POST /api/rule-feedback          Submit rule feedback with auto-quarantine
  * - POST /api/skill-threats          Submit skill threat from audit
  * - GET  /api/atr-rules              Fetch confirmed ATR rules (?since= filter)
  * - GET  /api/feeds/ip-blocklist     IP blocklist feed (text/plain, ?minReputation=)
@@ -19,6 +20,7 @@
  * - POST /api/telemetry              Record anonymous telemetry event from CLI
  * - POST /api/scan-events           Report scan event from any source (bulk/CLI/web)
  * - GET  /api/metrics               Aggregated metrics across all sources (public, cached 60s)
+ * - GET  /api/version               Build/deploy info: version, commit, uptime (public, cached 30s)
  * - GET  /api/badge/:author/:skill   ATR Scanned SVG badge for a skill
  * - GET  /api/badge/stats            Badge statistics (JSON)
  * - GET  /health                     Health check
@@ -30,6 +32,15 @@ import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { createRequire } from 'node:module';
+// Read package.json version (for /api/version endpoint, deploy verification)
+const _require = createRequire(import.meta.url);
+const _pkg = _require('../package.json');
+const TC_VERSION = _pkg.version;
+// Server-process startup timestamp for uptime reporting in /api/version.
+// This is module-scoped so it captures the actual import-time of the process,
+// not the time the first request is handled.
+const SERVER_START_TIME = new Date();
 import { ThreatCloudDB } from './database.js';
 import { createBadgeRouter } from './badge-api.js';
 import { LLMReviewer } from './llm-reviewer.js';
@@ -63,6 +74,7 @@ export class ThreatCloudServer {
     badgeRouter;
     promotionTimer = null;
     rateLimits = new Map();
+    registrationRateLimits = new Map();
     rateLimitCleanupTimer = null;
     statsCache = null;
     /** Promotion interval: 2 minutes / 推廣間隔：2 分鐘 */
@@ -119,10 +131,22 @@ export class ThreatCloudServer {
                 // Start promotion + review cron (every 15 minutes)
                 this.promotionTimer = setInterval(() => {
                     try {
-                        // Step 1: Promote confirmed proposals to rules
-                        const promoted = this.db.promoteConfirmedProposals();
-                        if (promoted > 0) {
-                            log.info(`Promotion cycle: ${promoted} proposal(s) promoted to rules`);
+                        // Step 1: Move confirmed proposals to canary staging
+                        const toCanary = this.db.promoteConfirmedProposals();
+                        if (toCanary > 0) {
+                            log.info(`Promotion cycle: ${toCanary} proposal(s) moved to canary staging`);
+                        }
+                        // Step 1b: Promote canary rules that survived 24hr observation
+                        const canaryResult = this.db.promoteCanaryRules();
+                        if (canaryResult.promoted > 0 || canaryResult.quarantined > 0) {
+                            log.info(`Canary cycle: ${canaryResult.promoted} promoted, ${canaryResult.quarantined} quarantined`);
+                        }
+                        // Step 1c: Self-heal orphaned promoted proposals whose upsertRule
+                        // call failed during a previous cycle (status=promoted but no
+                        // corresponding row in rules table). Idempotent.
+                        const healed = this.db.healOrphanedPromotedProposals();
+                        if (healed > 0) {
+                            log.info(`Self-heal: re-upserted ${healed} orphaned promoted proposal(s)`);
                         }
                         // Step 2: Retry LLM review for proposals that haven't been reviewed yet
                         if (this.llmReviewer?.isAvailable()) {
@@ -130,6 +154,11 @@ export class ThreatCloudServer {
                                 log.error('Review retry failed', err);
                             });
                         }
+                        // Step 3: Purge expired verdict cache entries
+                        const purged = this.db.purgeExpiredVerdictCache();
+                        if (purged > 0) {
+                            log.info(`Verdict cache: purged ${purged} expired entries`);
+                        }
                     }
                     catch (err) {
                         log.error('Promotion cycle failed', err);
@@ -142,6 +171,10 @@ export class ThreatCloudServer {
                         if (now > entry.resetAt)
                             this.rateLimits.delete(ip);
                     }
+                    for (const [ip, entry] of this.registrationRateLimits) {
+                        if (now > entry.resetAt)
+                            this.registrationRateLimits.delete(ip);
+                    }
                     // Aggregate old telemetry events into hourly buckets
                     try {
                         const cleaned = this.db.cleanupTelemetryEvents();
@@ -208,10 +241,26 @@ export class ThreatCloudServer {
             : rawPathname === '/v1'
                 ? '/'
                 : rawPathname;
-        if (pathname !== '/health' && this.config.apiKeyRequired) {
+        // Public endpoints that don't require API key authentication.
+        // Read-only data endpoints are public. Write endpoints require auth.
+        // GET /api/rules is public so Guard can pull open-source ATR rules without a key.
+        const publicPaths = new Set(['/health', '/api/stats', '/api/metrics', '/api/clients/register']);
+        const isPublicRead = publicPaths.has(pathname) || (pathname === '/api/rules' && req.method === 'GET');
+        // Track the role that authenticated this request so route handlers can
+        // enforce scope (e.g. L5 partner endpoints only accept role=partner|admin).
+        let authRole = 'anonymous';
+        if (!isPublicRead && this.config.apiKeyRequired) {
             const authHeader = req.headers.authorization ?? '';
             const token = authHeader.replace('Bearer ', '');
-            if (!this.config.apiKeys.includes(token)) {
+            const isValidApiKey = this.config.apiKeys.includes(token);
+            const isAdminKey = this.config.adminApiKey ? token === this.config.adminApiKey : false;
+            let clientKeyInfo = null;
+            if (!isValidApiKey && !isAdminKey && token.length > 0) {
+                clientKeyInfo = this.db.getClientKeyInfo(token);
+                if (clientKeyInfo)
+                    this.db.validateClientKey(token); // bump last_used_at
+            }
+            if (!isValidApiKey && !isAdminKey && !clientKeyInfo) {
                 this.sendJson(res, 401, { ok: false, error: 'Invalid API key', request_id: requestId });
                 log.info('request', {
                     method: req.method,
@@ -223,6 +272,36 @@ export class ThreatCloudServer {
                 });
                 return;
             }
+            authRole = isAdminKey
+                ? 'admin'
+                : isValidApiKey
+                    ? 'static'
+                    : clientKeyInfo?.role === 'partner'
+                        ? 'client-partner'
+                        : 'client-guard';
+        }
+        // L5 partner-sync: /api/atr-rules/live is role-gated. Only admin or
+        // partner-tier client keys can reach it. Guard auto-provisioned keys
+        // are scoped to telemetry upload only; they must NOT be able to exfiltrate
+        // TC crystallization data.
+        if (pathname === '/api/atr-rules/live' && req.method === 'GET') {
+            if (authRole !== 'admin' && authRole !== 'static' && authRole !== 'client-partner') {
+                this.sendJson(res, 403, {
+                    ok: false,
+                    error: 'Partner key required for L5 live-sync endpoint',
+                    docs: 'https://agentthreatrule.org/partner-sync',
+                    request_id: requestId,
+                });
+                log.info('request', {
+                    method: req.method,
+                    path: rawPathname,
+                    status: 403,
+                    duration_ms: Date.now() - startTime,
+                    client_ip: clientIP,
+                    request_id: requestId,
+                });
+                return;
+            }
         }
         // CORS — restrict to known origins
         const allowedOrigins = (process.env['CORS_ALLOWED_ORIGINS'] ??
@@ -253,7 +332,11 @@ export class ThreatCloudServer {
                 case '/health':
                     this.sendJson(res, 200, {
                         ok: true,
-                        data: { status: 'healthy', uptime: process.uptime() },
+                        data: {
+                            status: 'healthy',
+                            uptime: process.uptime(),
+                            schemaVersion: this.db.getSchemaVersion(),
+                        },
                     });
                     break;
                 case '/admin':
@@ -274,9 +357,25 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/atr-rules/live':
+                    // L5 runtime sync — public, cacheable, partner-facing alias of /api/rules
+                    // scoped to confirmed ATR rules only (source IN atr, atr-community).
+                    // Accepts ?since=<ISO> for incremental pulls; responds with ETag +
+                    // Last-Modified so partners can cheap-poll every N minutes.
+                    if (req.method === 'GET') {
+                        const u = new URL(url, `http://localhost:${this.config.port}`);
+                        if (!u.searchParams.has('source')) {
+                            u.searchParams.set('source', 'atr');
+                        }
+                        this.handleGetRules(u.pathname + '?' + u.searchParams.toString(), res, req);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/rules':
                     if (req.method === 'GET') {
-                        this.handleGetRules(url, res);
+                        this.handleGetRules(url, res, req);
                     }
                     else if (req.method === 'POST') {
                         if (!this.checkAdminAuth(req)) {
@@ -292,6 +391,45 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/rules/sync':
+                    // Admin-only: ATR repo CI syncs rules via admin key
+                    if (req.method === 'POST') {
+                        if (!this.checkAdminAuth(req)) {
+                            this.sendJson(res, 403, { ok: false, error: 'Admin API key required for rule sync' });
+                            break;
+                        }
+                        await this.handleSyncATRRules(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/rules/by-source':
+                    // Admin-only: DELETE /api/rules/by-source?source=yara to purge rules by source
+                    if (req.method === 'DELETE') {
+                        if (!this.checkAdminAuth(req)) {
+                            this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                            break;
+                        }
+                        await this.handleDeleteRulesBySource(url, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/rules/bulk-delete':
+                    // Admin-only: POST /api/rules/bulk-delete { ruleIds: [...] }
+                    if (req.method === 'POST') {
+                        if (!this.checkAdminAuth(req)) {
+                            this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                            break;
+                        }
+                        await this.handleBulkDeleteRules(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/stats':
                     if (req.method === 'GET') {
                         this.handleGetStats(res);
@@ -322,6 +460,25 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/atr-proposals/from-payload':
+                    // External red-team input (garak, human pentest, etc.) — takes a
+                    // raw attack payload, runs the TC drafter tool-use loop, returns
+                    // the generated ATR YAML. Admin or static key only; partner keys
+                    // intentionally cannot call this (LLM cost management).
+                    if (req.method === 'POST') {
+                        if (authRole !== 'admin' && authRole !== 'static') {
+                            this.sendJson(res, 403, {
+                                ok: false,
+                                error: 'Admin or static API key required for drafter endpoint',
+                            });
+                            break;
+                        }
+                        await this.handleDraftProposalFromPayload(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/atr-feedback':
                     if (req.method === 'POST') {
                         await this.handlePostATRFeedback(req, res);
@@ -330,6 +487,64 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/rule-feedback':
+                    if (req.method === 'POST') {
+                        await this.handlePostRuleFeedback(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/clients/register':
+                    if (req.method === 'POST') {
+                        await this.handleClientRegister(req, res, clientIP);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/admin/client-keys':
+                    if (!this.checkAdminAuth(req)) {
+                        this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                        break;
+                    }
+                    if (req.method === 'GET') {
+                        const params = new URL(url, `http://localhost:${this.config.port}`).searchParams;
+                        const limit = Math.min(200, Math.max(1, parseInt(params.get('limit') ?? '50', 10)));
+                        const offset = Math.max(0, parseInt(params.get('offset') ?? '0', 10));
+                        this.sendJson(res, 200, { ok: true, data: this.db.listClientKeys(limit, offset) });
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/admin/client-keys/revoke':
+                    if (!this.checkAdminAuth(req)) {
+                        this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                        break;
+                    }
+                    if (req.method === 'POST') {
+                        await this.handleClientKeyRevoke(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/admin/partner-keys':
+                    // L5 partner provisioning. Admin-only. Issues a partner-tier
+                    // client key that can access /api/atr-rules/live. Raw key is
+                    // returned exactly once — the caller must store it.
+                    if (!this.checkAdminAuth(req)) {
+                        this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                        break;
+                    }
+                    if (req.method === 'POST') {
+                        await this.handlePartnerKeyIssue(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/skill-threats':
                     if (req.method === 'GET') {
                         if (!this.checkAdminAuth(req)) {
@@ -347,7 +562,7 @@ export class ThreatCloudServer {
                     break;
                 case '/api/atr-rules':
                     if (req.method === 'GET') {
-                        this.handleGetATRRules(url, res);
+                        this.handleGetATRRules(url, res, req);
                     }
                     else {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
@@ -371,7 +586,7 @@ export class ThreatCloudServer {
                     break;
                 case '/api/skill-whitelist':
                     if (req.method === 'GET') {
-                        this.handleGetSkillWhitelist(res);
+                        this.handleGetSkillWhitelist(url, res);
                     }
                     else if (req.method === 'POST') {
                         await this.handlePostSkillWhitelist(req, res);
@@ -458,6 +673,14 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/version':
+                    if (req.method === 'GET') {
+                        this.handleGetVersion(res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/contributors':
                     if (req.method === 'GET') {
                         this.handleGetContributors(res);
@@ -482,6 +705,39 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/migrator/telemetry':
+                    // Migrator-specific telemetry (per-rule fingerprints, no rule body).
+                    // POST is open (any partner / install can submit); GET is admin-only.
+                    if (req.method === 'POST') {
+                        await this.handlePostMigratorTelemetry(req, res);
+                    }
+                    else if (req.method === 'GET') {
+                        if (!this.checkAdminAuth(req)) {
+                            this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                            break;
+                        }
+                        await this.handleGetMigratorTelemetryStats(res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/migrator/crystallization-candidates':
+                    // Surfaces fingerprints recurring across N+ tenants. Admin only.
+                    // Output is metadata only (no rule body); admin uses this to
+                    // identify which Migrator-derived rules to outreach for opt-in
+                    // contribution back to ATR mainline.
+                    if (req.method === 'GET') {
+                        if (!this.checkAdminAuth(req)) {
+                            this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                            break;
+                        }
+                        await this.handleGetMigratorCrystallizationCandidates(url, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/usage':
                     if (req.method === 'POST') {
                         await this.handlePostUsageEvent(req, res);
@@ -498,6 +754,46 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/activations':
+                    if (req.method === 'POST') {
+                        const body = await this.readBody(req);
+                        const data = JSON.parse(body);
+                        if (!data.clientId) {
+                            this.sendJson(res, 400, { ok: false, error: 'clientId required' });
+                            break;
+                        }
+                        this.db.recordActivation({
+                            clientId: data.clientId,
+                            platform: data.platform ?? 'unknown',
+                            osType: data.osType ?? 'unknown',
+                            panguardVersion: data.panguardVersion ?? 'unknown',
+                            nodeVersion: data.nodeVersion ?? 'unknown',
+                        });
+                        this.sendJson(res, 200, { ok: true });
+                    }
+                    else if (req.method === 'GET') {
+                        if (!this.checkAdminAuth(req)) {
+                            this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                            break;
+                        }
+                        const activationStats = this.db.getActivationStats();
+                        this.sendJson(res, 200, { ok: true, data: activationStats });
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                // ─── Org / Device / Policy endpoints (Threat Model #1, #6) ───
+                case '/api/devices/heartbeat':
+                    // Requires API key (enforced by general auth gate above).
+                    // Guard sends periodic heartbeats with device metadata.
+                    if (req.method === 'POST') {
+                        await this.handleDeviceHeartbeat(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/admin/reset-rules':
                     if (req.method === 'POST') {
                         if (!this.checkAdminAuth(req)) {
@@ -532,12 +828,71 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
-                default:
+                default: {
+                    // Org fleet/policy routes with path params
+                    // Threat Model: Fleet view (#6), Policy engine (#1, #6)
+                    const orgDevicesMatch = pathname.match(/^\/api\/orgs\/([^/]+)\/devices$/);
+                    if (orgDevicesMatch) {
+                        const orgId = decodeURIComponent(orgDevicesMatch[1]);
+                        if (req.method === 'GET') {
+                            if (!this.checkAdminAuth(req)) {
+                                this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                                break;
+                            }
+                            const devices = this.db.getDevicesByOrg(orgId);
+                            const count = this.db.getDeviceCount(orgId);
+                            this.sendJson(res, 200, { ok: true, data: { devices, total: count } });
+                        }
+                        else {
+                            this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                        }
+                        break;
+                    }
+                    const orgPoliciesMatch = pathname.match(/^\/api\/orgs\/([^/]+)\/policies$/);
+                    if (orgPoliciesMatch) {
+                        const orgId = decodeURIComponent(orgPoliciesMatch[1]);
+                        if (!this.checkAdminAuth(req)) {
+                            this.sendJson(res, 403, { ok: false, error: 'Admin API key required' });
+                            break;
+                        }
+                        if (req.method === 'GET') {
+                            const policies = this.db.getOrgPolicies(orgId);
+                            this.sendJson(res, 200, { ok: true, data: policies });
+                        }
+                        else if (req.method === 'POST') {
+                            const body = await this.readBody(req);
+                            const data = JSON.parse(body);
+                            if (!data.category || !data.action || !['allow', 'block'].includes(data.action)) {
+                                this.sendJson(res, 400, {
+                                    ok: false,
+                                    error: 'category and action (allow|block) required',
+                                });
+                                break;
+                            }
+                            this.db.setOrgPolicy(orgId, data.category, data.action);
+                            this.sendJson(res, 200, { ok: true });
+                        }
+                        else if (req.method === 'DELETE') {
+                            const body = await this.readBody(req);
+                            const data = JSON.parse(body);
+                            if (!data.category) {
+                                this.sendJson(res, 400, { ok: false, error: 'category required' });
+                                break;
+                            }
+                            const deleted = this.db.deleteOrgPolicy(orgId, data.category);
+                            this.sendJson(res, 200, { ok: true, deleted });
+                        }
+                        else {
+                            this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                        }
+                        break;
+                    }
                     // Badge API handles /api/badge/* paths with dynamic segments
                     if (this.badgeRouter.handleRequest(pathname, req.method ?? 'GET', res)) {
                         break;
                     }
                     this.sendJson(res, 404, { ok: false, error: 'Not found' });
+                }
             }
         }
         catch (err) {
@@ -590,6 +945,101 @@ export class ThreatCloudServer {
             this.sendJson(res, 400, { ok: false, error: 'Invalid request body' });
         }
     }
+    /**
+     * POST /api/migrator/telemetry — record a Migrator run summary.
+     * Body shape matches MigratorTelemetryEvent from
+     * @panguard/migrator/telemetry/tc-reporter:
+     *   { schema_version, install_id, migrator_version, run, rules[], frameworks }
+     * One event yields N rows in migrator_telemetry (one per rule).
+     * Carries fingerprints only — never rule body, never customer ID.
+     */
+    async handlePostMigratorTelemetry(req, res) {
+        try {
+            const body = await this.readBody(req);
+            const data = JSON.parse(body);
+            if (!data.install_id || !Array.isArray(data.rules) || data.rules.length === 0) {
+                this.sendJson(res, 400, {
+                    ok: false,
+                    error: 'install_id and rules[] are required',
+                });
+                return;
+            }
+            const { recordMigratorTelemetry } = await import('./migrator-crystallization.js');
+            const result = recordMigratorTelemetry(this.db.getRawDb(), {
+                install_id: data.install_id,
+                migrator_version: data.migrator_version ?? 'unknown',
+                source_kind: data.run?.source_kind ?? 'sigma',
+                rules: data.rules.map((r) => ({
+                    atr_id: r.atr_id,
+                    category: r.category ?? 'unknown',
+                    severity: r.severity ?? 'low',
+                    has_agent_analogue: r.has_agent_analogue === true,
+                    condition_hash: r.condition_hash,
+                    framework_count: r.framework_count ?? 0,
+                })),
+                ...(data.frameworks !== undefined ? { frameworks: data.frameworks } : {}),
+            });
+            this.sendJson(res, 200, { ok: true, data: { rows_inserted: result.rows_inserted } });
+        }
+        catch (err) {
+            this.sendJson(res, 400, {
+                ok: false,
+                error: err instanceof Error ? err.message : 'Invalid request body',
+            });
+        }
+    }
+    /** GET /api/migrator/telemetry — admin stats. */
+    async handleGetMigratorTelemetryStats(res) {
+        try {
+            const { getMigratorTelemetryStats } = await import('./migrator-crystallization.js');
+            const stats = getMigratorTelemetryStats(this.db.getRawDb());
+            this.sendJson(res, 200, { ok: true, data: stats });
+        }
+        catch (err) {
+            this.sendJson(res, 500, {
+                ok: false,
+                error: err instanceof Error ? err.message : 'failed',
+            });
+        }
+    }
+    /**
+     * GET /api/migrator/crystallization-candidates — admin only.
+     * Query params:
+     *   - minTenants (default 3): minimum distinct install_ids on a fingerprint
+     *   - windowDays (default 30): observation window
+     *   - limit (default 100)
+     */
+    async handleGetMigratorCrystallizationCandidates(rawUrl, res) {
+        try {
+            const { findCrystallizationCandidates } = await import('./migrator-crystallization.js');
+            const parsed = new URL(rawUrl, 'http://localhost');
+            const minTenants = Number(parsed.searchParams.get('minTenants') ?? '3');
+            const windowDays = Number(parsed.searchParams.get('windowDays') ?? '30');
+            const limit = Number(parsed.searchParams.get('limit') ?? '100');
+            const minTenantCount = Number.isFinite(minTenants) ? minTenants : 3;
+            const winDays = Number.isFinite(windowDays) ? windowDays : 30;
+            const lim = Number.isFinite(limit) ? limit : 100;
+            const candidates = findCrystallizationCandidates(this.db.getRawDb(), {
+                minTenantCount,
+                windowDays: winDays,
+                limit: lim,
+            });
+            this.sendJson(res, 200, {
+                ok: true,
+                data: {
+                    candidates,
+                    query: { minTenants: minTenantCount, windowDays: winDays, limit: lim },
+                    total: candidates.length,
+                },
+            });
+        }
+        catch (err) {
+            this.sendJson(res, 500, {
+                ok: false,
+                error: err instanceof Error ? err.message : 'failed',
+            });
+        }
+    }
     /** POST /api/usage - Record usage event (scan, cli_install, etc.) */
     async handlePostUsageEvent(req, res) {
         try {
@@ -649,7 +1099,7 @@ export class ThreatCloudServer {
         });
     }
     /** GET /api/rules?since=<ISO>&category=<cat>&severity=<sev>&source=<src> */
-    handleGetRules(url, res) {
+    handleGetRules(url, res, req) {
         const params = new URL(url, `http://localhost:${this.config.port}`).searchParams;
         const since = params.get('since');
         const filters = {
@@ -663,7 +1113,32 @@ export class ThreatCloudServer {
             ? this.db.getRulesSince(since, filters)
             : this.db.getAllRules(5000, filters);
         const ruleList = Array.isArray(rules) ? rules : [];
-        this.sendJson(res, 200, { ok: true, data: ruleList, meta: { total: ruleList.length } });
+        // L5 runtime sync support: ETag + Last-Modified so partners can cheap-poll.
+        // ETag = hash of (count + latest publishedAt) — cheap and changes when content does.
+        // Last-Modified = max(publishedAt) in result set.
+        let latestPublishedAt = '';
+        for (const r of ruleList) {
+            const p = typeof r.publishedAt === 'string' ? r.publishedAt : '';
+            if (p > latestPublishedAt)
+                latestPublishedAt = p;
+        }
+        const etag = `W/"${ruleList.length}-${latestPublishedAt}"`;
+        res.setHeader('ETag', etag);
+        if (latestPublishedAt) {
+            try {
+                res.setHeader('Last-Modified', new Date(latestPublishedAt).toUTCString());
+            }
+            catch {
+                /* ignore malformed date */
+            }
+        }
+        const ifNoneMatch = req?.headers['if-none-match'];
+        if (ifNoneMatch && ifNoneMatch === etag) {
+            res.writeHead(304);
+            res.end();
+            return;
+        }
+        this.sendJson(res, 200, { ok: true, data: ruleList, meta: { total: ruleList.length, etag } });
     }
     /** POST /api/rules - Publish rules (single or batch) */
     async handlePostRule(req, res) {
@@ -696,6 +1171,131 @@ export class ThreatCloudServer {
         this.db.audit.logAction('admin', 'rule.create', 'rule', undefined, { count }, clientIP);
         this.sendJson(res, 201, { ok: true, data: { message: `${count} rule(s) published`, count } });
     }
+    /**
+     * POST /api/rules/sync — Admin-only endpoint for ATR repo CI to sync rules.
+     * Requires admin API key. Only accepts source='atr' (community rules use POST /api/rules).
+     * Body: { rules: [{ ruleId, ruleContent, source }] }. Max 200 per request.
+     */
+    async handleSyncATRRules(req, res) {
+        const body = await this.readBody(req);
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return;
+        }
+        const rawObj = raw;
+        const rawRules = 'rules' in rawObj && Array.isArray(rawObj['rules']) ? rawObj['rules'] : [raw];
+        if (rawRules.length > 200) {
+            this.sendJson(res, 400, { ok: false, error: 'Maximum 200 rules per sync request' });
+            return;
+        }
+        const now = new Date().toISOString();
+        let count = 0;
+        let skipped = 0;
+        for (const rawRule of rawRules) {
+            const result = tryValidateInput(RulePublishSchema, rawRule);
+            if (!result.ok) {
+                skipped++;
+                continue;
+            }
+            // Only allow source='atr' — community rules require admin key
+            if (result.data.source !== 'atr') {
+                skipped++;
+                continue;
+            }
+            const ruleData = {
+                ...result.data,
+                publishedAt: result.data.publishedAt || now,
+            };
+            this.db.upsertRule(ruleData);
+            count++;
+        }
+        const clientIP = req.socket.remoteAddress ?? 'unknown';
+        this.db.audit.logAction('system', 'rule.sync', 'rule', undefined, { count, skipped }, clientIP);
+        this.sendJson(res, 200, {
+            ok: true,
+            data: { message: `${count} rule(s) synced, ${skipped} skipped`, count, skipped },
+        });
+    }
+    /** POST /api/rules/bulk-delete — Admin-only delete by rule IDs */
+    async handleBulkDeleteRules(req, res) {
+        const body = await this.readBody(req);
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return;
+        }
+        const rawObj = raw;
+        const ruleIds = rawObj['ruleIds'];
+        if (!Array.isArray(ruleIds) || ruleIds.length === 0) {
+            this.sendJson(res, 400, { ok: false, error: 'Missing or empty ruleIds array' });
+            return;
+        }
+        if (ruleIds.length > 500) {
+            this.sendJson(res, 400, { ok: false, error: 'Maximum 500 rule IDs per request' });
+            return;
+        }
+        const count = this.db.deleteRulesByIds(ruleIds);
+        const clientIP = req.socket.remoteAddress ?? 'unknown';
+        this.db.audit.logAction('admin', 'rule.bulk-delete', 'rule', undefined, { count, requested: ruleIds.length }, clientIP);
+        this.sendJson(res, 200, { ok: true, data: { message: `Deleted ${count} rule(s)`, count } });
+    }
+    /** DELETE /api/rules/by-source?source=yara — Admin-only bulk purge */
+    /** POST /api/devices/heartbeat — Guard sends periodic device metadata */
+    async handleDeviceHeartbeat(req, res) {
+        const body = await this.readBody(req);
+        let data;
+        try {
+            data = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return;
+        }
+        const deviceId = typeof data['deviceId'] === 'string' ? data['deviceId'].slice(0, 128) : '';
+        const orgId = typeof data['orgId'] === 'string' ? data['orgId'].slice(0, 128) : '';
+        if (!deviceId || !orgId) {
+            this.sendJson(res, 400, { ok: false, error: 'deviceId and orgId required' });
+            return;
+        }
+        // Auto-create org if it doesn't exist (first device creates the org)
+        if (!this.db.getOrg(orgId)) {
+            this.db.createOrg(orgId, orgId);
+        }
+        this.db.upsertDevice({
+            deviceId,
+            orgId,
+            hostname: typeof data['hostname'] === 'string' ? data['hostname'].slice(0, 256) : undefined,
+            osType: typeof data['osType'] === 'string' ? data['osType'].slice(0, 64) : undefined,
+            agentCount: typeof data['agentCount'] === 'number' ? data['agentCount'] : undefined,
+            guardVersion: typeof data['guardVersion'] === 'string' ? data['guardVersion'].slice(0, 32) : undefined,
+        });
+        this.sendJson(res, 200, { ok: true });
+    }
+    async handleDeleteRulesBySource(url, res) {
+        const params = new URLSearchParams(url.split('?')[1] ?? '');
+        const source = params.get('source');
+        if (!source) {
+            this.sendJson(res, 400, { ok: false, error: 'Missing ?source= parameter' });
+            return;
+        }
+        // Safety: refuse to delete ATR rules via this endpoint
+        if (source === 'atr' || source === 'atr-community') {
+            this.sendJson(res, 400, { ok: false, error: 'Cannot purge ATR rules via this endpoint' });
+            return;
+        }
+        const count = this.db.deleteRulesBySource(source);
+        this.sendJson(res, 200, {
+            ok: true,
+            data: { message: `Deleted ${count} ${source} rule(s)`, count },
+        });
+    }
     /** GET /api/stats (cached 60s) */
     handleGetStats(res) {
         res.setHeader('Cache-Control', 'public, max-age=60, s-maxage=60');
@@ -736,6 +1336,78 @@ export class ThreatCloudServer {
         const threats = this.db.getSkillThreats(limit);
         this.sendJson(res, 200, { ok: true, data: threats });
     }
+    /**
+     * POST /api/atr-proposals/from-payload — drafter endpoint for external
+     * red-team input. Runs the TC tool-use drafter on the supplied attack
+     * payload and returns the generated ATR YAML. Admin or static key only.
+     */
+    async handleDraftProposalFromPayload(req, res) {
+        if (!this.llmReviewer?.isAvailable()) {
+            this.sendJson(res, 503, {
+                ok: false,
+                error: 'Drafter unavailable (LLM reviewer not configured — check ANTHROPIC_API_KEY and billing)',
+            });
+            return;
+        }
+        const body = await this.readBody(req);
+        if (!body) {
+            this.sendJson(res, 400, { ok: false, error: 'Request body required' });
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+            return;
+        }
+        const payload = typeof parsed.payload === 'string' ? parsed.payload : '';
+        if (payload.length < 16) {
+            this.sendJson(res, 400, {
+                ok: false,
+                error: 'payload required (min 16 chars, max 8000 — longer prompts are truncated)',
+            });
+            return;
+        }
+        if (payload.length > 8000) {
+            this.sendJson(res, 400, {
+                ok: false,
+                error: 'payload too long (max 8000 chars)',
+            });
+            return;
+        }
+        const drafterResult = await this.llmReviewer.draftRuleFromPayload(payload, {
+            probe: typeof parsed.probe === 'string' ? parsed.probe.slice(0, 128) : undefined,
+            detector: typeof parsed.detector === 'string' ? parsed.detector.slice(0, 128) : undefined,
+            targetModel: typeof parsed.targetModel === 'string' ? parsed.targetModel.slice(0, 128) : undefined,
+            partnerName: typeof parsed.partnerName === 'string' ? parsed.partnerName.slice(0, 64) : undefined,
+            severity: typeof parsed.severity === 'string' ? parsed.severity.slice(0, 16) : undefined,
+        });
+        if (!drafterResult) {
+            // Not an error per se — drafter may legitimately decline (NO_THREATS_FOUND,
+            // duplicate of existing coverage, quality gate failure). Surface that as
+            // 200 + drafted:false so the caller can distinguish from auth/input errors.
+            this.sendJson(res, 200, {
+                ok: true,
+                data: {
+                    drafted: false,
+                    reason: 'Drafter declined (NO_THREATS_FOUND, duplicate of existing rule, or failed quality gate / self-test — see server logs for specifics)',
+                },
+            });
+            return;
+        }
+        this.sendJson(res, 201, {
+            ok: true,
+            data: {
+                drafted: true,
+                patternHash: drafterResult.patternHash,
+                ruleContent: drafterResult.ruleContent,
+                toolCalls: drafterResult.toolCalls,
+                nextSteps: 'Proposal entered atr_proposals as pending. LLM self-review runs async; admin-approve or community consensus moves it to canary; safety gate + auto-merge publish to npm.',
+            },
+        });
+    }
     /** POST /api/atr-proposals - Submit or confirm an ATR rule proposal */
     async handlePostATRProposal(req, res) {
         const data = await this.parseAndValidate(req, res, ATRProposalSchema);
@@ -793,7 +1465,154 @@ export class ThreatCloudServer {
         this.db.insertATRFeedback(data.ruleId, data.isTruePositive, clientId);
         this.sendJson(res, 201, { ok: true, data: { message: 'Feedback received' } });
     }
+    /** POST /api/rule-feedback - Submit negative feedback on a canary/active rule, auto-quarantine at threshold */
+    async handlePostRuleFeedback(req, res) {
+        const body = await this.readBody(req);
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return;
+        }
+        const schema = z.object({
+            ruleId: z.string().min(1),
+            isTruePositive: z.boolean(),
+        });
+        const parsed = schema.safeParse(raw);
+        if (!parsed.success) {
+            this.sendJson(res, 400, { ok: false, error: parsed.error.message });
+            return;
+        }
+        const clientId = req.headers['x-panguard-client-id'] ?? undefined;
+        this.db.insertATRFeedback(parsed.data.ruleId, parsed.data.isTruePositive, clientId);
+        // Auto-quarantine canary rules with > 3 negative reports
+        if (!parsed.data.isTruePositive) {
+            const negCount = this.db.getNegativeFeedbackCount(parsed.data.ruleId);
+            if (negCount >= 3) {
+                this.db.quarantineProposal(parsed.data.ruleId);
+                log.info(`Rule ${parsed.data.ruleId} auto-quarantined after ${negCount} negative reports`);
+                this.sendJson(res, 201, {
+                    ok: true,
+                    data: { message: 'Feedback received, rule quarantined', quarantined: true },
+                });
+                return;
+            }
+        }
+        this.sendJson(res, 201, {
+            ok: true,
+            data: { message: 'Feedback received', quarantined: false },
+        });
+    }
     /** POST /api/skill-threats - Submit skill threat from audit */
+    /** POST /api/clients/register — auto-provision client API key */
+    async handleClientRegister(req, res, clientIP) {
+        // Rate limit: 10 registrations per hour per IP
+        const entry = this.registrationRateLimits.get(clientIP);
+        const now = Date.now();
+        if (entry && now < entry.resetAt) {
+            if (entry.count >= 10) {
+                this.sendJson(res, 429, {
+                    ok: false,
+                    error: 'Registration rate limit exceeded. Try again later.',
+                });
+                return;
+            }
+            entry.count++;
+        }
+        else {
+            this.registrationRateLimits.set(clientIP, { count: 1, resetAt: now + 3_600_000 });
+        }
+        const body = await this.readBody(req);
+        if (!body) {
+            this.sendJson(res, 400, { ok: false, error: 'Request body required' });
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+            return;
+        }
+        const clientId = parsed.clientId;
+        if (!clientId || typeof clientId !== 'string' || clientId.length < 8 || clientId.length > 128) {
+            this.sendJson(res, 400, { ok: false, error: 'clientId must be a string (8-128 chars)' });
+            return;
+        }
+        const result = this.db.registerClientKey(clientId, clientIP);
+        this.db.audit.logAction('system', 'client_key.register', 'client_key', clientId, { ip: clientIP }, clientIP);
+        this.sendJson(res, 201, { ok: true, data: { clientKey: result.clientKey } });
+    }
+    /** POST /api/admin/client-keys/revoke — revoke client keys */
+    async handleClientKeyRevoke(req, res) {
+        const body = await this.readBody(req);
+        if (!body) {
+            this.sendJson(res, 400, { ok: false, error: 'Request body required' });
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+            return;
+        }
+        if (!parsed.clientId || typeof parsed.clientId !== 'string') {
+            this.sendJson(res, 400, { ok: false, error: 'clientId required' });
+            return;
+        }
+        const revoked = this.db.revokeClientKey(parsed.clientId);
+        const clientIP = req.socket.remoteAddress ?? 'unknown';
+        this.db.audit.logAction('admin', 'client_key.revoke', 'client_key', parsed.clientId, { revokedCount: revoked }, clientIP);
+        this.sendJson(res, 200, { ok: true, data: { revoked } });
+    }
+    /**
+     * Admin-only: issue a partner-tier client key for L5 live-sync access.
+     * Body: { partnerName: string, issuedBy?: string }
+     * Returns raw key once — never retrievable again.
+     */
+    async handlePartnerKeyIssue(req, res) {
+        const body = await this.readBody(req);
+        if (!body) {
+            this.sendJson(res, 400, { ok: false, error: 'Request body required' });
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+            return;
+        }
+        const partnerName = typeof parsed.partnerName === 'string' ? parsed.partnerName.trim() : '';
+        // Slug-like validation — no spaces, no colons (we already use `partner:` prefix internally)
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{1,63}$/.test(partnerName)) {
+            this.sendJson(res, 400, {
+                ok: false,
+                error: 'partnerName must be 2-64 chars, alphanumeric + dash/underscore only',
+            });
+            return;
+        }
+        const issuedBy = typeof parsed.issuedBy === 'string' ? parsed.issuedBy.slice(0, 64) : 'admin';
+        const { clientKey } = this.db.registerPartnerKey(partnerName, issuedBy);
+        const clientIP = req.socket.remoteAddress ?? 'unknown';
+        this.db.audit.logAction('admin', 'partner_key.issue', 'client_key', `partner:${partnerName}`, { issuedBy }, clientIP);
+        // The key is returned exactly once. The caller MUST store it.
+        this.sendJson(res, 201, {
+            ok: true,
+            data: {
+                partnerName,
+                clientId: `partner:${partnerName}`,
+                clientKey,
+                note: 'Store this key now. It will not be retrievable again. Use as `Authorization: Bearer <key>` header on /api/atr-rules/live.',
+            },
+        });
+    }
     async handlePostSkillThreat(req, res) {
         const data = await this.parseAndValidate(req, res, SkillThreatSchema);
         if (!data)
@@ -835,15 +1654,46 @@ export class ThreatCloudServer {
             .slice(0, 16);
         if (this.db.hasATRProposal(patternHash))
             return;
-        // If LLM reviewer is available, use it for high-quality rule generation
-        if (this.llmReviewer?.isAvailable()) {
-            // Build a synthetic tool description from aggregated findings
+        // Fetch actual ATR rule detection patterns that triggered on this skill.
+        // This is the key input for LLM: real regex patterns, not just finding titles.
+        const triggeredRules = agg.atrRuleIds.length > 0 ? this.db.getRuleContentByIds(agg.atrRuleIds) : [];
+        // Extract detection sections from rule YAML for LLM context
+        const detectionPatterns = triggeredRules.map((r) => {
+            // Extract detection block from YAML
+            const detMatch = r.ruleContent.match(/detection:[\s\S]*?(?=\n[a-z]|\n---|$)/);
+            const titleMatch = r.ruleContent.match(/title:\s*['"]?([^'"\n]+)/);
+            return {
+                ruleId: r.ruleId,
+                title: titleMatch?.[1]?.trim() ?? r.ruleId,
+                detection: detMatch?.[0]?.trim() ?? '(detection not parseable)',
+            };
+        });
+        if (this.llmReviewer?.isAvailable() && detectionPatterns.length > 0) {
+            // Build rich context: actual attack patterns, not just finding titles
+            const patternContext = detectionPatterns
+                .map((p) => `### ${p.ruleId}: ${p.title}\n${p.detection}`)
+                .join('\n\n');
+            const toolDescriptions = [
+                {
+                    name: skillName,
+                    description: `This skill was flagged ${agg.reportCount} times (avg risk: ${Math.round(agg.avgRiskScore)}) by ${agg.atrRuleIds.length} distinct ATR rules.\n\nTriggered rules and their detection patterns:\n\n${patternContext}\n\nFinding titles: ${agg.findings.join('; ')}`,
+                },
+            ];
+            log.info(`Flywheel bridge: LLM generating ATR proposal for ${skillName} ` +
+                `(${agg.reportCount} reports, ${agg.atrRuleIds.length} ATR rules: ${agg.atrRuleIds.join(', ')})`);
+            void this.llmReviewer
+                .analyzeSkills([{ package: skillName, tools: toolDescriptions }])
+                .catch((err) => {
+                log.error(`LLM analysis for skill bridge failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        else if (this.llmReviewer?.isAvailable()) {
+            // LLM available but no rule patterns — pass findings as-is (legacy path)
             const toolDescriptions = agg.findings.map((f, i) => ({
                 name: `finding_${i}`,
                 description: f,
             }));
-            log.info(`Flywheel bridge: generating ATR proposal for ${skillName} (${agg.reportCount} reports) / ` +
-                `飛輪橋接: 為 ${skillName} 產生 ATR 提案 (${agg.reportCount} 個報告)`);
+            log.info(`Flywheel bridge: LLM generating ATR proposal for ${skillName} (${agg.reportCount} reports, no rule context)`);
             void this.llmReviewer
                 .analyzeSkills([{ package: skillName, tools: toolDescriptions }])
                 .catch((err) => {
@@ -851,61 +1701,37 @@ export class ThreatCloudServer {
             });
         }
         else {
-            // No LLM available — scaffold a basic pattern-based proposal
-            const severity = agg.maxRiskLevel === 'CRITICAL' ? 'critical' : 'high';
-            const date = new Date().toISOString().slice(0, 10).replace(/-/g, '/');
-            const findingSummary = agg.findings.slice(0, 5).join('; ');
-            const ruleContent = `title: "Community Consensus: ${agg.findings[0]?.slice(0, 60) ?? skillName}"
-id: ATR-2026-DRAFT-${patternHash.slice(0, 8)}
-status: draft
-description: |
-  Auto-generated from ${agg.reportCount} independent threat reports for skill "${skillName}".
-  Avg risk score: ${Math.round(agg.avgRiskScore)}.
-  Findings: ${findingSummary.slice(0, 300)}
-author: "Threat Cloud Auto-Bridge"
-date: "${date}"
-schema_version: "0.1"
-detection_tier: community
-maturity: experimental
-severity: ${severity}
-tags:
-  category: skill-compromise
-  subcategory: community-consensus
-  confidence: high
-detection:
-  conditions:
-    - field: skill_manifest
-      operator: contains
-      value: "${skillName}"
-      description: "Skill reported by ${agg.reportCount} independent sources"
-  condition: any
-response:
-  actions: [alert, snapshot]`;
-            this.db.insertATRProposal({
-                patternHash,
-                ruleContent,
-                llmProvider: 'community-bridge',
-                llmModel: 'aggregation',
-                selfReviewVerdict: JSON.stringify({
-                    approved: true,
-                    source: 'skill-threat-bridge',
-                    skillName,
-                    reportCount: agg.reportCount,
-                    avgRiskScore: Math.round(agg.avgRiskScore),
-                }),
-            });
-            log.info(`Flywheel bridge: basic ATR proposal created for ${skillName} (${agg.reportCount} reports) / ` +
-                `飛輪橋接: 基礎 ATR 提案已建立 ${skillName}`);
+            // No LLM — add to blacklist directly, don't generate garbage rules
+            log.info(`Flywheel bridge: no LLM available, skipping rule generation for ${skillName} ` +
+                `(${agg.reportCount} reports, avg risk ${Math.round(agg.avgRiskScore)}). ` +
+                `Skill is already blacklisted via threat reports.`);
         }
     }
-    /** GET /api/atr-rules?since=<ISO> - Fetch confirmed/promoted ATR rules */
-    handleGetATRRules(url, res) {
+    /** GET /api/atr-rules?since=<ISO> - Fetch promoted ATR rules (+ canary for 10% of clients) */
+    handleGetATRRules(url, res, req) {
         res.setHeader('Cache-Control', 'public, max-age=3600, s-maxage=3600');
         const params = new URL(url, `http://localhost:${this.config.port}`).searchParams;
         const since = params.get('since') ?? undefined;
         const rules = this.db.getConfirmedATRRules(since);
         const ruleList = Array.isArray(rules) ? rules : [];
-        this.sendJson(res, 200, { ok: true, data: ruleList, meta: { total: ruleList.length } });
+        // Include canary rules for ~10% of clients based on client ID hash
+        let includeCanary = false;
+        if (req) {
+            const clientId = req.headers['x-panguard-client-id'];
+            if (clientId) {
+                const hash = clientId.split('').reduce((acc, ch) => acc + ch.charCodeAt(0), 0);
+                includeCanary = hash % 10 === 0;
+            }
+        }
+        if (includeCanary) {
+            const canaryRules = this.db.getCanaryATRRules();
+            ruleList.push(...canaryRules);
+        }
+        this.sendJson(res, 200, {
+            ok: true,
+            data: ruleList,
+            meta: { total: ruleList.length, includesCanary: includeCanary },
+        });
     }
     /** GET /api/feeds/ip-blocklist?minReputation=70 - IP blocklist feed (plain text) */
     handleGetIPBlocklist(url, res) {
@@ -952,9 +1778,11 @@ response:
         }
         this.sendJson(res, 201, { ok: true, data: { message: `${count} skill(s) reported`, count } });
     }
-    /** GET /api/skill-whitelist - Fetch community-confirmed safe skills */
-    handleGetSkillWhitelist(res) {
-        const whitelist = this.db.getSkillWhitelist();
+    /** GET /api/skill-whitelist?since=ISO — Fetch community-confirmed safe skills (incremental) */
+    handleGetSkillWhitelist(url, res) {
+        const params = new URL(url, `http://localhost:${this.config.port}`).searchParams;
+        const since = params.get('since') ?? undefined;
+        const whitelist = this.db.getSkillWhitelist(since);
         this.sendJson(res, 200, { ok: true, data: whitelist });
     }
     /**
@@ -966,8 +1794,10 @@ response:
         const params = new URL(url, `http://localhost:${this.config.port}`).searchParams;
         const minReports = Number(params.get('minReports') ?? '3');
         const minAvgRisk = Number(params.get('minAvgRisk') ?? '70');
-        res.setHeader('Cache-Control', 'public, max-age=1800, s-maxage=1800');
-        const blacklist = this.db.getSkillBlacklist(minReports, minAvgRisk);
+        const since = params.get('since') ?? undefined;
+        // Shorter cache for incremental queries
+        res.setHeader('Cache-Control', since ? 'public, max-age=60' : 'public, max-age=1800, s-maxage=1800');
+        const blacklist = this.db.getSkillBlacklist(minReports, minAvgRisk, since);
         this.sendJson(res, 200, { ok: true, data: blacklist });
     }
     /** PATCH /api/atr-proposals - Admin approve/reject a proposal */
@@ -1013,6 +1843,19 @@ response:
     async handlePostSkillBlacklist(req, res) {
         const body = await this.readBody(req);
         const data = JSON.parse(body);
+        // Support bulk upload: { skills: [{ skillName, reason }] }
+        if (Array.isArray(data.skills)) {
+            let added = 0;
+            for (const entry of data.skills) {
+                if (entry.skillName) {
+                    this.db.addToBlacklist(entry.skillName, entry.reason || 'Bulk admin block');
+                    added++;
+                }
+            }
+            this.sendJson(res, 201, { ok: true, data: { added, total: data.skills.length } });
+            return;
+        }
+        // Single skill upload
         const { skillName, reason } = data;
         if (!skillName) {
             this.sendJson(res, 400, { ok: false, error: 'skillName required' });
@@ -1044,13 +1887,6 @@ response:
      * Response: { ok: true, data: { analyzed, proposalsCreated, results } }
      */
     async handleAnalyzeSkills(req, res) {
-        if (!this.llmReviewer?.isAvailable()) {
-            this.sendJson(res, 503, {
-                ok: false,
-                error: 'LLM reviewer not available — ANTHROPIC_API_KEY not configured on server',
-            });
-            return;
-        }
         const AnalyzeSkillsSchema = z.object({
             skills: z
                 .array(z.object({
@@ -1066,26 +1902,161 @@ response:
         const data = await this.parseAndValidate(req, res, AnalyzeSkillsSchema);
         if (!data)
             return;
+        const { createHash } = await import('node:crypto');
         const skills = data.skills;
-        log.info(`Analyzing ${skills.length} skills with LLM`, {
+        // Compute content hash for each skill (deterministic: sorted tools, null-byte separated)
+        const computeHash = (tools) => {
+            const canonical = [...tools]
+                .map((t) => `${t.name}\n${t.description}`)
+                .sort()
+                .join('\0');
+            return createHash('sha256').update(canonical).digest('hex');
+        };
+        const allResults = [];
+        const uncachedSkills = [];
+        const uncachedMeta = [];
+        log.info(`Analyzing ${skills.length} skills (checking cache + rug pull)`, {
             packages: skills.map((s) => s.package),
         });
-        const results = await this.llmReviewer.analyzeSkills(skills);
-        const proposalsCreated = results.reduce((sum, r) => sum + r.proposals.length, 0);
-        log.info(`LLM analysis complete: ${proposalsCreated} proposals from ${skills.length} skills`);
+        for (const skill of skills) {
+            const contentHash = computeHash(skill.tools);
+            let rugPullDetected = false;
+            // ── Rug pull check: has this skill's content changed? ──
+            const previousHash = this.db.getLatestSkillHash(skill.package);
+            // Save old verdict BEFORE marking superseded (getLatestSkillHash won't find it after)
+            const previousVerdict = previousHash?.scanVerdict ?? null;
+            if (previousHash && previousHash.contentHash !== contentHash) {
+                rugPullDetected = true;
+                this.db.markSkillHashSuperseded(skill.package, previousHash.contentHash, contentHash);
+                log.info(`[RUG PULL] Candidate: ${skill.package} hash changed`, {
+                    oldHash: previousHash.contentHash.slice(0, 12),
+                    newHash: contentHash.slice(0, 12),
+                });
+            }
+            // ── Verdict cache check (skip if rug pull — force rescan) ──
+            if (!rugPullDetected) {
+                const cached = this.db.getVerdictCache(contentHash);
+                if (cached) {
+                    let verdict;
+                    try {
+                        verdict = JSON.parse(cached.verdict);
+                    }
+                    catch {
+                        // Corrupted cache entry — invalidate and fall through to LLM scan
+                        this.db.invalidateVerdictCache(contentHash);
+                        uncachedSkills.push(skill);
+                        uncachedMeta.push({ contentHash, rugPull: false, previousVerdict: null });
+                        continue;
+                    }
+                    allResults.push({
+                        package: skill.package,
+                        threatsFound: verdict.threatsFound,
+                        proposalCount: verdict.proposalCount,
+                        patternHashes: verdict.patternHashes,
+                        status: verdict.status,
+                        cached: true,
+                        rugPullDetected: false,
+                    });
+                    // Update last_seen in hash history
+                    this.db.recordSkillHash({ skillName: skill.package, contentHash });
+                    continue;
+                }
+            }
+            // Cache miss or rug pull — needs LLM analysis
+            uncachedSkills.push(skill);
+            uncachedMeta.push({ contentHash, rugPull: rugPullDetected, previousVerdict });
+        }
+        // ── Run LLM analysis on uncached skills ──
+        let proposalsCreated = 0;
+        if (uncachedSkills.length > 0) {
+            if (!this.llmReviewer?.isAvailable()) {
+                // No LLM but we can still return cached results + record hashes
+                for (let i = 0; i < uncachedSkills.length; i++) {
+                    const skill = uncachedSkills[i];
+                    const meta = uncachedMeta[i];
+                    this.db.recordSkillHash({
+                        skillName: skill.package,
+                        contentHash: meta.contentHash,
+                        rugPullFlag: meta.rugPull,
+                    });
+                    allResults.push({
+                        package: skill.package,
+                        threatsFound: false,
+                        proposalCount: 0,
+                        patternHashes: [],
+                        status: 'skipped_no_llm',
+                        cached: false,
+                        rugPullDetected: meta.rugPull,
+                    });
+                }
+            }
+            else {
+                const llmResults = await this.llmReviewer.analyzeSkills(uncachedSkills);
+                for (let i = 0; i < llmResults.length; i++) {
+                    const r = llmResults[i];
+                    const meta = uncachedMeta[i];
+                    const verdictData = {
+                        threatsFound: r.threatsFound,
+                        proposalCount: r.proposals.length,
+                        patternHashes: r.proposals.map((p) => p.patternHash),
+                        status: r.status,
+                    };
+                    // Store in verdict cache
+                    this.db.insertVerdictCache({
+                        contentHash: meta.contentHash,
+                        skillName: r.package,
+                        verdict: JSON.stringify(verdictData),
+                    });
+                    // Record hash history
+                    this.db.recordSkillHash({
+                        skillName: r.package,
+                        contentHash: meta.contentHash,
+                        scanVerdict: JSON.stringify(verdictData),
+                        rugPullFlag: meta.rugPull,
+                    });
+                    // Rug pull HIGH alert: old was clean, new has threats
+                    if (meta.rugPull && r.threatsFound) {
+                        let prevClean = true;
+                        if (meta.previousVerdict) {
+                            try {
+                                prevClean = !JSON.parse(meta.previousVerdict)
+                                    .threatsFound;
+                            }
+                            catch {
+                                /* treat as clean if unparseable */
+                            }
+                        }
+                        if (prevClean) {
+                            log.info(`[RUG PULL CONFIRMED] ${r.package} went from clean to malicious`, {
+                                contentHash: meta.contentHash.slice(0, 12),
+                            });
+                        }
+                    }
+                    proposalsCreated += r.proposals.length;
+                    allResults.push({
+                        package: r.package,
+                        threatsFound: r.threatsFound,
+                        proposalCount: r.proposals.length,
+                        patternHashes: r.proposals.map((p) => p.patternHash),
+                        status: r.status,
+                        cached: false,
+                        rugPullDetected: meta.rugPull,
+                        ...(r.errorReason ? { errorReason: r.errorReason } : {}),
+                    });
+                }
+            }
+        }
+        const cachedCount = allResults.filter((r) => r.cached).length;
+        const rugPullCount = allResults.filter((r) => r.rugPullDetected).length;
+        log.info(`Analysis complete: ${allResults.length} skills (${cachedCount} cached, ${rugPullCount} rug pull, ${proposalsCreated} proposals)`);
         this.sendJson(res, 200, {
             ok: true,
             data: {
-                analyzed: results.length,
+                analyzed: allResults.length,
                 proposalsCreated,
-                results: results.map((r) => ({
-                    package: r.package,
-                    threatsFound: r.threatsFound,
-                    proposalCount: r.proposals.length,
-                    patternHashes: r.proposals.map((p) => p.patternHash),
-                    status: r.status,
-                    ...(r.errorReason ? { errorReason: r.errorReason } : {}),
-                })),
+                cachedCount,
+                rugPullCount,
+                results: allResults,
             },
         });
     }
@@ -1174,6 +2145,37 @@ response:
             data: { ...metrics, npmDownloads },
         });
     }
+    /**
+     * GET /api/version — public deploy verification endpoint.
+     *
+     * Reports the package version, server start time, uptime, Node version,
+     * and (if running on Railway) the Railway deployment metadata. The
+     * commit SHA is read from `RAILWAY_GIT_COMMIT_SHA` if Railway sets it,
+     * or `APP_COMMIT_SHA` if the build pipeline injects it manually.
+     *
+     * Used by external tooling and CI to verify which commit is actually
+     * running in production. Without this endpoint, deploy verification
+     * relied on inspecting Railway's dashboard, which is not scriptable.
+     *
+     * Public, no auth, no rate-limit. Cached for 30 seconds.
+     */
+    handleGetVersion(res) {
+        res.setHeader('Cache-Control', 'public, max-age=30, s-maxage=30');
+        const now = Date.now();
+        const uptimeSeconds = Math.floor((now - SERVER_START_TIME.getTime()) / 1000);
+        this.sendJson(res, 200, {
+            ok: true,
+            data: {
+                version: TC_VERSION,
+                commit: process.env['RAILWAY_GIT_COMMIT_SHA'] ?? process.env['APP_COMMIT_SHA'] ?? 'unknown',
+                deploymentId: process.env['RAILWAY_DEPLOYMENT_ID'] ?? 'unknown',
+                environment: process.env['RAILWAY_ENVIRONMENT_NAME'] ?? process.env['NODE_ENV'] ?? 'unknown',
+                startedAt: SERVER_START_TIME.toISOString(),
+                uptimeSeconds,
+                nodeVersion: process.version,
+            },
+        });
+    }
     /** GET /api/contributors - Public leaderboard (hashed IDs, no PII) */
     handleGetContributors(res) {
         res.setHeader('Cache-Control', 'public, max-age=3600, s-maxage=3600');