@oculisecurity/cli 0.1.0

package/dist/routes/hooks.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHooksRoute = registerHooksRoute;
+const uuid_1 = require("uuid");
+const router_1 = require("./adapters/router");
+function registerHooksRoute(app, ctx) {
+    app.post('/v1/hooks', async (request, reply) => {
+        const body = request.body;
+        if (!body || typeof body !== 'object') {
+            reply.code(400).send({ error: 'Invalid request body' });
+            return;
+        }
+        // ── Adapter selection ───────────────────────────────────────────────────
+        // X-Oculi-Adapter header lets the CLI bypass auto-detection entirely.
+        const explicitAdapter = request.headers['x-oculi-adapter'];
+        const routed = (0, router_1.route)(body, explicitAdapter);
+        if (!routed) {
+            reply.code(400).send({
+                error: 'Unrecognised hook payload format. Supported: claude-code, cursor, windsurf.',
+            });
+            return;
+        }
+        const { adapter, event } = routed;
+        // ── From here the pipeline is completely adapter-agnostic ───────────────
+        const requestId = (0, uuid_1.v4)();
+        const sessionId = event.session_id ?? requestId;
+        const ip = request.ip;
+        const args = event.tool_args ?? {};
+        const argsJson = JSON.stringify(args);
+        const storedArgsJson = ctx.audit.storeFullArgs ? argsJson : null;
+        const startMs = Date.now();
+        const tool = event.tool ?? '__stop__';
+        request.log.info({ adapter: routed.adapterName, tool: event.tool, phase: event.phase }, 'hook received');
+        // ── Pre-decided fast path ───────────────────────────────────────────────
+        // When the CLI sends X-Oculi-Local-Decision (deny | warn), the local policy
+        // engine has already executed. Record the event verbatim and skip rate
+        // limit + central policy. Warn is persisted as decision='allow' with a
+        // distinguishing reason prefix because the audit_logs CHECK constraint only
+        // allows 'allow' | 'deny'; surfacing warn as a first-class decision is a
+        // follow-up that requires a table-rebuild migration.
+        const localDec = request.headers['x-oculi-local-decision'];
+        if (localDec === 'deny' || localDec === 'warn') {
+            const localReasonHeader = request.headers['x-oculi-local-reason'];
+            const localReason = (Array.isArray(localReasonHeader) ? localReasonHeader[0] : localReasonHeader) ??
+                'oculi: pre-decided';
+            ctx.audit.log({
+                requestId,
+                timestamp: event.timestamp ?? new Date().toISOString(),
+                actor: event.actor,
+                orgId: 'default',
+                upstreamId: `ext:${event.ide_source}`,
+                tool,
+                argsHash: ctx.audit.hash(args),
+                argsJson: storedArgsJson,
+                decision: localDec === 'deny' ? 'deny' : 'allow',
+                reason: localReason,
+                latencyMs: Date.now() - startMs,
+                outcome: localDec === 'deny' ? 'denied' : 'success',
+                ip,
+                sessionId,
+            });
+            reply.code(200).send({});
+            return;
+        }
+        // ── Post / complete phase: telemetry only ───────────────────────────────
+        if (event.phase === 'post' || event.phase === 'complete') {
+            const resultStr = event.tool_result != null ? JSON.stringify(event.tool_result) : null;
+            const responseJson = resultStr
+                ? resultStr.length <= 8192 ? resultStr : resultStr.slice(0, 8192) + '…'
+                : null;
+            ctx.audit.log({
+                requestId,
+                timestamp: event.timestamp ?? new Date().toISOString(),
+                actor: event.actor,
+                orgId: 'default',
+                upstreamId: `ext:${event.ide_source}`,
+                tool,
+                argsHash: ctx.audit.hash(args),
+                argsJson: storedArgsJson,
+                decision: 'allow',
+                reason: 'telemetry',
+                latencyMs: event.duration_ms ?? 0,
+                outcome: event.error ? 'error' : 'success',
+                responseHash: event.tool_result != null ? ctx.audit.hash(event.tool_result) : undefined,
+                responseJson,
+                ip,
+                sessionId,
+            });
+            reply.code(202).send({ received: 1 });
+            return;
+        }
+        // ── Pre-phase: rate limit → policy → audit → respond ───────────────────
+        // 1. Rate limiting
+        const rlKey = `${event.actor}:${tool}`;
+        const rlResult = ctx.rateLimiter.check(rlKey);
+        if (!rlResult.allowed) {
+            ctx.audit.log({
+                requestId,
+                timestamp: new Date().toISOString(),
+                actor: event.actor,
+                orgId: 'default',
+                upstreamId: `ext:${event.ide_source}`,
+                tool,
+                argsHash: ctx.audit.hash(args),
+                argsJson: storedArgsJson,
+                decision: 'deny',
+                reason: 'rate limit exceeded',
+                latencyMs: Date.now() - startMs,
+                outcome: 'denied',
+                ip,
+                sessionId,
+            });
+            reply
+                .code(adapter.denyStatusCode())
+                .send(JSON.parse(adapter.formatDeny('rate limit exceeded', event)));
+            return;
+        }
+        // 2. Policy evaluation
+        const policyInput = {
+            actor: event.actor,
+            orgId: 'default',
+            roles: ['developer'],
+            upstreamId: `ext:${event.ide_source}`,
+            tool,
+            args,
+            time: new Date().toISOString(),
+            ip,
+            sessionId,
+        };
+        let decision;
+        try {
+            decision = await ctx.policy.evaluate(policyInput);
+        }
+        catch (err) {
+            // Policy eval failure → fail open so IDEs aren't blocked
+            request.log.error({ err }, 'policy eval error in hook — failing open');
+            reply.code(200).send(JSON.parse(adapter.formatAllow(event)));
+            return;
+        }
+        // 3. Audit
+        ctx.audit.log({
+            requestId,
+            timestamp: new Date().toISOString(),
+            actor: event.actor,
+            orgId: 'default',
+            upstreamId: `ext:${event.ide_source}`,
+            tool,
+            argsHash: ctx.audit.hash(args),
+            argsJson: storedArgsJson,
+            decision: decision.allow ? 'allow' : 'deny',
+            reason: decision.reason,
+            latencyMs: Date.now() - startMs,
+            outcome: decision.allow ? 'success' : 'denied',
+            ip,
+            sessionId,
+        });
+        // 4. Respond in the adapter's native wire format
+        if (!decision.allow) {
+            reply
+                .code(adapter.denyStatusCode())
+                .send(JSON.parse(adapter.formatDeny(decision.reason, event)));
+            return;
+        }
+        reply.code(200).send(JSON.parse(adapter.formatAllow(event)));
+    });
+}

