@sleep2agi/commhub-server 0.9.0-preview.3 → 0.9.0-preview.5

package/src/vault.test.ts

@@ -0,0 +1,200 @@
+// RFC-028 P1 §4.1 vault layer tests. F2 lazy gate is the critical
+// invariant — existing prod hub升级 without ANET_HUB_SECRET_VAULT_KEY
+// must NOT boot-fail. Every test runs with deterministic key isolation.
+
+import { describe, expect, test, beforeEach, afterAll } from "bun:test";
+import {
+  encryptSecret, decryptSecret,
+  vaultUpsert, vaultGet, vaultListKeys, vaultDelete,
+  vaultStatusForBoot, vaultMasterKeyFingerprint,
+  _resetVaultKeyForTest, VaultError,
+} from "./vault.js";
+import { db } from "./db.js";
+
+const TEST_KEY_HEX = "0123456789abcdef".repeat(4);   // 32 bytes hex = 64 chars
+
+function setKey(hex: string | undefined): void {
+  if (hex === undefined) delete process.env.ANET_HUB_SECRET_VAULT_KEY;
+  else process.env.ANET_HUB_SECRET_VAULT_KEY = hex;
+  _resetVaultKeyForTest();
+}
+
+beforeEach(() => {
+  db.run("DELETE FROM network_secrets");
+  db.run("DELETE FROM provider_models");
+  db.run("DELETE FROM providers");
+});
+afterAll(() => { _resetVaultKeyForTest(); delete process.env.ANET_HUB_SECRET_VAULT_KEY; });
+
+describe("RFC-028 P1 §4.1 F2 — LAZY GATE (critical: don't brick prod hub)", () => {
+  test("hub boot WITHOUT env + WITHOUT vault data → vaultStatusForBoot says configured=false, needsKeyToOp=false (boots OK)", () => {
+    setKey(undefined);
+    const s = vaultStatusForBoot();
+    expect(s.configured).toBe(false);
+    expect(s.tablesHaveData).toBe(false);
+    expect(s.needsKeyToOp).toBe(false);
+    // Crucially: no throw, no crash, hub keeps running.
+  });
+
+  test("hub boot WITH env + WITHOUT vault data → configured=true, tablesEmpty (no fingerprint needed)", () => {
+    setKey(TEST_KEY_HEX);
+    const s = vaultStatusForBoot();
+    expect(s.configured).toBe(true);
+    expect(s.tablesHaveData).toBe(false);
+    expect(s.needsKeyToOp).toBe(false);
+  });
+
+  test("hub WITHOUT env + WITH vault data → needsKeyToOp=true (banner warning, NO throw)", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_test", "TEST_KEY", "plaintext-value");
+    setKey(undefined);
+    const s = vaultStatusForBoot();
+    expect(s.configured).toBe(false);
+    expect(s.tablesHaveData).toBe(true);
+    expect(s.needsKeyToOp).toBe(true);
+    // Still no throw — banner is informational; throw only happens on
+    // actual vault op (test below).
+  });
+
+  test("vault op WITHOUT env throws vault_master_key_missing (lazy throw, not boot throw)", () => {
+    setKey(undefined);
+    expect(() => vaultUpsert("net_test", "K", "v")).toThrow(VaultError);
+    try { vaultUpsert("net_test", "K", "v"); }
+    catch (e: any) { expect(e.code).toBe("vault_master_key_missing"); }
+  });
+
+  test("vault op WITH invalid env (not 32 bytes hex) throws vault_master_key_invalid", () => {
+    setKey("not-hex");
+    expect(() => vaultUpsert("net_test", "K", "v")).toThrow(/vault_master_key_invalid/);
+    setKey("aabbcc");  // too short
+    expect(() => vaultUpsert("net_test", "K", "v")).toThrow(/vault_master_key_invalid/);
+  });
+});
+
+describe("RFC-028 P1 §4.1 — AES-GCM encrypt/decrypt round-trip", () => {
+  test("encrypt+decrypt roundtrip preserves plaintext", () => {
+    setKey(TEST_KEY_HEX);
+    const pt = "sk-ant-api03-abc123xyz";
+    const enc = encryptSecret(pt);
+    expect(enc.ciphertext.length).toBeGreaterThan(0);
+    expect(enc.iv.length).toBe(12);
+    expect(enc.tag.length).toBe(16);
+    expect(decryptSecret(enc)).toBe(pt);
+  });
+
+  test("ciphertext is unique per call (random IV)", () => {
+    setKey(TEST_KEY_HEX);
+    const a = encryptSecret("same-secret");
+    const b = encryptSecret("same-secret");
+    expect(a.iv.equals(b.iv)).toBe(false);
+    expect(a.ciphertext.equals(b.ciphertext)).toBe(false);
+    // Both decrypt back to same plaintext
+    expect(decryptSecret(a)).toBe("same-secret");
+    expect(decryptSecret(b)).toBe("same-secret");
+  });
+
+  test("tamper detection — flipping ciphertext bit throws vault_decrypt_failed", () => {
+    setKey(TEST_KEY_HEX);
+    const enc = encryptSecret("important");
+    enc.ciphertext[0] ^= 0x01;
+    expect(() => decryptSecret(enc)).toThrow(/vault_decrypt_failed/);
+  });
+
+  test("tamper detection — flipping tag bit throws vault_decrypt_failed", () => {
+    setKey(TEST_KEY_HEX);
+    const enc = encryptSecret("important");
+    enc.tag[0] ^= 0x01;
+    expect(() => decryptSecret(enc)).toThrow(/vault_decrypt_failed/);
+  });
+
+  test("wrong key cannot decrypt", () => {
+    setKey(TEST_KEY_HEX);
+    const enc = encryptSecret("important");
+    setKey("ff".repeat(32));  // different key
+    expect(() => decryptSecret(enc)).toThrow(/vault_decrypt_failed/);
+  });
+});
+
+describe("RFC-028 P1 §4.1 — DB ops + key listing (永不返 value)", () => {
+  test("vaultUpsert + vaultGet roundtrip via DB", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_A", "ANTHROPIC_API_KEY", "sk-ant-prod-1");
+    expect(vaultGet("net_A", "ANTHROPIC_API_KEY")).toBe("sk-ant-prod-1");
+  });
+
+  test("vaultUpsert replaces existing key (same network_id + key)", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_B", "K1", "v1");
+    vaultUpsert("net_B", "K1", "v2");
+    expect(vaultGet("net_B", "K1")).toBe("v2");
+  });
+
+  test("vaultGet returns null for missing key (does NOT throw)", () => {
+    setKey(TEST_KEY_HEX);
+    expect(vaultGet("net_X", "MISSING")).toBeNull();
+  });
+
+  test("vaultListKeys returns key NAMES only (no values, ever)", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_L", "KEY_A", "value-a");
+    vaultUpsert("net_L", "KEY_B", "value-b");
+    const keys = vaultListKeys("net_L");
+    expect(keys).toEqual(["KEY_A", "KEY_B"]);  // sorted; no values
+    expect(JSON.stringify(keys)).not.toContain("value-a");
+    expect(JSON.stringify(keys)).not.toContain("value-b");
+  });
+
+  test("network isolation — netA's secret不 visible to netB", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_A", "SHARED_NAME", "value-from-A");
+    vaultUpsert("net_B", "SHARED_NAME", "value-from-B");
+    expect(vaultGet("net_A", "SHARED_NAME")).toBe("value-from-A");
+    expect(vaultGet("net_B", "SHARED_NAME")).toBe("value-from-B");
+    expect(vaultListKeys("net_A")).toEqual(["SHARED_NAME"]);
+    expect(vaultListKeys("net_B")).toEqual(["SHARED_NAME"]);
+  });
+
+  test("vaultDelete removes key + returns true; second delete returns false", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_D", "K", "v");
+    expect(vaultDelete("net_D", "K")).toBe(true);
+    expect(vaultGet("net_D", "K")).toBeNull();
+    expect(vaultDelete("net_D", "K")).toBe(false);  // no-op
+  });
+});
+
+describe("RFC-028 P1 §4.1 — master key fingerprint", () => {
+  test("fingerprint same for same key, different for different key", () => {
+    setKey(TEST_KEY_HEX);
+    const fp1 = vaultMasterKeyFingerprint();
+    expect(fp1.length).toBe(16);
+    setKey(TEST_KEY_HEX);  // re-set same key
+    expect(vaultMasterKeyFingerprint()).toBe(fp1);
+    setKey("ff".repeat(32));
+    expect(vaultMasterKeyFingerprint()).not.toBe(fp1);
+  });
+});
+
+describe("RFC-028 P1 §4.1 — DB ciphertext storage (PRAGMA-style: NO plaintext in DB)", () => {
+  test("BLOB stored is ciphertext, not plaintext (raw SELECT verifies)", () => {
+    setKey(TEST_KEY_HEX);
+    const plaintext = "sk-very-secret-key-do-not-leak";
+    vaultUpsert("net_P", "ANTHROPIC_API_KEY", plaintext);
+    const raw = db.get<{ ciphertext: Buffer | Uint8Array; iv: Buffer | Uint8Array; tag: Buffer | Uint8Array }>(
+      "SELECT ciphertext, iv, tag FROM network_secrets WHERE network_id = ?1 AND key = ?2",
+      "net_P", "ANTHROPIC_API_KEY",
+    );
+    expect(raw).not.toBeNull();
+    const ctBuf = Buffer.isBuffer(raw!.ciphertext) ? raw!.ciphertext : Buffer.from(raw!.ciphertext as any);
+    // Plaintext substring MUST NOT appear in ciphertext bytes
+    expect(ctBuf.toString("binary")).not.toContain(plaintext);
+    expect(ctBuf.toString("utf8")).not.toContain(plaintext);
+    // Even as hex / base64 / partial — bytes must not match plaintext bytes
+    const plainBytes = Buffer.from(plaintext, "utf8");
+    let found = false;
+    for (let i = 0; i <= ctBuf.length - plainBytes.length; i++) {
+      if (ctBuf.subarray(i, i + plainBytes.length).equals(plainBytes)) { found = true; break; }
+    }
+    expect(found).toBe(false);
+  });
+});

