@oculisecurity/cli 0.1.0

package/dist/routes/adapters/index.js

@@ -0,0 +1,56 @@
+"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.detectAdapter = detectAdapter;
+const ClaudeCode = __importStar(require("./claude-code"));
+const Cursor = __importStar(require("./cursor"));
+const Windsurf = __importStar(require("./windsurf"));
+// Order matters: most specific first to avoid false positives
+const ADAPTERS = [
+    ClaudeCode,
+    Cursor,
+    Windsurf,
+];
+/**
+ * Find the first adapter that recognises the given payload.
+ * Returns null if no adapter matches (unknown source).
+ */
+function detectAdapter(body) {
+    for (const adapter of ADAPTERS) {
+        if (adapter.detect(body))
+            return adapter;
+    }
+    return null;
+}

package/dist/routes/adapters/router.d.ts

@@ -0,0 +1,31 @@
+import { OculiEvent } from './schema';
+import { HookAdapter } from './index';
+export interface RouteResult {
+    /** Canonical adapter name ('claude-code', 'cursor', 'windsurf'). */
+    adapterName: string;
+    /** The adapter that handled this payload. */
+    adapter: HookAdapter;
+    /** Normalised event — the only thing the policy engine and telemetry see. */
+    event: OculiEvent;
+}
+/**
+ * Route a parsed hook payload to the correct adapter.
+ *
+ * Priority:
+ *   1. Explicit — if `explicit` names a known adapter, use it immediately
+ *      without inspecting the payload.  Zero detection overhead, deterministic.
+ *   2. Auto-detect — iterate the registry until an adapter's detect() matches.
+ *
+ * Returns null when no adapter matches.
+ */
+export declare function route(body: Record<string, unknown>, explicit?: string): RouteResult | null;
+/**
+ * Route a raw JSON string (hook stdin) to the correct adapter.
+ * Parses stdin and delegates to route().
+ *
+ * @param stdin         Raw JSON string from the IDE hook.
+ * @param explicitName  Optional adapter name — skips auto-detection when provided.
+ */
+export declare function routeStdin(stdin: string, explicitName?: string): RouteResult | null;
+/** Returns the canonical names of all registered adapters. */
+export declare function registeredAdapters(): string[];

package/dist/routes/adapters/router.js

@@ -0,0 +1,97 @@
+"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.route = route;
+exports.routeStdin = routeStdin;
+exports.registeredAdapters = registeredAdapters;
+const ClaudeCode = __importStar(require("./claude-code"));
+const Cursor = __importStar(require("./cursor"));
+const Windsurf = __importStar(require("./windsurf"));
+/**
+ * Central adapter registry.
+ * Add new IDE adapters here — nothing else needs to change.
+ */
+const ADAPTER_REGISTRY = {
+    'claude-code': ClaudeCode,
+    'cursor': Cursor,
+    'windsurf': Windsurf,
+};
+/**
+ * Route a parsed hook payload to the correct adapter.
+ *
+ * Priority:
+ *   1. Explicit — if `explicit` names a known adapter, use it immediately
+ *      without inspecting the payload.  Zero detection overhead, deterministic.
+ *   2. Auto-detect — iterate the registry until an adapter's detect() matches.
+ *
+ * Returns null when no adapter matches.
+ */
+function route(body, explicit) {
+    // Strategy 1 — explicit adapter by name
+    if (explicit) {
+        const adapter = ADAPTER_REGISTRY[explicit.toLowerCase()];
+        if (adapter) {
+            return { adapterName: explicit.toLowerCase(), adapter, event: adapter.normalize(body) };
+        }
+    }
+    // Strategy 2 — auto-detect from payload fields
+    for (const [name, adapter] of Object.entries(ADAPTER_REGISTRY)) {
+        if (adapter.detect(body)) {
+            return { adapterName: name, adapter, event: adapter.normalize(body) };
+        }
+    }
+    return null;
+}
+/**
+ * Route a raw JSON string (hook stdin) to the correct adapter.
+ * Parses stdin and delegates to route().
+ *
+ * @param stdin         Raw JSON string from the IDE hook.
+ * @param explicitName  Optional adapter name — skips auto-detection when provided.
+ */
+function routeStdin(stdin, explicitName) {
+    let body;
+    try {
+        body = JSON.parse(stdin);
+    }
+    catch {
+        return null;
+    }
+    return route(body, explicitName);
+}
+/** Returns the canonical names of all registered adapters. */
+function registeredAdapters() {
+    return Object.keys(ADAPTER_REGISTRY);
+}

