fullcourtdefense-cli 1.6.13 → 1.7.0

package/dist/commands/flushSpool.d.ts

@@ -0,0 +1,13 @@
+import { BotGuardConfig } from '../config';
+export interface FlushSpoolArgs {
+    apiUrl?: string;
+    shieldId?: string;
+    shieldKey?: string;
+    heartbeat?: string;
+}
+/**
+ * `fullcourtdefense flush-spool` — drain the local telemetry spool to the backend
+ * and send a heartbeat. Normally invoked detached by the hook; can also be run
+ * from cron/launchd/Task Scheduler for steady liveness on idle machines.
+ */
+export declare function flushSpoolCommand(args: FlushSpoolArgs, config: BotGuardConfig): Promise<void>;

package/dist/commands/flushSpool.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flushSpoolCommand = flushSpoolCommand;
+const config_1 = require("../config");
+const telemetry_1 = require("../telemetry");
+/**
+ * `fullcourtdefense flush-spool` — drain the local telemetry spool to the backend
+ * and send a heartbeat. Normally invoked detached by the hook; can also be run
+ * from cron/launchd/Task Scheduler for steady liveness on idle machines.
+ */
+async function flushSpoolCommand(args, config) {
+    const creds = (0, config_1.resolveCliCredentials)(config, {
+        shieldId: args.shieldId,
+        shieldKey: args.shieldKey,
+        apiUrl: args.apiUrl,
+    });
+    if (!creds.shieldId)
+        return; // nothing to attribute to
+    const result = await (0, telemetry_1.flushSpool)({
+        apiUrl: creds.apiUrl,
+        shieldId: creds.shieldId,
+        shieldKey: creds.shieldKey,
+        heartbeat: args.heartbeat !== 'false',
+    });
+    if (result) {
+        console.log(`Flushed ${result.accepted} event(s)${result.deduped ? `, ${result.deduped} deduped` : ''}.`);
+    }
+}

package/dist/commands/hook.d.ts

@@ -25,6 +25,7 @@ export interface HookArgs {
     shieldId?: string;
     shieldKey?: string;
     shadow?: string;
+    enforce?: string;
     failClosed?: string;
     timeout?: string;
     approvalMode?: string;

package/dist/commands/hook.js

@@ -38,7 +38,10 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const config_1 = require("../config");
+const runtimeConfig_1 = require("../runtimeConfig");
+const telemetry_1 = require("../telemetry");
 const deterministicGuard_1 = require("./deterministicGuard");
+const taintLedger_1 = require("./taintLedger");
 const DEBUG_LOG = path.join(os.homedir(), '.fullcourtdefense-hook.log');
 /** Append a diagnostic line so we can see exactly what Cursor invoked + the verdict. */
 function dbg(obj) {
@@ -322,7 +325,11 @@ function machineMetadata() {
     };
 }
 async function hookCommand(args, config) {
-    const shadow = args.shadow === 'true';
+    // Mode is server-authoritative (pulled from the cached runtime bundle), with
+    // local flags as explicit overrides. Resolved after creds below.
+    let shadow = args.shadow === 'true';
+    const forceMonitor = args.shadow === 'true';
+    const forceEnforce = args.enforce === 'true';
     const failClosed = args.failClosed === 'true';
     const timeoutMs = Number(args.timeout) > 0 ? Number(args.timeout) : 8000;
     const approvalMode = args.approvalMode === 'wait' ? 'wait' : 'block';
@@ -336,6 +343,24 @@ async function hookCommand(args, config) {
     const shieldId = creds.shieldId;
     const shieldKey = creds.shieldKey;
     const apiUrl = creds.apiUrl;
+    // Server-authoritative enforcement mode: the console flips shield.mode and the
+    // machine applies it on the next poll. Cached locally (stale-while-error), so
+    // this is instant when fresh and bounded (~1.5s) only when stale.
+    if (!forceMonitor && !forceEnforce && shieldId) {
+        try {
+            const bundle = await (0, runtimeConfig_1.getRuntimeBundle)({ apiUrl, shieldId, shieldKey });
+            if (bundle.source !== 'default') {
+                shadow = bundle.mode !== 'block'; // 'monitor'/'shadow' => report-only
+                dbg({ phase: 'mode_resolved', mode: bundle.mode, source: bundle.source, shadow });
+            }
+        }
+        catch { /* keep the local default */ }
+    }
+    if (forceEnforce)
+        shadow = false;
+    // Keep device liveness fresh during active use (throttled, detached — never blocks).
+    if (shieldId)
+        (0, telemetry_1.triggerFlush)(false);
     let raw = '';
     let stdinErr = '';
     const isTTY = !!process.stdin.isTTY;
@@ -400,6 +425,9 @@ async function hookCommand(args, config) {
         dbg({ phase: 'prompt_text', textLen: text.length, textPreview: text.slice(0, 300) });
         if (!text)
             respond(false);
+        // Record the developer's prompt so taint-tracking can later tell whether a
+        // sensitive action (network/git) was actually requested by the human.
+        (0, taintLedger_1.recordUserPrompt)(sessionId(payload), text);
         const localBlock = (0, deterministicGuard_1.scanDeterministicPrompt)(text);
         if (localBlock) {
             dbg({ phase: 'local_deterministic_prompt_block', event, ruleId: localBlock.ruleId, category: localBlock.category });
@@ -433,9 +461,31 @@ async function enforceActionPolicy(ctx) {
             respond(false, undefined, `[FullCourtDefense shadow] would block ${call.toolName}: ${localBlock.reason}`);
             return;
         }
+        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName: call.toolName, reason: localBlock.reason, ruleId: localBlock.ruleId, offlineEnforced: true });
+        (0, telemetry_1.triggerFlush)(true);
         respond(true, `Blocked by FullCourtDefense local guard — ${localBlock.reason}`, `FullCourtDefense blocked this ${event} locally (${localBlock.ruleId}). Do not retry.`);
         return;
     }
+    // --- Deterministic taint tracking (local, no backend) ---
+    // Evaluate the sink against the PRIOR ledger state first, BEFORE this event
+    // records its own ingress (so a lone remote pull doesn't self-taint then
+    // self-block). Reads / web / MCP output are never blocked here — only a
+    // sensitive sink the user never requested, after untrusted ingestion.
+    const sessId = sessionId(payload);
+    const taintFinding = (0, taintLedger_1.checkTaintedSink)(sessId, event, call.toolName, call.toolArgs);
+    if (taintFinding) {
+        dbg({ phase: 'local_taint_block', event, tool: call.toolName, ruleId: taintFinding.ruleId, sink: taintFinding.sink.kind, targets: taintFinding.sink.targets });
+        if (shadow) {
+            respond(false, undefined, `[FullCourtDefense shadow] would block ${call.toolName}: ${taintFinding.reason}`);
+            return;
+        }
+        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName: call.toolName, reason: taintFinding.reason, ruleId: taintFinding.ruleId, offlineEnforced: true });
+        (0, telemetry_1.triggerFlush)(true);
+        respond(true, `Blocked by FullCourtDefense taint guard — ${taintFinding.reason}`, `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} Do not retry.`);
+        return;
+    }
+    // Record untrusted ingress for this event (never blocks).
+    (0, taintLedger_1.noteIngress)(sessId, event, call.toolName, call.toolArgs);
     const headers = { 'Content-Type': 'application/json' };
     if (shieldKey)
         headers['x-shield-key'] = shieldKey;
