@oculisecurity/cli 0.1.0

package/dist/services/policy.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyService = void 0;
+const axios_1 = __importDefault(require("axios"));
+// ---------------------------------------------------------------------------
+// OPA Client
+// ---------------------------------------------------------------------------
+async function queryOPA(opaUrl, input) {
+    const url = `${opaUrl}/v1/data/gateway/authz`;
+    const response = await axios_1.default.post(url, { input }, { timeout: 3000 });
+    const result = response.data.result ?? {};
+    return {
+        allow: result.allow ?? false,
+        reason: result.reason ?? 'denied by policy',
+        redactions: result.redactions ?? {},
+        maxArgsSize: result.max_args_size ?? 102400,
+    };
+}
+// ---------------------------------------------------------------------------
+// Built-in fallback policy (mirrors gateway.rego logic in TypeScript)
+// Used when OPA_ENABLED=false or OPA is unreachable.
+// ---------------------------------------------------------------------------
+const TOOL_ALLOWLISTS = {
+    'fs-server': new Set(['readFile', 'listDir', 'writeFile']),
+    'http-server': new Set(['fetchUrl', 'postUrl']),
+};
+const DANGEROUS_PATTERNS = [
+    '../',
+    '..\\',
+    ';',
+    '&&',
+    '||',
+    '`',
+    '$(',
+    '${',
+    '%2e%2e',
+    '%252e',
+];
+const WRITE_TOOLS = new Set(['writeFile', 'postUrl']);
+const SENSITIVE_FIELDS = {
+    secretKey: true,
+    password: true,
+    token: true,
+    apiKey: true,
+    secret: true,
+    privateKey: true,
+};
+function fallbackPolicy(input) {
+    // 1. Tool must be specified
+    if (!input.tool) {
+        return { allow: false, reason: 'tool not specified' };
+    }
+    // 2. Hook sources (IDE events) → always allow at gateway level.
+    // Enforcement is handled by local policy on the client side.
+    // The gateway's role for hooks is audit + centralized policy overlay.
+    const isHookSource = input.upstreamId.startsWith('ext:');
+    if (isHookSource) {
+        return { allow: true, reason: 'allowed', redactions: {}, maxArgsSize: 102400 };
+    }
+    // ── Everything below applies only to MCP upstream proxy calls ──
+    // 3. Tool must be in allowlist for this upstream
+    const allowed = TOOL_ALLOWLISTS[input.upstreamId];
+    if (!allowed || !allowed.has(input.tool)) {
+        return { allow: false, reason: 'tool not in allowlist for this upstream' };
+    }
+    // 4. Dangerous argument patterns
+    for (const [key, val] of Object.entries(input.args)) {
+        if (typeof val === 'string') {
+            for (const pattern of DANGEROUS_PATTERNS) {
+                if (val.toLowerCase().includes(pattern.toLowerCase()) || val.includes(pattern)) {
+                    return {
+                        allow: false,
+                        reason: `dangerous argument pattern detected in '${key}'`,
+                    };
+                }
+            }
+        }
+    }
+    // 5. Role restriction for write tools
+    if (WRITE_TOOLS.has(input.tool)) {
+        const hasWritePermission = input.roles.includes('admin') || input.roles.includes('editor');
+        if (!hasWritePermission) {
+            return {
+                allow: false,
+                reason: 'role restriction: insufficient permissions for write operations',
+            };
+        }
+    }
+    // Allow — determine redactions based on role
+    const redactions = input.roles.includes('admin') ? {} : SENSITIVE_FIELDS;
+    return {
+        allow: true,
+        reason: 'allowed',
+        redactions,
+        maxArgsSize: 102400,
+    };
+}
+// ---------------------------------------------------------------------------
+// PolicyService — chooses OPA or fallback
+// ---------------------------------------------------------------------------
+class PolicyService {
+    opaUrl;
+    opaEnabled;
+    constructor(config) {
+        this.opaUrl = config.opaUrl;
+        this.opaEnabled = config.opaEnabled;
+    }
+    async evaluate(input) {
+        if (!this.opaEnabled) {
+            return fallbackPolicy(input);
+        }
+        try {
+            return await queryOPA(this.opaUrl, input);
+        }
+        catch (err) {
+            // OPA unreachable — fall back to built-in policy and log warning
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[policy] OPA unreachable (${msg}), using built-in fallback`);
+            return fallbackPolicy(input);
+        }
+    }
+}
+exports.PolicyService = PolicyService;

package/dist/services/ratelimit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Token-bucket rate limiter (in-memory, per actor:tool key).
+ *
+ * Each bucket starts at `capacity` tokens and refills at `refillPerMs` tokens/ms.
+ * A successful check consumes 1 token; if the bucket is empty the call is denied.
+ *
+ * NOTE: This is single-process only. For multi-replica deployments, swap to a
+ * shared store (Redis INCR + sliding-window, for example).
+ */
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    /** Approximate ms until at least one token is available */
+    retryAfterMs: number;
+}
+export declare class RateLimiter {
+    private readonly buckets;
+    private readonly capacity;
+    private readonly refillPerMs;
+    constructor(capacity: number, refillPerSecond: number);
+    check(key: string): RateLimitResult;
+    /** Prune stale buckets (call periodically to avoid unbounded memory growth) */
+    cleanup(maxIdleMs?: number): void;
+    /** For testing: reset all buckets */
+    reset(): void;
+}

package/dist/services/ratelimit.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Token-bucket rate limiter (in-memory, per actor:tool key).
+ *
+ * Each bucket starts at `capacity` tokens and refills at `refillPerMs` tokens/ms.
+ * A successful check consumes 1 token; if the bucket is empty the call is denied.
+ *
+ * NOTE: This is single-process only. For multi-replica deployments, swap to a
+ * shared store (Redis INCR + sliding-window, for example).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+class RateLimiter {
+    buckets = new Map();
+    capacity;
+    refillPerMs;
+    constructor(capacity, refillPerSecond) {
+        this.capacity = capacity;
+        this.refillPerMs = refillPerSecond / 1000;
+    }
+    check(key) {
+        // capacity === 0 disables rate limiting (every request allowed). Used by
+        // `oculi serve` on localhost so IDE hook bursts don't trip 429s.
+        if (this.capacity === 0) {
+            return { allowed: true, remaining: Number.POSITIVE_INFINITY, retryAfterMs: 0 };
+        }
+        const now = Date.now();
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = { tokens: this.capacity, lastRefillMs: now };
+            this.buckets.set(key, bucket);
+        }
+        // Refill based on elapsed time
+        const elapsedMs = now - bucket.lastRefillMs;
+        bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsedMs * this.refillPerMs);
+        bucket.lastRefillMs = now;
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            return { allowed: true, remaining: Math.floor(bucket.tokens), retryAfterMs: 0 };
+        }
+        // Denied: calculate wait time
+        const tokensNeeded = 1 - bucket.tokens;
+        const retryAfterMs = Math.ceil(tokensNeeded / this.refillPerMs);
+        return { allowed: false, remaining: 0, retryAfterMs };
+    }
+    /** Prune stale buckets (call periodically to avoid unbounded memory growth) */
+    cleanup(maxIdleMs = 3_600_000 /* 1 hour */) {
+        const cutoff = Date.now() - maxIdleMs;
+        for (const [key, bucket] of this.buckets) {
+            if (bucket.lastRefillMs < cutoff) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+    /** For testing: reset all buckets */
+    reset() {
+        this.buckets.clear();
+    }
+}
+exports.RateLimiter = RateLimiter;

package/dist/services/sanitizer.d.ts

@@ -0,0 +1,9 @@
+import { PolicyDecision } from '../types';
+/**
+ * Apply policy redactions and transforms to an upstream response payload.
+ *
+ * - redactions: remove keys from the top-level response object (and recursively
+ *   from nested objects)
+ * - transforms: apply truncation, masking, or removal to specific fields
+ */
+export declare function sanitizeResponse(payload: unknown, decision: PolicyDecision): unknown;

package/dist/services/sanitizer.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeResponse = sanitizeResponse;
+/**
+ * Apply policy redactions and transforms to an upstream response payload.
+ *
+ * - redactions: remove keys from the top-level response object (and recursively
+ *   from nested objects)
+ * - transforms: apply truncation, masking, or removal to specific fields
+ */
+function sanitizeResponse(payload, decision) {
+    if (payload === null || payload === undefined)
+        return payload;
+    if (typeof payload !== 'object')
+        return payload;
+    if (Array.isArray(payload)) {
+        return payload.map((item) => sanitizeResponse(item, decision));
+    }
+    const obj = payload;
+    const result = {};
+    const redactions = decision.redactions ?? {};
+    const transforms = decision.transforms ?? {};
+    for (const [key, value] of Object.entries(obj)) {
+        // Apply transform first (takes precedence)
+        if (transforms[key]) {
+            const transformed = applyTransform(value, transforms[key]);
+            if (transformed !== REMOVED) {
+                result[key] = transformed;
+            }
+            continue;
+        }
+        // Apply redaction
+        if (redactions[key]) {
+            // Replace value with placeholder rather than deleting the key,
+            // so callers know a redaction occurred.
+            result[key] = '[REDACTED]';
+            continue;
+        }
+        // Recurse into nested objects
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = sanitizeResponse(value, decision);
+        }
+        else if (Array.isArray(value)) {
+            result[key] = value.map((item) => sanitizeResponse(item, decision));
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+const REMOVED = Symbol('REMOVED');
+function applyTransform(value, transform) {
+    switch (transform.type) {
+        case 'remove':
+            return REMOVED;
+        case 'mask':
+            if (typeof value === 'string') {
+                return transform.mask ?? '***';
+            }
+            return '***';
+        case 'truncate':
+            if (typeof value === 'string') {
+                const max = transform.maxLength ?? 1000;
+                if (value.length > max) {
+                    return value.slice(0, max) + `...[truncated ${value.length - max} chars]`;
+                }
+            }
+            return value;
+        default:
+            return value;
+    }
+}

package/dist/services/sqlite-loader.d.ts

@@ -0,0 +1,4 @@
+import type Database from 'better-sqlite3';
+type DatabaseCtor = typeof Database;
+export declare function loadSqlite(): DatabaseCtor;
+export {};

package/dist/services/sqlite-loader.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSqlite = loadSqlite;
+let cached = null;
+function loadSqlite() {
+    if (cached)
+        return cached;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        cached = require('better-sqlite3');
+        return cached;
+    }
+    catch {
+        throw new Error('better-sqlite3 is not installed. The Oculi gateway server requires a C++ toolchain to build. See https://oculisecurity.com/docs/gateway-install for setup, or use the CLI in local-policy-only mode.');
+    }
+}

package/dist/services/telemetry-log.d.ts

@@ -0,0 +1,76 @@
+import { OculiEvent } from '../routes/adapters/schema';
+export interface TelemetryLogEntry {
+    schema_version: string;
+    ide_source: string;
+    actor: string;
+    org_id: string;
+    hook_event_name: string;
+    phase: string;
+    session_id: string;
+    trace_id?: string;
+    tool?: string;
+    tool_args?: Record<string, unknown>;
+    file_path?: string;
+    shell_command?: string;
+    mcp_server?: string;
+    timestamp: string;
+    duration_ms?: number;
+    error?: string;
+    context?: {
+        workspace?: string;
+        conversation_id?: string;
+    };
+    action?: {
+        command?: string;
+        content_hash?: string;
+    };
+    policy_decision: 'allow' | 'warn' | 'deny';
+    policy_rule_ids: string[];
+}
+/**
+ * Find the nearest `.oculi/` directory by walking up from `startDir`.
+ * If none is found, creates `.oculi/` in startDir (or cwd).
+ */
+export declare function findOrCreateOculiDir(startDir?: string): string;
+/**
+ * Find existing `.oculi/telemetry.jsonl` by walking up. Returns null if none exists.
+ */
+export declare function findTelemetryLog(startDir?: string): string | null;
+/**
+ * Convert an OculiEvent + policy decision into a log entry (omitting raw_payload).
+ */
+export declare function eventToLogEntry(event: OculiEvent, decision: 'allow' | 'warn' | 'deny', ruleIds?: string[]): TelemetryLogEntry;
+/**
+ * Append a telemetry log entry to `.oculi/telemetry.jsonl`.
+ * Handles rotation automatically.
+ */
+export declare function appendTelemetry(entry: TelemetryLogEntry, oculiDir?: string): string;
+export interface ReadOptions {
+    since?: Date;
+    filter?: 'allow' | 'warn' | 'deny';
+}
+/**
+ * Read telemetry log entries from a file with optional filtering.
+ */
+export declare function readTelemetryLines(logPath: string, opts?: ReadOptions): TelemetryLogEntry[];
+/**
+ * Get the path to the telemetry log file (creating .oculi/ dir if needed).
+ */
+export declare function getTelemetryLogPath(oculiDir?: string): string;
+export interface OffsetReadResult {
+    entries: TelemetryLogEntry[];
+    /** End offset after the last fully-read line (suitable as the next checkpoint). */
+    newOffset: number;
+    /** Number of lines that failed to parse as JSON. */
+    skipped: number;
+    /** True iff the file was smaller than the requested offset — likely rotated. */
+    rotated: boolean;
+}
+/**
+ * Read telemetry entries starting at a byte offset. Used for incremental
+ * replay into sqlite — caller persists `newOffset` to resume next time.
+ *
+ * If the file is shorter than `offset` (rotation happened since last read),
+ * starts from byte 0 and reports `rotated: true`.
+ */
+export declare function readTelemetryLinesFromOffset(filePath: string, offset: number): OffsetReadResult;

package/dist/services/telemetry-log.js

@@ -0,0 +1,260 @@
+"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.findOrCreateOculiDir = findOrCreateOculiDir;
+exports.findTelemetryLog = findTelemetryLog;
+exports.eventToLogEntry = eventToLogEntry;
+exports.appendTelemetry = appendTelemetry;
+exports.readTelemetryLines = readTelemetryLines;
+exports.getTelemetryLogPath = getTelemetryLogPath;
+exports.readTelemetryLinesFromOffset = readTelemetryLinesFromOffset;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// ---------------------------------------------------------------------------
+// Directory discovery
+// ---------------------------------------------------------------------------
+const LOG_FILENAME = 'telemetry.jsonl';
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
+const MAX_ROTATIONS = 5;
+/**
+ * Find the nearest `.oculi/` directory by walking up from `startDir`.
+ * If none is found, creates `.oculi/` in startDir (or cwd).
+ */
+function findOrCreateOculiDir(startDir) {
+    let dir = startDir ?? process.cwd();
+    // Walk up to find existing .oculi/
+    let search = dir;
+    while (true) {
+        const candidate = path.join(search, '.oculi');
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+        const parent = path.dirname(search);
+        if (parent === search)
+            break;
+        search = parent;
+    }
+    // Check home directory
+    const globalDir = path.join(os.homedir(), '.oculi');
+    if (fs.existsSync(globalDir) && fs.statSync(globalDir).isDirectory()) {
+        return globalDir;
+    }
+    // Create in the starting directory
+    const newDir = path.join(dir, '.oculi');
+    fs.mkdirSync(newDir, { recursive: true });
+    return newDir;
+}
+/**
+ * Find existing `.oculi/telemetry.jsonl` by walking up. Returns null if none exists.
+ */
+function findTelemetryLog(startDir) {
+    let dir = startDir ?? process.cwd();
+    while (true) {
+        const candidate = path.join(dir, '.oculi', LOG_FILENAME);
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const globalPath = path.join(os.homedir(), '.oculi', LOG_FILENAME);
+    if (fs.existsSync(globalPath))
+        return globalPath;
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Rotation
+// ---------------------------------------------------------------------------
+function rotatedName(dir, n) {
+    return path.join(dir, `telemetry.${n}.jsonl`);
+}
+function rotateIfNeeded(logPath) {
+    if (!fs.existsSync(logPath))
+        return;
+    let size;
+    try {
+        size = fs.statSync(logPath).size;
+    }
+    catch {
+        return;
+    }
+    if (size < MAX_FILE_SIZE)
+        return;
+    const dir = path.dirname(logPath);
+    // Delete oldest if at cap
+    const oldest = rotatedName(dir, MAX_ROTATIONS);
+    if (fs.existsSync(oldest)) {
+        fs.unlinkSync(oldest);
+    }
+    // Shift existing rotated files up: N → N+1
+    for (let i = MAX_ROTATIONS - 1; i >= 1; i--) {
+        const from = rotatedName(dir, i);
+        const to = rotatedName(dir, i + 1);
+        if (fs.existsSync(from)) {
+            fs.renameSync(from, to);
+        }
+    }
+    // Rename current → .1
+    fs.renameSync(logPath, rotatedName(dir, 1));
+}
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+/**
+ * Convert an OculiEvent + policy decision into a log entry (omitting raw_payload).
+ */
+function eventToLogEntry(event, decision, ruleIds = []) {
+    return {
+        schema_version: event.schema_version,
+        ide_source: event.ide_source,
+        actor: event.actor,
+        org_id: event.org_id,
+        hook_event_name: event.hook_event_name,
+        phase: event.phase,
+        session_id: event.session_id,
+        trace_id: event.trace_id,
+        tool: event.tool,
+        tool_args: event.tool_args,
+        file_path: event.file_path,
+        shell_command: event.shell_command,
+        mcp_server: event.mcp_server,
+        timestamp: event.timestamp,
+        duration_ms: event.duration_ms,
+        error: event.error,
+        context: event.context,
+        action: event.action,
+        policy_decision: decision,
+        policy_rule_ids: ruleIds,
+    };
+}
+/**
+ * Append a telemetry log entry to `.oculi/telemetry.jsonl`.
+ * Handles rotation automatically.
+ */
+function appendTelemetry(entry, oculiDir) {
+    const dir = oculiDir ?? findOrCreateOculiDir();
+    const logPath = path.join(dir, LOG_FILENAME);
+    rotateIfNeeded(logPath);
+    const line = JSON.stringify(entry) + '\n';
+    fs.appendFileSync(logPath, line, 'utf8');
+    return logPath;
+}
+/**
+ * Read telemetry log entries from a file with optional filtering.
+ */
+function readTelemetryLines(logPath, opts = {}) {
+    if (!fs.existsSync(logPath))
+        return [];
+    const raw = fs.readFileSync(logPath, 'utf8');
+    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+    const entries = [];
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (opts.since && new Date(entry.timestamp) < opts.since)
+                continue;
+            if (opts.filter && entry.policy_decision !== opts.filter)
+                continue;
+            entries.push(entry);
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return entries;
+}
+/**
+ * Get the path to the telemetry log file (creating .oculi/ dir if needed).
+ */
+function getTelemetryLogPath(oculiDir) {
+    const dir = oculiDir ?? findOrCreateOculiDir();
+    return path.join(dir, LOG_FILENAME);
+}
+/**
+ * Read telemetry entries starting at a byte offset. Used for incremental
+ * replay into sqlite — caller persists `newOffset` to resume next time.
+ *
+ * If the file is shorter than `offset` (rotation happened since last read),
+ * starts from byte 0 and reports `rotated: true`.
+ */
+function readTelemetryLinesFromOffset(filePath, offset) {
+    if (!fs.existsSync(filePath)) {
+        return { entries: [], newOffset: offset, skipped: 0, rotated: false };
+    }
+    const size = fs.statSync(filePath).size;
+    let rotated = false;
+    let startOffset = offset;
+    if (size < offset) {
+        rotated = true;
+        startOffset = 0;
+    }
+    if (size === startOffset) {
+        return { entries: [], newOffset: startOffset, skipped: 0, rotated };
+    }
+    const fd = fs.openSync(filePath, 'r');
+    const length = size - startOffset;
+    const buf = Buffer.alloc(length);
+    try {
+        fs.readSync(fd, buf, 0, length, startOffset);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const text = buf.toString('utf8');
+    // If the file does NOT end in a newline, the trailing fragment is a
+    // half-written line — don't consume it. The next read will pick it up.
+    const lastNewlineRel = text.lastIndexOf('\n');
+    if (lastNewlineRel === -1) {
+        // No complete line in this slice yet — leave offset unchanged.
+        return { entries: [], newOffset: offset, skipped: 0, rotated };
+    }
+    const consumed = text.slice(0, lastNewlineRel + 1);
+    const newOffset = startOffset + Buffer.byteLength(consumed, 'utf8');
+    const entries = [];
+    let skipped = 0;
+    for (const line of consumed.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            skipped++;
+        }
+    }
+    return { entries, newOffset, skipped, rotated };
+}