package/dist/routes/adapters/schema.d.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+/**
+ * OculiEvent — canonical hook event schema (schema_version: '1')
+ *
+ * All IDE hook adapters (Claude Code, Cursor, Windsurf, …) normalize their
+ * raw wire payloads to this shape before the gateway processes them.
+ *
+ * snake_case throughout to match the raw wire formats as closely as possible.
+ */
+export declare const OculiEventSchema: z.ZodObject<{
+    /** Increment when the schema has breaking changes. */
+    schema_version: z.ZodLiteral<"1">;
+    /** Which IDE emitted the hook: 'claude-code' | 'cursor' | 'windsurf' | … */
+    ide_source: z.ZodString;
+    /** Actor name. Defaults to ide_source when no JWT is present. */
+    actor: z.ZodString;
+    /** Organization ID. Defaults to 'default'. */
+    org_id: z.ZodDefault<z.ZodString>;
+    /** Raw event name from the IDE, preserved verbatim (e.g. 'PreToolUse', 'beforeShellExecution'). */
+    hook_event_name: z.ZodString;
+    /**
+     * Lifecycle phase:
+     *   pre      — hook fires before tool execution; enforcement gate
+     *   post     — hook fires after tool execution; telemetry only
+     *   complete — agent session ended (Cursor 'stop' event); telemetry only
+     */
+    phase: z.ZodEnum<["pre", "post", "complete"]>;
+    /** Session identifier. Claude Code: session_id. Cursor: conversation_id. */
+    session_id: z.ZodString;
+    /** Sub-session trace. Cursor: generation_id. */
+    trace_id: z.ZodOptional<z.ZodString>;
+    /** Normalized tool name. Absent for stop/complete events. */
+    tool: z.ZodOptional<z.ZodString>;
+    /** Tool arguments as a key-value map. */
+    tool_args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Tool result (post-phase only). */
+    tool_result: z.ZodOptional<z.ZodUnknown>;
+    /** File path for file-oriented operations (readFile, writeFile). */
+    file_path: z.ZodOptional<z.ZodString>;
+    /** Shell command string for shell execution events. */
+    shell_command: z.ZodOptional<z.ZodString>;
+    /** MCP server name for MCP tool calls. */
+    mcp_server: z.ZodOptional<z.ZodString>;
+    /** Workspace root directories (Cursor). */
+    workspace_roots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Current working directory (Claude Code). */
+    cwd: z.ZodOptional<z.ZodString>;
+    /** ISO 8601 timestamp; set by the adapter at normalize time. */
+    timestamp: z.ZodString;
+    /** Tool execution duration in milliseconds (post-phase only). */
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    /** Error message if the tool failed. */
+    error: z.ZodOptional<z.ZodString>;
+    /** Workspace and identity context, unified from IDE-specific fields. */
+    context: z.ZodOptional<z.ZodObject<{
+        /** Workspace root (Claude Code: cwd; Cursor: workspace_roots[0]). */
+        workspace: z.ZodOptional<z.ZodString>;
+        /** IDE conversation identifier (Cursor: conversation_id). */
+        conversation_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        workspace?: string | undefined;
+        conversation_id?: string | undefined;
+    }, {
+        workspace?: string | undefined;
+        conversation_id?: string | undefined;
+    }>>;
+    /** Normalised action data for the tool invocation. */
+    action: z.ZodOptional<z.ZodObject<{
+        /** Shell command for shell execution events (tool: 'shell'). */
+        command: z.ZodOptional<z.ZodString>;
+        /** SHA-256 prefix (16 hex chars) of file content for read/edit events. */
+        content_hash: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        command?: string | undefined;
+        content_hash?: string | undefined;
+    }, {
+        command?: string | undefined;
+        content_hash?: string | undefined;
+    }>>;
+    /** Original wire payload, preserved verbatim for audit and debugging. */
+    raw_payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    schema_version: "1";
+    ide_source: string;
+    actor: string;
+    org_id: string;
+    hook_event_name: string;
+    phase: "pre" | "post" | "complete";
+    session_id: string;
+    timestamp: string;
+    raw_payload: Record<string, unknown>;
+    trace_id?: string | undefined;
+    tool?: string | undefined;
+    tool_args?: Record<string, unknown> | undefined;
+    tool_result?: unknown;
+    file_path?: string | undefined;
+    shell_command?: string | undefined;
+    mcp_server?: string | undefined;
+    workspace_roots?: string[] | undefined;
+    cwd?: string | undefined;
+    duration_ms?: number | undefined;
+    error?: string | undefined;
+    context?: {
+        workspace?: string | undefined;
+        conversation_id?: string | undefined;
+    } | undefined;
+    action?: {
+        command?: string | undefined;
+        content_hash?: string | undefined;
+    } | undefined;
+}, {
+    schema_version: "1";
+    ide_source: string;
+    actor: string;
+    hook_event_name: string;
+    phase: "pre" | "post" | "complete";
+    session_id: string;
+    timestamp: string;
+    raw_payload: Record<string, unknown>;
+    org_id?: string | undefined;
+    trace_id?: string | undefined;
+    tool?: string | undefined;
+    tool_args?: Record<string, unknown> | undefined;
+    tool_result?: unknown;
+    file_path?: string | undefined;
+    shell_command?: string | undefined;
+    mcp_server?: string | undefined;
+    workspace_roots?: string[] | undefined;
+    cwd?: string | undefined;
+    duration_ms?: number | undefined;
+    error?: string | undefined;
+    context?: {
+        workspace?: string | undefined;
+        conversation_id?: string | undefined;
+    } | undefined;
+    action?: {
+        command?: string | undefined;
+        content_hash?: string | undefined;
+    } | undefined;
+}>;
+export type OculiEvent = z.infer<typeof OculiEventSchema>;

