fullcourtdefense-cli 1.0.2 → 1.1.0

package/dist/commands/hook.js

@@ -0,0 +1,312 @@
+"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.hookCommand = hookCommand;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const DEFAULT_API_URL = 'https://api.fullcourtdefense.ai';
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        const stdin = process.stdin;
+        if (stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        stdin.setEncoding('utf8');
+        stdin.on('data', (chunk) => { data += chunk; });
+        stdin.on('end', () => resolve(data));
+        stdin.on('error', () => resolve(data));
+        // Safety: if nothing arrives, don't hang forever.
+        setTimeout(() => resolve(data), 2000).unref?.();
+    });
+}
+/** Load ~/.fullcourtdefense.yml (machine-wide creds) as a fallback to project config. */
+function loadHomeShield() {
+    try {
+        const candidates = ['.fullcourtdefense.yml', '.fullcourtdefense.yaml'];
+        for (const name of candidates) {
+            const p = path.join(os.homedir(), name);
+            if (!fs.existsSync(p))
+                continue;
+            const text = fs.readFileSync(p, 'utf8');
+            const pick = (key) => {
+                const m = text.match(new RegExp(`^\\s*${key}\\s*:\\s*(.+)\\s*$`, 'm'));
+                if (!m)
+                    return undefined;
+                return m[1].replace(/^["']|["']$/g, '').trim() || undefined;
+            };
+            return { shieldId: pick('shieldId'), shieldKey: pick('shieldKey'), apiUrl: pick('apiUrl') };
+        }
+    }
+    catch { /* ignore */ }
+    return {};
+}
+function inferEvent(explicit, payload) {
+    const e = (explicit || '').toLowerCase();
+    if (e) {
+        if (e.startsWith('prompt'))
+            return 'prompt';
+        if (e.startsWith('shell'))
+            return 'shell';
+        if (e.startsWith('mcp'))
+            return 'mcp';
+        if (e.startsWith('file') || e === 'edit')
+            return 'file';
+        if (e.startsWith('read'))
+            return 'read';
+    }
+    if (typeof payload.command === 'string')
+        return 'shell';
+    if (payload.tool_name || payload.toolName || payload.tool_input || payload.arguments)
+        return 'mcp';
+    if (payload.prompt || payload.text || payload.message)
+        return 'prompt';
+    if (payload.edits || payload.file_path || payload.path)
+        return 'file';
+    return 'unknown';
+}
+/** Pull the meaningful text to scan out of a Cursor hook payload, per event. */
+function extractText(event, p) {
+    const str = (v) => (typeof v === 'string' ? v : '');
+    switch (event) {
+        case 'prompt': {
+            const direct = str(p.prompt) || str(p.text) || str(p.message) || str(p.content);
+            if (direct)
+                return direct;
+            // Some shapes nest the prompt or send a messages array.
+            const promptObj = p.prompt;
+            if (promptObj && typeof promptObj === 'object') {
+                const t = str(promptObj.text) || str(promptObj.content);
+                if (t)
+                    return t;
+            }
+            const messages = p.messages;
+            if (Array.isArray(messages) && messages.length) {
+                const last = messages[messages.length - 1];
+                return str(last?.content) || str(last?.text);
+            }
+            return '';
+        }
+        case 'shell':
+            return str(p.command) || str(p.cmd);
+        case 'mcp': {
+            const name = str(p.tool_name) || str(p.toolName) || str(p.name);
+            const input = p.tool_input ?? p.arguments ?? p.input ?? p.params;
+            const inputStr = typeof input === 'string' ? input : input ? safeJson(input) : '';
+            return [name, inputStr].filter(Boolean).join(': ');
+        }
+        case 'file': {
+            const edits = p.edits;
+            if (Array.isArray(edits)) {
+                return edits.map((e) => str(e.new_text) || str(e.text) || str(e.content)).filter(Boolean).join('\n');
+            }
+            return str(p.content) || str(p.new_text) || '';
+        }
+        case 'read':
+            return str(p.file_path) || str(p.path) || '';
+        default:
+            return str(p.prompt) || str(p.text) || str(p.message) || str(p.command) || '';
+    }
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/** Per-event attribution that maps onto the existing Shield runtime headers. */
+function attributionFor(event, p) {
+    const h = {};
+    const set = (k, v) => { if (v)
+        h[k] = v; };
+    switch (event) {
+        case 'prompt':
+            set('x-input-source', 'user');
+            set('x-runtime-event-type', 'user_message');
+            set('x-runtime-trust', 'trusted_user');
+            break;
+        case 'shell':
+            set('x-input-source', 'tool');
+            set('x-runtime-event-type', 'action_request');
+            set('x-action-type', 'shell');
+            set('x-runtime-sink', 'execute');
+            set('x-runtime-trust', 'untrusted');
+            break;
+        case 'mcp':
+            set('x-input-source', 'tool');
+            set('x-runtime-event-type', 'tool_call');
+            set('x-tool-name', String(p.tool_name || p.toolName || p.name || 'mcp'));
+            set('x-runtime-trust', 'untrusted');
+            break;
+        case 'file':
+            set('x-input-source', 'generated');
+            set('x-runtime-event-type', 'memory_write');
+            break;
+        case 'read':
+            set('x-input-source', 'tool');
+            set('x-runtime-event-type', 'memory_read');
+            break;
+        default:
+            set('x-input-source', 'user');
+    }
+    return h;
+}
+/** Stable developer identity, used for per-developer attribution on shield events. */
+function developerId() {
+    if (process.env.FULLCOURTDEFENSE_DEVELOPER_ID)
+        return process.env.FULLCOURTDEFENSE_DEVELOPER_ID;
+    try {
+        const u = os.userInfo().username;
+        return `${u}@${os.hostname()}`;
+    }
+    catch {
+        return 'unknown-developer';
+    }
+}
+/** Cursor conversation/session id when present, else a stable per-machine id. */
+function sessionId(p) {
+    const fromPayload = p.conversation_id || p.conversationId || p.session_id || p.sessionId;
+    if (typeof fromPayload === 'string' && fromPayload)
+        return fromPayload;
+    return `cursor-${os.hostname()}`;
+}
+function emit(decision, blocked) {
+    process.stdout.write(JSON.stringify(decision));
+    // Exit 2 is the universal "block" signal across all hook events.
+    process.exit(blocked ? 2 : 0);
+}
+async function hookCommand(args, config) {
+    const shadow = args.shadow === 'true';
+    const failClosed = args.failClosed === 'true';
+    const timeoutMs = Number(args.timeout) > 0 ? Number(args.timeout) : 8000;
+    const home = loadHomeShield();
+    const shieldId = args.shieldId || process.env.FULLCOURTDEFENSE_SHIELD_ID || config.shieldId || home.shieldId;
+    const shieldKey = args.shieldKey || process.env.FULLCOURTDEFENSE_SHIELD_KEY || config.shieldKey || home.shieldKey;
+    const apiUrl = (args.apiUrl || process.env.FULLCOURTDEFENSE_API_URL || config.apiUrl || home.apiUrl || DEFAULT_API_URL)
+        .replace(/\/$/, '');
+    let raw = '';
+    try {
+        raw = await readStdin();
+    }
+    catch { /* ignore */ }
+    let payload = {};
+    if (raw.trim()) {
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            payload = {};
+        }
+    }
+    const event = inferEvent(args.event, payload);
+    const text = extractText(event, payload).trim();
+    // Nothing to scan, or no Shield configured → allow (fail-open by design here:
+    // a misconfigured machine must not brick the developer's IDE).
+    if (!text)
+        emit({ permission: 'allow' }, false);
+    if (!shieldId) {
+        emit({
+            permission: 'allow',
+            agent_message: 'FullCourtDefense hook installed but no Shield ID configured (run `fullcourtdefense configure`).',
+        }, false);
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        // Behaves exactly like a normal Shield agent calling the public proxy:
+        // Shield key + runtime/developer attribution headers, body { message }.
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-runtime-source-id': developerId(),
+            'x-developer-id': developerId(),
+            'x-session-id': sessionId(payload),
+            ...attributionFor(event, payload),
+        };
+        if (shieldKey)
+            headers['x-shield-key'] = shieldKey;
+        const resp = await fetch(`${apiUrl}/api/shield/proxy/${shieldId}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ message: text }),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!resp.ok) {
+            // Backend rejected (quota, bad shield, etc.) — fail open unless told otherwise.
+            const blocked = failClosed;
+            emit({
+                permission: blocked ? 'deny' : 'allow',
+                user_message: blocked ? `FullCourtDefense gate unavailable (HTTP ${resp.status}) — blocked by fail-closed policy.` : undefined,
+                agent_message: `FullCourtDefense gate returned HTTP ${resp.status}.`,
+            }, blocked);
+        }
+        const data = await resp.json().catch(() => ({}));
+        const sh = (data._shield || {});
+        const action = String(sh.action || '');
+        // Proxy returns 'blocked_input' / 'blocked_output' when it blocks; in monitor
+        // mode it returns 'allowed' (never block, even if wouldBlock is set).
+        const isBlocked = action.startsWith('blocked');
+        const reason = String(sh.reason || 'policy_violation');
+        const explanation = String(sh.reason || 'Flagged by FullCourtDefense.');
+        if (!isBlocked) {
+            emit({ permission: 'allow' }, false);
+        }
+        // Blocked verdict. In shadow mode we annotate but let it through.
+        if (shadow) {
+            emit({
+                permission: 'allow',
+                agent_message: `[FullCourtDefense shadow] would block ${event} (${reason}): ${explanation}`,
+            }, false);
+        }
+        emit({
+            permission: 'deny',
+            user_message: `Blocked by FullCourtDefense — ${reason}. ${explanation}`,
+            agent_message: `FullCourtDefense blocked this ${event} as "${reason}". Do not retry; revise to remove the flagged content.`,
+        }, true);
+    }
+    catch (err) {
+        // Network error / timeout.
+        const blocked = failClosed;
+        emit({
+            permission: blocked ? 'deny' : 'allow',
+            user_message: blocked ? 'FullCourtDefense gate unreachable — blocked by fail-closed policy.' : undefined,
+            agent_message: `FullCourtDefense hook error: ${err instanceof Error ? err.message : String(err)}.`,
+        }, blocked);
+    }
+}

package/dist/commands/init.js

@@ -68,20 +68,20 @@ async function initCommand() {
     const categories = categoriesRaw === 'all'
         ? '[jailbreak, prompt_injection, data_extraction, role_manipulation, encoding_attack, social_engineering]'
         : `[${categoriesRaw}]`;
-    const content = `# FullCourtDefense CLI Configuration
-# Docs: https://fullcourtdefense.ai/docs/cli
-
-apiKey: \${BOTGUARD_API_KEY}
-apiUrl: https://api.fullcourtdefense.ai
-shieldId: ${shieldId}
-${shieldKey ? `shieldKey: ${shieldKey}\n` : ''}
-
-scan:
-  endpoint: ${endpoint}
-  description: "${description}"
-  categories: ${categories}
-  failThreshold: ${threshold}
-  format: table
+    const content = `# FullCourtDefense CLI Configuration
+# Docs: https://fullcourtdefense.ai/docs/cli
+
+apiKey: \${FULLCOURTDEFENSE_API_KEY}
+apiUrl: https://api.fullcourtdefense.ai
+shieldId: ${shieldId}
+${shieldKey ? `shieldKey: ${shieldKey}\n` : ''}
+
+scan:
+  endpoint: ${endpoint}
+  description: "${description}"
+  categories: ${categories}
+  failThreshold: ${threshold}
+  format: table
 `;
     fs.writeFileSync(target, content, 'utf-8');
     console.log('');

package/dist/commands/installCursorHook.d.ts

@@ -0,0 +1,12 @@
+import { BotGuardConfig } from '../config';
+export interface InstallHookArgs {
+    project?: string;
+    shieldId?: string;
+    shieldKey?: string;
+    apiUrl?: string;
+    shadow?: string;
+    failClosed?: string;
+    events?: string;
+}
+export declare function installCursorHookCommand(args: InstallHookArgs, config: BotGuardConfig): Promise<void>;
+export declare function uninstallCursorHookCommand(args: InstallHookArgs): Promise<void>;

package/dist/commands/installCursorHook.js

@@ -0,0 +1,186 @@
+"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.installCursorHookCommand = installCursorHookCommand;
+exports.uninstallCursorHookCommand = uninstallCursorHookCommand;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const COLOR = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[31m', yellow: '\x1b[33m', green: '\x1b[32m', cyan: '\x1b[36m', gray: '\x1b[90m',
+};
+// Stable marker embedded in every command we write, so uninstall/re-install can
+// find our entries regardless of the install path (npm global vs local dev).
+const MANAGED_MARKER = '--fcd-managed true';
+const MANAGED_TAG = 'fullcourtdefense';
+const EVENT_MAP = {
+    prompt: { hookKey: 'beforeSubmitPrompt', flag: 'prompt', failClosedDefault: false },
+    shell: { hookKey: 'beforeShellExecution', flag: 'shell', failClosedDefault: true },
+    mcp: { hookKey: 'beforeMCPExecution', flag: 'mcp', failClosedDefault: true },
+    file: { hookKey: 'afterFileEdit', flag: 'file', failClosedDefault: false },
+    read: { hookKey: 'beforeReadFile', flag: 'read', failClosedDefault: false },
+};
+/** Build the absolute, shell-agnostic command that invokes this CLI's `hook`. */
+function buildHookCommand(flag, opts) {
+    const nodeExe = process.execPath; // real node binary (handles Windows/Linux/mac)
+    const scriptPath = process.argv[1] || path.join(__dirname, '..', 'index.js');
+    const q = (s) => (/\s/.test(s) ? `"${s}"` : s);
+    let cmd = `${q(nodeExe)} ${q(scriptPath)} hook --event ${flag}`;
+    if (opts.shadow)
+        cmd += ' --shadow true';
+    if (opts.failClosed)
+        cmd += ' --fail-closed true';
+    cmd += ` ${MANAGED_MARKER}`;
+    return cmd;
+}
+function hooksJsonPath(projectScope) {
+    return projectScope
+        ? path.join(process.cwd(), '.cursor', 'hooks.json')
+        : path.join(os.homedir(), '.cursor', 'hooks.json');
+}
+function readHooksJson(file) {
+    if (!fs.existsSync(file))
+        return { version: 1, hooks: {} };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return { version: 1, hooks: {} };
+        parsed.version = parsed.version || 1;
+        parsed.hooks = parsed.hooks && typeof parsed.hooks === 'object' ? parsed.hooks : {};
+        return parsed;
+    }
+    catch {
+        return { version: 1, hooks: {} };
+    }
+}
+function isManaged(entry) {
+    return typeof entry?.command === 'string'
+        && (entry.command.includes(MANAGED_MARKER) || entry.command.includes(MANAGED_TAG));
+}
+/** Save the home-level Shield credentials so the hook can find them machine-wide. */
+function writeHomeShield(input) {
+    if (!input.shieldId && !input.shieldKey && !input.apiUrl)
+        return undefined;
+    const target = path.join(os.homedir(), '.fullcourtdefense.yml');
+    const existing = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '# FullCourtDefense CLI Configuration\n';
+    const lines = existing.split(/\r?\n/);
+    const setKey = (key, value) => {
+        if (!value)
+            return;
+        const idx = lines.findIndex((l) => new RegExp(`^\\s*${key}\\s*:`).test(l));
+        const next = `${key}: ${value}`;
+        if (idx >= 0)
+            lines[idx] = next;
+        else
+            lines.push(next);
+    };
+    setKey('shieldId', input.shieldId);
+    setKey('shieldKey', input.shieldKey);
+    setKey('apiUrl', input.apiUrl);
+    fs.writeFileSync(target, lines.filter((l, i, a) => !(l === '' && a[i - 1] === '')).join('\n').trim() + '\n', 'utf8');
+    return target;
+}
+async function installCursorHookCommand(args, config) {
+    const projectScope = args.project === 'true';
+    const shadow = args.shadow === 'true';
+    const file = hooksJsonPath(projectScope);
+    const requested = (args.events || 'prompt,shell,mcp')
+        .split(',').map((e) => e.trim().toLowerCase()).filter(Boolean);
+    const events = requested.filter((e) => EVENT_MAP[e]);
+    if (events.length === 0) {
+        console.error(`${COLOR.red}No valid events. Choose from: ${Object.keys(EVENT_MAP).join(', ')}${COLOR.reset}`);
+        process.exit(1);
+    }
+    // Persist creds machine-wide (home) so the runtime hook resolves them.
+    const shieldId = args.shieldId || config.shieldId;
+    const shieldKey = args.shieldKey || config.shieldKey;
+    const apiUrl = args.apiUrl || config.apiUrl;
+    const credFile = writeHomeShield({ shieldId, shieldKey, apiUrl });
+    const json = readHooksJson(file);
+    for (const e of events) {
+        const { hookKey, flag, failClosedDefault } = EVENT_MAP[e];
+        const failClosed = args.failClosed !== undefined ? args.failClosed === 'true' : failClosedDefault;
+        const entry = {
+            command: buildHookCommand(flag, { shadow, failClosed }),
+            timeout: 10,
+        };
+        if (failClosed)
+            entry.failClosed = true;
+        const list = Array.isArray(json.hooks[hookKey]) ? json.hooks[hookKey] : [];
+        // Replace any prior FullCourtDefense-managed entry; preserve the user's other hooks.
+        const preserved = list.filter((x) => !isManaged(x));
+        json.hooks[hookKey] = [...preserved, entry];
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(json, null, 2) + '\n', 'utf8');
+    console.log('');
+    console.log(`${COLOR.green}${COLOR.bold}FullCourtDefense Cursor hook installed.${COLOR.reset}`);
+    console.log(`${COLOR.gray}Scope:${COLOR.reset} ${projectScope ? 'project (.cursor/hooks.json)' : 'machine-wide (~/.cursor/hooks.json)'}`);
+    console.log(`${COLOR.gray}File:${COLOR.reset}  ${file}`);
+    console.log(`${COLOR.gray}Events:${COLOR.reset} ${events.map((e) => EVENT_MAP[e].hookKey).join(', ')}`);
+    if (shadow)
+        console.log(`${COLOR.yellow}Mode: SHADOW (monitor only — nothing is blocked).${COLOR.reset}`);
+    if (credFile)
+        console.log(`${COLOR.gray}Creds:${COLOR.reset} ${credFile}`);
+    if (!shieldId) {
+        console.log('');
+        console.log(`${COLOR.yellow}No Shield ID set.${COLOR.reset} Run ${COLOR.bold}fullcourtdefense configure${COLOR.reset} or pass ${COLOR.bold}--shield-id${COLOR.reset}, then re-run install.`);
+    }
+    console.log('');
+    console.log(`${COLOR.gray}Restart Cursor (or it will hot-reload hooks.json). Verify in Cursor → Settings → Hooks.${COLOR.reset}`);
+    console.log(`${COLOR.gray}Remove with:${COLOR.reset} fullcourtdefense uninstall-cursor-hook${projectScope ? ' --project true' : ''}`);
+}
+async function uninstallCursorHookCommand(args) {
+    const projectScope = args.project === 'true';
+    const file = hooksJsonPath(projectScope);
+    if (!fs.existsSync(file)) {
+        console.log(`${COLOR.yellow}No hooks.json found at ${file}. Nothing to remove.${COLOR.reset}`);
+        return;
+    }
+    const json = readHooksJson(file);
+    let removed = 0;
+    for (const key of Object.keys(json.hooks)) {
+        const list = Array.isArray(json.hooks[key]) ? json.hooks[key] : [];
+        const kept = list.filter((x) => !isManaged(x));
+        removed += list.length - kept.length;
+        if (kept.length)
+            json.hooks[key] = kept;
+        else
+            delete json.hooks[key];
+    }
+    fs.writeFileSync(file, JSON.stringify(json, null, 2) + '\n', 'utf8');
+    console.log(`${COLOR.green}Removed ${removed} FullCourtDefense hook entr${removed === 1 ? 'y' : 'ies'} from ${file}.${COLOR.reset}`);
+}

package/dist/commands/local-scan.d.ts

@@ -37,5 +37,8 @@ export interface LocalScanArgs {
     configShieldKey?: string;
     configApiUrl?: string;
     apiUrl?: string;
+    open?: string;
+    noOpen?: string;
+    openUi?: string;
 }
 export declare function localScanCommand(args: LocalScanArgs): Promise<void>;