custodex 1.0.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "custodex",
+  "version": "1.0.0",
+  "description": "Universal AI agent governance — one command to govern Claude, Cursor, Gemini CLI, and OpenCode",
+  "type": "module",
+  "bin": { "custodex": "dist/index.js" },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["ai-governance", "mcp", "claude", "cursor", "gemini", "agent-security"],
+  "author": "Custodex",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "files": ["dist/", "hooks/", "plugins/"]
+}

package/plugins/custodex-opencode.ts

@@ -0,0 +1,330 @@
+/**
+ * OpenCode Plugin for Custodex AI Governance
+ *
+ * Provides mandatory pre-execution verification and post-execution telemetry
+ * for every tool call made by OpenCode sessions. Installed automatically by
+ * `npx custodex` into ~/.config/opencode/plugins/custodex-opencode.ts.
+ *
+ * Runtime: Bun (used by OpenCode). Uses native fetch — zero dependencies.
+ *
+ * Config resolution order:
+ *   1. ~/.custodex/config.json  { apiKey, baseUrl }
+ *   2. CUSTODEX_API_KEY + CUSTODEX_BASE_URL environment variables
+ *   3. Warn and return empty hooks (graceful no-op)
+ */
+
+import { readFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Shape of ~/.custodex/config.json */
+interface CustodexConfig {
+  apiKey: string;
+  baseUrl: string;
+}
+
+/** Custodex /api/verify response */
+interface VerifyResponse {
+  decision: "allowed" | "denied";
+  reason?: string;
+  enforcementLevel?: "warn" | "throttle" | "block" | "suspend";
+  violatedPolicies?: string[];
+}
+
+/** Custodex /api/agents/register response */
+interface RegisterResponse {
+  agentId: string;
+  name: string;
+  status: string;
+}
+
+/** OpenCode session.created event payload */
+interface SessionCreatedInput {
+  sessionId?: string;
+  [key: string]: unknown;
+}
+
+/** OpenCode tool.execute.before event payload */
+interface ToolExecuteInput {
+  tool?: string;
+  [key: string]: unknown;
+}
+
+/** OpenCode tool.execute args/output payload */
+interface ToolExecuteOutput {
+  args?: Record<string, unknown>;
+  result?: unknown;
+  [key: string]: unknown;
+}
+
+/** OpenCode plugin context object */
+interface OpenCodeContext {
+  project?: string;
+  directory?: string;
+  [key: string]: unknown;
+}
+
+// ─── Config Loading ───────────────────────────────────────────────────────────
+
+/**
+ * Load Custodex configuration from disk or environment variables.
+ *
+ * Tries ~/.custodex/config.json first, falls back to env vars.
+ * Returns null if neither source provides both apiKey and baseUrl.
+ */
+function loadConfig(): CustodexConfig | null {
+  const configPath = join(homedir(), ".custodex", "config.json");
+
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw) as Partial<CustodexConfig>;
+    if (parsed.apiKey && parsed.baseUrl) {
+      return { apiKey: parsed.apiKey, baseUrl: parsed.baseUrl };
+    }
+  } catch {
+    // File does not exist or is not valid JSON — fall through to env vars
+  }
+
+  const apiKey = process.env["CUSTODEX_API_KEY"];
+  const baseUrl = process.env["CUSTODEX_BASE_URL"];
+
+  if (apiKey && baseUrl) {
+    return { apiKey, baseUrl };
+  }
+
+  return null;
+}
+
+// ─── HTTP Client ──────────────────────────────────────────────────────────────
+
+/**
+ * Send a POST request to the Custodex API.
+ *
+ * Uses native fetch (available in Node 18+ / Bun). Times out after 4 seconds.
+ * Returns parsed JSON on success or null on any error (network, timeout, non-2xx).
+ *
+ * @param config - Custodex API configuration
+ * @param path   - API path, e.g. "/api/verify"
+ * @param body   - JSON-serialisable request body
+ */
+async function custodexFetch(
+  config: CustodexConfig,
+  path: string,
+  body: object
+): Promise<unknown> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 4_000);
+
+  try {
+    const response = await fetch(`${config.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return (await response.json()) as unknown;
+  } catch {
+    // Network error, timeout, or parse failure — treat as null
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// ─── Tool → Action / Scope Mapping ───────────────────────────────────────────
+
+/**
+ * Map an OpenCode tool name to a Custodex action string.
+ *
+ * @param tool - The tool name reported by OpenCode (e.g. "Write", "Bash")
+ */
+function mapToolToAction(tool: string): string {
+  if (/write|edit|patch/i.test(tool)) return "file:write";
+  if (/read/i.test(tool)) return "file:read";
+  if (/bash|shell|exec/i.test(tool)) return "shell:execute";
+  if (/glob|grep|search|find/i.test(tool)) return "file:search";
+  if (/fetch|web|http/i.test(tool)) return "web:access";
+  if (/agent|task|spawn/i.test(tool)) return "agent:spawn";
+  return "tool:use";
+}
+
+/**
+ * Map an OpenCode tool name to a Custodex scope string.
+ *
+ * @param tool - The tool name reported by OpenCode
+ */
+function mapToolToScope(tool: string): string {
+  if (/write|edit|patch/i.test(tool)) return "file:write";
+  if (/read/i.test(tool)) return "file:read";
+  if (/bash|shell|exec/i.test(tool)) return "shell:execute";
+  if (/glob|grep|search|find/i.test(tool)) return "file:search";
+  if (/fetch|web|http/i.test(tool)) return "web:access";
+  return "tool:use";
+}
+
+// ─── State ────────────────────────────────────────────────────────────────────
+
+/**
+ * In-memory map from OpenCode session ID → Custodex agent ID.
+ *
+ * OpenCode runs in a single process, so a module-level Map is safe.
+ * The key "current" is used when no explicit session ID is present.
+ */
+const agentIds = new Map<string, string>();
+
+/**
+ * Ensure the Custodex state directory exists.
+ * Created lazily on first session to avoid side-effects at import time.
+ */
+const stateDir = join(homedir(), ".custodex", "state");
+let stateDirEnsured = false;
+
+function ensureStateDir(): void {
+  if (!stateDirEnsured) {
+    mkdirSync(stateDir, { recursive: true });
+    stateDirEnsured = true;
+  }
+}
+
+// ─── Plugin Export ────────────────────────────────────────────────────────────
+
+/**
+ * CustodexGovernance — OpenCode plugin entry point.
+ *
+ * Receives the OpenCode context object and returns an event-hook map.
+ * All hooks are async. Throwing in `tool.execute.before` blocks the action.
+ *
+ * @param ctx - OpenCode context with project/directory metadata
+ */
+export const CustodexGovernance = async (ctx: OpenCodeContext): Promise<Record<string, unknown>> => {
+  const config = loadConfig();
+
+  if (!config) {
+    console.warn(
+      "[Custodex] No configuration found. " +
+      "Run `npx custodex` to set up governance, or set " +
+      "CUSTODEX_API_KEY and CUSTODEX_BASE_URL environment variables."
+    );
+    return {};
+  }
+
+  ensureStateDir();
+
+  return {
+    // ── Register agent on session creation ──────────────────────────────────
+    /**
+     * Called when OpenCode starts a new session.
+     *
+     * Registers an ephemeral agent with Custodex and stores the resulting
+     * agentId in module-level state for use by subsequent hooks.
+     */
+    "session.created": async (input: SessionCreatedInput): Promise<void> => {
+      const sessionKey = input.sessionId ?? "current";
+      const agentName = `${ctx.project ?? "unknown"}-opencode`;
+
+      const result = await custodexFetch(config, "/api/agents/register", {
+        name: agentName,
+        scopes: ["read", "write", "execute"],
+        metadata: {
+          source: "opencode-plugin",
+          project: ctx.directory ?? ctx.project ?? "unknown",
+          sessionId: sessionKey,
+        },
+        protocol: "mcp",
+      }) as RegisterResponse | null;
+
+      if (result?.agentId) {
+        agentIds.set(sessionKey, result.agentId);
+        // Always keep a "current" alias for hooks that don't receive sessionId
+        agentIds.set("current", result.agentId);
+      }
+    },
+
+    // ── MANDATORY: verify before tool execution ──────────────────────────────
+    /**
+     * Called synchronously before every tool invocation.
+     *
+     * Queries Custodex /api/verify with the mapped action and scope.
+     * If the decision is "denied", throws an Error to block the tool call.
+     * OpenCode treats a thrown error in this hook as a hard block.
+     *
+     * A null response (API down / timeout) defaults to allow so that a
+     * Custodex outage does not halt developer workflows. Change to throw
+     * if your policy requires fail-closed behaviour.
+     */
+    "tool.execute.before": async (
+      input: ToolExecuteInput,
+      output: ToolExecuteOutput
+    ): Promise<void> => {
+      const agentId = agentIds.get("current");
+      const toolName = input.tool ?? "unknown";
+      const action = mapToolToAction(toolName);
+      const scope = mapToolToScope(toolName);
+
+      // Truncate tool args to avoid sending large payloads
+      const toolInput = JSON.stringify(output.args ?? {}).slice(0, 500);
+
+      const result = await custodexFetch(config, "/api/verify", {
+        action,
+        scope,
+        metadata: {
+          agentId,
+          toolName,
+          toolInput,
+          source: "opencode",
+        },
+      }) as VerifyResponse | null;
+
+      if (result?.decision === "denied") {
+        throw new Error(
+          `[Custodex] Governance denied: ${result.reason ?? "Policy violation"}` +
+          (result.violatedPolicies?.length
+            ? ` (policies: ${result.violatedPolicies.join(", ")})`
+            : "")
+        );
+      }
+    },
+
+    // ── Log telemetry after tool execution (fire-and-forget) ─────────────────
+    /**
+     * Called after every tool invocation completes (success or error).
+     *
+     * Posts telemetry to Custodex asynchronously — never awaited, never
+     * allowed to propagate errors. A failure here must not affect the session.
+     */
+    "tool.execute.after": async (
+      input: ToolExecuteInput,
+      _output: ToolExecuteOutput
+    ): Promise<void> => {
+      const agentId = agentIds.get("current");
+      const toolName = input.tool ?? "unknown";
+      const action = mapToolToAction(toolName);
+      const scope = mapToolToScope(toolName);
+
+      // Fire-and-forget: intentionally not awaited
+      custodexFetch(config, "/api/telemetry", {
+        action,
+        scope,
+        decision: "allowed",
+        latencyMs: 0,
+        metadata: {
+          agentId,
+          toolName,
+          source: "opencode",
+        },
+      }).catch((): void => {
+        // Silently discard telemetry errors — never block the session
+      });
+    },
+  };
+};