package/src/vault.ts

@@ -0,0 +1,156 @@
+// RFC-028 P1 §4.1 — vault layer (AES-GCM at-rest + lazy master key gate).
+//
+// F2 CRITICAL: master key from ANET_HUB_SECRET_VAULT_KEY env is
+// resolved LAZILY — hub boot does NOT require it. Existing prod hubs
+// without the env should boot + run normally. The env is only required
+// when:
+//   (a) vault write hits (upsert_network_secret)
+//   (b) vault read hits (probe / create-node env_refs)
+//   (c) network_secrets / providers tables are non-empty at boot
+//       (banner status only — doesn't throw)
+//
+// If the env is missing AND a vault op runs → throw `vault_master_key_missing`
+// with explicit migration message. Existing hub stays up.
+
+import { createCipheriv, createDecipheriv, randomBytes, createHash } from "node:crypto";
+import { db } from "./db.js";
+
+let _masterKey: Buffer | null = null;
+let _bootBannerShown = false;
+
+/** Lazy getter — throws on first vault op if env missing. */
+export function getVaultMasterKey(): Buffer {
+  if (_masterKey) return _masterKey;
+  const hex = process.env.ANET_HUB_SECRET_VAULT_KEY;
+  if (!hex) {
+    throw new VaultError("vault_master_key_missing",
+      "ANET_HUB_SECRET_VAULT_KEY env var not set. Generate one: openssl rand -hex 32. " +
+      "Required only when using vault/provider features; this op tried to access vault."
+    );
+  }
+  if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+    throw new VaultError("vault_master_key_invalid",
+      "ANET_HUB_SECRET_VAULT_KEY must be 32 bytes hex (64 chars). Generate: openssl rand -hex 32"
+    );
+  }
+  _masterKey = Buffer.from(hex, "hex");
+  return _masterKey;
+}
+
+/** Banner-only check (does not throw). Call on boot for operator visibility. */
+export function vaultStatusForBoot(): { configured: boolean; tablesHaveData: boolean; needsKeyToOp: boolean } {
+  const configured = !!process.env.ANET_HUB_SECRET_VAULT_KEY
+    && /^[0-9a-fA-F]{64}$/.test(process.env.ANET_HUB_SECRET_VAULT_KEY);
+  let tablesHaveData = false;
+  try {
+    const r1 = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM network_secrets");
+    const r2 = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM providers");
+    tablesHaveData = (r1?.n || 0) > 0 || (r2?.n || 0) > 0;
+  } catch { /* tables may not exist yet */ }
+  return {
+    configured,
+    tablesHaveData,
+    needsKeyToOp: tablesHaveData && !configured,
+  };
+}
+
+/** Reset for unit tests (must be combined with delete process.env.ANET_HUB_SECRET_VAULT_KEY). */
+export function _resetVaultKeyForTest(): void { _masterKey = null; _bootBannerShown = false; }
+
+export class VaultError extends Error {
+  constructor(public code: string, msg: string) {
+    super(`${code}: ${msg}`);
+    this.name = "VaultError";
+  }
+}
+
+// ── AES-GCM encrypt/decrypt ─────────────────────────────────────────
+// AES-256-GCM. 12-byte IV per RFC 5116. Auth tag is 16 bytes. We
+// store iv + ciphertext + tag separately (DB schema mirrors NIST SP
+// 800-38D structure for forward-compatibility).
+
+const ALGO = "aes-256-gcm";
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+export interface EncryptedSecret {
+  ciphertext: Buffer;
+  iv: Buffer;
+  tag: Buffer;
+}
+
+export function encryptSecret(plaintext: string): EncryptedSecret {
+  const key = getVaultMasterKey();
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return { ciphertext: ct, iv, tag };
+}
+
+export function decryptSecret(enc: EncryptedSecret): string {
+  const key = getVaultMasterKey();
+  if (enc.tag.length !== TAG_BYTES) {
+    throw new VaultError("vault_tag_invalid", `auth tag must be ${TAG_BYTES} bytes, got ${enc.tag.length}`);
+  }
+  const decipher = createDecipheriv(ALGO, key, enc.iv);
+  decipher.setAuthTag(enc.tag);
+  try {
+    const pt = Buffer.concat([decipher.update(enc.ciphertext), decipher.final()]);
+    return pt.toString("utf8");
+  } catch (e: any) {
+    // GCM auth fail = either wrong key, tampered ciphertext, or
+    // tampered iv/tag. All collapse to one error.
+    throw new VaultError("vault_decrypt_failed", `AES-GCM auth fail (key/iv/tag/ciphertext mismatch): ${e?.message || e}`);
+  }
+}
+
+// ── DB ops ───────────────────────────────────────────────────────────
+
+export function vaultUpsert(networkId: string, key: string, plaintext: string): void {
+  const enc = encryptSecret(plaintext);
+  const now = Date.now();
+  db.run(
+    `INSERT INTO network_secrets (network_id, key, ciphertext, iv, tag, created_at, updated_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?6)
+     ON CONFLICT(network_id, key) DO UPDATE SET
+       ciphertext = ?3, iv = ?4, tag = ?5, updated_at = ?6`,
+    [networkId, key, enc.ciphertext, enc.iv, enc.tag, now],
+  );
+}
+
+/** Returns the decrypted plaintext, or null if no row.
+ *  Throws VaultError on missing key / decrypt failure. */
+export function vaultGet(networkId: string, key: string): string | null {
+  const row = db.get<{ ciphertext: Buffer; iv: Buffer; tag: Buffer }>(
+    "SELECT ciphertext, iv, tag FROM network_secrets WHERE network_id = ?1 AND key = ?2",
+    networkId, key,
+  );
+  if (!row) return null;
+  return decryptSecret({
+    ciphertext: Buffer.isBuffer(row.ciphertext) ? row.ciphertext : Buffer.from(row.ciphertext as any),
+    iv:         Buffer.isBuffer(row.iv)         ? row.iv         : Buffer.from(row.iv as any),
+    tag:        Buffer.isBuffer(row.tag)        ? row.tag        : Buffer.from(row.tag as any),
+  });
+}
+
+/** List vault key names for a network (NEVER returns values). */
+export function vaultListKeys(networkId: string): string[] {
+  const rows = db.all<{ key: string }>(
+    "SELECT key FROM network_secrets WHERE network_id = ?1 ORDER BY key",
+    networkId,
+  );
+  return rows.map(r => r.key);
+}
+
+export function vaultDelete(networkId: string, key: string): boolean {
+  const r: any = db.run("DELETE FROM network_secrets WHERE network_id = ?1 AND key = ?2", [networkId, key]);
+  return (r?.changes ?? 0) > 0;
+}
+
+/** Test/diagnostic: fingerprint of master key (sha256 hex first 8) so
+ *  ops can verify two hubs share the same vault key without leaking it. */
+export function vaultMasterKeyFingerprint(): string {
+  const key = getVaultMasterKey();
+  return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}