package/dist/routes/adapters/schema.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OculiEventSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * OculiEvent — canonical hook event schema (schema_version: '1')
+ *
+ * All IDE hook adapters (Claude Code, Cursor, Windsurf, …) normalize their
+ * raw wire payloads to this shape before the gateway processes them.
+ *
+ * snake_case throughout to match the raw wire formats as closely as possible.
+ */
+exports.OculiEventSchema = zod_1.z.object({
+    /** Increment when the schema has breaking changes. */
+    schema_version: zod_1.z.literal('1'),
+    // ── Source identity ────────────────────────────────────────────────────────
+    /** Which IDE emitted the hook: 'claude-code' | 'cursor' | 'windsurf' | … */
+    ide_source: zod_1.z.string().min(1),
+    /** Actor name. Defaults to ide_source when no JWT is present. */
+    actor: zod_1.z.string().min(1),
+    /** Organization ID. Defaults to 'default'. */
+    org_id: zod_1.z.string().default('default'),
+    // ── Hook identity ──────────────────────────────────────────────────────────
+    /** Raw event name from the IDE, preserved verbatim (e.g. 'PreToolUse', 'beforeShellExecution'). */
+    hook_event_name: zod_1.z.string().min(1),
+    /**
+     * Lifecycle phase:
+     *   pre      — hook fires before tool execution; enforcement gate
+     *   post     — hook fires after tool execution; telemetry only
+     *   complete — agent session ended (Cursor 'stop' event); telemetry only
+     */
+    phase: zod_1.z.enum(['pre', 'post', 'complete']),
+    // ── Session / trace ────────────────────────────────────────────────────────
+    /** Session identifier. Claude Code: session_id. Cursor: conversation_id. */
+    session_id: zod_1.z.string().min(1),
+    /** Sub-session trace. Cursor: generation_id. */
+    trace_id: zod_1.z.string().optional(),
+    // ── Tool invocation (absent for 'stop' / 'complete' events) ───────────────
+    /** Normalized tool name. Absent for stop/complete events. */
+    tool: zod_1.z.string().optional(),
+    /** Tool arguments as a key-value map. */
+    tool_args: zod_1.z.record(zod_1.z.unknown()).optional(),
+    /** Tool result (post-phase only). */
+    tool_result: zod_1.z.unknown().optional(),
+    // ── Resource context ───────────────────────────────────────────────────────
+    /** File path for file-oriented operations (readFile, writeFile). */
+    file_path: zod_1.z.string().optional(),
+    /** Shell command string for shell execution events. */
+    shell_command: zod_1.z.string().optional(),
+    /** MCP server name for MCP tool calls. */
+    mcp_server: zod_1.z.string().optional(),
+    /** Workspace root directories (Cursor). */
+    workspace_roots: zod_1.z.array(zod_1.z.string()).optional(),
+    /** Current working directory (Claude Code). */
+    cwd: zod_1.z.string().optional(),
+    // ── Timing ─────────────────────────────────────────────────────────────────
+    /** ISO 8601 timestamp; set by the adapter at normalize time. */
+    timestamp: zod_1.z.string().min(1),
+    /** Tool execution duration in milliseconds (post-phase only). */
+    duration_ms: zod_1.z.number().optional(),
+    // ── Status ─────────────────────────────────────────────────────────────────
+    /** Error message if the tool failed. */
+    error: zod_1.z.string().optional(),
+    // ── Normalised cross-IDE context ───────────────────────────────────────────
+    /** Workspace and identity context, unified from IDE-specific fields. */
+    context: zod_1.z.object({
+        /** Workspace root (Claude Code: cwd; Cursor: workspace_roots[0]). */
+        workspace: zod_1.z.string().optional(),
+        /** IDE conversation identifier (Cursor: conversation_id). */
+        conversation_id: zod_1.z.string().optional(),
+    }).optional(),
+    // ── Normalised action payload ──────────────────────────────────────────────
+    /** Normalised action data for the tool invocation. */
+    action: zod_1.z.object({
+        /** Shell command for shell execution events (tool: 'shell'). */
+        command: zod_1.z.string().optional(),
+        /** SHA-256 prefix (16 hex chars) of file content for read/edit events. */
+        content_hash: zod_1.z.string().optional(),
+    }).optional(),
+    // ── Raw payload ────────────────────────────────────────────────────────────
+    /** Original wire payload, preserved verbatim for audit and debugging. */
+    raw_payload: zod_1.z.record(zod_1.z.unknown()),
+});

