@oculisecurity/cli 0.1.0

package/dist/services/tool-executor.d.ts

@@ -0,0 +1,46 @@
+import { AuthenticatedActor } from '../types';
+import { PolicyService } from './policy';
+import { AuditService } from './audit';
+import { UpstreamConnector } from './upstream';
+import { RateLimiter } from './ratelimit';
+export interface ToolExecutorContext {
+    policy: PolicyService;
+    audit: AuditService;
+    upstream: UpstreamConnector;
+    rateLimiter: RateLimiter;
+}
+export interface ExecuteToolInput {
+    actor: AuthenticatedActor;
+    upstreamId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    sessionId?: string;
+    ip: string;
+}
+export type ExecuteToolResult = {
+    kind: 'allow';
+    requestId: string;
+    result: unknown;
+    upstreamId: string;
+    latencyMs: number;
+    reason: string;
+} | {
+    kind: 'deny';
+    requestId: string;
+    reason: string;
+    httpStatus: 400 | 403 | 413 | 429;
+    retryAfterMs?: number;
+} | {
+    kind: 'error';
+    requestId: string;
+    message: string;
+    httpStatus: number;
+    upstreamId: string;
+    latencyMs: number;
+    reason: string;
+};
+export declare class ToolExecutor {
+    private readonly ctx;
+    constructor(ctx: ToolExecutorContext);
+    execute(input: ExecuteToolInput): Promise<ExecuteToolResult>;
+}

package/dist/services/tool-executor.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolExecutor = void 0;
+const uuid_1 = require("uuid");
+const upstream_1 = require("./upstream");
+const sanitizer_1 = require("./sanitizer");
+// ---------------------------------------------------------------------------
+// ToolExecutor — shared 7-step pipeline (validate → rate-limit → policy →
+// size-check → forward → sanitize → audit)
+// ---------------------------------------------------------------------------
+class ToolExecutor {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async execute(input) {
+        const requestId = (0, uuid_1.v4)();
+        const startMs = Date.now();
+        const sessionId = input.sessionId ?? (0, uuid_1.v4)();
+        const argsJson = JSON.stringify(input.args);
+        const storedArgsJson = this.ctx.audit.storeFullArgs ? argsJson : null;
+        // ------------------------------------------------------------------
+        // 1. Validate upstream
+        // ------------------------------------------------------------------
+        const upstreamCfg = this.ctx.upstream.getConfig(input.upstreamId);
+        if (!upstreamCfg) {
+            return { kind: 'deny', requestId, reason: `Unknown upstreamId '${input.upstreamId}'`, httpStatus: 400 };
+        }
+        // ------------------------------------------------------------------
+        // 2. Rate limiting (token bucket per actor:tool)
+        // ------------------------------------------------------------------
+        const rlKey = `${input.actor.actor}:${input.tool}`;
+        const rlResult = this.ctx.rateLimiter.check(rlKey);
+        if (!rlResult.allowed) {
+            this.ctx.audit.log({
+                requestId,
+                timestamp: new Date().toISOString(),
+                actor: input.actor.actor,
+                orgId: input.actor.orgId,
+                upstreamId: input.upstreamId,
+                tool: input.tool,
+                argsHash: this.ctx.audit.hash(input.args),
+                argsJson: storedArgsJson,
+                decision: 'deny',
+                reason: 'rate limit exceeded',
+                latencyMs: Date.now() - startMs,
+                outcome: 'denied',
+                ip: input.ip,
+                sessionId,
+            });
+            return { kind: 'deny', requestId, reason: 'rate limit exceeded', httpStatus: 429, retryAfterMs: rlResult.retryAfterMs };
+        }
+        // ------------------------------------------------------------------
+        // 3. Policy evaluation (OPA or built-in fallback)
+        // ------------------------------------------------------------------
+        const policyInput = {
+            actor: input.actor.actor,
+            orgId: input.actor.orgId,
+            roles: input.actor.roles,
+            upstreamId: input.upstreamId,
+            tool: input.tool,
+            args: input.args,
+            time: new Date().toISOString(),
+            ip: input.ip,
+            sessionId,
+        };
+        const decision = await this.ctx.policy.evaluate(policyInput);
+        if (!decision.allow) {
+            this.ctx.audit.log({
+                requestId,
+                timestamp: new Date().toISOString(),
+                actor: input.actor.actor,
+                orgId: input.actor.orgId,
+                upstreamId: input.upstreamId,
+                tool: input.tool,
+                argsHash: this.ctx.audit.hash(input.args),
+                argsJson: storedArgsJson,
+                decision: 'deny',
+                reason: decision.reason,
+                latencyMs: Date.now() - startMs,
+                outcome: 'denied',
+                ip: input.ip,
+                sessionId,
+            });
+            return { kind: 'deny', requestId, reason: decision.reason, httpStatus: 403 };
+        }
+        // ------------------------------------------------------------------
+        // 4. Args size check
+        // ------------------------------------------------------------------
+        const maxSize = decision.maxArgsSize ?? 102400;
+        if (Buffer.byteLength(argsJson) > maxSize) {
+            return { kind: 'deny', requestId, reason: `Args payload exceeds max size (${maxSize} bytes)`, httpStatus: 413 };
+        }
+        // ------------------------------------------------------------------
+        // 5. Forward to upstream + 6. Sanitize + 7. Audit
+        // ------------------------------------------------------------------
+        try {
+            const result = await this.ctx.upstream.call(input.upstreamId, {
+                tool: input.tool,
+                args: input.args,
+                sessionId,
+                actor: input.actor.actor,
+            });
+            const sanitized = (0, sanitizer_1.sanitizeResponse)(result.data, decision);
+            const responseStr = JSON.stringify(result.data);
+            const responseJson = responseStr.length <= 8192 ? responseStr : responseStr.slice(0, 8192) + '…';
+            this.ctx.audit.log({
+                requestId,
+                timestamp: new Date().toISOString(),
+                actor: input.actor.actor,
+                orgId: input.actor.orgId,
+                upstreamId: input.upstreamId,
+                tool: input.tool,
+                argsHash: this.ctx.audit.hash(input.args),
+                argsJson: storedArgsJson,
+                decision: 'allow',
+                reason: decision.reason,
+                latencyMs: Date.now() - startMs,
+                outcome: 'success',
+                responseHash: this.ctx.audit.hash(result.data),
+                responseJson,
+                ip: input.ip,
+                sessionId,
+            });
+            return {
+                kind: 'allow',
+                requestId,
+                result: sanitized,
+                upstreamId: input.upstreamId,
+                latencyMs: result.latencyMs,
+                reason: decision.reason,
+            };
+        }
+        catch (err) {
+            const upstreamErr = err;
+            const errMsg = upstreamErr.message ?? 'Upstream error';
+            const latencyMs = upstreamErr.latencyMs ?? 0;
+            const statusCode = upstreamErr instanceof upstream_1.UpstreamError ? upstreamErr.statusCode : 502;
+            this.ctx.audit.log({
+                requestId,
+                timestamp: new Date().toISOString(),
+                actor: input.actor.actor,
+                orgId: input.actor.orgId,
+                upstreamId: input.upstreamId,
+                tool: input.tool,
+                argsHash: this.ctx.audit.hash(input.args),
+                argsJson: storedArgsJson,
+                decision: 'allow',
+                reason: decision.reason,
+                latencyMs: Date.now() - startMs,
+                outcome: 'error',
+                ip: input.ip,
+                sessionId,
+            });
+            return {
+                kind: 'error',
+                requestId,
+                message: errMsg,
+                httpStatus: statusCode,
+                upstreamId: input.upstreamId,
+                latencyMs,
+                reason: decision.reason,
+            };
+        }
+    }
+}
+exports.ToolExecutor = ToolExecutor;

