pi-opa-net 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-opa-net",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OPA-backed bash command guard for the pi ecosystem — structured decision-output.v1 JSON, fail-open default, Claude Code hook protocol compatible. Agent-agnostic engine + CLI.",
   "type": "module",
   "main": "src/index.ts",
@@ -45,7 +45,9 @@
     "unlock-keys"
   ],
   "pi": {
-    "skills": ["./skills"]
+    "skills": [
+      "./skills"
+    ]
   },
   "dependencies": {
     "ajv": "^8.17.1",

package/src/pi/audit.ts

@@ -0,0 +1,81 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { DecisionOutput } from '../output/DecisionBuilder.ts';
+
+/**
+ * Redact common secret patterns from a command string before audit.
+ * - Bearer tokens / Authorization headers
+ * - API keys (sk-... long hex/alnum)
+ */
+export function redactSecrets(text: string): string {
+  let out = text;
+  // Authorization: Bearer <token>
+  out = out.replace(/(Bearer\s+)([A-Za-z0-9._\-]+)/gi, '$1[REDACTED]');
+  // Generic sk-<token> (Stripe/Anthropic/etc API keys)
+  out = out.replace(/\bsk-[A-Za-z0-9_\-]{6,}/g, 'sk-[REDACTED]');
+  return out;
+}
+
+/**
+ * Audit sink bridge — writes one JSONL line per decision.
+ *
+ * Test/unit injectable: tests pass an `auditSink` with a captured `write`.
+ * Production wires this to a real filesystem sink (JSONL append).
+ */
+export interface AuditSink {
+  write: (entry: unknown) => Promise<void>;
+}
+
+export interface WriteAuditEntryInput {
+  sessionId: string | undefined;
+  decision: Pick<
+    DecisionOutput,
+    'decision' | 'source' | 'reasons' | 'input' | 'evaluated_at' | 'decision_id'
+  >;
+  auditSink: AuditSink;
+}
+
+interface AuditEntry {
+  decision_id: string;
+  decision: string;
+  source: string;
+  command: string;
+  rule_ids: string[];
+  evaluated_at: string;
+}
+
+export async function writeAuditEntry(input: WriteAuditEntryInput): Promise<void> {
+  if (!input.sessionId) return;
+
+  const entry: AuditEntry = {
+    decision_id: input.decision.decision_id,
+    decision: input.decision.decision,
+    source: input.decision.source,
+    command: redactSecrets(input.decision.input.raw),
+    rule_ids: input.decision.reasons.map((r) => r.rule_id),
+    evaluated_at: input.decision.evaluated_at,
+  };
+
+  await input.auditSink.write(entry);
+}
+
+/**
+ * Default filesystem audit sink — appends JSONL to `${cwd}/.pi-opa-net/audit/${decision_id}.jsonl`.
+ * Production wires this when ctx.auditSink is not injected.
+ */
+export function createFilesystemAuditSink(cwd: string): AuditSink {
+  const auditDir = resolve(cwd, '.pi-opa-net', 'audit');
+  return {
+    write: async (entry: unknown) => {
+      try {
+        mkdirSync(auditDir, { recursive: true });
+        const decisionId = (entry as { decision_id?: string }).decision_id ?? 'unknown';
+        const logPath = resolve(auditDir, `${decisionId}.jsonl`);
+        appendFileSync(logPath, `${JSON.stringify(entry)}\n`);
+      } catch {
+        // Audit write failure is non-fatal — log to stderr and continue.
+        console.error('[pi-opa-net] audit write failed, continuing without audit');
+      }
+    },
+  };
+}

package/src/pi/index.ts

@@ -0,0 +1,33 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { registerToolCallEvent } from './tool-call.ts';
+
+type PiExtensionApi = Parameters<typeof registerToolCallEvent>[0];
+
+/**
+ * Auto-discover the rule/policy config shipped alongside the pi agent.
+ *
+ * Mirrors pi-safety-net/src/pi/index.ts: derives agent dir from PI_CODING_AGENT_DIR
+ * or PI_SESSION_FILE (sessions/ parent), checks for a `<agentDir>/pi-opa-net/rules/`
+ * candidate, and sets PIOPANET_HOME so the engine picks it up zero-config.
+ */
+function autoDiscoverOpaNetHome(): void {
+  if (process.env.PIOPANET_HOME) return;
+  const agentDir =
+    process.env.PI_CODING_AGENT_DIR ||
+    (process.env.PI_SESSION_FILE && dirname(dirname(process.env.PI_SESSION_FILE)));
+  if (!agentDir) return;
+  const candidate = join(agentDir, 'pi-opa-net');
+  if (existsSync(join(candidate, 'rules'))) {
+    process.env.PIOPANET_HOME = candidate;
+  }
+}
+
+export default function piOpaNetExtension(pi: PiExtensionApi): void {
+  autoDiscoverOpaNetHome();
+  registerToolCallEvent(pi);
+}
+
+// Re-export for direct unit-test access.
+export { handlePiToolCall, registerToolCallEvent } from './tool-call.ts';
+export type { PiToolCallContext, PiToolCallResult } from './tool-call.ts';

package/src/pi/tool-call.ts

@@ -0,0 +1,193 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { DecisionOutput } from '../output/DecisionBuilder.ts';
+import { type AuditSink, createFilesystemAuditSink, writeAuditEntry } from './audit.ts';
+
+/** Fail-closed block reason — mirrors pi-safety-net's REASON_SAFETY_NET_FAILED_CLOSED. */
+export const REASON_OPA_NET_FAILED_CLOSED =
+  'OPA-Net fail-closed: command evaluation failed unexpectedly.';
+
+/** Reason prefix for malformed shell tool input. */
+const REASON_MALFORMED_SHELL_INPUT =
+  'OPA-Net fail-closed: shell tool call input missing required command field.';
+
+type PiApi = {
+  on: (
+    event: 'tool_call',
+    handler: (event: unknown, ctx: PiToolCallContext) => Promise<PiToolCallResult>,
+  ) => void;
+};
+
+export type EvalOpts = { cwd?: string; env?: NodeJS.ProcessEnv };
+
+export type PiToolCallContext = {
+  cwd: string;
+  sessionManager: {
+    getSessionFile: () => string | undefined;
+  };
+  /**
+   * Inject-able eval function. Unit tests pass a stub. Production wires this
+   * to the real `bin/pi-opa-net.js eval` subprocess.
+   */
+  opaNetEvalCommand?: (command: string, opts?: EvalOpts) => Promise<DecisionOutput>;
+  /** Optional audit sink for test capture. Production wires filesystem sink. */
+  auditSink?: AuditSink;
+  /** Reserved for future config passthrough. */
+  opaNetConfigOptions?: Record<string, unknown>;
+};
+
+export type PiToolCallResult = { block: true; reason: string } | undefined;
+
+type PiToolCallEvent = {
+  type?: string;
+  toolName?: string;
+  input?: Record<string, unknown>;
+};
+
+type PiShellToolAdapter = {
+  commandField: string;
+  cwdField?: string;
+};
+
+const PI_SHELL_TOOL_ADAPTERS: Partial<Record<string, PiShellToolAdapter>> = {
+  bash: { commandField: 'command' },
+  Shell: { commandField: 'command', cwdField: 'working_directory' },
+};
+
+type PiShellToolCall = { command: string; cwd: string } | { malformed: true };
+
+export function registerToolCallEvent(pi: PiApi): void {
+  pi.on('tool_call', handlePiToolCall);
+}
+
+function isStrictMode(): boolean {
+  return process.env.PIOPANET_STRICT === '1';
+}
+
+/**
+ * Default subprocess eval — spawns `bin/pi-opa-net.js eval "<cmd>" --json`
+ * and parses stdout as DecisionOutput. This is the production bridge:
+ * without this, the handler has no way to evaluate commands.
+ *
+ * Mirrors pi-safety-net's `?? analyzeCommand` default.
+ */
+async function defaultEvalCommand(command: string, opts?: EvalOpts): Promise<DecisionOutput> {
+  const binPath = resolve(fileURLToPath(import.meta.url), '../../../bin/pi-opa-net.js');
+  const cwd = opts?.cwd ?? process.cwd();
+
+  return new Promise((accept, reject) => {
+    const child = spawn('bun', [binPath, 'eval', command, '--json'], {
+      cwd,
+      env: opts?.env ?? process.env,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on('data', (d: Buffer) => {
+      stderr += d.toString();
+    });
+    child.on('error', reject);
+    child.on('close', (code: number | null) => {
+      if (code !== 0 && code !== 2) {
+        // Exit code 0 = allow, 2 = deny. Anything else = subprocess error.
+        reject(new Error(`pi-opa-net eval exited ${code}: ${stderr}`));
+        return;
+      }
+      try {
+        const decision = JSON.parse(stdout.trim()) as DecisionOutput;
+        accept(decision);
+      } catch (err) {
+        reject(
+          new Error(`pi-opa-net eval non-JSON stdout: ${stdout.slice(0, 200)}\nstderr: ${stderr}`),
+        );
+      }
+    });
+  });
+}
+
+/** @internal — exported for test coverage */
+export async function handlePiToolCall(
+  event: unknown,
+  ctx: PiToolCallContext,
+): Promise<PiToolCallResult> {
+  const shellToolCall = getPiShellToolCall(event, ctx);
+  if (!shellToolCall) return undefined;
+
+  if ('malformed' in shellToolCall) {
+    return blockPiToolCall(REASON_MALFORMED_SHELL_INPUT);
+  }
+
+  const { command, cwd } = shellToolCall;
+
+  // Use injected eval OR default subprocess eval.
+  const evalCommand = ctx.opaNetEvalCommand ?? defaultEvalCommand;
+
+  let decision: DecisionOutput;
+  try {
+    decision = await evalCommand(command, { cwd });
+  } catch {
+    // Fork fail-open default: do not brick the agent on eval errors.
+    if (isStrictMode()) {
+      return blockPiToolCall(REASON_OPA_NET_FAILED_CLOSED, command);
+    }
+    return undefined;
+  }
+
+  // Allow + log_only: proceed (with audit).
+  // opa-unlocked: engine already filtered — plugin trusts it.
+  // fail-open / cached: degraded paths — proceed silently.
+  if (
+    decision.decision === 'allow' ||
+    decision.action === 'allow' ||
+    decision.action === 'log_only'
+  ) {
+    return undefined;
+  }
+
+  // Deny + block: translate + audit + block.
+  if (decision.decision === 'deny' && decision.action === 'block') {
+    const sessionId = ctx.sessionManager.getSessionFile();
+    if (sessionId) {
+      const auditSink = ctx.auditSink ?? createFilesystemAuditSink(cwd);
+      await writeAuditEntry({
+        sessionId,
+        decision,
+        auditSink,
+      });
+    }
+    return blockPiToolCall(formatBlockReason(decision), command);
+  }
+
+  // prompt_user (reserved v2) — treat as allow for now.
+  return undefined;
+}
+
+function getPiShellToolCall(event: unknown, ctx: PiToolCallContext): PiShellToolCall | undefined {
+  if (!event || typeof event !== 'object') return undefined;
+  const toolCall = event as PiToolCallEvent;
+  if (typeof toolCall.toolName !== 'string') return undefined;
+
+  const adapter = PI_SHELL_TOOL_ADAPTERS[toolCall.toolName];
+  if (!adapter) return undefined;
+  if (!toolCall.input || typeof toolCall.input !== 'object') return { malformed: true };
+
+  const command = toolCall.input[adapter.commandField];
+  if (typeof command !== 'string') return { malformed: true };
+
+  const cwdInput = adapter.cwdField ? toolCall.input[adapter.cwdField] : undefined;
+  const cwd = typeof cwdInput === 'string' ? resolve(ctx.cwd, cwdInput) : ctx.cwd;
+  return { command, cwd };
+}
+
+function formatBlockReason(decision: DecisionOutput): string {
+  const reasons = decision.reasons.map((r) => `${r.rule_id}: ${r.message}`).join('; ');
+  const header = decision.summary || 'BLOCKED by OPA-Net';
+  return `${header}\nReason: ${reasons}\nRule family: ${decision.reasons[0]?.family ?? 'unknown'}`;
+}
+
+function blockPiToolCall(reason: string, _command?: string): PiToolCallResult {
+  return { block: true, reason };
+}