@wopr-network/platform-core 0.1.0

package/src/security/credential-vault/store.ts

@@ -0,0 +1,284 @@
+import { createHmac, randomUUID } from "node:crypto";
+import type { AdminAuditLog } from "../../admin/audit-log.js";
+import { decrypt, encrypt, generateInstanceKey } from "../encryption.js";
+import type { EncryptedPayload } from "../types.js";
+import type { ISecretAuditRepository, SecretAuditEvent } from "./audit-repository.js";
+import type { ICredentialRepository } from "./credential-repository.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Auth mechanism for injecting the key into upstream requests. */
+export type AuthType = "header" | "bearer" | "basic";
+
+/** Input for creating a new credential. */
+export interface CreateCredentialInput {
+  provider: string;
+  keyName: string;
+  /** Plaintext API key — encrypted before storage, never persisted raw. */
+  plaintextKey: string;
+  authType: AuthType;
+  authHeader?: string;
+  createdBy: string;
+}
+
+/** Input for rotating an existing credential's key. */
+export interface RotateCredentialInput {
+  id: string;
+  /** New plaintext API key. */
+  plaintextKey: string;
+  rotatedBy: string;
+}
+
+/** A credential record with the encrypted value omitted for listing. */
+export interface CredentialSummary {
+  id: string;
+  provider: string;
+  keyName: string;
+  authType: string;
+  authHeader: string | null;
+  isActive: boolean;
+  lastValidated: string | null;
+  createdAt: string;
+  rotatedAt: string | null;
+  createdBy: string;
+}
+
+/** A decrypted credential ready for gateway injection. */
+export interface DecryptedCredential {
+  id: string;
+  provider: string;
+  keyName: string;
+  /** The plaintext API key. MUST be discarded after use. */
+  plaintextKey: string;
+  authType: string;
+  authHeader: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
+export interface ICredentialVaultStore {
+  create(input: CreateCredentialInput): Promise<string>;
+  list(provider?: string): Promise<CredentialSummary[]>;
+  getById(id: string): Promise<CredentialSummary | null>;
+  decrypt(id: string): Promise<DecryptedCredential | null>;
+  getActiveForProvider(provider: string): Promise<DecryptedCredential[]>;
+  rotate(input: RotateCredentialInput): Promise<boolean>;
+  setActive(id: string, isActive: boolean, changedBy: string): Promise<boolean>;
+  markValidated(id: string): Promise<boolean>;
+  delete(id: string, deletedBy: string): Promise<boolean>;
+}
+
+/**
+ * Credential vault store — encrypted CRUD for platform-level provider API keys.
+ *
+ * SECURITY:
+ * - Keys are encrypted with AES-256-GCM before storage.
+ * - The encryption key is derived from a platform secret (env var).
+ * - Plaintext keys are never logged, persisted, or returned in list operations.
+ * - All mutations are audit-logged.
+ */
+export class CredentialVaultStore implements ICredentialVaultStore {
+  private readonly repo: ICredentialRepository;
+  private readonly encryptionKey: Buffer;
+  private readonly auditLog: AdminAuditLog | null;
+  private readonly secretAuditRepo: ISecretAuditRepository | null;
+
+  constructor(
+    repo: ICredentialRepository,
+    encryptionKey: Buffer,
+    auditLog?: AdminAuditLog,
+    secretAuditRepo?: ISecretAuditRepository,
+  ) {
+    this.repo = repo;
+    this.encryptionKey = encryptionKey;
+    this.auditLog = auditLog ?? null;
+    this.secretAuditRepo = secretAuditRepo ?? null;
+  }
+
+  private recordSecretAudit(
+    credentialId: string,
+    accessedBy: string,
+    action: "read" | "write" | "delete",
+    ip?: string | null,
+  ): void {
+    if (!this.secretAuditRepo) return;
+    const event: SecretAuditEvent = {
+      id: randomUUID(),
+      credentialId,
+      accessedAt: Date.now(),
+      accessedBy,
+      action,
+      ip: ip ?? null,
+    };
+    // Fire-and-forget — audit must never break primary operations
+    this.secretAuditRepo.insert(event).catch(() => {});
+  }
+
+  /** Create a new provider credential. Returns the record ID. */
+  async create(input: CreateCredentialInput): Promise<string> {
+    const id = randomUUID();
+    const encrypted = encrypt(input.plaintextKey, this.encryptionKey);
+    const serialized = JSON.stringify(encrypted);
+
+    await this.repo.insert({
+      id,
+      provider: input.provider,
+      keyName: input.keyName,
+      encryptedValue: serialized,
+      authType: input.authType,
+      authHeader: input.authHeader ?? null,
+      createdBy: input.createdBy,
+    });
+
+    this.audit(input.createdBy, "credential.create", {
+      credentialId: id,
+      provider: input.provider,
+      keyName: input.keyName,
+    });
+    this.recordSecretAudit(id, input.createdBy, "write");
+
+    return id;
+  }
+
+  /** List all credentials for a provider (or all providers). Never returns encrypted values. */
+  async list(provider?: string): Promise<CredentialSummary[]> {
+    const rows = await this.repo.list(provider);
+    return rows.map((r) => ({ ...r, isActive: r.isActive }));
+  }
+
+  /** Get a single credential summary by ID. */
+  async getById(id: string): Promise<CredentialSummary | null> {
+    const row = await this.repo.getSummaryById(id);
+    if (!row) return null;
+    return { ...row, isActive: row.isActive };
+  }
+
+  /**
+   * Decrypt and return a credential's key. For gateway use only.
+   *
+   * SECURITY: The returned plaintext key MUST be discarded after use.
+   */
+  async decrypt(id: string): Promise<DecryptedCredential | null> {
+    const row = await this.repo.getFullById(id);
+    if (!row) return null;
+
+    const payload: EncryptedPayload = JSON.parse(row.encryptedValue);
+    const plaintextKey = decrypt(payload, this.encryptionKey);
+
+    return {
+      id: row.id,
+      provider: row.provider,
+      keyName: row.keyName,
+      plaintextKey,
+      authType: row.authType,
+      authHeader: row.authHeader,
+    };
+  }
+
+  /**
+   * Get the active credential(s) for a provider, decrypted.
+   * Returns all active keys for load distribution; caller picks one.
+   *
+   * SECURITY: Returned keys MUST be discarded after use.
+   */
+  async getActiveForProvider(provider: string): Promise<DecryptedCredential[]> {
+    const rows = await this.repo.listActiveForProvider(provider);
+    return rows.map((row) => {
+      const payload: EncryptedPayload = JSON.parse(row.encryptedValue);
+      const plaintextKey = decrypt(payload, this.encryptionKey);
+      return {
+        id: row.id,
+        provider: row.provider,
+        keyName: row.keyName,
+        plaintextKey,
+        authType: row.authType,
+        authHeader: row.authHeader,
+      };
+    });
+  }
+
+  /** Rotate a credential's key. Encrypts the new key and records the rotation timestamp. */
+  async rotate(input: RotateCredentialInput): Promise<boolean> {
+    const existing = await this.repo.getSummaryById(input.id);
+    if (!existing) return false;
+
+    const encrypted = encrypt(input.plaintextKey, this.encryptionKey);
+    const serialized = JSON.stringify(encrypted);
+    await this.repo.updateEncryptedValue(input.id, serialized);
+
+    this.audit(input.rotatedBy, "credential.rotate", {
+      credentialId: input.id,
+      provider: existing.provider,
+    });
+    this.recordSecretAudit(input.id, input.rotatedBy, "write");
+
+    return true;
+  }
+
+  /** Mark a credential as active or inactive. */
+  async setActive(id: string, isActive: boolean, changedBy: string): Promise<boolean> {
+    const existing = await this.repo.getSummaryById(id);
+    if (!existing) return false;
+
+    await this.repo.setActive(id, isActive);
+
+    this.audit(changedBy, isActive ? "credential.activate" : "credential.deactivate", {
+      credentialId: id,
+      provider: existing.provider,
+    });
+    this.recordSecretAudit(id, changedBy, "write");
+
+    return true;
+  }
+
+  /** Record a successful validation timestamp. */
+  async markValidated(id: string): Promise<boolean> {
+    return this.repo.markValidated(id);
+  }
+
+  /** Permanently delete a credential. */
+  async delete(id: string, deletedBy: string): Promise<boolean> {
+    const existing = await this.repo.getSummaryById(id);
+    if (!existing) return false;
+
+    await this.repo.deleteById(id);
+
+    this.audit(deletedBy, "credential.delete", {
+      credentialId: id,
+      provider: existing.provider,
+      keyName: existing.keyName,
+    });
+    this.recordSecretAudit(id, deletedBy, "delete");
+
+    return true;
+  }
+
+  // -----------------------------------------------------------------------
+  // Audit helper
+  // -----------------------------------------------------------------------
+
+  private audit(adminUser: string, action: string, details: Record<string, unknown>): void {
+    if (!this.auditLog) return;
+    this.auditLog.log({
+      adminUser,
+      action,
+      category: "config",
+      details,
+    });
+  }
+}
+
+/**
+ * Derive the credential vault encryption key from a platform secret.
+ * If no secret is provided, generates a random key (suitable for tests only).
+ */
+export function getVaultEncryptionKey(platformSecret?: string): Buffer {
+  if (platformSecret) {
+    return createHmac("sha256", platformSecret).update("credential-vault").digest();
+  }
+  return generateInstanceKey();
+}

package/src/security/encryption.test.ts

@@ -0,0 +1,114 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { decrypt, deriveInstanceKey, encrypt, generateInstanceKey } from "./encryption.js";
+
+describe("encryption", () => {
+  describe("generateInstanceKey", () => {
+    it("returns a 32-byte buffer", () => {
+      const key = generateInstanceKey();
+      expect(key).toBeInstanceOf(Buffer);
+      expect(key.length).toBe(32);
+    });
+
+    it("generates unique keys", () => {
+      const a = generateInstanceKey();
+      const b = generateInstanceKey();
+      expect(a.equals(b)).toBe(false);
+    });
+  });
+
+  describe("deriveInstanceKey", () => {
+    it("returns a 32-byte buffer", () => {
+      const key = deriveInstanceKey("instance-123", "platform-secret");
+      expect(key).toBeInstanceOf(Buffer);
+      expect(key.length).toBe(32);
+    });
+
+    it("is deterministic for the same inputs", () => {
+      const a = deriveInstanceKey("instance-123", "secret");
+      const b = deriveInstanceKey("instance-123", "secret");
+      expect(a.equals(b)).toBe(true);
+    });
+
+    it("differs for different instance IDs", () => {
+      const a = deriveInstanceKey("instance-1", "secret");
+      const b = deriveInstanceKey("instance-2", "secret");
+      expect(a.equals(b)).toBe(false);
+    });
+
+    it("differs for different secrets", () => {
+      const a = deriveInstanceKey("instance-1", "secret-a");
+      const b = deriveInstanceKey("instance-1", "secret-b");
+      expect(a.equals(b)).toBe(false);
+    });
+  });
+
+  describe("encrypt / decrypt round-trip", () => {
+    const key = generateInstanceKey();
+
+    it("encrypts and decrypts a simple string", () => {
+      const plaintext = "hello world";
+      const encrypted = encrypt(plaintext, key);
+      const decrypted = decrypt(encrypted, key);
+      expect(decrypted).toBe(plaintext);
+    });
+
+    it("encrypts and decrypts JSON secrets", () => {
+      const secrets = JSON.stringify({ ANTHROPIC_API_KEY: "sk-ant-test123", DISCORD_TOKEN: "token123" });
+      const encrypted = encrypt(secrets, key);
+      const decrypted = decrypt(encrypted, key);
+      expect(decrypted).toBe(secrets);
+    });
+
+    it("encrypts and decrypts empty string", () => {
+      const encrypted = encrypt("", key);
+      const decrypted = decrypt(encrypted, key);
+      expect(decrypted).toBe("");
+    });
+
+    it("produces different ciphertext for same plaintext (random IV)", () => {
+      const plaintext = "same data";
+      const a = encrypt(plaintext, key);
+      const b = encrypt(plaintext, key);
+      expect(a.ciphertext).not.toBe(b.ciphertext);
+      expect(a.iv).not.toBe(b.iv);
+    });
+
+    it("returns hex-encoded fields", () => {
+      const encrypted = encrypt("test", key);
+      expect(encrypted.iv).toMatch(/^[0-9a-f]+$/);
+      expect(encrypted.authTag).toMatch(/^[0-9a-f]+$/);
+      expect(encrypted.ciphertext).toMatch(/^[0-9a-f]+$/);
+    });
+  });
+
+  describe("decrypt error cases", () => {
+    const key = generateInstanceKey();
+
+    it("throws with wrong key", () => {
+      const encrypted = encrypt("secret data", key);
+      const wrongKey = generateInstanceKey();
+      expect(() => decrypt(encrypted, wrongKey)).toThrow();
+    });
+
+    it("throws with tampered ciphertext", () => {
+      const encrypted = encrypt("secret data", key);
+      const tampered = { ...encrypted, ciphertext: "deadbeef".repeat(8) };
+      expect(() => decrypt(tampered, tampered.iv.length > 0 ? key : key)).toThrow();
+    });
+
+    it("throws with tampered auth tag", () => {
+      const encrypted = encrypt("secret data", key);
+      const tampered = { ...encrypted, authTag: "00".repeat(16) };
+      expect(() => decrypt(tampered, key)).toThrow();
+    });
+
+    it("throws with wrong key length", () => {
+      const shortKey = randomBytes(16);
+      expect(() => encrypt("test", shortKey)).toThrow("Encryption key must be 32 bytes");
+      expect(() => decrypt({ iv: "", authTag: "", ciphertext: "" }, shortKey)).toThrow(
+        "Encryption key must be 32 bytes",
+      );
+    });
+  });
+});

package/src/security/encryption.ts

@@ -0,0 +1,65 @@
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";
+import type { EncryptedPayload } from "./types.js";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_BYTES = 16;
+const KEY_BYTES = 32;
+
+/**
+ * Derive a per-instance encryption key from the instance ID and a platform secret.
+ * Uses HMAC-SHA256 so the platform never stores the raw key — it's deterministic
+ * from (instanceId + platformSecret) but the secret lives only in Docker secrets.
+ */
+export function deriveInstanceKey(instanceId: string, platformSecret: string): Buffer {
+  return createHmac("sha256", platformSecret).update(instanceId).digest();
+}
+
+/**
+ * Generate a random 32-byte encryption key.
+ * Used when creating a new instance to produce a Docker secret.
+ */
+export function generateInstanceKey(): Buffer {
+  return randomBytes(KEY_BYTES);
+}
+
+/**
+ * Encrypt a plaintext string with AES-256-GCM.
+ * Returns a structured payload with iv, authTag, and ciphertext (all hex-encoded).
+ */
+export function encrypt(plaintext: string, key: Buffer): EncryptedPayload {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(`Encryption key must be ${KEY_BYTES} bytes, got ${key.length}`);
+  }
+
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf-8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  return {
+    iv: iv.toString("hex"),
+    authTag: authTag.toString("hex"),
+    ciphertext: encrypted.toString("hex"),
+  };
+}
+
+/**
+ * Decrypt an AES-256-GCM encrypted payload back to plaintext.
+ * Throws on tampered data or wrong key.
+ */
+export function decrypt(payload: EncryptedPayload, key: Buffer): string {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(`Encryption key must be ${KEY_BYTES} bytes, got ${key.length}`);
+  }
+
+  const iv = Buffer.from(payload.iv, "hex");
+  const authTag = Buffer.from(payload.authTag, "hex");
+  const ciphertext = Buffer.from(payload.ciphertext, "hex");
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return decrypted.toString("utf-8");
+}