package/dist/routes/mcp.d.ts

@@ -0,0 +1,10 @@
+import { FastifyInstance } from 'fastify';
+import { UpstreamConnector } from '../services/upstream';
+import { ToolExecutor } from '../services/tool-executor';
+interface McpRouteContext {
+    executor: ToolExecutor;
+    upstream: UpstreamConnector;
+    jwtSecret: string;
+}
+export declare function registerMcpRoutes(app: FastifyInstance, ctx: McpRouteContext): void;
+export {};

package/dist/routes/mcp.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMcpRoutes = registerMcpRoutes;
+const uuid_1 = require("uuid");
+const auth_1 = require("../middleware/auth");
+const MCP_PROTOCOL_VERSION = '2024-11-05';
+const GATEWAY_VERSION = '0.1.0';
+// ---------------------------------------------------------------------------
+// In-process SSE session store
+// TODO: multi-replica — replace with Redis pub/sub so sessions survive restarts
+// and work across gateway replicas.
+// ---------------------------------------------------------------------------
+const sseSessions = new Map();
+/** Split "{upstreamId}__{toolName}" — returns null if format is invalid. */
+function parseToolName(namespaced) {
+    const idx = namespaced.indexOf('__');
+    if (idx === -1)
+        return null;
+    return { upstreamId: namespaced.slice(0, idx), tool: namespaced.slice(idx + 2) };
+}
+function buildToolList(upstream) {
+    return upstream.listUpstreams().flatMap((u) => (u.tools ?? []).map((toolName) => ({
+        name: `${u.id}__${toolName}`,
+        description: `${toolName} on ${u.name}`,
+        inputSchema: { type: 'object', additionalProperties: true },
+    })));
+}
+function jsonRpcError(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+function registerMcpRoutes(app, ctx) {
+    // -------------------------------------------------------------------------
+    // GET /mcp — establish SSE push channel (used by Claude Desktop / Code and
+    // any other MCP client that prefers the legacy SSE transport).
+    // -------------------------------------------------------------------------
+    app.get('/mcp', async (request, reply) => {
+        const actor = (0, auth_1.resolveActor)(request, ctx.jwtSecret);
+        if (!actor) {
+            reply.code(401).send({ error: 'Unauthorized. Provide Authorization: Bearer <token> header or ?token= query parameter.' });
+            return;
+        }
+        const sessionId = (0, uuid_1.v4)();
+        // Take over the raw HTTP response — Fastify must not touch it after this
+        reply.raw.setHeader('Content-Type', 'text/event-stream');
+        reply.raw.setHeader('Cache-Control', 'no-cache');
+        reply.raw.setHeader('Connection', 'keep-alive');
+        reply.raw.setHeader('X-Accel-Buffering', 'no'); // disable nginx buffering
+        reply.raw.flushHeaders();
+        sseSessions.set(sessionId, reply);
+        // Tell the client which URL to POST messages to
+        const endpointUrl = `/mcp?session=${sessionId}`;
+        reply.raw.write(`data: ${JSON.stringify({ type: 'endpoint', uri: endpointUrl })}\n\n`);
+        // Heartbeat every 30 s to keep the connection alive through proxies
+        const heartbeat = setInterval(() => {
+            if (!reply.raw.writableEnded) {
+                reply.raw.write(': ping\n\n');
+            }
+        }, 30_000);
+        request.raw.on('close', () => {
+            clearInterval(heartbeat);
+            sseSessions.delete(sessionId);
+        });
+        // Fastify's reply lifecycle is now bypassed — prevent it from finalising
+        await new Promise((resolve) => request.raw.on('close', resolve));
+    });
+    // -------------------------------------------------------------------------
+    // POST /mcp — JSON-RPC 2.0 message handler (MCP 2024-11-05 streamable HTTP
+    // transport). Supports both:
+    //   - Streamable HTTP: respond directly in the HTTP body (no ?session=)
+    //   - SSE transport: forward response over the SSE channel (?session=<id>)
+    // -------------------------------------------------------------------------
+    app.post('/mcp', async (request, reply) => {
+        const actor = (0, auth_1.resolveActor)(request, ctx.jwtSecret);
+        if (!actor) {
+            reply.code(401).send({ error: 'Unauthorized' });
+            return;
+        }
+        const msg = request.body;
+        const sessionId = request.query.session;
+        const sseReply = sessionId ? sseSessions.get(sessionId) : undefined;
+        /** Send a JSON-RPC response — either over SSE or directly as HTTP body. */
+        const respond = (payload) => {
+            if (sseReply && !sseReply.raw.writableEnded) {
+                sseReply.raw.write(`data: ${JSON.stringify(payload)}\n\n`);
+                reply.code(202).send();
+            }
+            else {
+                reply.code(200).send(payload);
+            }
+        };
+        // MCP protocol: stateless — clients may call tools/call without initialize.
+        // Note: initialize is optional for clients that skip handshake.
+        switch (msg.method) {
+            // -------------------------------------------------------------------
+            case 'initialize':
+                respond({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    result: {
+                        protocolVersion: MCP_PROTOCOL_VERSION,
+                        capabilities: { tools: {} },
+                        serverInfo: { name: 'oculi-security-gateway', version: GATEWAY_VERSION },
+                    },
+                });
+                return;
+            // -------------------------------------------------------------------
+            case 'tools/list':
+                respond({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    result: { tools: buildToolList(ctx.upstream) },
+                });
+                return;
+            // -------------------------------------------------------------------
+            case 'tools/call': {
+                const params = msg.params;
+                if (!params?.name) {
+                    respond(jsonRpcError(msg.id, -32602, 'params.name is required'));
+                    return;
+                }
+                const parsed = parseToolName(params.name);
+                if (!parsed) {
+                    respond(jsonRpcError(msg.id, -32602, `Invalid tool name '${params.name}'. Expected format: '{upstreamId}__{toolName}'`));
+                    return;
+                }
+                const execResult = await ctx.executor.execute({
+                    actor,
+                    upstreamId: parsed.upstreamId,
+                    tool: parsed.tool,
+                    args: params.arguments ?? {},
+                    ip: request.ip,
+                });
+                // MCP spec: tool errors use isError:true in result, not JSON-RPC error
+                switch (execResult.kind) {
+                    case 'allow':
+                        respond({
+                            jsonrpc: '2.0',
+                            id: msg.id,
+                            result: {
+                                content: [{ type: 'text', text: JSON.stringify(execResult.result) }],
+                                isError: false,
+                            },
+                        });
+                        break;
+                    case 'deny':
+                    case 'error':
+                        respond({
+                            jsonrpc: '2.0',
+                            id: msg.id,
+                            result: {
+                                content: [{
+                                        type: 'text',
+                                        text: execResult.kind === 'deny' ? execResult.reason : execResult.message,
+                                    }],
+                                isError: true,
+                            },
+                        });
+                        break;
+                }
+                return;
+            }
+            // -------------------------------------------------------------------
+            default:
+                respond(jsonRpcError(msg.id, -32601, `Method not found: ${String(msg.method)}`));
+        }
+    });
+}

package/dist/routes/openai-tools.d.ts

@@ -0,0 +1,9 @@
+import { FastifyInstance } from 'fastify';
+import { UpstreamConnector } from '../services/upstream';
+import { ToolExecutor } from '../services/tool-executor';
+interface OpenAIToolsRouteContext {
+    executor: ToolExecutor;
+    upstream: UpstreamConnector;
+}
+export declare function registerOpenAIToolsRoutes(app: FastifyInstance, ctx: OpenAIToolsRouteContext): void;
+export {};

package/dist/routes/openai-tools.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerOpenAIToolsRoutes = registerOpenAIToolsRoutes;
+/** Split "{upstreamId}__{toolName}" into parts. Returns null if format invalid. */
+function parseToolName(namespaced) {
+    const idx = namespaced.indexOf('__');
+    if (idx === -1)
+        return null;
+    return { upstreamId: namespaced.slice(0, idx), tool: namespaced.slice(idx + 2) };
+}
+function registerOpenAIToolsRoutes(app, ctx) {
+    // -----------------------------------------------------------------------
+    // GET /v1/openai/tools — list all tools in OpenAI function schema format
+    // -----------------------------------------------------------------------
+    app.get('/v1/openai/tools', async (request, reply) => {
+        if (!request.actor?.actor) {
+            reply.code(401).send({ error: 'Unauthorized' });
+            return;
+        }
+        const data = ctx.upstream.listUpstreams().flatMap((u) => (u.tools ?? []).map((toolName) => ({
+            type: 'function',
+            function: {
+                name: `${u.id}__${toolName}`,
+                description: `${toolName} on ${u.name}`,
+                parameters: {
+                    type: 'object',
+                    properties: {},
+                    additionalProperties: true,
+                },
+            },
+        })));
+        reply.send({ object: 'list', data });
+    });
+    // -----------------------------------------------------------------------
+    // POST /v1/openai/tools — execute an array of OpenAI tool_calls
+    // -----------------------------------------------------------------------
+    app.post('/v1/openai/tools', {
+        schema: {
+            body: {
+                type: 'object',
+                required: ['tool_calls'],
+                properties: {
+                    tool_calls: { type: 'array' },
+                    session_id: { type: 'string' },
+                },
+            },
+        },
+    }, async (request, reply) => {
+        if (!request.actor?.actor) {
+            reply.code(401).send({ error: 'Unauthorized' });
+            return;
+        }
+        const { tool_calls, session_id } = request.body;
+        if (!Array.isArray(tool_calls) || tool_calls.length === 0) {
+            reply.code(400).send({ error: 'tool_calls must be a non-empty array' });
+            return;
+        }
+        const results = [];
+        // Execute sequentially — avoids burst tripping rate limiter and matches
+        // how OpenAI clients consume tool results (ordered array).
+        for (const call of tool_calls) {
+            if (call.type !== 'function') {
+                results.push({
+                    tool_call_id: call.id,
+                    role: 'tool',
+                    content: JSON.stringify({ error: `Unsupported tool call type: ${String(call.type)}` }),
+                });
+                continue;
+            }
+            const parsed = parseToolName(call.function.name);
+            if (!parsed) {
+                results.push({
+                    tool_call_id: call.id,
+                    role: 'tool',
+                    content: JSON.stringify({
+                        error: `Invalid tool name '${call.function.name}'. Expected format: '{upstreamId}__{toolName}'`,
+                    }),
+                });
+                continue;
+            }
+            let args;
+            try {
+                args = JSON.parse(call.function.arguments);
+            }
+            catch {
+                results.push({
+                    tool_call_id: call.id,
+                    role: 'tool',
+                    content: JSON.stringify({ error: 'Failed to parse tool arguments as JSON' }),
+                });
+                continue;
+            }
+            const execResult = await ctx.executor.execute({
+                actor: request.actor,
+                upstreamId: parsed.upstreamId,
+                tool: parsed.tool,
+                args,
+                sessionId: session_id,
+                ip: request.ip,
+            });
+            let content;
+            switch (execResult.kind) {
+                case 'allow':
+                    content =
+                        typeof execResult.result === 'string'
+                            ? execResult.result
+                            : JSON.stringify(execResult.result);
+                    break;
+                case 'deny':
+                    content = JSON.stringify({ error: execResult.reason });
+                    break;
+                case 'error':
+                    content = JSON.stringify({ error: execResult.message });
+                    break;
+            }
+            results.push({ tool_call_id: call.id, role: 'tool', content });
+        }
+        // Always HTTP 200 — per-tool errors are encoded in content, per OpenAI conventions
+        reply.code(200).send(results);
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+import { FastifyInstance } from 'fastify';
+import { AppConfig } from './config';
+import { AuditService } from './services/audit';
+import { RateLimiter } from './services/ratelimit';
+export interface GatewayServer {
+    app: FastifyInstance;
+    audit: AuditService;
+    rateLimiter: RateLimiter;
+    close: () => Promise<void>;
+}
+export declare function buildServer(config: AppConfig): Promise<GatewayServer>;

package/dist/server.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServer = buildServer;
+const path_1 = __importDefault(require("path"));
+const fastify_1 = __importDefault(require("fastify"));
+const cors_1 = __importDefault(require("@fastify/cors"));
+const static_1 = __importDefault(require("@fastify/static"));
+const auth_1 = require("./middleware/auth");
+const health_1 = require("./routes/health");
+const call_1 = require("./routes/call");
+const admin_1 = require("./routes/admin");
+const events_1 = require("./routes/events");
+const hooks_1 = require("./routes/hooks");
+const openai_tools_1 = require("./routes/openai-tools");
+const mcp_1 = require("./routes/mcp");
+const policy_1 = require("./services/policy");
+const audit_1 = require("./services/audit");
+const upstream_1 = require("./services/upstream");
+const ratelimit_1 = require("./services/ratelimit");
+const policy_store_1 = require("./services/policy-store");
+const tool_executor_1 = require("./services/tool-executor");
+async function buildServer(config) {
+    const app = (0, fastify_1.default)({
+        logger: config.logLevel !== 'silent'
+            ? // Route pino to stderr so it can't pollute the `oculi serve` banner
+                // on stdout. Logs still print, just to the appropriate stream.
+                { level: config.logLevel, stream: process.stderr }
+            : false,
+        trustProxy: true, // needed for accurate request.ip behind Docker/nginx
+    });
+    // -----------------------------------------------------------------------
+    // Plugins
+    // -----------------------------------------------------------------------
+    await app.register(cors_1.default, { origin: true });
+    // Serve admin UI from public/
+    const publicDir = path_1.default.join(__dirname, '..', 'public');
+    await app.register(static_1.default, {
+        root: publicDir,
+        prefix: '/admin',
+        maxAge: 0,
+        immutable: false,
+        setHeaders(res, filePath) {
+            if (filePath.endsWith('.html')) {
+                res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+                res.setHeader('Pragma', 'no-cache');
+                res.setHeader('Expires', '0');
+            }
+        },
+    });
+    // -----------------------------------------------------------------------
+    // Services
+    // -----------------------------------------------------------------------
+    const audit = new audit_1.AuditService(config);
+    const policy = new policy_1.PolicyService(config);
+    const policyStore = new policy_store_1.PolicyStore(config);
+    const upstream = new upstream_1.UpstreamConnector(config);
+    const rateLimiter = new ratelimit_1.RateLimiter(config.rateLimitCapacity, config.rateLimitRefillPerSecond);
+    // Periodically clean up stale rate-limit buckets
+    const cleanupInterval = setInterval(() => rateLimiter.cleanup(), 60_000);
+    cleanupInterval.unref(); // don't prevent process exit
+    // Serve favicon at root for browsers
+    app.get('/favicon.svg', (_req, reply) => {
+        reply.type('image/svg+xml').sendFile('favicon.svg');
+    });
+    app.get('/favicon.ico', (_req, reply) => {
+        reply.type('image/svg+xml').sendFile('favicon.svg');
+    });
+    // -----------------------------------------------------------------------
+    // Auth middleware (all routes except /health and /admin static)
+    // -----------------------------------------------------------------------
+    (0, auth_1.registerAuthMiddleware)(app, config.jwtSecret);
+    // -----------------------------------------------------------------------
+    // Routes
+    // -----------------------------------------------------------------------
+    (0, health_1.registerHealthRoutes)(app);
+    const executor = new tool_executor_1.ToolExecutor({ policy, audit, upstream, rateLimiter });
+    (0, call_1.registerCallRoutes)(app, { policy, audit, upstream, rateLimiter });
+    (0, openai_tools_1.registerOpenAIToolsRoutes)(app, { executor, upstream });
+    (0, mcp_1.registerMcpRoutes)(app, { executor, upstream, jwtSecret: config.jwtSecret });
+    (0, admin_1.registerAdminRoutes)(app, { audit, upstream, config, policyStore, policy });
+    (0, events_1.registerEventsRoute)(app, { audit });
+    (0, hooks_1.registerHooksRoute)(app, { policy, audit, rateLimiter });
+    // -----------------------------------------------------------------------
+    // 404 handler — SPA catch-all for /admin/* paths
+    // -----------------------------------------------------------------------
+    app.setNotFoundHandler((req, reply) => {
+        if (req.method === 'GET' && req.url.startsWith('/admin/')) {
+            reply.type('text/html').sendFile('index.html');
+            return;
+        }
+        reply.code(404).send({ error: 'Not found' });
+    });
+    // -----------------------------------------------------------------------
+    // Error handler
+    // -----------------------------------------------------------------------
+    app.setErrorHandler((error, _req, reply) => {
+        app.log.error(error);
+        if (error.statusCode === 400) {
+            reply.code(400).send({ error: error.message, code: 'VALIDATION_ERROR' });
+            return;
+        }
+        reply.code(500).send({ error: 'Internal server error' });
+    });
+    return {
+        app,
+        audit,
+        rateLimiter,
+        async close() {
+            clearInterval(cleanupInterval);
+            await app.close();
+            audit.close();
+            policyStore.close();
+        },
+    };
+}