orca-opencode-plugin 1.1.0

package/README.md

@@ -0,0 +1,189 @@
+# Orca OpenCode Plugin
+
+OpenCode plugin wrapper for Orca runtime guardrails.
+
+## What this plugin does
+
+This plugin adds Orca-native lifecycle hooks to OpenCode. It lets OpenCode call the Orca CLI for policy checks, audit logging, and runtime safety decisions without duplicating policy logic.
+
+The plugin is a thin integration layer. The Orca CLI remains the source of truth for all policy decisions.
+
+## Prerequisites
+
+- Orca CLI built and available in PATH (run `orca doctor` to verify)
+- OpenCode host installed
+
+Orca must be installed separately. The plugin does not bundle the Orca CLI.
+
+## Install from npm
+
+Add to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["orca-opencode-plugin"]
+}
+```
+
+Then install dependencies:
+
+```bash
+npm install orca-opencode-plugin
+```
+
+The strongest local protection remains running OpenCode through `orca run -- opencode`; the OpenCode plugin provides native hooks and guardrails inside OpenCode.
+
+## Install from local path
+
+If you prefer to use the plugin directly from the Orca repository:
+
+### Project-local install
+
+Copy or symlink this directory into your project:
+
+```bash
+# From the Orca repo root
+mkdir -p .opencode/plugins
+cp integrations/opencode-plugin/orca.ts .opencode/plugins/orca.ts
+```
+
+See `examples/project-plugin-path.md` for details.
+
+### Global install
+
+Copy or symlink to the OpenCode global plugins directory:
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp integrations/opencode-plugin/orca.ts ~/.config/opencode/plugins/orca.ts
+```
+
+See `examples/global-plugin-path.md` for details.
+
+### Verify the plugin is recognized
+
+```bash
+orca plugin doctor opencode
+```
+
+## Verify install
+
+Run the Orca plugin doctor:
+
+```bash
+orca plugin doctor opencode
+```
+
+Expected output sections:
+- Orca version
+- Policy status (present/valid)
+- Plugin directories (opencode: found)
+- Host binaries (opencode: detected or not detected)
+
+## Hooks included
+
+The plugin registers lifecycle hooks that call `orca hook opencode <event>`:
+
+| Event | When it fires | Behavior |
+|-------|---------------|----------|
+| `session.created` | At the start of an OpenCode session | Informational (readiness log) |
+| `tool.execute.before` | Before OpenCode invokes a tool | **Blocking** — Orca can prevent the tool call |
+| `tool.execute.after` | After OpenCode finishes using a tool | Informational (audit only) |
+| `permission.asked` | When OpenCode requests user permission | **Blocking** — Orca can deny the permission |
+| `file.edited` | When a file is edited by OpenCode | Informational (audit only) |
+| `command.executed` | When a shell command is executed | Informational (audit only) |
+| `session.updated` | When the session state changes | Informational (audit only) |
+| `session.idle` | When the session becomes idle | Informational (audit only) |
+| `session.error` | When a session error occurs | Informational (audit only) |
+| `shell.env` | When the shell environment is read | Informational (secrets redacted) |
+
+## How hooks call Orca
+
+Each hook sends a JSON payload to `orca hook opencode <event>` via stdin and reads a JSON decision from stdout. The plugin preserves OpenCode's expected return values. Human-readable logs go to stderr.
+
+Example payload for `tool.execute.before`:
+
+```json
+{
+  "version": 1,
+  "host": "opencode",
+  "event": "PreToolUse",
+  "payload": {
+    "tool": "shell",
+    "command": "git status"
+  },
+  "session_id": "session-uuid",
+  "timestamp": "2026-01-01T00:00:00Z"
+}
+```
+
+Example response:
+
+```json
+{
+  "version": 1,
+  "decision": "allow",
+  "risk": "low",
+  "category": "command",
+  "reason": "policy_allow",
+  "message": "Allowed by policy"
+}
+```
+
+If the decision is `block`, the plugin throws an error that prevents the tool from executing.
+
+## Run redteam
+
+```bash
+orca redteam --ci
+```
+
+## Replay sessions
+
+```bash
+orca replay --session last --verify
+```
+
+## Uninstall
+
+Remove the plugin from your OpenCode configuration:
+
+```bash
+# npm package
+npm uninstall orca-opencode-plugin
+
+# Project-local file
+rm .opencode/plugins/orca.ts
+
+# Global file
+rm ~/.config/opencode/plugins/orca.ts
+```
+
+This plugin does not mutate host configuration, so uninstalling is safe.
+
+## Known limitations
+
+- Hooks are advisory for informational events; blocking hooks depend on OpenCode honoring thrown errors.
+- The strongest protection remains `orca run -- opencode`.
+- Plugin installation depends on OpenCode version and plugin loading mechanism.
+- No telemetry is collected.
+- Official npm publication is in progress; the package structure is ready for publication.
+
+## Security model
+
+- This plugin calls the Orca CLI; it does not reimplement policy logic.
+- No raw secrets are persisted in plugin files.
+- Secrets are redacted from payloads before sending to Orca (keys matching `password`, `token`, `secret`, `api_key`, etc. are replaced with `[REDACTED]`).
+- Hook return values remain valid for OpenCode parsing.
+- Human logs go to stderr.
+- CI mode never prompts.
+- This plugin does not claim stronger enforcement than OpenCode hooks support.
+
+## No MCP server behavior
+
+The OpenCode plugin does not add MCP server behavior or drone-specific plugin features.
+
+## Strongest protection warning
+
+> The Orca OpenCode plugin adds lifecycle hooks for OpenCode. For the strongest local protection, run the OpenCode process itself through Orca with `orca run -- opencode`.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+interface OpenCodeContext {
+    hooks: {
+        on: (event: string, handler: (data: unknown) => unknown | Promise<unknown>) => void;
+    };
+    shell?: {
+        $: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<{
+            stdout: string;
+            stderr: string;
+            exitCode: number;
+        }>;
+    };
+    logger?: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+    session?: {
+        id?: string;
+        cwd?: string;
+    };
+}
+export default function orcaPlugin(context: OpenCodeContext): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,UAAU,eAAe;IACvB,KAAK,EAAE;QACL,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;KACrF,CAAC;IACF,KAAK,CAAC,EAAE;QACN,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC3H,CAAC;IACF,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;KAC9B,CAAC;IACF,OAAO,CAAC,EAAE;QACR,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAgID,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CA6FjE"}