package/src/security/host-validation.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { validateNodeHost } from "./host-validation.js";
+
+describe("validateNodeHost", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  // --- VALID hosts ---
+  it("accepts a public IPv4 address", () => {
+    expect(() => validateNodeHost("203.0.113.10")).not.toThrow();
+  });
+
+  it("accepts a valid hostname", () => {
+    expect(() => validateNodeHost("node-1.fleet.wopr.network")).not.toThrow();
+  });
+
+  it("accepts a public IPv6 address", () => {
+    expect(() => validateNodeHost("2001:db8::1")).not.toThrow();
+  });
+
+  // --- ALWAYS blocked ---
+  it("rejects empty string", () => {
+    expect(() => validateNodeHost("")).toThrow("Invalid node host");
+  });
+
+  it("rejects whitespace-only string", () => {
+    expect(() => validateNodeHost("   ")).toThrow("Invalid node host");
+  });
+
+  it("rejects loopback 127.0.0.1", () => {
+    expect(() => validateNodeHost("127.0.0.1")).toThrow("Invalid node host");
+  });
+
+  it("rejects loopback 127.0.0.2", () => {
+    expect(() => validateNodeHost("127.0.0.2")).toThrow("Invalid node host");
+  });
+
+  it("rejects link-local 169.254.169.254", () => {
+    expect(() => validateNodeHost("169.254.169.254")).toThrow("Invalid node host");
+  });
+
+  it("rejects IPv6 loopback ::1", () => {
+    expect(() => validateNodeHost("::1")).toThrow("Invalid node host");
+  });
+
+  it("rejects IPv6-mapped loopback ::ffff:127.0.0.1", () => {
+    expect(() => validateNodeHost("::ffff:127.0.0.1")).toThrow("Invalid node host");
+  });
+
+  it("rejects multicast 224.0.0.1", () => {
+    expect(() => validateNodeHost("224.0.0.1")).toThrow("Invalid node host");
+  });
+
+  it("rejects broadcast 255.255.255.255", () => {
+    expect(() => validateNodeHost("255.255.255.255")).toThrow("Invalid node host");
+  });
+
+  it("rejects 0.0.0.0", () => {
+    expect(() => validateNodeHost("0.0.0.0")).toThrow("Invalid node host");
+  });
+
+  it("rejects localhost hostname", () => {
+    expect(() => validateNodeHost("localhost")).toThrow("Invalid node host");
+  });
+
+  // --- Private ranges (blocked by default) ---
+  it("rejects 10.x.x.x by default", () => {
+    expect(() => validateNodeHost("10.0.0.1")).toThrow("Invalid node host");
+  });
+
+  it("rejects 172.16.x.x by default", () => {
+    expect(() => validateNodeHost("172.16.0.1")).toThrow("Invalid node host");
+  });
+
+  it("rejects 192.168.x.x by default", () => {
+    expect(() => validateNodeHost("192.168.1.1")).toThrow("Invalid node host");
+  });
+
+  it("rejects IPv6 unique local fc00::", () => {
+    expect(() => validateNodeHost("fc00::1")).toThrow("Invalid node host");
+  });
+
+  // --- Private ranges (allowed with env var) ---
+  it("allows 10.x.x.x when ALLOW_PRIVATE_NODE_HOSTS=true", () => {
+    vi.stubEnv("ALLOW_PRIVATE_NODE_HOSTS", "true");
+    expect(() => validateNodeHost("10.0.0.1")).not.toThrow();
+  });
+
+  it("allows 172.16.x.x when ALLOW_PRIVATE_NODE_HOSTS=true", () => {
+    vi.stubEnv("ALLOW_PRIVATE_NODE_HOSTS", "true");
+    expect(() => validateNodeHost("172.16.0.1")).not.toThrow();
+  });
+
+  it("allows 192.168.x.x when ALLOW_PRIVATE_NODE_HOSTS=true", () => {
+    vi.stubEnv("ALLOW_PRIVATE_NODE_HOSTS", "true");
+    expect(() => validateNodeHost("192.168.1.1")).not.toThrow();
+  });
+
+  it("still blocks loopback even with ALLOW_PRIVATE_NODE_HOSTS=true", () => {
+    vi.stubEnv("ALLOW_PRIVATE_NODE_HOSTS", "true");
+    expect(() => validateNodeHost("127.0.0.1")).toThrow("Invalid node host");
+  });
+
+  it("still blocks link-local even with ALLOW_PRIVATE_NODE_HOSTS=true", () => {
+    vi.stubEnv("ALLOW_PRIVATE_NODE_HOSTS", "true");
+    expect(() => validateNodeHost("169.254.169.254")).toThrow("Invalid node host");
+  });
+
+  // --- Malformed IPv4-looking strings ---
+  it("rejects malformed dotted-quad 999.999.999.999", () => {
+    expect(() => validateNodeHost("999.999.999.999")).toThrow("Invalid node host: malformed IPv4 address");
+  });
+
+  it("rejects malformed dotted-quad 256.0.0.1", () => {
+    expect(() => validateNodeHost("256.0.0.1")).toThrow("Invalid node host: malformed IPv4 address");
+  });
+
+  it("rejects malformed dotted-quad 1.2.3.999", () => {
+    expect(() => validateNodeHost("1.2.3.999")).toThrow("Invalid node host: malformed IPv4 address");
+  });
+
+  // --- Hostname validation ---
+  it("rejects hostnames with spaces", () => {
+    expect(() => validateNodeHost("host name")).toThrow("Invalid node host");
+  });
+
+  it("rejects hostnames starting with a dot", () => {
+    expect(() => validateNodeHost(".example.com")).toThrow("Invalid node host");
+  });
+
+  it("rejects hostnames longer than 253 characters", () => {
+    const long = "a".repeat(254);
+    expect(() => validateNodeHost(long)).toThrow("Invalid node host");
+  });
+});