pi-opa-net 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,8 +5,50 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-07-20
+
+### Added
+
+- **Capability-based unlock-keys** (`src/unlock/`) — trusted agents present a per-rule salted HMAC key (long-lived `ll_<16hex>` or TTL `ttl.<exp>.<16hex>`); the TS-side post-eval filter demotes matching deny reasons. Schema stays v1 (additive). Policy file `safety.rego` is unchanged.
+- **`unlock-key` CLI subcommand** — `pi-opa-net unlock-key <rule_id> [--ttl <sec>]` mints keys; `--list` enumerates catalog rule_ids. Refuses unknown rule_ids and the god-key `PIOPANET_UNLOCK_ALL`.
+- **Three delivery channels** — `PIOPANET_UNLOCK_KEYS` env (comma-separated), `--unlock <key>` (repeatable), `--unlock-stdin` (requires positional command arg).
+- **Salt seam** (`SaltResolver`) — deploy-local `~/.pi-opa-net/salt` with auto-gen (atomic `wx`, mode 0o600), env override (`PIOPANET_UNLOCK_SALT` literal, `PIOPANET_UNLOCK_SALT_FILE` path), warn on world-readable. Interface for future remote/keychain resolver.
+- **Audit seam** (`AuditSink` + `NoOpSink`) — decision record is the sole audit surface in v1. Interface for future `FileAppendSink`/`WebhookSink`.
+- **All-or-nothing multi-rule semantics** — allow ⟺ every `severity:block` reason has a matching valid key. Partial bypass forbidden; `metadata.unlock_blocked_count` records remaining blockers.
+- **Three new schema sources** — `'opa-unlocked'` (legitimate bypass), `'fail-open-keyless'` (OPA down + keys present, auditable degradation), `'unlock-filter-error'` (filter crash falls back to un-filtered decision, never allows-by-accident).
+- **Cache poisoning guard** — when unlock keys present, `cacheTtlMs` forced to 0 regardless of `PI_OPA_CACHE_TTL_MS`.
+- **Decision-output.v1 schema (additive)** — `reasons[]` gains optional `bypassed`, `unlock_key_id` (first 8 hex only — full key NEVER logged), `unlock_key_type`, `unlock_expires_at`, `unlock_status`; `metadata` gains `unlock_count`, `unlock_blocked_count`, `unlock_agent`. `additionalProperties:false` preserved everywhere.
+- **OpenSpec change** at `openspec/changes/rule-unlock-keys/` — proposal, design (D1–D11), spec (REQ-001..018 + 9 scenarios), tasks.
+- **109 new tests** (304 total pass) covering key derivation, parser, verifier, filter, salt resolver, audit sink, decision builder integration, CLI, schema, and e2e flow. Typecheck + lint clean.
+
+### Decisions (locked, immutable)
+
+- **LD-L1**: per-rule granularity (one rule = one key, no per-command)
+- **LD-L2**: no god-key (refuse `PIOPANET_UNLOCK_ALL`)
+- **LD-L3**: two lifetimes (LL + TTL) via self-describing prefix
+- **LD-L4**: delivery = ENV + `--unlock` + `--unlock-stdin`
+- **LD-L6**: TS-side post-eval filter (keys never enter OPA input/trace)
+- **LD-Y1/Y2**: deploy-local salt + NoOp audit (YAGNI seams for future)
+- **LD-G1**: fail-open+keys → `source:fail-open-keyless`
+- **LD-G2**: `--unlock-stdin` requires positional command
+- **LD-G3**: `cacheTtlMs` forced 0 when keys present
+- **LD-G6**: all-or-nothing multi-rule semantics
+- **LD-G8**: filter crash → fall back to un-filtered decision
+
+### Verifier-loop
+
+- Pre-merge: jewilo 2/2 APPROVE, hash `072026-c604475a` (fullDigest `c604475a...`).
+- Post-merge: jewilo-dev with rag-quick model 2/2 APPROVE, hash `072026-7291243b`.
+
 ## [Unreleased]
 