package/dist/index.js

@@ -0,0 +1,179 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+const SECRET_KEYS = [
+    'password', 'token', 'secret', 'api_key', 'apikey', 'api_secret',
+    'auth', 'authorization', 'bearer', 'private_key', 'access_token',
+    'refresh_token', 'credential', 'passwd', 'pwd',
+];
+function redactSecrets(data) {
+    if (data === null || data === undefined)
+        return data;
+    if (typeof data === 'string')
+        return data;
+    if (Array.isArray(data))
+        return data.map(redactSecrets);
+    if (typeof data !== 'object')
+        return data;
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+        if (SECRET_KEYS.some((s) => lowerKey.includes(s))) {
+            result[key] = '[REDACTED]';
+        }
+        else {
+            result[key] = redactSecrets(value);
+        }
+    }
+    return result;
+}
+function buildPayload(event, data, sessionId) {
+    return {
+        version: 1,
+        host: 'opencode',
+        event,
+        payload: redactSecrets(data),
+        session_id: sessionId,
+        timestamp: new Date().toISOString(),
+    };
+}
+function findOrca(cwd) {
+    try {
+        const which = execSync('which orca', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+        const bin = which.trim();
+        if (bin)
+            return bin;
+    }
+    catch {
+        // orca not in PATH
+    }
+    const candidates = [
+        cwd ? join(cwd, 'zig-out', 'bin', 'orca') : null,
+        cwd ? join(cwd, '..', 'zig-out', 'bin', 'orca') : null,
+        cwd ? join(cwd, '..', '..', 'zig-out', 'bin', 'orca') : null,
+        resolve('zig-out', 'bin', 'orca'),
+        resolve('..', 'zig-out', 'bin', 'orca'),
+        resolve('..', '..', 'zig-out', 'bin', 'orca'),
+    ].filter((p) => p !== null);
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+async function callOrca(orcaBin, event, data, sessionId, blocking, shell, logger) {
+    const payload = buildPayload(event, data, sessionId);
+    const payloadJson = JSON.stringify(payload);
+    let stdout = '';
+    try {
+        if (shell?.$) {
+            const result = await shell.$ `echo ${payloadJson} | ${orcaBin} hook opencode ${event}`;
+            stdout = result.stdout ?? '';
+        }
+        else {
+            stdout = execSync(`${orcaBin} hook opencode ${event}`, {
+                input: payloadJson,
+                encoding: 'utf-8',
+                timeout: blocking ? 15000 : 10000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        if (!stdout.trim()) {
+            return { decision: 'allow' };
+        }
+        return JSON.parse(stdout);
+    }
+    catch (err) {
+        const safeErr = redactSecrets({ message: err.message });
+        logger?.error?.(`[orca] Hook ${event} failed: ${safeErr.message}`);
+        return blocking
+            ? {
+                decision: 'block',
+                risk: 'high',
+                category: 'unknown',
+                reason: 'orca_hook_error',
+                message: 'Orca hook failed; blocking as a precaution.',
+            }
+            : {
+                decision: 'allow',
+                risk: 'unknown',
+                category: 'unknown',
+                reason: 'orca_hook_error',
+                message: 'Orca hook failed; allowing because this event is non-blocking.',
+            };
+    }
+}
+export default function orcaPlugin(context) {
+    const cwd = context.session?.cwd ?? process.cwd();
+    const sessionId = context.session?.id;
+    const orcaBin = findOrca(cwd);
+    const { shell, logger } = context;
+    if (!orcaBin) {
+        logger?.warn?.('[orca] Binary not found in PATH or typical build paths. ' +
+            'Build with: zig build (produces ./zig-out/bin/orca)');
+        return;
+    }
+    logger?.info?.(`[orca] Plugin loaded. Binary: ${orcaBin}`);
+    context.hooks.on('session.created', async (session) => {
+        logger?.info?.('[orca] Plugin ready for session.');
+        await callOrca(orcaBin, 'SessionStart', { session_id: session?.id }, sessionId, false, shell, logger);
+    });
+    context.hooks.on('tool.execute.before', async (toolCall) => {
+        const response = await callOrca(orcaBin, 'PreToolUse', toolCall, sessionId, true, shell, logger);
+        if (response.decision === 'block') {
+            const msg = response.message || response.reason || 'Blocked by Orca policy';
+            logger?.error?.(`[orca] Blocked tool execution: ${msg}`);
+            throw new Error(`Orca blocked tool execution: ${msg}`);
+        }
+        if (response.decision === 'warn') {
+            logger?.warn?.(`[orca] Warning: ${response.message || response.reason}`);
+        }
+        return toolCall;
+    });
+    context.hooks.on('tool.execute.after', async (result) => {
+        await callOrca(orcaBin, 'PostToolUse', result, sessionId, false, shell, logger);
+        return result;
+    });
+    context.hooks.on('permission.asked', async (permission) => {
+        const response = await callOrca(orcaBin, 'PermissionRequest', permission, sessionId, true, shell, logger);
+        if (response.decision === 'block') {
+            const msg = response.message || response.reason || 'Blocked by Orca policy';
+            logger?.error?.(`[orca] Blocked permission: ${msg}`);
+            throw new Error(`Orca blocked permission request: ${msg}`);
+        }
+        if (response.decision === 'warn') {
+            logger?.warn?.(`[orca] Permission warning: ${response.message || response.reason}`);
+        }
+        return permission;
+    });
+    context.hooks.on('file.edited', async (edit) => {
+        await callOrca(orcaBin, 'FileEdit', edit, sessionId, false, shell, logger);
+        return edit;
+    });
+    context.hooks.on('command.executed', async (command) => {
+        await callOrca(orcaBin, 'CommandExecuted', command, sessionId, false, shell, logger);
+        return command;
+    });
+    context.hooks.on('session.updated', async (session) => {
+        await callOrca(orcaBin, 'SessionUpdate', session, sessionId, false, shell, logger);
+        return session;
+    });
+    context.hooks.on('session.idle', async (session) => {
+        await callOrca(orcaBin, 'SessionIdle', session, sessionId, false, shell, logger);
+        return session;
+    });
+    context.hooks.on('session.error', async (error) => {
+        const safeError = redactSecrets({
+            message: error?.message,
+            stack: error?.stack,
+            type: error?.type,
+        });
+        await callOrca(orcaBin, 'SessionError', safeError, sessionId, false, shell, logger);
+        return error;
+    });
+    context.hooks.on('shell.env', async (env) => {
+        const safeEnv = redactSecrets(env);
+        await callOrca(orcaBin, 'ShellEnv', safeEnv, sessionId, false, shell, logger);
+        return env;
+    });
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "orca-opencode-plugin",
+  "version": "1.1.0",
+  "description": "OpenCode plugin wrapper for Orca runtime guardrails.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "orca",
+    "ai-agents",
+    "security",
+    "guardrails"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chriskarani/orca.git"
+  },
+  "homepage": "https://github.com/chriskarani/orca#readme",
+  "bugs": {
+    "url": "https://github.com/chriskarani/orca/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "typescript": "^6.0.3"
+  }
+}