package/dist/services/upstream.d.ts

@@ -0,0 +1,18 @@
+import { AppConfig } from '../config';
+import { UpstreamCallRequest, UpstreamConfig } from '../types';
+export interface UpstreamResult {
+    data: unknown;
+    latencyMs: number;
+}
+export declare class UpstreamConnector {
+    private readonly registry;
+    constructor(config: AppConfig);
+    getConfig(upstreamId: string): UpstreamConfig | undefined;
+    listUpstreams(): UpstreamConfig[];
+    call(upstreamId: string, body: UpstreamCallRequest): Promise<UpstreamResult>;
+}
+export declare class UpstreamError extends Error {
+    readonly statusCode: number;
+    readonly latencyMs: number;
+    constructor(message: string, statusCode: number, latencyMs: number);
+}

package/dist/services/upstream.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpstreamError = exports.UpstreamConnector = void 0;
+const axios_1 = __importDefault(require("axios"));
+class UpstreamConnector {
+    registry;
+    constructor(config) {
+        this.registry = new Map(config.upstreams.map((u) => [u.id, u]));
+    }
+    getConfig(upstreamId) {
+        return this.registry.get(upstreamId);
+    }
+    listUpstreams() {
+        return Array.from(this.registry.values());
+    }
+    async call(upstreamId, body) {
+        const upstream = this.registry.get(upstreamId);
+        if (!upstream) {
+            throw new Error(`Unknown upstream: '${upstreamId}'`);
+        }
+        const url = `${upstream.baseUrl}/v1/call`;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (upstream.authHeader) {
+            headers['Authorization'] = upstream.authHeader;
+        }
+        const startMs = Date.now();
+        try {
+            const response = await axios_1.default.post(url, body, {
+                headers,
+                timeout: upstream.timeout,
+                validateStatus: () => true, // handle non-2xx ourselves
+            });
+            const latencyMs = Date.now() - startMs;
+            if (response.status >= 400) {
+                const errData = response.data;
+                throw new UpstreamError(errData?.error ??
+                    `Upstream returned ${response.status}`, response.status, latencyMs);
+            }
+            return { data: response.data, latencyMs };
+        }
+        catch (err) {
+            if (err instanceof UpstreamError)
+                throw err;
+            const latencyMs = Date.now() - startMs;
+            const axiosErr = err;
+            if (axiosErr.code === 'ECONNABORTED') {
+                throw new UpstreamError(`Upstream '${upstreamId}' timed out after ${upstream.timeout}ms`, 504, latencyMs);
+            }
+            if (axiosErr.code === 'ECONNREFUSED') {
+                throw new UpstreamError(`Upstream '${upstreamId}' connection refused at ${url}`, 502, latencyMs);
+            }
+            throw new UpstreamError(`Upstream '${upstreamId}' error: ${axiosErr.message}`, 502, latencyMs);
+        }
+    }
+}
+exports.UpstreamConnector = UpstreamConnector;
+class UpstreamError extends Error {
+    statusCode;
+    latencyMs;
+    constructor(message, statusCode, latencyMs) {
+        super(message);
+        this.statusCode = statusCode;
+        this.latencyMs = latencyMs;
+        this.name = 'UpstreamError';
+    }
+}
+exports.UpstreamError = UpstreamError;

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+export interface JWTPayload {
+    sub: string;
+    actor: string;
+    orgId: string;
+    roles: string[];
+    iat: number;
+    exp: number;
+}
+export interface AuthenticatedActor {
+    sub: string;
+    actor: string;
+    orgId: string;
+    roles: string[];
+}
+/** POST /v1/call — incoming request body */
+export interface CallRequest {
+    upstreamId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    sessionId?: string;
+}
+/** Structured response from the gateway */
+export interface GatewayResponse {
+    requestId: string;
+    decision: {
+        allow: boolean;
+        reason: string;
+    };
+    upstream?: {
+        id: string;
+        latencyMs: number;
+    };
+    result?: unknown;
+    error?: string;
+}
+/** Input sent to OPA (or fallback policy engine) */
+export interface PolicyInput {
+    actor: string;
+    orgId: string;
+    roles: string[];
+    upstreamId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    time: string;
+    ip: string;
+    sessionId: string;
+}
+/** Decision returned by OPA / fallback */
+export interface PolicyDecision {
+    allow: boolean;
+    reason: string;
+    redactions?: Record<string, boolean>;
+    transforms?: Record<string, Transform>;
+    maxArgsSize?: number;
+}
+export interface Transform {
+    type: 'truncate' | 'mask' | 'remove';
+    maxLength?: number;
+    mask?: string;
+}
+export interface UpstreamConfig {
+    id: string;
+    name: string;
+    baseUrl: string;
+    authHeader?: string;
+    timeout: number;
+    tools?: string[];
+}
+/** Body forwarded to the upstream MCP server */
+export interface UpstreamCallRequest {
+    tool: string;
+    args: Record<string, unknown>;
+    sessionId: string;
+    actor: string;
+}
+/** A single tool-call event reported by an external agent */
+export interface TelemetryEvent {
+    tool: string;
+    args?: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    durationMs?: number;
+    timestamp?: string;
+    actor?: string;
+    sessionId?: string;
+    meta?: Record<string, unknown>;
+}
+/** POST /v1/events — batch of events from an agent */
+export interface TelemetryPayload {
+    source: string;
+    orgId?: string;
+    events: TelemetryEvent[];
+}
+export interface AuditRecord {
+    id?: number;
+    requestId: string;
+    timestamp: string;
+    actor: string;
+    orgId: string;
+    upstreamId: string;
+    tool: string;
+    argsHash: string;
+    argsJson?: string | null;
+    decision: 'allow' | 'deny';
+    reason: string;
+    latencyMs: number;
+    outcome: 'success' | 'error' | 'denied';
+    responseHash?: string | null;
+    responseJson?: string | null;
+    ip: string;
+    sessionId: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// Core domain types for the Oculi Security Gateway
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@oculisecurity/cli",
+  "version": "0.1.0",
+  "description": "Security layer for AI coding agents. Visibility, policy enforcement, and audit trails for Claude Code, Cursor, and Windsurf.",
+  "main": "dist/index.js",
+  "bin": {
+    "oculi": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "public/",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "postbuild": "chmod +x dist/cli.js",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "hook": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build",
+    "preuninstall": "node dist/cli.js uninstall || true"
+  },
+  "keywords": [
+    "ai-security",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "policy-enforcement",
+    "audit",
+    "hooks",
+    "agent-security",
+    "mcp"
+  ],
+  "author": "Oculi Security LLC <alex@oculisecurity.com> (https://oculisecurity.com)",
+  "homepage": "https://oculisecurity.com",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@fastify/cors": "^9.0.1",
+    "@fastify/static": "^7.0.4",
+    "axios": "^1.7.2",
+    "fastify": "^4.28.1",
+    "jsonwebtoken": "^9.0.2",
+    "uuid": "^11.1.1",
+    "yaml": "^2.4.5",
+    "zod": "^3.25.76"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^9.6.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.10",
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/node": "^20.14.10",
+    "@types/supertest": "^6.0.2",
+    "@vitest/coverage-v8": "^1.6.0",
+    "supertest": "^7.0.0",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.3",
+    "vitest": "^1.6.0"
+  }
+}

package/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="8" fill="#0a0a0f"/>
+  <circle cx="16" cy="16" r="11" fill="rgba(99, 179, 237, 0.1)" stroke="#63b3ed" stroke-width="2"/>
+</svg>