package/dist/routes/adapters/windsurf.d.ts

@@ -0,0 +1,6 @@
+import { OculiEvent } from './schema';
+export declare function detect(body: Record<string, unknown>): boolean;
+export declare function normalize(body: Record<string, unknown>): OculiEvent;
+export declare function formatAllow(_event: OculiEvent): string;
+export declare function formatDeny(reason: string, _event: OculiEvent): string;
+export declare function denyStatusCode(): number;

package/dist/routes/adapters/windsurf.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detect = detect;
+exports.normalize = normalize;
+exports.formatAllow = formatAllow;
+exports.formatDeny = formatDeny;
+exports.denyStatusCode = denyStatusCode;
+function detect(body) {
+    return (typeof body.agent_action_name === 'string' &&
+        body.agent_action_name.startsWith('pre_mcp_tool_use') ||
+        (typeof body.agent_action_name === 'string' &&
+            body.agent_action_name.startsWith('post_mcp_tool_use')));
+}
+function normalize(body) {
+    const actionName = body.agent_action_name;
+    const phase = actionName.startsWith('pre_') ? 'pre' : 'post';
+    const toolInfo = body.tool_info;
+    const tool = toolInfo
+        ? `${toolInfo.mcp_server_name}__${toolInfo.mcp_tool_name}`
+        : undefined;
+    const mcp_server = toolInfo?.mcp_server_name;
+    return {
+        schema_version: '1',
+        ide_source: 'windsurf',
+        actor: 'windsurf',
+        org_id: 'default',
+        hook_event_name: actionName,
+        phase,
+        session_id: body.trajectory_id ?? 'windsurf-unknown',
+        trace_id: body.execution_id,
+        tool,
+        tool_args: toolInfo?.mcp_tool_arguments,
+        mcp_server,
+        timestamp: body.timestamp ?? new Date().toISOString(),
+        raw_payload: body,
+    };
+}
+// Windsurf allow: HTTP 200, no specific body needed
+function formatAllow(_event) {
+    return JSON.stringify({ status: 'allow' });
+}
+// Windsurf block: caller sends HTTP 403 — body is informational only
+function formatDeny(reason, _event) {
+    return JSON.stringify({ status: 'deny', reason });
+}
+function denyStatusCode() {
+    return 403; // Windsurf uses HTTP 403 to signal a block
+}

package/dist/routes/admin.d.ts

@@ -0,0 +1,15 @@
+import { FastifyInstance } from 'fastify';
+import { AppConfig } from '../config';
+import { AuditService } from '../services/audit';
+import { UpstreamConnector } from '../services/upstream';
+import { PolicyStore } from '../services/policy-store';
+import { PolicyService } from '../services/policy';
+interface AdminRouteContext {
+    audit: AuditService;
+    upstream: UpstreamConnector;
+    config: AppConfig;
+    policyStore: PolicyStore;
+    policy: PolicyService;
+}
+export declare function registerAdminRoutes(app: FastifyInstance, ctx: AdminRouteContext): void;
+export {};