@@ -465,6 +515,7 @@ async function enforceActionPolicy(ctx) {
         clearTimeout(timer);
         if (!resp.ok) {
             dbg({ phase: 'policy_http_error', event, status: resp.status });
+            (0, telemetry_1.spoolEvent)({ decision: 'allow', toolName: call.toolName, reason: `degraded: backend HTTP ${resp.status}`, offlineEnforced: true });
             respond(false, undefined, degradedAllowMessage(event, `Backend returned HTTP ${resp.status}.`));
             return;
         }
@@ -478,6 +529,8 @@ async function enforceActionPolicy(ctx) {
     }
     catch (err) {
         dbg({ phase: 'policy_exception', event, error: err instanceof Error ? err.message : String(err) });
+        (0, telemetry_1.spoolEvent)({ decision: 'allow', toolName: call.toolName, reason: `degraded: ${err instanceof Error ? err.message : String(err)}`, offlineEnforced: true });
+        (0, telemetry_1.triggerFlush)(false);
         respond(false, undefined, degradedAllowMessage(event, `Hook error: ${err instanceof Error ? err.message : String(err)}.`));
         return;
     }

package/dist/commands/installAll.js

@@ -33,7 +33,8 @@ async function installAllCommand(args, config) {
             shieldKey: creds.shieldKey,
             apiUrl: creds.apiUrl,
             project: args.cursorProject,
-            events: 'prompt,shell,mcp',
+            // Scope is MCP/tool actions only — prompt text never leaves the machine.
+            events: 'shell,mcp',
             failClosed: 'true',
         };
         try {

package/dist/commands/login.d.ts

@@ -0,0 +1,15 @@
+import { BotGuardConfig } from '../config';
+export interface LoginArgs {
+    /** Reusable, non-expiring fleet enrollment token (or FCD_ENROLL_TOKEN env). */
+    token?: string;
+    apiUrl?: string;
+}
+/**
+ * `fullcourtdefense login` — zero-paste machine enrollment.
+ *
+ * The machine authenticates to the org with a reusable fleet token (distributed
+ * by IT/MDM), self-enrolls under its stable machine id, and receives a dedicated
+ * per-machine Shield (monitor-first). Credentials are written to
+ * ~/.fullcourtdefense.yml so no manual copy/paste of Shield IDs/keys is needed.
+ */
+export declare function loginCommand(args: LoginArgs, config: BotGuardConfig): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loginCommand = loginCommand;
+const config_1 = require("../config");
+const machineIdentity_1 = require("../machineIdentity");
+/**
+ * `fullcourtdefense login` — zero-paste machine enrollment.
+ *
+ * The machine authenticates to the org with a reusable fleet token (distributed
+ * by IT/MDM), self-enrolls under its stable machine id, and receives a dedicated
+ * per-machine Shield (monitor-first). Credentials are written to
+ * ~/.fullcourtdefense.yml so no manual copy/paste of Shield IDs/keys is needed.
+ */
+async function loginCommand(args, config) {
+    const creds = (0, config_1.resolveCliCredentials)(config, { apiUrl: args.apiUrl });
+    const apiUrl = creds.apiUrl;
+    const token = (args.token || process.env.FCD_ENROLL_TOKEN || '').trim();
+    if (!token) {
+        throw new Error('A fleet enrollment token is required. Pass --token <token> or set FCD_ENROLL_TOKEN.\n'
+            + 'An org admin issues one from the AI Fleet console (Settings → Fleet enrollment token).');
+    }
+    const identity = (0, machineIdentity_1.getMachineIdentity)();
+    const shieldName = (0, machineIdentity_1.suggestedShieldName)(identity);
+    console.log('\x1b[1mEnrolling this machine…\x1b[0m');
+    console.log(`  Device:  ${identity.developerName}`);
+    console.log(`  OS:      ${identity.osFriendly}`);
+    console.log(`  Shield:  ${shieldName}`);
+    const resp = await fetch(`${apiUrl}/api/cli/enroll`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-fleet-token': token,
+        },
+        body: JSON.stringify({
+            machineId: identity.machineId,
+            user: identity.user,
+            hostname: identity.hostname,
+            developerName: identity.developerName,
+            osFriendly: identity.osFriendly,
+            platform: identity.platform,
+            shieldName,
+        }),
+    });
+    const data = (await resp.json().catch(() => ({})));
+    if (!resp.ok || data.success === false || !data.data) {
+        throw new Error(data.error || `Enrollment failed (HTTP ${resp.status})`);
+    }
+    const result = data.data;
+    const savedPath = (0, config_1.saveSetupConfig)({
+        organizationId: result.organizationId,
+        shieldId: result.shieldId,
+        shieldKey: result.shieldKey,
+        apiUrl,
+    });
+    console.log('');
+    console.log(`\x1b[32m✓ ${result.reused ? 'Re-enrolled' : 'Enrolled'}\x1b[0m  ${result.shieldName}`);
+    console.log(`  Mode:    ${result.mode} (monitor-first — no blocking until you enable enforcement)`);
+    console.log(`  Config:  ${savedPath}`);
+    console.log('');
+    console.log('Next: \x1b[1mfullcourtdefense install-all\x1b[0m to wrap your MCP clients and Cursor hooks.');
+}