+### Added
+
+- **Cupcake-compatible policy** (`.cupcake/policies/claude/cc_safety_net_parity.rego`) that ports all 42 active `cc-safety-net` user rules into OPA/Rego v1 with the Cupcake custom-policy structure: `# METADATA`, `package cupcake.policies.cc_safety_net_parity`, `import rego.v1`, and mandatory self-filtering. The aggregation entrypoint `data.cupcake.system.evaluate` is provided in `.cupcake/system/evaluate.rego`.
+- **Rulebook fixture** at `tests/fixtures/user-rules.rulebook.json` and a new `tests/cupcake/cc_safety_net_parity.test.ts` suite that runs all 53 rulebook `tests[]` fixtures + 12 tmux/pkill/killall scenarios + self-filtering checks.
+- **4 missing tmux/pkill/killall rules** to the pi-opa-net engine (`policy/safety.rego`, `src/rules/catalog.ts`) for full 42-rule parity with the active `cc-safety-net` rulebook.
+- **DecisionBuilder disambiguation** for rules that share identical reason text (the tmux session-kill family): the registry now maps `(message, family)` to rule metadata when a raw deny carries a `family` hint, falling back to the previous message-only lookup.
+- **Documentation**: `docs/cupcake-parity.md` describing the Cupcake policy and standalone `opa eval` usage; README updated to reflect the 42-rule catalog and the new policy file.
 ## [0.1.0] - 2026-07-01
 
 ### Added

package/README.md

@@ -20,11 +20,21 @@ Three limitations of today's asymmetric, agent-specific guard output that this f
 
 ## Status
 
-- **Stable:** v0.1.0 — schema v1.0, 37-rule catalog, full TDD coverage
+- **Stable:** v0.2.0 — schema v1.0 (additive), 42-rule catalog, capability-based unlock-keys, full TDD coverage (304 tests)
+  - Cupcake-compatible policy: `.cupcake/policies/claude/cc_safety_net_parity.rego` (all 42 active `cc-safety-net` rules in OPA/Rego v1)
+  - **Capability-based unlock-keys** (v0.2.0) — trusted agents present a per-rule salted HMAC key; TS-side post-eval filter demotes matching deny reasons.
 - **Engine:** OPA 1.x (lazy-loaded on every dev box)
 - **Scope:** bash command guarding only (see [`docs/locked-decisions.yaml`](docs/locked-decisions.yaml) LD3)
 - **Pi extension:** the thin tool_call adapter lives in a separate future repo (`pi-opa-net-ext`, per OT5) — this package is the engine + library
 
+## Features
+
+- **OPA-backed decisions** — every command evaluated by an [OPA](https://www.openpolicyagent.org/)/Rego policy; 42-rule catalog (full `cc-safety-net` user-rule parity).
+- **Symmetric structured output** — both allow AND deny emit the full `decision-output.v1` schema with `reasons[].rule_id` provenance, fail-mode observability, and parse-confidence surfacing.
+- **Fail-open by default** — never bricks the shell; matches the `pi-safety-net` fork guarantee. `PI_OPA_FAIL_MODE=closed` for fail-closed.
+- **Capability-based unlock-keys** (v0.2.0) — grant trusted agents a per-rule salted HMAC key (long-lived `ll_<16hex>` or TTL `ttl.<exp>.<16hex>`). TS-side post-eval filter demotes matching deny reasons. All-or-nothing multi-rule semantics; every bypass is auditable via `source:'opa-unlocked'`.
+- **Claude Code hook compatible** — exit codes `0 = allow`, `2 = deny`; JSON on stdout.
+- **Pluggable seams** — `SaltResolver` (deploy-local salt now, remote/keychain later) and `AuditSink` (decision-record only now, file/webhook later).
 ## Installation
 
 ### Prerequisites
@@ -48,6 +58,33 @@ bun add pi-opa-net
 bunx pi-opa-net eval "git stash pop"
 ```
 
+### For AI Agents (pi / OpenCode / Claude Code / Codex)
+
+Add to your `settings.json`:
+
+```jsonc
+{
+  "packages": ["pi-opa-net"]
+}
+```
+
+Or tell your agent:
+
+```
+Install and configure pi-opa-net by following:
+https://raw.githubusercontent.com/buihongduc132/pi-opa-net/refs/heads/main/README.md
+```
+
+### For pi (git-sourced)
+
+In `settings.json`:
+
+```jsonc
+{
+  "packages": ["https://github.com/buihongduc132/pi-opa-net"]
+}
+```
+
 ## Usage
 
 ### CLI
@@ -179,12 +216,17 @@ bun run lint             # biome
 bun run smoke            # one-shot CLI check
 ```
 
-E2E tests run the live CLI against real OPA + the real policy, covering ≥40% of the 37-rule catalog.
+E2E tests run the live CLI against real OPA + the real policy, covering ≥40% of the 42-rule catalog.
+
+## Cupcake-compatible policy
+
+This repo also ships a Cupcake-format OPA/Rego policy at `.cupcake/policies/claude/cc_safety_net_parity.rego` that ports all 42 active `cc-safety-net` user rules. It can be evaluated directly by OPA or consumed as a Cupcake catalog overlay. See [`docs/cupcake-parity.md`](docs/cupcake-parity.md) for details, including the standalone `opa eval` examples and the input/output contract.
 
 ## Decisions & open threads
 
 - [`docs/locked-decisions.yaml`](docs/locked-decisions.yaml) — LD1–LD5 (immutable inputs).
 - [`docs/open-threads.yaml`](docs/open-threads.yaml) — OT1–OT5 resolved at implementation time.
+- [`docs/cupcake-parity.md`](docs/cupcake-parity.md) — Cupcake-format policy documentation + standalone `opa eval` usage.
 
 ## Project health
 
@@ -198,6 +240,8 @@ E2E tests run the live CLI against real OPA + the real policy, covering ≥40% o
 - [`pi-safety-net`](https://www.npmjs.com/package/pi-safety-net) — the fail-open fork of cc-safety-net (Path A: non-pi agents). pi-opa-net is Path B (OPA-backed, structured output).
 - [`cc-safety-net`](https://www.npmjs.com/package/cc-safety-net) — upstream Claude Code safety net.
 
-## License
-
 MIT © [buihongduc132](https://github.com/buihongduc132)
+
+## Repository
+
+**GitHub**: [buihongduc132/pi-opa-net](https://github.com/buihongduc132/pi-opa-net)

package/bin/pi-opa-net.js

@@ -5,11 +5,17 @@
  * Usage:
  *   pi-opa-net eval "<command>"              # claude-code mode (default)
  *   pi-opa-net eval "<command>" --json        # full schema on stdout always
+ *   pi-opa-net eval "<command>" --unlock <key>  # present unlock key
  *   echo "<command>" | pi-opa-net eval        # read from stdin
+ *   pi-opa-net unlock-key <rule_id>           # mint long-lived key
+ *   pi-opa-net unlock-key <rule_id> --ttl 3600 # mint TTL key
+ *   pi-opa-net unlock-key --list              # list unlockable rule_ids
  *
  * Exit codes: 0=allow, 2=deny (Claude Code hook protocol compatible).
  */
 import { defaultPolicyPath, runCli } from '../src/cli/run.ts';
+import { listUnlockableRules, mintUnlockKey } from '../src/cli/unlock-key.ts';
+import { configFromEnv } from '../src/config/Config.ts';
 
 function parseArgs(argv) {
   const args = argv.slice(2); // drop node + script
@@ -17,6 +23,8 @@ function parseArgs(argv) {
   let command;
   let policyPath = defaultPolicyPath();
   let sawAction = false;
+  const unlockKeys = [];
+  let unlockStdin = false;
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -24,6 +32,10 @@ function parseArgs(argv) {
       mode = 'json';
     } else if (a === '--policy' || a === '-p') {
       policyPath = args[++i];
+    } else if (a === '--unlock') {
+      unlockKeys.push(args[++i]);
+    } else if (a === '--unlock-stdin') {
+      unlockStdin = true;
     } else if (a === '--help' || a === '-h') {
       printHelp();
       process.exit(0);
@@ -36,30 +48,99 @@ function parseArgs(argv) {
       }
     }
   }
-  return { command, mode, policyPath };
+  return { command, mode, policyPath, unlockKeys, unlockStdin };
 }
 
 function printHelp() {
   console.error(`pi-opa-net — OPA-backed bash command guard
 
 Usage:
-  pi-opa-net eval "<command>" [--json] [--policy <path>]
+  pi-opa-net eval "<command>" [--json] [--policy <path>] [--unlock <key> ...]
   echo "<command>" | pi-opa-net eval
+  pi-opa-net unlock-key <rule_id> [--ttl <sec>]
+  pi-opa-net unlock-key --list
 
 Modes:
   (default)   claude-code: suppress stdout on allow, JSON on deny
   --json      always emit full decision-output.v1 schema on stdout
 
+Unlock:
+  --unlock <key>        Present an unlock key (repeatable)
+  --unlock-stdin        Read a single key from stdin (requires positional command)
+  PIOPANET_UNLOCK_KEYS  Comma-separated keys via env var
+
 Exit codes: 0=allow, 2=deny`);
 }
 
+/**
+ * Dispatch the unlock-key subcommand.
+ * Returns exit code; never throws (prints error to stderr).
+ */
+function runUnlockKey(subArgs) {
+  // Parse sub-args: --list, --ttl <sec>, or <rule_id>
+  let ruleId;
+  let ttlSec;
+  for (let i = 0; i < subArgs.length; i++) {
+    const a = subArgs[i];
+    if (a === '--list') {
+      for (const id of listUnlockableRules()) {
+        console.log(id);
+      }
+      return 0;
+    }
+    if (a === '--ttl') {
+      ttlSec = Number.parseInt(subArgs[++i], 10);
+    } else if (!a.startsWith('-')) {
+      ruleId = a;
+    }
+  }
+
+  if (!ruleId) {
+    console.error('error: unlock-key requires a rule_id argument (or --list)');
+    return 1;
+  }
+
+  try {
+    const config = configFromEnv(defaultPolicyPath());
+    const key = mintUnlockKey({
+      ruleId,
+      saltPath: config.unlockSaltPath,
+      ttlSec,
+    });
+    console.log(key);
+    return 0;
+  } catch (e) {
+    console.error(`error: ${e.message}`);
+    return 1;
+  }
+}
+
 async function main() {
-  const { command, mode, policyPath } = parseArgs(process.argv);
-  const { stdout, exitCode } = await runCli({ command, mode, policyPath });
-  if (stdout) {
-    console.log(stdout);
+  const rawArgs = process.argv.slice(2);
+
+  // Dispatch unlock-key subcommand.
+  if (rawArgs[0] === 'unlock-key') {
+    const exitCode = runUnlockKey(rawArgs.slice(1));
+    process.exit(exitCode);
+  }
+
+  const { command, mode, policyPath, unlockKeys, unlockStdin } = parseArgs(process.argv);
+  try {
+    const { stdout, exitCode } = await runCli({
+      command,
+      mode,
+      policyPath,
+      unlockKeys,
+      unlockStdin,
+    });
+    if (stdout) {
+      console.log(stdout);
+    }
+    process.exit(exitCode);
+  } catch (e) {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
   }
-  process.exit(exitCode);
 }
 
 void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-opa-net",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -30,6 +30,7 @@
   },
   "keywords": [
     "pi-package",
+    "pi-extension",
     "pi",
     "pi-coding-agent",
     "pi-library",
@@ -39,7 +40,9 @@
     "safety-net",
     "claude-code",
     "policy",
-    "decision-output"
+    "decision-output",
+    "capability-based",
+    "unlock-keys"
   ],
   "pi": {
     "skills": ["./skills"]

package/policy/safety.rego

@@ -356,6 +356,42 @@ deny[msg] if {
     msg := "Public GitLab repository creation is blocked by default."
 }
 
+# ──────────────────────────────────────────────────────────────────
+# GROUP G — tmux / pkill / killall session protection
+# (cc-safety-net parity: block-tmux-kill-server, block-tmux-kill-session,
+#  block-pkill-tmux-wezterm, block-killall-tmux-wezterm)
+#
+# The pi-opa-net parser treats tmux/pkill/killall as non-subcommand programs,
+# so the kill verb lands in input.args. Messages are copied verbatim from the
+# canonical rulebook reason field.
+# ──────────────────────────────────────────────────────────────────
+
+session_kill_targets := ["tmux", "wezterm", "wezterm-mux-server"]
+
+deny[msg] if {
+    input.program == "tmux"
+    has_any_arg(input.args, ["kill-server"])
+    msg := "Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically — hand the exact command back to the user and let them run it themselves."
+}
+
+deny[msg] if {
+    input.program == "tmux"
+    has_any_arg(input.args, ["kill-session"])
+    msg := "Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically — hand the exact command back to the user and let them run it themselves."
+}
+
+deny[msg] if {
+    input.program == "pkill"
+    has_any_arg(input.args, session_kill_targets)
+    msg := "Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically — hand the exact command back to the user and let them run it themselves."
+}
+
+deny[msg] if {
+    input.program == "killall"
+    has_any_arg(input.args, session_kill_targets)
+    msg := "Killing the tmux/wezterm server destroys ALL sessions, panes, and in-flight work across every client. Do NOT run this automatically — hand the exact command back to the user and let them run it themselves."
+}
+
 # ──────────────────────────────────────────────────────────────────
 # USAGE
 # ──────────────────────────────────────────────────────────────────

package/schemas/decision-output.v1.json

@@ -29,8 +29,8 @@
 
     "source": {
       "type": "string",
-      "enum": ["opa", "fail-open", "fail-closed", "cached"],
-      "description": "Where the decision came from. opa=live OPA eval; fail-open=OPA unreachable, defaulted allow (see [OT2]); fail-closed=OPA unreachable, defaulted deny; cached=replay of prior decision for identical input within TTL."
+      "enum": ["opa", "fail-open", "fail-closed", "cached", "opa-unlocked", "fail-open-keyless", "unlock-filter-error"],
+      "description": "Where the decision came from. opa=live OPA eval; fail-open=OPA unreachable, defaulted allow (see [OT2]); fail-closed=OPA unreachable, defaulted deny; cached=replay of prior decision for identical input within TTL; opa-unlocked=OPA denied but all blocking rules bypassed via valid unlock keys; fail-open-keyless=OPA unreachable AND unlock keys present (degradation, not legitimate bypass); unlock-filter-error=unlock filter crashed, fell back to engine verdict."
     },
 
     "reasons": {
@@ -95,13 +95,37 @@
         },
         "family": {
           "type": "string",
-          "enum": ["git", "docker", "rm", "gcloud", "bq", "gh", "glab", "bd", "builtin", "custom"],
+          "enum": ["git", "docker", "rm", "gcloud", "bq", "gh", "glab", "bd", "builtin", "custom", "tmux", "pkill", "killall"],
           "description": "Rule family for grouping/filtering. Matches the 6 families in the rego translation (turn6)."
         },
         "severity": {
           "type": "string",
           "enum": ["block", "warn", "info"],
           "description": "Reserved for v2 tiered outcomes. Today always 'block'. Lets future prompt_user/log_only rules coexist with hard blocks."
+        },
+        "bypassed": {
+          "type": "boolean",
+          "description": "True when this deny reason was bypassed by a valid unlock key."
+        },
+        "unlock_key_id": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{8}$",
+          "description": "First 8 hex of the unlock key mac (truncated — full key MUST NEVER appear)."
+        },
+        "unlock_key_type": {
+          "type": "string",
+          "enum": ["ll", "ttl"],
+          "description": "Type of unlock key used to bypass this reason."
+        },
+        "unlock_expires_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 expiry timestamp (TTL keys only)."
+        },
+        "unlock_status": {
+          "type": "string",
+          "enum": ["valid", "expired"],
+          "description": "Status of the unlock key attempt for this reason."
         }
       }
     },
@@ -166,6 +190,20 @@
         "session_id": {
           "type": "string",
           "description": "Calling agent's session ID if available (pi session, claude session, etc.). Empty string if not provided."
+        },
+        "unlock_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of deny reasons bypassed by valid unlock keys."
+        },
+        "unlock_blocked_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of deny reasons still blocking after unlock attempt (all-or-nothing semantics)."
+        },
+        "unlock_agent": {
+          "type": "string",
+          "description": "Agent identifier that presented the unlock keys."
         }
       }
     }

package/src/audit/AuditSink.ts

@@ -0,0 +1,26 @@
+/**
+ * Audit sink seam [D9 / LD-Y2].
+ *
+ * The decision record (stdout JSON) IS the audit surface in v1. The default
+ * NoOpSink does nothing — no file, no network, no throw. Future sinks
+ * (FileAppendSink, WebhookSink) swap in via config with zero pipeline changes.
+ */
+
+/** Record passed to AuditSink.onUnlock for each unlock event. */
+export interface UnlockRecord {
+  readonly ruleId: string;
+  readonly unlockKeyId: string;
+  readonly keyType: 'll' | 'ttl';
+  readonly timestamp: string;
+}
+
+export interface AuditSink {
+  onUnlock(record: UnlockRecord): void;
+}
+
+/** No-op default — side-effect-free. */
+export class NoOpSink implements AuditSink {
+  onUnlock(_record: UnlockRecord): void {
+    // Intentionally empty — the decision record is the sole audit surface.
+  }
+}

package/src/cli/run.ts

@@ -1,10 +1,13 @@
 import { resolve } from 'node:path';
 import { configFromEnv } from '../config/Config.ts';
 import { OpaCliEngine, probeOpaVersion } from '../engine/index.ts';
-import { DecisionBuilder } from '../output/DecisionBuilder.ts';
+import { DecisionBuilder, type DecisionOutput } from '../output/DecisionBuilder.ts';
 import { OutputFormatter, validateDecision } from '../output/OutputFormatter.ts';
 import { CommandParserCoordinator } from '../parser/index.ts';
 import { RULES, RuleRegistry } from '../rules/index.ts';
+import { SaltResolver } from '../unlock/SaltResolver.ts';
+import { UnlockFilter } from '../unlock/UnlockFilter.ts';
+import type { UnlockResult } from '../unlock/types.ts';
 
 export interface CliOptions {
   /** Command string to evaluate. If omitted, read from stdin. */
@@ -13,6 +16,12 @@ export interface CliOptions {
   readonly mode: 'json' | 'claude-code';
   /** Path to the .rego policy. */
   readonly policyPath: string;
+  /** Unlock keys from --unlock flags (repeatable). */
+  readonly unlockKeys?: readonly string[];
+  /** Read a single unlock key from stdin (requires positional command). */
+  readonly unlockStdin?: boolean;
+  /** Injected stdin content (for testing — bypasses fd 0 read). */
+  readonly stdin?: string;
 }
 
 export interface CliResult {
@@ -27,12 +36,32 @@ export interface CliResult {
  * is unit-testable. The bin wrapper calls process.exit with the returned code.
  */
 export async function runCli(opts: CliOptions): Promise<CliResult> {
+  // LD-G2: --unlock-stdin requires a positional command argument.
+  if (opts.unlockStdin && (!opts.command || opts.command.length === 0)) {
+    throw new Error('--unlock-stdin requires a positional command argument');
+  }
+
   const raw = resolveRaw(opts);
   if (raw === '') {
     return { stdout: '', exitCode: 0 };
   }
 
+  // Read unlock key from stdin if --unlock-stdin [LD-L4].
+  let stdinKey: string | undefined;
+  if (opts.unlockStdin) {
+    stdinKey = readStdinKey(opts);
+  }
+
   const config = configFromEnv(opts.policyPath);
+
+  // Collect unlock keys from all channels: ENV + --unlock + --unlock-stdin.
+  const unlockKeys = dedupe([
+    ...(config.unlockKeys ?? []),
+    ...(opts.unlockKeys ?? []),
+    ...(stdinKey ? [stdinKey] : []),
+  ]);
+  const hasKeys = unlockKeys.length > 0;
+
   const parser = new CommandParserCoordinator();
   const parsed = parser.parse(raw);
 
@@ -45,7 +74,42 @@ export async function runCli(opts: CliOptions): Promise<CliResult> {
     registry: new RuleRegistry(RULES),
     digest: engine.rulebookDigest(),
   });
-  const output = builder.build(parsed, engineDecision);
+
+  let output: DecisionOutput;
+
+  if (engineDecision.source === 'fail-open' && hasKeys) {
+    // LD-G1: OPA down + keys present → fail-open-keyless (NOT opa-unlocked).
+    output = builder.build(parsed, engineDecision);
+    output = { ...output, source: 'fail-open-keyless' };
+  } else if (!hasKeys || engineDecision.decision === 'allow') {
+    // No keys or engine said allow → no unlock filtering.
+    output = builder.build(parsed, engineDecision);
+  } else {
+    // Engine said deny + keys present → run unlock filter [D1].
+    let unlockResult: UnlockResult | undefined;
+    let filterCrashed = false;
+
+    const salt = new SaltResolver({ saltPath: config.unlockSaltPath ?? '' }).resolve();
+    try {
+      unlockResult = UnlockFilter.filter(
+        engineDecision.reasons,
+        unlockKeys,
+        salt,
+        Date.now(),
+        new RuleRegistry(RULES),
+      );
+    } catch {
+      // LD-G8: filter crash → fall back to un-filtered engine decision.
+      filterCrashed = true;
+    }
+
+    if (filterCrashed) {
+      output = builder.build(parsed, engineDecision);
+      output = { ...output, source: 'unlock-filter-error' };
+    } else {
+      output = builder.build(parsed, engineDecision, { unlockResult });
+    }
+  }
 
   // Hard internal gate: the record MUST validate against the schema before emit.
   validateDecision(output);
@@ -68,6 +132,32 @@ function resolveRaw(opts: CliOptions): string {
   }
 }
 
+/** Read a single unlock key from stdin (or injected opts.stdin for testing). */
+function readStdinKey(opts: CliOptions): string {
+  if (opts.stdin !== undefined) {
+    return opts.stdin.trim();
+  }
+  try {
+    const fs = require('node:fs') as typeof import('node:fs');
+    return fs.readFileSync(0, 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+/** De-duplicate a string array while preserving order. */
+function dedupe(arr: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const s of arr) {
+    if (!seen.has(s)) {
+      seen.add(s);
+      out.push(s);
+    }
+  }
+  return out;
+}
+
 /** Resolve the default policy path relative to package root. */
 export function defaultPolicyPath(): string {
   // import.meta.dir is available under Bun; fall back to cwd-relative for Node.

package/src/cli/unlock-key.ts

@@ -0,0 +1,52 @@
+import { RULES } from '../rules/index.ts';
+import { KeyDerivation } from '../unlock/KeyDerivation.ts';
+import { SaltResolver } from '../unlock/SaltResolver.ts';
+
+/** Options for minting an unlock key. */
+export interface MintUnlockKeyOptions {
+  /** Rule ID to mint a key for. Must be in the catalog. */
+  readonly ruleId: string;
+  /** Path to the salt file (auto-generates if missing). */
+  readonly saltPath?: string;
+  /** Direct salt buffer (bypasses SaltResolver — for testing). */
+  readonly salt?: Buffer;
+  /** TTL in seconds. Omit for a long-lived key. */
+  readonly ttlSec?: number;
+}
+
+/**
+ * Mint an unlock key for a catalog-registered rule_id [D3].
+ *
+ * - Long-lived: `ll_<16hex>` where mac = HMAC(salt, rule_id).
+ * - TTL: `ttl.<exp>.<16hex>` where exp = floor(now/1000) + ttlSec,
+ *   mac = HMAC(salt, rule_id + '.' + str(exp)).
+ *
+ * @throws if ruleId is not in the catalog.
+ */
+export function mintUnlockKey(opts: MintUnlockKeyOptions): string {
+  if (!isKnownRule(opts.ruleId)) {
+    throw new Error(
+      `unknown rule_id '${opts.ruleId}' — not in catalog. Run 'unlock-key --list' for valid IDs.`,
+    );
+  }
+
+  const salt = opts.salt ?? new SaltResolver({ saltPath: opts.saltPath }).resolve();
+
+  if (opts.ttlSec !== undefined && opts.ttlSec > 0) {
+    const exp = Math.floor(Date.now() / 1000) + opts.ttlSec;
+    const mac = KeyDerivation.derive(salt, `${opts.ruleId}.${exp}`);
+    return `ttl.${exp}.${mac}`;
+  }
+
+  const mac = KeyDerivation.derive(salt, opts.ruleId);
+  return `ll_${mac}`;
+}
+
+/** Enumerate catalog-registered rule_ids (excludes gcloud/bq sprintf rules). */
+export function listUnlockableRules(): readonly string[] {
+  return RULES.map((r) => r.ruleId);
+}
+
+function isKnownRule(ruleId: string): boolean {
+  return RULES.some((r) => r.ruleId === ruleId);
+}