pi-opa-net 0.1.0 → 0.3.0

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.
+  }
+}

package/src/unlock/UnlockFilter.ts

@@ -0,0 +1,107 @@
+import type { RawDeny } from '../engine/types.ts';
+import type { RuleRegistry } from '../rules/index.ts';
+import { KeyParser } from './KeyParser.ts';
+import { KeyVerifier } from './KeyVerifier.ts';
+import type { UnlockReasonInfo, UnlockResult, VerifyResult } from './types.ts';
+
+/**
+ * All-or-nothing unlock filter [D5 / LD-G6].
+ *
+ * For each deny reason (severity:block), checks if ANY presented key validly
+ * unlocks that reason's rule_id. `allow ⟺ every block reason has a valid key`.
+ *
+ * Expired TTL keys are reported (unlock_status:'expired') but do NOT bypass.
+ * `unlock_key_id` is always the first 8 hex of the matching key's mac — the
+ * full 16-hex key NEVER appears in the result.
+ */
+export class UnlockFilter {
+  // Static-only utility class — private constructor prevents instantiation.
+  private constructor() {}
+
+  /**
+   * @param reasons  Raw deny reasons from the engine.
+   * @param keys     Raw key strings presented by the agent.
+   * @param salt     Deploy-local salt buffer.
+   * @param nowMs    Verifier process clock in ms (Date.now()).
+   * @param registry Rule registry for message → rule_id lookup.
+   */
+  static filter(
+    reasons: readonly RawDeny[],
+    keys: readonly string[],
+    salt: Buffer,
+    nowMs: number,
+    registry: RuleRegistry,
+  ): UnlockResult {
+    const infos: UnlockReasonInfo[] = reasons.map((deny) => {
+      const meta = registry.lookup(deny);
+      const ruleId = meta.ruleId;
+
+      let validResult: VerifyResult | null = null;
+      let expiredResult: VerifyResult | null = null;
+      let validKey: string | null = null;
+
+      for (const key of keys) {
+        const result = KeyVerifier.verify(key, ruleId, salt, nowMs);
+        if (result.valid) {
+          validResult = result;
+          validKey = key;
+          break;
+        }
+        if (result.reason === 'expired' && !expiredResult) {
+          expiredResult = result;
+        }
+      }
+
+      if (validResult) {
+        const parsed = KeyParser.parse(validKey!);
+        const fullMac = parsed?.mac ?? '';
+        const keyId = fullMac.slice(0, 8);
+        const keyType = validResult.keyType;
+        const expiresAt = validResult.expiresAt;
+        return {
+          message: deny.message,
+          ruleId,
+          bypassed: true,
+          unlockKeyId: keyId,
+          keyType,
+          expiresAt,
+          unlockStatus: 'valid',
+          unlock_key_id: keyId,
+          unlock_key_type: keyType,
+          unlock_expires_at: expiresAt,
+          unlock_status: 'valid',
+        };
+      }
+
+      if (expiredResult) {
+        return {
+          message: deny.message,
+          ruleId,
+          bypassed: false,
+          unlockKeyId: '',
+          unlock_key_id: '',
+          unlockStatus: 'expired',
+          unlock_status: 'expired',
+        };
+      }
+
+      return {
+        message: deny.message,
+        ruleId,
+        bypassed: false,
+        unlockKeyId: '',
+        unlock_key_id: '',
+      };
+    });
+
+    const bypassedCount = infos.filter((r) => r.bypassed).length;
+    const blockedCount = infos.length - bypassedCount;
+
+    return {
+      allow: blockedCount === 0,
+      bypassedCount,
+      blockedCount,
+      reasons: infos,
+    };
+  }
+}

package/src/unlock/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared types for the unlock subsystem [D1-D11].
+ *
+ * These types are the contract between UnlockFilter → DecisionBuilder.
+ * Internal (TS-side) property naming uses camelCase; the DecisionBuilder
+ * translates to snake_case schema fields at output time.
+ */
+
+/** Result of parsing a raw key string. */
+export interface ParsedKey {
+  readonly type: 'll' | 'ttl';
+  readonly mac: string;
+  /** Unix expiry in seconds. Present only for TTL keys. */
+  readonly exp?: number;
+}
+
+/** Outcome of verifying a parsed key against a rule_id + salt. */
+export interface VerifyResult {
+  readonly valid: boolean;
+  readonly reason?: 'malformed' | 'wrong-rule' | 'wrong-salt' | 'expired';
+  readonly keyType?: 'll' | 'ttl';
+  /** Unix expiry in seconds (TTL only). */
+  readonly expiresAt?: number;
+  readonly unlockStatus?: 'valid' | 'expired';
+}
+
+/**
+ * Per-reason unlock info produced by UnlockFilter.
+ *
+ * Carries BOTH camelCase (consumed by DecisionBuilder) and snake_case
+ * (consumed by UnlockFilter test assertions) aliases so the same object
+ * satisfies both consumers without conversion.
+ */
+export interface UnlockReasonInfo {
+  readonly message: string;
+  readonly ruleId: string;
+  readonly bypassed: boolean;
+
+  /** camelCase aliases — DecisionBuilder reads these. */
+  readonly unlockKeyId: string;
+  readonly keyType?: 'll' | 'ttl';
+  readonly expiresAt?: number;
+  readonly unlockStatus?: 'valid' | 'expired';
+
+  /** snake_case aliases — schema-compatible / UnlockFilter assertions. */
+  readonly unlock_key_id: string;
+  readonly unlock_key_type?: 'll' | 'ttl';
+  readonly unlock_expires_at?: number;
+  readonly unlock_status?: 'valid' | 'expired';
+}
+
+/** Aggregate result of filtering reasons through unlock keys. */
+export interface UnlockResult {
+  readonly allow: boolean;
+  readonly bypassedCount: number;
+  readonly blockedCount: number;
+  readonly reasons: readonly UnlockReasonInfo[];
+}