pi-opa-net 0.1.0 → 0.2.0

package/src/config/Config.ts

@@ -23,6 +23,12 @@ export interface EngineConfig {
   readonly hostname?: string;
   /** Calling session ID for metadata (pi/claude session). Empty if none. */
   readonly sessionId?: string;
+  /** Unlock keys from PIOPANET_UNLOCK_KEYS / --unlock (comma-separated env). */
+  readonly unlockKeys?: readonly string[];
+  /** Path to the deploy-local salt file (or PIOPANET_UNLOCK_SALT override). */
+  readonly unlockSaltPath?: string;
+  /** Agent ID for unlock audit metadata (PIOPANET_AGENT_ID). */
+  readonly unlockAgentId?: string;
 }
 
 const ENV = process.env;
@@ -63,9 +69,25 @@ function readdirSafe(path: string): string[] {
 export function configFromEnv(policyPath: string): EngineConfig {
   const failMode: FailMode = (ENV.PI_OPA_FAIL_MODE as FailMode) === 'closed' ? 'closed' : 'open';
   const timeoutMs = ENV.PI_OPA_TIMEOUT_MS ? Number.parseInt(ENV.PI_OPA_TIMEOUT_MS, 10) : 250;
-  const cacheTtlMs = ENV.PI_OPA_CACHE_TTL_MS
+  const baseCacheTtlMs = ENV.PI_OPA_CACHE_TTL_MS
     ? Number.parseInt(ENV.PI_OPA_CACHE_TTL_MS, 10)
     : DEFAULT_CACHE_TTL_MS;
+
+  // Unlock keys: PIOPANET_UNLOCK_KEYS (comma-separated, trimmed).
+  const unlockKeys = (ENV.PIOPANET_UNLOCK_KEYS ?? '')
+    .split(',')
+    .map((k) => k.trim())
+    .filter((k) => k.length > 0);
+
+  // LD-G3: force cacheTtlMs=0 when unlock keys are present (cache poisoning guard).
+  const cacheTtlMs = unlockKeys.length > 0 ? 0 : baseCacheTtlMs;
+
+  // Salt path: PIOPANET_UNLOCK_SALT or PIOPANET_UNLOCK_SALT_FILE → default ~/.pi-opa-net/salt.
+  const unlockSaltPath =
+    ENV.PIOPANET_UNLOCK_SALT ?? ENV.PIOPANET_UNLOCK_SALT_FILE ?? defaultSaltPath();
+
+  const unlockAgentId = ENV.PIOPANET_AGENT_ID;
+
   return {
     opaBinary: resolveOpaBinary(),
     policyPath,
@@ -74,5 +96,14 @@ export function configFromEnv(policyPath: string): EngineConfig {
     cacheTtlMs,
     hostname: ENV.PI_OPA_HOSTNAME,
     sessionId: ENV.PI_OPA_SESSION_ID,
+    unlockKeys,
+    unlockSaltPath,
+    unlockAgentId,
   };
 }
+
+/** Default salt file path: ~/.pi-opa-net/salt. */
+function defaultSaltPath(): string {
+  const home = ENV.HOME ?? process.env.HOME ?? '';
+  return `${home}/.pi-opa-net/salt`;
+}

package/src/output/DecisionBuilder.ts

@@ -4,13 +4,21 @@ import type { EngineConfig } from '../config/Config.ts';
 import type { EngineDecision, RawDeny } from '../engine/types.ts';
 import type { ParsedCommand } from '../parser/types.ts';
 import { type RuleMeta, type RuleRegistry, inferFamilyFromProgram } from '../rules/index.ts';
+import type { UnlockResult } from '../unlock/types.ts';
 
 /** The schema-compliant decision output (decision-output.v1). */
 export interface DecisionOutput {
   readonly schema_version: '1.0';
   readonly decision: 'allow' | 'deny';
   readonly action: 'allow' | 'block' | 'prompt_user' | 'log_only';
-  readonly source: 'opa' | 'fail-open' | 'fail-closed' | 'cached';
+  readonly source:
+    | 'opa'
+    | 'fail-open'
+    | 'fail-closed'
+    | 'cached'
+    | 'opa-unlocked'
+    | 'fail-open-keyless'
+    | 'unlock-filter-error';
   readonly reasons: readonly Reason[];
   readonly input: EvaluatedInput;
   readonly summary: string;
@@ -26,6 +34,11 @@ export interface Reason {
   readonly message: string;
   readonly family: string;
   readonly severity: 'block' | 'warn' | 'info';
+  readonly bypassed?: boolean;
+  readonly unlock_key_id?: string;
+  readonly unlock_key_type?: 'll' | 'ttl';
+  readonly unlock_expires_at?: string;
+  readonly unlock_status?: 'valid' | 'expired';
 }
 
 export interface EvaluatedInput {
@@ -43,6 +56,9 @@ export interface DecisionMetadata {
   readonly policy_path: string;
   readonly hostname: string;
   readonly session_id: string;
+  readonly unlock_count?: number;
+  readonly unlock_blocked_count?: number;
+  readonly unlock_agent?: string;
 }
 
 export interface DecisionBuilderDeps {
@@ -70,15 +86,49 @@ export class DecisionBuilder {
     this.deps = deps;
   }
 
-  build(parsed: ParsedCommand, engine: EngineDecision): DecisionOutput {
-    const reasons = engine.decision === 'deny' ? this.buildReasons(engine.reasons, parsed) : [];
+  build(
+    parsed: ParsedCommand,
+    engine: EngineDecision,
+    opts?: { unlockResult?: UnlockResult },
+  ): DecisionOutput {
+    const unlockResult = opts?.unlockResult;
+    const reasons =
+      engine.decision === 'deny' ? this.buildReasons(engine.reasons, parsed, unlockResult) : [];
     const suggestions = this.collectSuggestions(reasons);
-    const action = engine.decision === 'allow' ? 'allow' : 'block';
+
+    // Determine source and decision based on unlock result.
+    let source: DecisionOutput['source'] = engine.source;
+    let decision = engine.decision;
+    if (unlockResult && unlockResult.bypassedCount > 0 && unlockResult.blockedCount === 0) {
+      source = 'opa-unlocked';
+      decision = 'allow';
+    }
+
+    const action = decision === 'allow' ? 'allow' : 'block';
+
+    // Build metadata with optional unlock fields.
+    const metadata: DecisionMetadata = {
+      engine: 'opa',
+      opa_version: engine.opaVersion,
+      rulebook_digest: this.deps.digest,
+      policy_path: this.deps.config.policyPath,
+      hostname: this.deps.config.hostname ?? osHostname(),
+      session_id: this.deps.config.sessionId ?? '',
+    };
+    if (unlockResult) {
+      const meta = metadata as unknown as Record<string, unknown>;
+      meta.unlock_count = unlockResult.bypassedCount;
+      meta.unlock_blocked_count = unlockResult.blockedCount;
+      if (this.deps.config.unlockAgentId) {
+        meta.unlock_agent = this.deps.config.unlockAgentId;
+      }
+    }
+
     return {
       schema_version: '1.0',
-      decision: engine.decision,
+      decision,
       action,
-      source: engine.source,
+      source,
       reasons,
       input: {
         raw: parsed.raw,
@@ -89,29 +139,50 @@ export class DecisionBuilder {
       },
       summary: this.summary(engine, parsed, reasons),
       suggestions,
-      metadata: {
-        engine: 'opa',
-        opa_version: engine.opaVersion,
-        rulebook_digest: this.deps.digest,
-        policy_path: this.deps.config.policyPath,
-        hostname: this.deps.config.hostname ?? osHostname(),
-        session_id: this.deps.config.sessionId ?? '',
-      },
+      metadata,
       evaluated_at: (this.deps.now ?? (() => new Date()))().toISOString(),
       decision_id: (this.deps.uuid ?? randomUUID)(),
       duration_ms: engine.durationMs,
     };
   }
 
-  private buildReasons(raw: readonly RawDeny[], parsed: ParsedCommand): Reason[] {
-    return raw.map((d) => {
-      const meta = this.deps.registry.lookup(d);
-      return {
+  private buildReasons(
+    raw: readonly RawDeny[],
+    parsed: ParsedCommand,
+    unlockResult?: UnlockResult,
+  ): Reason[] {
+    return raw.map((d, i) => {
+      const familyHint = inferFamilyFromProgram(parsed.program);
+      const meta = this.deps.registry.lookup(d, familyHint, parsed.args);
+      const reason: Record<string, unknown> = {
         rule_id: meta.ruleId,
         message: meta.message,
         family: this.resolveFamily(meta, parsed),
-        severity: 'block' as const,
+        severity: 'block',
       };
+
+      // Merge unlock info if available.
+      if (unlockResult && i < unlockResult.reasons.length) {
+        const info = unlockResult.reasons[i];
+        if (info.bypassed) {
+          reason.bypassed = true;
+          reason.severity = 'info'; // Demote bypassed reason severity.
+        }
+        const keyId = info.unlockKeyId ?? info.unlock_key_id;
+        if (keyId) reason.unlock_key_id = keyId;
+        const keyType = info.keyType ?? info.unlock_key_type;
+        if (keyType) reason.unlock_key_type = keyType;
+        const exp = info.expiresAt ?? info.unlock_expires_at;
+        if (typeof exp === 'number') {
+          reason.unlock_expires_at = new Date(exp * 1000).toISOString();
+        } else if (typeof exp === 'string') {
+          reason.unlock_expires_at = exp;
+        }
+        const status = info.unlockStatus ?? info.unlock_status;
+        if (status) reason.unlock_status = status;
+      }
+
+      return reason as unknown as Reason;
     });
   }
 

package/src/rules/RuleRegistry.ts

@@ -10,7 +10,10 @@ export type RuleFamily =
   | 'glab'
   | 'bd'
   | 'builtin'
-  | 'custom';
+  | 'custom'
+  | 'tmux'
+  | 'pkill'
+  | 'killall';
 
 export interface RuleMeta {
   readonly ruleId: string;
@@ -18,6 +21,15 @@ export interface RuleMeta {
   readonly message: string;
   /** Safe alternatives for the "did you mean?" UX. Optional. */
   readonly suggestions?: readonly string[];
+  /**
+   * Disambiguation tokens used ONLY when multiple registered rules share an
+   * identical message AND family (collision). If any of these tokens appears
+   * in the parsed command's args, this candidate wins. Only needed for rules
+   * whose reason text is byte-identical to a sibling rule's (e.g.
+   * block-tmux-kill-server vs block-tmux-kill-session, which share the same
+   * verbatim reason and family 'tmux').
+   */
+  readonly matchArgs?: readonly string[];
 }
 
 /**
@@ -28,20 +40,51 @@ export interface RuleMeta {
  * so audits trace decision → rule → source line. Messages not in the registry
  * fall back to a synthesized `custom:<hash>` id with family=custom.
  *
+ * Multiple rules MAY share an identical message (e.g. the four
+ * tmux/pkill/killall session-kill rules all carry the same verbatim reason
+ * text). Such collisions are stored as a list and resolved by family hint
+ * (inferred from the parsed program) when one is supplied to lookup().
+ *
  * Keeping this in TS (not rego) is intentional: rego is the policy, this is the
  * provenance metadata layer. DRY — one canonical list, consumed by the builder.
  */
 export class RuleRegistry {
-  private readonly byMessage: Map<string, RuleMeta>;
+  private readonly byMessage: Map<string, RuleMeta[]>;
 
   constructor(rules: readonly RuleMeta[]) {
-    this.byMessage = new Map(rules.map((r) => [r.message, r]));
+    this.byMessage = new Map<string, RuleMeta[]>();
+    for (const r of rules) {
+      const arr = this.byMessage.get(r.message) ?? [];
+      arr.push(r);
+      this.byMessage.set(r.message, arr);
+    }
   }
 
-  /** Look up metadata for a deny message; synthesizes a custom entry if unknown. */
-  lookup(deny: RawDeny): RuleMeta {
-    const found = this.byMessage.get(deny.message);
-    if (found) return found;
+  /**
+   * Look up metadata for a deny message; synthesizes a custom entry if unknown.
+   *
+   * Collision resolution order when several registered rules share the same
+   * message:
+   *   1. `familyHint` (inferred from the parsed program) narrows to that family.
+   *   2. `parsedArgs` narrows further to a candidate whose `matchArgs` intersects
+   *      the parsed args (for rules that share message AND family, e.g. the two
+   *      tmux kill-* rules).
+   *   3. Otherwise the first remaining candidate is returned.
+   */
+  lookup(deny: RawDeny, familyHint?: string, parsedArgs?: readonly string[]): RuleMeta {
+    const candidates = this.byMessage.get(deny.message);
+    if (candidates && candidates.length > 0) {
+      let pool = candidates;
+      if (familyHint) {
+        const byFamily = pool.filter((c) => c.family === familyHint);
+        if (byFamily.length > 0) pool = byFamily;
+      }
+      if (parsedArgs && pool.length > 1) {
+        const byArgs = pool.filter((c) => c.matchArgs?.some((t) => parsedArgs.includes(t)));
+        if (byArgs.length > 0) pool = byArgs;
+      }
+      return pool[0];
+    }
     return {
       ruleId: `custom:${hashMessage(deny.message)}`,
       family: 'custom',

package/src/rules/catalog.ts

@@ -1,4 +1,4 @@
-import type { RuleMeta } from './RuleRegistry.ts';
+import type { RuleFamily, RuleMeta } from './RuleRegistry.ts';
 
 /**
  * Canonical rule catalog — mirrors policy/safety.rego message-for-message.
@@ -206,15 +206,51 @@ export const RULES: readonly RuleMeta[] = [
     family: 'glab',
     message: 'Public GitLab repository creation is blocked by default.',
   },
+  // ── GROUP G: tmux / pkill / killall session protection (cc-safety-net parity) ──
+  {
+    ruleId: 'block-tmux-kill-server',
+    family: 'tmux',
+    message:
+      'Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically \u2014 hand the exact command back to the user and let them run it themselves.',
+    matchArgs: ['kill-server'],
+  },
+  {
+    ruleId: 'block-tmux-kill-session',
+    family: 'tmux',
+    message:
+      'Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically \u2014 hand the exact command back to the user and let them run it themselves.',
+    matchArgs: ['kill-session'],
+  },
+  {
+    ruleId: 'block-pkill-tmux-wezterm',
+    family: 'pkill',
+    message:
+      'Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically \u2014 hand the exact command back to the user and let them run it themselves.',
+  },
+  {
+    ruleId: 'block-killall-tmux-wezterm',
+    family: 'killall',
+    message:
+      'Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically \u2014 hand the exact command back to the user and let them run it themselves.',
+  },
 ];
 
-/** gcloud/bq produce sprintf messages — family inferred from program. */
-export function inferFamilyFromProgram(program: string): 'gcloud' | 'bq' | 'custom' {
+/** gcloud/bq produce sprintf messages — family inferred from program.
+ *  tmux/pkill/killall rules share identical reason text (the four session-kill
+ *  rules), so their family is also inferred from the program to disambiguate
+ *  the message-keyed registry. */
+export function inferFamilyFromProgram(program: string): RuleFamily {
   switch (program) {
     case 'gcloud':
       return 'gcloud';
     case 'bq':
       return 'bq';
+    case 'tmux':
+      return 'tmux';
+    case 'pkill':
+      return 'pkill';
+    case 'killall':
+      return 'killall';
     default:
       return 'custom';
   }

package/src/unlock/KeyDerivation.ts

@@ -0,0 +1,28 @@
+import { createHmac } from 'node:crypto';
+
+/**
+ * Salted HMAC-SHA256 key derivation [D2].
+ *
+ * `derive(salt, rule_id) = HMAC-SHA256(salt, rule_id).hex().slice(0, 16)`
+ *
+ * 16 hex = 64-bit mac. Salt defeats rainbow tables (rule_ids are public).
+ * HMAC (not bare SHA) so salt stays secret under known-message attack.
+ */
+export class KeyDerivation {
+  // Static-only utility class — private constructor prevents instantiation.
+  private constructor() {}
+
+  /**
+   * Derive a 16-hex (64-bit) mac from salt + rule_id.
+   * @throws if rule_id or salt is empty.
+   */
+  static derive(salt: Buffer, ruleId: string): string {
+    if (!ruleId) {
+      throw new Error('rule_id must not be empty');
+    }
+    if (salt.length === 0) {
+      throw new Error('salt must not be empty');
+    }
+    return createHmac('sha256', salt).update(ruleId).digest('hex').slice(0, 16);
+  }
+}

package/src/unlock/KeyParser.ts

@@ -0,0 +1,33 @@
+import type { ParsedKey } from './types.ts';
+
+/**
+ * Parse self-describing key strings [D3].
+ *
+ * - Long-lived: `ll_<16hex>` → { type:'ll', mac }
+ * - TTL:        `ttl.<unix-exp-sec>.<16hex>` → { type:'ttl', exp, mac }
+ *
+ * Returns null for any malformed input. Hex MUST be lowercase.
+ */
+export class KeyParser {
+  // Static-only utility class — private constructor prevents instantiation.
+  private constructor() {}
+
+  private static readonly LL_RE = /^ll_([a-f0-9]{16})$/;
+  private static readonly TTL_RE = /^ttl\.(\d+)\.([a-f0-9]{16})$/;
+
+  static parse(raw: string): ParsedKey | null {
+    if (typeof raw !== 'string') return null;
+
+    const ll = raw.match(KeyParser.LL_RE);
+    if (ll) {
+      return { type: 'll', mac: ll[1] };
+    }
+
+    const ttl = raw.match(KeyParser.TTL_RE);
+    if (ttl) {
+      return { type: 'ttl', exp: Number.parseInt(ttl[1], 10), mac: ttl[2] };
+    }
+
+    return null;
+  }
+}

package/src/unlock/KeyVerifier.ts

@@ -0,0 +1,74 @@
+import { RULES } from '../rules/index.ts';
+import { KeyDerivation } from './KeyDerivation.ts';
+import { KeyParser } from './KeyParser.ts';
+import type { VerifyResult } from './types.ts';
+
+/**
+ * Verify a raw key string against a rule_id + salt [D2][D3].
+ *
+ * LL: valid iff `derive(salt, rule_id) === parsed.mac`.
+ * TTL: valid iff `derive(salt, rule_id + '.' + str(exp)) === parsed.mac`
+ *      AND `now/1000 <= exp` (strict, no skew tolerance).
+ *
+ * When the mac does not match, wrong-rule vs wrong-salt is disambiguated by
+ * re-deriving against every catalog rule_id with the given salt. If any
+ * known rule matches → wrong-rule; otherwise → wrong-salt.
+ */
+export class KeyVerifier {
+  // Static-only utility class — private constructor prevents instantiation.
+  private constructor() {}
+
+  /**
+   * @param rawKey   Key string (ll_… or ttl.…) from the agent.
+   * @param ruleId   The rule_id to check against.
+   * @param salt     Deploy-local salt buffer.
+   * @param nowMs    Verifier process clock in milliseconds (Date.now()).
+   */
+  static verify(rawKey: string, ruleId: string, salt: Buffer, nowMs: number): VerifyResult {
+    const parsed = KeyParser.parse(rawKey);
+    if (!parsed) {
+      return { valid: false, reason: 'malformed' };
+    }
+
+    const input =
+      parsed.type === 'ttl' && parsed.exp !== undefined ? `${ruleId}.${parsed.exp}` : ruleId;
+    const derived = KeyDerivation.derive(salt, input);
+
+    if (derived === parsed.mac) {
+      // Mac matches — check TTL clock.
+      if (parsed.type === 'ttl' && parsed.exp !== undefined) {
+        const nowSec = nowMs / 1000;
+        if (nowSec > parsed.exp) {
+          return {
+            valid: false,
+            reason: 'expired',
+            keyType: 'ttl',
+            expiresAt: parsed.exp,
+            unlockStatus: 'expired',
+          };
+        }
+        return {
+          valid: true,
+          keyType: 'ttl',
+          expiresAt: parsed.exp,
+          unlockStatus: 'valid',
+        };
+      }
+      return { valid: true, keyType: 'll', unlockStatus: 'valid' };
+    }
+
+    // Mac mismatch — try every catalog rule with the given salt.
+    for (const rule of RULES) {
+      const tryInput =
+        parsed.type === 'ttl' && parsed.exp !== undefined
+          ? `${rule.ruleId}.${parsed.exp}`
+          : rule.ruleId;
+      const tryMac = KeyDerivation.derive(salt, tryInput);
+      if (tryMac === parsed.mac) {
+        return { valid: false, reason: 'wrong-rule', keyType: parsed.type };
+      }
+    }
+
+    return { valid: false, reason: 'wrong-salt', keyType: parsed.type };
+  }
+}

package/src/unlock/SaltResolver.ts

@@ -0,0 +1,98 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Salt resolution seam [D4 / LD-Y1].
+ *
+ * Precedence (first wins):
+ *   1. `PIOPANET_UNLOCK_SALT` env — literal value (for testing).
+ *   2. `saltPath` constructor option or `PIOPANET_UNLOCK_SALT_FILE` env — file path.
+ *   3. Auto-generate 32 random bytes at the file path (atomic `wx`, mode 0o600).
+ *
+ * On read, warns to stderr if the file mode is not 0o600.
+ */
+export interface SaltResolverOptions {
+  /** Explicit salt file path (typically from config.unlockSaltPath). */
+  readonly saltPath?: string;
+}
+
+const ENV = process.env;
+
+export class SaltResolver {
+  private readonly saltPath?: string;
+
+  constructor(opts: SaltResolverOptions = {}) {
+    this.saltPath = opts.saltPath ?? ENV.PIOPANET_UNLOCK_SALT_FILE ?? defaultSaltPath();
+  }
+
+  resolve(): Buffer {
+    // 1. PIOPANET_UNLOCK_SALT env — literal value OR path to an existing file.
+    //    If the value points to an existing file, read it; otherwise treat as literal.
+    const envSalt = ENV.PIOPANET_UNLOCK_SALT;
+    if (envSalt !== undefined) {
+      try {
+        const stat = statSync(envSalt);
+        if (stat.isFile()) {
+          warnIfBadMode(envSalt);
+          return readFileSync(envSalt);
+        }
+      } catch {
+        // Not an existing file path — fall through to literal.
+      }
+      return Buffer.from(envSalt);
+    }
+
+    const path = this.saltPath ?? defaultSaltPath();
+
+    // 2. Existing file — read + warn on bad mode.
+    if (existsSync(path)) {
+      warnIfBadMode(path);
+      return readFileSync(path);
+    }
+
+    // 3. Auto-generate atomically (O_CREAT | O_EXCL via flag:'wx').
+    ensureDir(path);
+    const generated = randomBytes(32);
+    try {
+      writeFileSync(path, generated, { flag: 'wx', mode: 0o600 });
+      return generated;
+    } catch (e) {
+      // Race: another process created the file between our existsSync and writeFileSync.
+      // Re-read the winner's file (no last-write-wins).
+      const err = e as NodeJS.ErrnoException;
+      if (err.code === 'EEXIST' && existsSync(path)) {
+        warnIfBadMode(path);
+        return readFileSync(path);
+      }
+      throw e;
+    }
+  }
+}
+
+function defaultSaltPath(): string {
+  const home = ENV.HOME ?? process.env.HOME ?? '';
+  return join(home, '.pi-opa-net', 'salt');
+}
+
+function ensureDir(path: string): void {
+  const dir = dirname(path);
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch {
+    // Directory may already exist — ignore.
+  }
+}
+
+function warnIfBadMode(path: string): void {
+  try {
+    const mode = statSync(path).mode & 0o777;
+    if (mode !== 0o600) {
+      process.stderr.write(
+        `warning: salt file ${path} has mode ${mode.toString(8)} (expected 0o600); other users on this host can read it and derive unlock keys.\n`,
+      );
+    }
+  } catch {
+    // Stat failed — nothing to warn about.
+  }
+}