package/dist/commands/taintLedger.d.ts

@@ -0,0 +1,58 @@
+export type TaintSourceType = 'mcp_output' | 'web_fetch' | 'external_file' | 'remote_pull';
+export interface TaintSource {
+    type: TaintSourceType;
+    detail: string;
+    at: string;
+}
+export interface TaintLedger {
+    sessionId: string;
+    tainted: boolean;
+    sources: TaintSource[];
+    userPrompts: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TaintSink {
+    kind: 'network' | 'git_push' | 'git_remote_add' | 'mcp_outbound';
+    /** External hosts/destinations referenced by the action. */
+    targets: string[];
+    detail: string;
+}
+export interface TaintFinding {
+    blocked: true;
+    ruleId: string;
+    reason: string;
+    evidence: string;
+    source: TaintSource;
+    sink: TaintSink;
+}
+/** Whether taint tracking is enabled (opt-out via env). */
+export declare function taintEnabled(): boolean;
+export declare function loadLedger(sessionId: string): TaintLedger;
+/** Record the developer's prompt text so sink actions can be checked against it. */
+export declare function recordUserPrompt(sessionId: string, text: string): void;
+/** Mark the session as having ingested untrusted content. Reading is never blocked. */
+export declare function markTaint(sessionId: string, source: TaintSource): void;
+type EventKind = 'prompt' | 'shell' | 'mcp' | 'file' | 'read' | 'unknown';
+/** Extract hostnames from any URLs / git/scp targets present in a string. */
+export declare function extractHosts(text: string): string[];
+/**
+ * Classify an event as untrusted INGRESS. Returns the source to record, or
+ * undefined if this event does not ingest untrusted content.
+ */
+export declare function classifyIngress(event: EventKind, toolName: string, toolArgs: Record<string, unknown>, workspacePath?: string): TaintSource | undefined;
+/**
+ * Detect whether an event is a SENSITIVE SINK (an action that can exfiltrate or
+ * reach attacker-controlled infrastructure). Returns sink info or undefined.
+ */
+export declare function detectSink(event: EventKind, toolName: string, toolArgs: Record<string, unknown>): TaintSink | undefined;
+/**
+ * The deterministic 3-rule check, evaluated against the CURRENT ledger state
+ * (call this BEFORE recording any ingress for the same event):
+ *
+ *   block IF  session.tainted  AND  is_sensitive_sink  AND  NOT user_authorized
+ */
+export declare function checkTaintedSink(sessionId: string, event: EventKind, toolName: string, toolArgs: Record<string, unknown>): TaintFinding | undefined;
+/** Record ingress for an event if applicable. Safe to call on every event. */
+export declare function noteIngress(sessionId: string, event: EventKind, toolName: string, toolArgs: Record<string, unknown>, workspacePath?: string): TaintSource | undefined;
+export {};

package/dist/commands/taintLedger.js

@@ -0,0 +1,370 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taintEnabled = taintEnabled;
+exports.loadLedger = loadLedger;
+exports.recordUserPrompt = recordUserPrompt;
+exports.markTaint = markTaint;
+exports.extractHosts = extractHosts;
+exports.classifyIngress = classifyIngress;
+exports.detectSink = detectSink;
+exports.checkTaintedSink = checkTaintedSink;
+exports.noteIngress = noteIngress;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Deterministic taint tracking for local IDE coding agents.
+ *
+ * Models indirect prompt injection as an information-flow problem, the same way
+ * Microsoft FIDES / Tessera / ShisaD do — but local and zero-backend. The idea:
+ *
+ *   1. INGRESS  — when the agent reads UNTRUSTED content (web fetch, MCP tool
+ *                 output, a file outside the workspace), the session is marked
+ *                 "tainted". Reading is NEVER blocked.
+ *   2. SINK     — when the agent later performs a SENSITIVE action (network
+ *                 command, git push, new remote) that the USER never asked for,
+ *                 AND the session is tainted, the action is blocked.
+ *
+ * Trust is "min-trust" (Tessera): one untrusted source drags the whole session
+ * to the floor, after which the agent may only do what the human explicitly
+ * authorized in their prompt — not what the ingested data suggests.
+ *
+ * Everything here is pure local logic over a per-session JSON file under
+ * ~/.fullcourtdefense/taint/<sessionId>.json. No model, no network call.
+ */
+const LEDGER_TTL_MS = 24 * 60 * 60 * 1000; // sessions older than 24h are pruned
+const MAX_PROMPTS = 30;
+const MAX_SOURCES = 50;
+/** Whether taint tracking is enabled (opt-out via env). */
+function taintEnabled() {
+    return process.env.FCD_TAINT_DISABLED !== 'true' && process.env.FCD_TAINT_DISABLED !== '1';
+}
+function taintDir() {
+    return path.join(os.homedir(), '.fullcourtdefense', 'taint');
+}
+function ledgerPath(sessionId) {
+    return path.join(taintDir(), `${safeSessionFile(sessionId)}.json`);
+}
+/** Make a session id safe to use as a filename. */
+function safeSessionFile(sessionId) {
+    const cleaned = sessionId.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 120);
+    return cleaned || 'default-session';
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function emptyLedger(sessionId) {
+    const ts = nowIso();
+    return { sessionId, tainted: false, sources: [], userPrompts: [], createdAt: ts, updatedAt: ts };
+}
+/** Best-effort prune of stale ledger files so old sessions don't pile up. */
+function pruneStale() {
+    try {
+        const dir = taintDir();
+        if (!fs.existsSync(dir))
+            return;
+        const cutoff = Date.now() - LEDGER_TTL_MS;
+        for (const name of fs.readdirSync(dir)) {
+            const file = path.join(dir, name);
+            try {
+                const stat = fs.statSync(file);
+                if (stat.mtimeMs < cutoff)
+                    fs.unlinkSync(file);
+            }
+            catch { /* ignore individual file errors */ }
+        }
+    }
+    catch { /* ignore */ }
+}
+function loadLedger(sessionId) {
+    const file = ledgerPath(sessionId);
+    try {
+        if (!fs.existsSync(file))
+            return emptyLedger(sessionId);
+        const stat = fs.statSync(file);
+        if (Date.now() - stat.mtimeMs > LEDGER_TTL_MS)
+            return emptyLedger(sessionId);
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return {
+            sessionId,
+            tainted: Boolean(parsed.tainted),
+            sources: Array.isArray(parsed.sources) ? parsed.sources.slice(-MAX_SOURCES) : [],
+            userPrompts: Array.isArray(parsed.userPrompts) ? parsed.userPrompts.slice(-MAX_PROMPTS) : [],
+            createdAt: typeof parsed.createdAt === 'string' ? parsed.createdAt : nowIso(),
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : nowIso(),
+        };
+    }
+    catch {
+        return emptyLedger(sessionId);
+    }
+}
+function saveLedger(ledger) {
+    try {
+        const dir = taintDir();
+        fs.mkdirSync(dir, { recursive: true });
+        ledger.updatedAt = nowIso();
+        fs.writeFileSync(ledgerPath(ledger.sessionId), JSON.stringify(ledger, null, 2), 'utf8');
+        pruneStale();
+    }
+    catch { /* best effort — never break the hook on disk errors */ }
+}
+/** Record the developer's prompt text so sink actions can be checked against it. */
+function recordUserPrompt(sessionId, text) {
+    if (!taintEnabled())
+        return;
+    const trimmed = (text || '').trim();
+    if (!trimmed)
+        return;
+    const ledger = loadLedger(sessionId);
+    ledger.userPrompts.push(trimmed.slice(0, 4000));
+    if (ledger.userPrompts.length > MAX_PROMPTS)
+        ledger.userPrompts = ledger.userPrompts.slice(-MAX_PROMPTS);
+    saveLedger(ledger);
+}
+/** Mark the session as having ingested untrusted content. Reading is never blocked. */
+function markTaint(sessionId, source) {
+    if (!taintEnabled())
+        return;
+    const ledger = loadLedger(sessionId);
+    ledger.tainted = true;
+    ledger.sources.push(source);
+    if (ledger.sources.length > MAX_SOURCES)
+        ledger.sources = ledger.sources.slice(-MAX_SOURCES);
+    saveLedger(ledger);
+}
+// ---------------------------------------------------------------------------
+// Ingress + sink classification
+// ---------------------------------------------------------------------------
+const WEB_MCP_TOOL_HINT = /(?:web|fetch|browse|browser|http|url|scrape|crawl|search|google|bing|read[_-]?page|open[_-]?url|wikipedia|news)/i;
+const NETWORK_CMD_HINT = /\b(?:curl|wget|nc|ncat|netcat|telnet|ftp|sftp|scp|ssh|socat|http|httpie|invoke-webrequest|invoke-restmethod|iwr|irm)\b/i;
+const REMOTE_PULL_HINT = /\b(?:curl|wget|git\s+clone|git\s+fetch|git\s+pull|svn\s+checkout|npx|pip\s+install|npm\s+install)\b/i;
+/** Pull every string value out of an args object (shallow-ish, bounded). */
+function collectStringValues(value, out = [], depth = 0) {
+    if (depth > 5 || value === null || value === undefined)
+        return out;
+    if (typeof value === 'string') {
+        if (value.trim())
+            out.push(value);
+        return out;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        out.push(String(value));
+        return out;
+    }
+    if (Array.isArray(value)) {
+        for (const v of value.slice(0, 40))
+            collectStringValues(v, out, depth + 1);
+        return out;
+    }
+    if (typeof value === 'object') {
+        for (const v of Object.values(value).slice(0, 60))
+            collectStringValues(v, out, depth + 1);
+    }
+    return out;
+}
+/** Extract hostnames from any URLs / git/scp targets present in a string. */
+function extractHosts(text) {
+    const hosts = new Set();
+    if (!text)
+        return [];
+    const urlRe = /\bhttps?:\/\/([^/\s'"`)]+)/gi;
+    let m;
+    while ((m = urlRe.exec(text)) !== null) {
+        const host = m[1].replace(/^.*@/, '').replace(/:.*$/, '').toLowerCase();
+        if (host)
+            hosts.add(host);
+    }
+    // git@host:path  and  scp user@host:path
+    const sshRe = /\b[\w.-]+@([\w.-]+):/g;
+    while ((m = sshRe.exec(text)) !== null) {
+        const host = m[1].toLowerCase();
+        if (host)
+            hosts.add(host);
+    }
+    return [...hosts].filter(h => !isLocalHost(h));
+}
+function isLocalHost(host) {
+    return host === 'localhost'
+        || host === '127.0.0.1'
+        || host === '::1'
+        || host === '0.0.0.0'
+        || host.endsWith('.local');
+}
+/** Strip a host to its registrable-ish tail (last two labels) for loose matching. */
+function registrableDomain(host) {
+    const parts = host.split('.').filter(Boolean);
+    if (parts.length <= 2)
+        return host;
+    return parts.slice(-2).join('.');
+}
+function workspaceRoot(workspacePath) {
+    return workspacePath || process.env.WORKSPACE_PATH || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+function isExternalFile(filePath, workspacePath) {
+    try {
+        const root = path.resolve(workspaceRoot(workspacePath));
+        const resolved = path.resolve(root, filePath);
+        const rel = path.relative(root, resolved);
+        return rel === '' ? false : (rel.startsWith('..') || path.isAbsolute(rel));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify an event as untrusted INGRESS. Returns the source to record, or
+ * undefined if this event does not ingest untrusted content.
+ */
+function classifyIngress(event, toolName, toolArgs, workspacePath) {
+    const at = nowIso();
+    if (event === 'read') {
+        const p = typeof toolArgs.path === 'string' ? toolArgs.path : '';
+        if (p && isExternalFile(p, workspacePath)) {
+            return { type: 'external_file', detail: p.slice(0, 200), at };
+        }
+        return undefined;
+    }
+    if (event === 'mcp') {
+        if (WEB_MCP_TOOL_HINT.test(toolName)) {
+            const strings = collectStringValues(toolArgs);
+            const hosts = strings.flatMap(extractHosts);
+            const detail = hosts.length ? `${toolName} -> ${hosts.join(', ')}` : toolName;
+            return { type: 'web_fetch', detail: detail.slice(0, 200), at };
+        }
+        return undefined;
+    }
+    if (event === 'shell') {
+        const command = typeof toolArgs.command === 'string' ? toolArgs.command : collectStringValues(toolArgs).join(' ');
+        if (REMOTE_PULL_HINT.test(command) && extractHosts(command).length > 0) {
+            return { type: 'remote_pull', detail: command.slice(0, 200), at };
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Detect whether an event is a SENSITIVE SINK (an action that can exfiltrate or
+ * reach attacker-controlled infrastructure). Returns sink info or undefined.
+ */
+function detectSink(event, toolName, toolArgs) {
+    if (event === 'shell') {
+        const command = typeof toolArgs.command === 'string' ? toolArgs.command : collectStringValues(toolArgs).join(' ');
+        if (/\bgit\s+remote\s+add\b/i.test(command)) {
+            return { kind: 'git_remote_add', targets: extractHosts(command), detail: command.slice(0, 200) };
+        }
+        if (/\bgit\s+push\b/i.test(command) && extractHosts(command).length > 0) {
+            return { kind: 'git_push', targets: extractHosts(command), detail: command.slice(0, 200) };
+        }
+        if (NETWORK_CMD_HINT.test(command)) {
+            const targets = extractHosts(command);
+            if (targets.length > 0)
+                return { kind: 'network', targets, detail: command.slice(0, 200) };
+        }
+        return undefined;
+    }
+    if (event === 'mcp') {
+        const outboundTool = /(?:http|fetch|request|curl|wget|webhook|upload|send|email|mail|slack|discord|teams|post|put|publish|notify|sms|message)/i.test(toolName);
+        if (!outboundTool)
+            return undefined;
+        const strings = collectStringValues(toolArgs);
+        const targets = strings.flatMap(extractHosts);
+        if (targets.length > 0)
+            return { kind: 'mcp_outbound', targets, detail: `${toolName} -> ${targets.join(', ')}`.slice(0, 200) };
+        return undefined;
+    }
+    return undefined;
+}
+/** Did the developer's prompt authorize reaching this target host? */
+function authorizedByPrompt(ledger, targets) {
+    if (targets.length === 0)
+        return true; // no external target to authorize
+    const haystack = ledger.userPrompts.join('\n').toLowerCase();
+    if (!haystack)
+        return false;
+    // Authorized only if EVERY external target the action contacts was mentioned
+    // by the user (host or its registrable domain appears in some prompt).
+    return targets.every(host => {
+        const h = host.toLowerCase();
+        return haystack.includes(h) || haystack.includes(registrableDomain(h));
+    });
+}
+/**
+ * The deterministic 3-rule check, evaluated against the CURRENT ledger state
+ * (call this BEFORE recording any ingress for the same event):
+ *
+ *   block IF  session.tainted  AND  is_sensitive_sink  AND  NOT user_authorized
+ */
+function checkTaintedSink(sessionId, event, toolName, toolArgs) {
+    if (!taintEnabled())
+        return undefined;
+    const sink = detectSink(event, toolName, toolArgs);
+    if (!sink)
+        return undefined;
+    const ledger = loadLedger(sessionId);
+    if (!ledger.tainted)
+        return undefined;
+    if (authorizedByPrompt(ledger, sink.targets))
+        return undefined;
+    const source = ledger.sources[ledger.sources.length - 1] || { type: 'mcp_output', detail: 'untrusted content', at: nowIso() };
+    const targetText = sink.targets.join(', ') || 'an external destination';
+    return {
+        blocked: true,
+        ruleId: 'local-taint-unrequested-sink',
+        reason: `Blocked ${describeSink(sink)} to ${targetText} that you did not request, after the agent `
+            + `ingested untrusted content (${source.type}: ${source.detail}). Likely indirect prompt injection.`,
+        evidence: sink.detail,
+        source,
+        sink,
+    };
+}
+function describeSink(sink) {
+    switch (sink.kind) {
+        case 'git_push': return 'a git push';
+        case 'git_remote_add': return 'a new git remote';
+        case 'mcp_outbound': return 'an outbound MCP action';
+        case 'network':
+        default: return 'a network command';
+    }
+}
+/** Record ingress for an event if applicable. Safe to call on every event. */
+function noteIngress(sessionId, event, toolName, toolArgs, workspacePath) {
+    if (!taintEnabled())
+        return undefined;
+    const source = classifyIngress(event, toolName, toolArgs, workspacePath);
+    if (source)
+        markTaint(sessionId, source);
+    return source;
+}

package/dist/index.js

@@ -40,6 +40,8 @@ const credits_1 = require("./commands/credits");
 const init_1 = require("./commands/init");
 const doctor_1 = require("./commands/doctor");
 const configure_1 = require("./commands/configure");
+const login_1 = require("./commands/login");
+const flushSpool_1 = require("./commands/flushSpool");
 const discover_1 = require("./commands/discover");
 const hook_1 = require("./commands/hook");
 const installCursorHook_1 = require("./commands/installCursorHook");
@@ -435,6 +437,24 @@ async function main() {
             await (0, configure_1.configureCommand)(args, config);
             break;
         }
+        case 'login': {
+            const args = {
+                token: flags.token || flags['enroll-token'],
+                apiUrl: flags['api-url'],
+            };
+            await (0, login_1.loginCommand)(args, config);
+            break;
+        }
+        case 'flush-spool': {
+            const args = {
+                apiUrl: flags['api-url'],
+                shieldId: flags['shield-id'],
+                shieldKey: flags['shield-key'],
+                heartbeat: flags.heartbeat,
+            };
+            await (0, flushSpool_1.flushSpoolCommand)(args, config);
+            break;
+        }
         case 'credits': {
             const args = {
                 apiKey: flags['api-key'],
@@ -488,6 +508,7 @@ async function main() {
                 shieldId: flags['shield-id'],
                 shieldKey: flags['shield-key'],
                 shadow: flags.shadow,
+                enforce: flags.enforce,
                 failClosed: flags['fail-closed'],
                 timeout: flags.timeout,
                 approvalMode: flags['approval-mode'],

package/dist/machineIdentity.d.ts

@@ -0,0 +1,23 @@
+export interface MachineIdentity {
+    /** Stable, OS-native hardware/OS id (hashed). Same value across networks + reboots. */
+    machineId: string;
+    /** Raw OS user name. */
+    user: string;
+    /** Normalized hostname (lowercased, `.local`/domain suffix stripped). */
+    hostname: string;
+    /** Human display identity, e.g. `boazl@boaz-pc`. Normalized for dedupe. */
+    developerName: string;
+    /** node platform: win32 | darwin | linux | ... */
+    platform: NodeJS.Platform;
+    /** Friendly OS label, e.g. `Windows 11`, `macOS 14`, `Ubuntu 22.04`. */
+    osFriendly: string;
+}
+/** Normalize a hostname: strip `.local`/domain suffix, lowercase. */
+export declare function normalizeHostname(raw: string): string;
+/**
+ * Compute (and cache) the stable machine identity. The raw OS id is hashed
+ * (SHA-256, 32 hex chars) so we never transmit the raw hardware UUID.
+ */
+export declare function getMachineIdentity(): MachineIdentity;
+/** Suggested per-machine Shield name, e.g. `boazl@boaz-pc · Windows 11`. */
+export declare function suggestedShieldName(identity?: MachineIdentity): string;

package/dist/machineIdentity.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeHostname = normalizeHostname;
+exports.getMachineIdentity = getMachineIdentity;
+exports.suggestedShieldName = suggestedShieldName;
+const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+/**
+ * OS-agnostic stable machine identity.
+ *
+ * The problem this solves: `os.hostname()` is unstable — macOS returns a
+ * transient Bonjour/`.local` name that changes per network, Linux hostnames are
+ * often generic (`localhost`, container ids), and Windows uppercases the name.
+ * Relying on it produces duplicate / drifting fleet entries for the SAME laptop.
+ *
+ * So we key fleet identity on an OS-native STABLE machine id:
+ *   - Windows: MachineGuid (HKLM\SOFTWARE\Microsoft\Cryptography)
+ *   - macOS:   IOPlatformUUID (ioreg)
+ *   - Linux:   /etc/machine-id (fallback /var/lib/dbus/machine-id)
+ *
+ * `username@hostname` is kept only as a human-readable display label.
+ */
+let cached;
+function safe(fn) {
+    try {
+        const value = fn();
+        return value && value.trim() ? value.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Normalize a hostname: strip `.local`/domain suffix, lowercase. */
+function normalizeHostname(raw) {
+    return raw
+        .trim()
+        .replace(/\.local$/i, '')
+        .replace(/\..*$/, '') // drop any remaining domain suffix
+        .toLowerCase() || 'unknown-host';
+}
+/** Raw OS-native stable id (UNHASHED). Internal — prefer `getMachineIdentity().machineId`. */
+function rawStableId() {
+    const platform = os.platform();
+    if (platform === 'win32') {
+        return safe(() => {
+            const out = (0, child_process_1.execFileSync)('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid'], { encoding: 'utf8', windowsHide: true, timeout: 4000 });
+            const match = out.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i);
+            return match ? match[1] : undefined;
+        });
+    }
+    if (platform === 'darwin') {
+        return safe(() => {
+            const out = (0, child_process_1.execFileSync)('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8', timeout: 4000 });
+            const match = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+            return match ? match[1] : undefined;
+        });
+    }
+    // linux + others
+    return (safe(() => fs.readFileSync('/etc/machine-id', 'utf8'))
+        || safe(() => fs.readFileSync('/var/lib/dbus/machine-id', 'utf8')));
+}
+function friendlyOs() {
+    const platform = os.platform();
+    const release = os.release();
+    if (platform === 'win32') {
+        // Windows 11 reports 10.0.22000+; 10.0.x below that is Windows 10.
+        const build = parseInt(release.split('.')[2] || '0', 10);
+        return build >= 22000 ? 'Windows 11' : 'Windows 10';
+    }
+    if (platform === 'darwin') {
+        const major = parseInt(release.split('.')[0] || '0', 10);
+        // Darwin kernel major -> macOS major (Darwin 23 => macOS 14, etc.)
+        const macMajor = major >= 20 ? major - 9 : major;
+        return macMajor > 0 ? `macOS ${macMajor}` : 'macOS';
+    }
+    if (platform === 'linux') {
+        const pretty = safe(() => {
+            const osRelease = fs.readFileSync('/etc/os-release', 'utf8');
+            const match = osRelease.match(/^PRETTY_NAME="?([^"\n]+)"?/m);
+            return match ? match[1] : undefined;
+        });
+        return pretty || 'Linux';
+    }
+    return `${platform} ${release}`;
+}
+/**
+ * Compute (and cache) the stable machine identity. The raw OS id is hashed
+ * (SHA-256, 32 hex chars) so we never transmit the raw hardware UUID.
+ */
+function getMachineIdentity() {
+    if (cached)
+        return cached;
+    const user = safe(() => os.userInfo().username) || process.env.USER || process.env.USERNAME || 'unknown-user';
+    const hostname = normalizeHostname(safe(() => os.hostname()) || 'unknown-host');
+    // Seed the hash with the OS-native id when available; fall back to a stable
+    // composite so we still produce a deterministic id on locked-down machines.
+    const raw = rawStableId() || `${hostname}|${user}|${os.platform()}|${os.arch()}`;
+    const machineId = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 32);
+    cached = {
+        machineId,
+        user,
+        hostname,
+        developerName: `${user.toLowerCase()}@${hostname}`,
+        platform: os.platform(),
+        osFriendly: friendlyOs(),
+    };
+    return cached;
+}
+/** Suggested per-machine Shield name, e.g. `boazl@boaz-pc · Windows 11`. */
+function suggestedShieldName(identity = getMachineIdentity()) {
+    return `${identity.developerName} · ${identity.osFriendly}`;
+}

package/dist/runtimeConfig.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Server-authoritative enforcement mode + policy version, pulled from
+ * GET /api/cli/bundle and cached locally so the hot path (the Cursor hook) never
+ * blocks on the network for the mode decision.
+ *
+ * Behavior:
+ *   - Fresh cache (< TTL): return immediately, no network.
+ *   - Stale cache: try a SHORT-timeout refresh; on success update + return; on
+ *     failure fall back to the last cached value (stale-while-error / fail-static).
+ *   - No cache + network fails: return source 'default' so the caller applies its
+ *     local fallback (the install-time flag).
+ *
+ * A console "Enforce" click flips shield.mode server-side; the machine picks it up
+ * on the next refresh (no push to the machine required).
+ */
+export type ShieldMode = 'block' | 'monitor' | 'shadow';
+export interface RuntimeBundle {
+    mode: ShieldMode;
+    version: string;
+    policyCount?: number;
+    pollIntervalMs?: number;
+}
+export interface FetchBundleInput {
+    apiUrl: string;
+    shieldId: string;
+    shieldKey?: string;
+    /** Override cache TTL (ms). */
+    ttlMs?: number;
+    /** Force a network refresh regardless of cache freshness. */
+    force?: boolean;
+}
+export interface EffectiveBundle extends RuntimeBundle {
+    source: 'server' | 'cache' | 'default';
+}
+/**
+ * Resolve the effective runtime bundle for a Shield, using the local cache when
+ * fresh and refreshing (briefly) when stale. Never throws — falls back to cache
+ * or a 'default' marker so the caller can apply its local fallback.
+ */
+export declare function getRuntimeBundle(input: FetchBundleInput): Promise<EffectiveBundle>;

package/dist/runtimeConfig.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRuntimeBundle = getRuntimeBundle;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const CACHE_PATH = path.join(os.homedir(), '.fullcourtdefense-runtime.json');
+const DEFAULT_TTL_MS = 60_000;
+const REFRESH_TIMEOUT_MS = 1_500; // tight: the hook must stay fast
+function readCacheFile() {
+    try {
+        const raw = fs.readFileSync(CACHE_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeCacheFile(data) {
+    try {
+        fs.writeFileSync(CACHE_PATH, JSON.stringify(data), { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch { /* cache is best-effort */ }
+}
+function isMode(value) {
+    return value === 'block' || value === 'monitor' || value === 'shadow';
+}
+/**
+ * Resolve the effective runtime bundle for a Shield, using the local cache when
+ * fresh and refreshing (briefly) when stale. Never throws — falls back to cache
+ * or a 'default' marker so the caller can apply its local fallback.
+ */
+async function getRuntimeBundle(input) {
+    const ttl = input.ttlMs ?? DEFAULT_TTL_MS;
+    const cache = readCacheFile();
+    const cached = cache[input.shieldId];
+    const fresh = cached && Date.now() - cached.fetchedAt < ttl;
+    if (cached && fresh && !input.force) {
+        return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+    }
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (input.shieldKey)
+            headers['x-shield-key'] = input.shieldKey;
+        if (cached?.version)
+            headers['If-None-Match'] = cached.version;
+        const resp = await fetch(`${input.apiUrl}/api/cli/bundle?shieldId=${encodeURIComponent(input.shieldId)}`, { method: 'GET', headers, signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS) });
+        // 304 Not Modified — cache is still valid; refresh its timestamp.
+        if (resp.status === 304 && cached) {
+            cache[input.shieldId] = { ...cached, fetchedAt: Date.now() };
+            writeCacheFile(cache);
+            return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+        }
+        if (resp.ok) {
+            const body = await resp.json().catch(() => ({}));
+            if (body.success && body.data && isMode(body.data.mode)) {
+                const entry = {
+                    mode: body.data.mode,
+                    version: body.data.version,
+                    policyCount: body.data.policyCount,
+                    pollIntervalMs: body.data.pollIntervalMs,
+                    fetchedAt: Date.now(),
+                };
+                cache[input.shieldId] = entry;
+                writeCacheFile(cache);
+                return { ...entry, source: 'server' };
+            }
+        }
+    }
+    catch { /* fall through to cache / default */ }
+    if (cached) {
+        return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+    }
+    return { mode: 'block', version: '', source: 'default' };
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,36 @@
+export interface SpoolEvent {
+    eventId: string;
+    type: 'verdict';
+    decision: 'allow' | 'block' | 'approval' | 'mask';
+    toolName?: string;
+    operation?: string;
+    reason?: string;
+    ruleId?: string;
+    /** True when this decision was enforced locally while the backend was unreachable. */
+    offlineEnforced?: boolean;
+    occurredAt: string;
+}
+/** Append one decision to the spool. Never throws (telemetry must not break the hook). */
+export declare function spoolEvent(event: Omit<SpoolEvent, 'eventId' | 'occurredAt' | 'type'> & Partial<Pick<SpoolEvent, 'occurredAt' | 'type'>>): void;
+export interface FlushInput {
+    apiUrl: string;
+    shieldId: string;
+    shieldKey?: string;
+    /** Include a heartbeat in this flush (drives device liveness). */
+    heartbeat?: boolean;
+    agentVersion?: string;
+    /** Whether protection points still look intact (tamper signal). */
+    integrityOk?: boolean;
+    timeoutMs?: number;
+}
+/** Drain the spool to the backend in one batch (+ optional heartbeat). Returns accepted count. */
+export declare function flushSpool(input: FlushInput): Promise<{
+    accepted: number;
+    deduped: number;
+} | null>;
+/**
+ * Opportunistically spawn a DETACHED flusher so the hot path (hook) never blocks
+ * on network I/O. Throttled via a marker file. `immediate` bypasses the throttle
+ * (used for critical blocks). The child reads creds from ~/.fullcourtdefense.yml.
+ */
+export declare function triggerFlush(immediate?: boolean): void;

package/dist/telemetry.js

@@ -0,0 +1,170 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spoolEvent = spoolEvent;
+exports.flushSpool = flushSpool;
+exports.triggerFlush = triggerFlush;
+const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const machineIdentity_1 = require("./machineIdentity");
+/**
+ * Local-first telemetry: every enforcement decision is appended to an on-disk
+ * spool (instant, offline-safe) and flushed to the backend in batches. Critical
+ * blocks trigger an immediate (detached) flush; everything else drains on the
+ * next opportunistic/heartbeat flush. Decisions enforced while the backend was
+ * unreachable are tagged `offlineEnforced` and replayed (idempotent on eventId)
+ * when connectivity returns.
+ */
+const SPOOL_PATH = path.join(os.homedir(), '.fullcourtdefense-spool.jsonl');
+const FLUSH_MARKER = path.join(os.homedir(), '.fullcourtdefense-flush.ts');
+const FLUSH_THROTTLE_MS = 30_000; // don't spawn a flusher more than this often
+const MAX_BATCH = 200;
+/** Append one decision to the spool. Never throws (telemetry must not break the hook). */
+function spoolEvent(event) {
+    try {
+        const full = {
+            eventId: crypto.randomUUID(),
+            occurredAt: event.occurredAt || new Date().toISOString(),
+            type: 'verdict',
+            decision: event.decision,
+            toolName: event.toolName,
+            operation: event.operation,
+            reason: event.reason,
+            ruleId: event.ruleId,
+            offlineEnforced: event.offlineEnforced,
+        };
+        fs.appendFileSync(SPOOL_PATH, JSON.stringify(full) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch { /* best-effort */ }
+}
+function readSpool() {
+    try {
+        const raw = fs.readFileSync(SPOOL_PATH, 'utf-8');
+        return raw.split('\n').map(l => l.trim()).filter(Boolean).map(l => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        }).filter((e) => !!e && !!e.eventId);
+    }
+    catch {
+        return [];
+    }
+}
+function rewriteSpool(remaining) {
+    try {
+        if (remaining.length === 0) {
+            if (fs.existsSync(SPOOL_PATH))
+                fs.unlinkSync(SPOOL_PATH);
+            return;
+        }
+        fs.writeFileSync(SPOOL_PATH, remaining.map(e => JSON.stringify(e)).join('\n') + '\n', { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch { /* best-effort */ }
+}
+/** Drain the spool to the backend in one batch (+ optional heartbeat). Returns accepted count. */
+async function flushSpool(input) {
+    const all = readSpool();
+    const batch = all.slice(0, MAX_BATCH);
+    const overflow = all.slice(MAX_BATCH);
+    if (batch.length === 0 && !input.heartbeat)
+        return null;
+    const identity = (0, machineIdentity_1.getMachineIdentity)();
+    const headers = { 'Content-Type': 'application/json' };
+    if (input.shieldKey)
+        headers['x-shield-key'] = input.shieldKey;
+    try {
+        const resp = await fetch(`${input.apiUrl}/api/cli/events:batch`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                shieldId: input.shieldId,
+                machineId: identity.machineId,
+                heartbeat: input.heartbeat
+                    ? { agentVersion: input.agentVersion, integrityOk: input.integrityOk, coverage: 'hooks' }
+                    : undefined,
+                events: batch,
+            }),
+            signal: AbortSignal.timeout(input.timeoutMs ?? 8000),
+        });
+        if (!resp.ok)
+            return null;
+        const body = await resp.json().catch(() => ({}));
+        if (!body.success)
+            return null;
+        // Successfully delivered → drop the flushed events, keep any overflow.
+        rewriteSpool(overflow);
+        return body.data || { accepted: batch.length, deduped: 0 };
+    }
+    catch {
+        return null; // keep the spool intact for the next attempt (offline-safe)
+    }
+}
+/**
+ * Opportunistically spawn a DETACHED flusher so the hot path (hook) never blocks
+ * on network I/O. Throttled via a marker file. `immediate` bypasses the throttle
+ * (used for critical blocks). The child reads creds from ~/.fullcourtdefense.yml.
+ */
+function triggerFlush(immediate = false) {
+    try {
+        if (!immediate) {
+            try {
+                const last = Number(fs.readFileSync(FLUSH_MARKER, 'utf-8'));
+                if (Number.isFinite(last) && Date.now() - last < FLUSH_THROTTLE_MS)
+                    return;
+            }
+            catch { /* no marker yet */ }
+        }
+        try {
+            fs.writeFileSync(FLUSH_MARKER, String(Date.now()), 'utf-8');
+        }
+        catch { /* ignore */ }
+        const entry = process.argv[1];
+        if (!entry)
+            return;
+        const child = (0, child_process_1.spawn)(process.execPath, [entry, 'flush-spool', '--heartbeat', 'true'], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.unref();
+    }
+    catch { /* best-effort */ }
+}

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.6.13"
+  "version": "1.7.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.6.13",
+  "version": "1.7.0",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {
@@ -15,6 +15,7 @@
   "scripts": {
     "build": "tsc && node scripts/copy-attack-corpus.js",
     "test:deterministic-guard": "npm run build && node scripts/test-deterministic-guard.js",
+    "test:taint-ledger": "npm run build && node scripts/test-taint-ledger.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [