@wopr-network/platform-core 0.1.0

package/src/security/host-validation.ts

@@ -0,0 +1,116 @@
+import { isIP } from "node:net";
+
+/**
+ * Validate a node registration host to prevent SSRF.
+ * Blocks loopback, link-local, multicast, broadcast, and unspecified addresses always.
+ * Blocks private ranges (10.x, 172.16-31.x, 192.168.x, fc00::/7) unless
+ * ALLOW_PRIVATE_NODE_HOSTS=true (for VPC deployments).
+ *
+ * NOTE: This validates the host string only. It does NOT perform DNS resolution,
+ * so hostnames that resolve to private IPs (e.g., via DNS rebinding or nip.io tricks)
+ * are not caught here. Out-of-scope for this issue.
+ */
+export function validateNodeHost(host: string): void {
+  const trimmed = host.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Invalid node host: empty");
+  }
+
+  // Check for "localhost" hostname
+  if (trimmed.toLowerCase() === "localhost") {
+    throw new Error("Invalid node host: loopback hostname");
+  }
+
+  const ipVersion = isIP(trimmed);
+
+  if (ipVersion === 4) {
+    validateIPv4(trimmed);
+    return;
+  }
+
+  if (ipVersion === 6) {
+    validateIPv6(trimmed);
+    return;
+  }
+
+  // Reject malformed IPv4-looking strings (e.g. 999.999.999.999) that isIP()
+  // returns 0 for but validateHostname() would accept as digit-only labels.
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(trimmed)) {
+    throw new Error("Invalid node host: malformed IPv4 address");
+  }
+
+  // Not an IP — treat as hostname
+  validateHostname(trimmed);
+}
+
+function validateIPv4(ip: string): void {
+  const parts = ip.split(".").map(Number);
+  const [a, b] = parts;
+
+  // Unspecified
+  if (a === 0) throw new Error("Invalid node host: unspecified address");
+
+  // Loopback — ALWAYS blocked
+  if (a === 127) throw new Error("Invalid node host: loopback address");
+
+  // Link-local — ALWAYS blocked
+  if (a === 169 && b === 254) throw new Error("Invalid node host: link-local address");
+
+  // Multicast
+  if (a >= 224 && a <= 239) throw new Error("Invalid node host: multicast address");
+
+  // Broadcast
+  if (a === 255 && b === 255) throw new Error("Invalid node host: broadcast address");
+
+  // Private ranges — blocked unless ALLOW_PRIVATE_NODE_HOSTS
+  if (!allowPrivateHosts()) {
+    if (a === 10) throw new Error("Invalid node host: private address");
+    if (a === 172 && b >= 16 && b <= 31) throw new Error("Invalid node host: private address");
+    if (a === 192 && b === 168) throw new Error("Invalid node host: private address");
+  }
+}
+
+function validateIPv6(ip: string): void {
+  const normalized = ip.toLowerCase();
+
+  // Loopback ::1 — ALWAYS blocked
+  if (normalized === "::1") throw new Error("Invalid node host: loopback address");
+
+  // Unspecified :: — ALWAYS blocked
+  if (normalized === "::") throw new Error("Invalid node host: unspecified address");
+
+  // IPv6-mapped IPv4 — check the embedded IPv4
+  const v4MappedMatch = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (v4MappedMatch) {
+    validateIPv4(v4MappedMatch[1]);
+    return;
+  }
+
+  // Link-local fe80::/10 — ALWAYS blocked
+  if (normalized.startsWith("fe80:") || normalized.startsWith("fe80")) {
+    throw new Error("Invalid node host: link-local address");
+  }
+
+  // Unique local fc00::/7 (fc00:: and fd00::) — private
+  if (!allowPrivateHosts()) {
+    if (normalized.startsWith("fc") || normalized.startsWith("fd")) {
+      throw new Error("Invalid node host: private address");
+    }
+  }
+}
+
+function validateHostname(host: string): void {
+  if (host.length > 253) throw new Error("Invalid node host: hostname too long");
+  if (host.startsWith(".") || host.endsWith(".")) throw new Error("Invalid node host: invalid hostname");
+  // RFC 1123: labels separated by dots, alphanumeric + hyphens
+  const labelPattern = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+  const labels = host.split(".");
+  for (const label of labels) {
+    if (label.length === 0 || label.length > 63) throw new Error("Invalid node host: invalid hostname");
+    if (!labelPattern.test(label)) throw new Error("Invalid node host: invalid hostname");
+  }
+}
+
+function allowPrivateHosts(): boolean {
+  return process.env.ALLOW_PRIVATE_NODE_HOSTS === "true";
+}

package/src/security/index.ts

@@ -0,0 +1,59 @@
+export type { EncryptedPayload, Provider, ValidateKeyRequest, ValidateKeyResponse, WriteSecretsRequest, ProviderEndpoint } from "./types.js";
+export { providerSchema, validateKeyRequestSchema, writeSecretsRequestSchema } from "./types.js";
+export { deriveInstanceKey, generateInstanceKey, encrypt, decrypt } from "./encryption.js";
+export { validateNodeHost } from "./host-validation.js";
+export { assertSafeRedirectUrl } from "./redirect-allowlist.js";
+export type { KeyLeakMatch } from "./key-audit.js";
+export { scanForKeyLeaks } from "./key-audit.js";
+export { writeEncryptedSeed, forwardSecretsToInstance } from "./key-injection.js";
+export { PROVIDER_ENDPOINTS, validateProviderKey } from "./key-validation.js";
+
+// Credential vault
+export {
+  type SecretAuditEvent,
+  type ISecretAuditRepository,
+  DrizzleSecretAuditRepository,
+  type CredentialRow,
+  type CredentialSummaryRow,
+  type InsertCredentialRow,
+  type ICredentialMigrationAccess,
+  type ICredentialRepository,
+  type IMigrationTenantKeyAccess,
+  DrizzleCredentialRepository,
+  DrizzleMigrationTenantKeyAccess,
+  type RotationResult,
+  reEncryptAllCredentials,
+  type MigrationResult,
+  migratePlaintextCredentials,
+  type PlaintextFinding,
+  auditCredentialEncryption,
+  type AuthType,
+  type CreateCredentialInput,
+  type CredentialSummary,
+  type DecryptedCredential,
+  type ICredentialVaultStore,
+  type RotateCredentialInput,
+  CredentialVaultStore,
+  getVaultEncryptionKey,
+} from "./credential-vault/index.js";
+
+// Tenant keys
+export {
+  type IKeyResolutionRepository,
+  DrizzleKeyResolutionRepository,
+  type ResolvedKey,
+  resolveApiKey,
+  buildPooledKeysMap,
+  type TenantApiKey,
+  type ITenantKeyRepository,
+  TenantKeyRepository,
+  type CapabilityName,
+  type TenantCapabilitySetting,
+  type ICapabilitySettingsRepository,
+  ALL_CAPABILITIES,
+  CapabilitySettingsStore,
+  type IOrgMembershipRepository,
+  type OrgResolvedKey,
+  DrizzleOrgMembershipRepository,
+  resolveApiKeyWithOrgFallback,
+} from "./tenant-keys/index.js";

package/src/security/key-audit.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { scanForKeyLeaks } from "./key-audit.js";
+
+describe("key-audit", () => {
+  describe("scanForKeyLeaks", () => {
+    it("detects Anthropic key patterns", () => {
+      const content = "info: processing request with key sk-ant-abcdefghijklmnopqrstuvwxyz123456";
+      const leaks = scanForKeyLeaks(content);
+      expect(leaks.length).toBe(1);
+      expect(leaks[0].provider).toBe("anthropic");
+      expect(leaks[0].line).toBe(1);
+    });
+
+    it("detects OpenAI key patterns", () => {
+      const content = "debug: using API key sk-abcdefghijklmnopqrstuvwxyz";
+      const leaks = scanForKeyLeaks(content);
+      expect(leaks.some((l) => l.provider === "openai")).toBe(true);
+    });
+
+    it("detects Google key patterns", () => {
+      const content = "config: api_key=AIzaSyA1234567890abcdefghijklmnopqrstuvwx";
+      const leaks = scanForKeyLeaks(content);
+      expect(leaks.some((l) => l.provider === "google")).toBe(true);
+    });
+
+    it("returns empty array for clean logs", () => {
+      const content = [
+        "info: server started on port 3000",
+        "info: health check passed",
+        "debug: processing request id=abc-123",
+      ].join("\n");
+      const leaks = scanForKeyLeaks(content);
+      expect(leaks).toEqual([]);
+    });
+
+    it("detects multiple leaks across lines", () => {
+      const content = [
+        "line 1: safe content",
+        "line 2: key=sk-ant-abcdefghijklmnopqrstuvwxyz",
+        "line 3: also sk-abcdefghijklmnopqrstuvwxyz",
+      ].join("\n");
+      const leaks = scanForKeyLeaks(content);
+      expect(leaks.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it("truncates matched key in output for safety", () => {
+      const content = "key: sk-ant-abcdefghijklmnopqrstuvwxyz123456";
+      const leaks = scanForKeyLeaks(content);
+      expect(leaks[0].match).toContain("...");
+      expect(leaks[0].match.length).toBeLessThan(40);
+    });
+
+    it("handles empty input", () => {
+      expect(scanForKeyLeaks("")).toEqual([]);
+    });
+  });
+});

package/src/security/key-audit.ts

@@ -0,0 +1,45 @@
+/**
+ * Key material audit — grep-based detection of leaked key patterns in log output.
+ *
+ * This utility scans arbitrary text (log lines, config dumps, etc.) for patterns
+ * that look like provider API keys. Used in tests to verify zero key leakage.
+ */
+
+/** Patterns that match common provider key formats. */
+const KEY_PATTERNS: { provider: string; pattern: RegExp }[] = [
+  { provider: "anthropic", pattern: /sk-ant-[A-Za-z0-9_-]{20,}/ },
+  { provider: "openai", pattern: /sk-[A-Za-z0-9]{20,}/ },
+  { provider: "google", pattern: /AIza[A-Za-z0-9_-]{30,}/ },
+  { provider: "discord", pattern: /[A-Za-z0-9_-]{24}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27,}/ },
+];
+
+export interface KeyLeakMatch {
+  provider: string;
+  line: number;
+  match: string;
+}
+
+/**
+ * Scan text content for key-like patterns.
+ * Returns an array of matches found — empty array means no leaks detected.
+ */
+export function scanForKeyLeaks(content: string): KeyLeakMatch[] {
+  const leaks: KeyLeakMatch[] = [];
+  const lines = content.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const { provider, pattern } of KEY_PATTERNS) {
+      const match = line.match(pattern);
+      if (match) {
+        leaks.push({
+          provider,
+          line: i + 1,
+          match: `${match[0].slice(0, 8)}...${match[0].slice(-4)}`,
+        });
+      }
+    }
+  }
+
+  return leaks;
+}

package/src/security/key-injection.test.ts

@@ -0,0 +1,131 @@
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { decrypt, generateInstanceKey } from "./encryption.js";
+import { forwardSecretsToInstance, writeEncryptedSeed } from "./key-injection.js";
+
+describe("key-injection", () => {
+  describe("writeEncryptedSeed", () => {
+    let tmpDir: string;
+    const key = generateInstanceKey();
+
+    beforeEach(async () => {
+      const { mkdtemp } = await import("node:fs/promises");
+      tmpDir = await mkdtemp(path.join(os.tmpdir(), "wopr-test-"));
+    });
+
+    afterEach(async () => {
+      const { rm } = await import("node:fs/promises");
+      await rm(tmpDir, { recursive: true, force: true });
+    });
+
+    it("writes secrets.enc to the woprHome directory", async () => {
+      const woprHome = path.join(tmpDir, "instance-1");
+      const secrets = { ANTHROPIC_API_KEY: "sk-ant-test123" };
+
+      await writeEncryptedSeed(woprHome, secrets, key);
+
+      const seedPath = path.join(woprHome, "secrets.enc");
+      const content = await readFile(seedPath, "utf-8");
+      const payload = JSON.parse(content);
+
+      expect(payload).toHaveProperty("iv");
+      expect(payload).toHaveProperty("authTag");
+      expect(payload).toHaveProperty("ciphertext");
+    });
+
+    it("encrypted seed can be decrypted back to original secrets", async () => {
+      const woprHome = path.join(tmpDir, "instance-2");
+      const secrets = { DISCORD_TOKEN: "token123", OPENAI_KEY: "sk-openai" };
+
+      await writeEncryptedSeed(woprHome, secrets, key);
+
+      const seedPath = path.join(woprHome, "secrets.enc");
+      const content = await readFile(seedPath, "utf-8");
+      const payload = JSON.parse(content);
+      const decrypted = JSON.parse(decrypt(payload, key));
+
+      expect(decrypted).toEqual(secrets);
+    });
+
+    it("creates directories recursively", async () => {
+      const woprHome = path.join(tmpDir, "deep", "nested", "dir");
+      await writeEncryptedSeed(woprHome, { KEY: "val" }, key);
+
+      const content = await readFile(path.join(woprHome, "secrets.enc"), "utf-8");
+      expect(JSON.parse(content)).toHaveProperty("ciphertext");
+    });
+
+    it("seed file does NOT contain plaintext key values", async () => {
+      const woprHome = path.join(tmpDir, "instance-3");
+      const secrets = { ANTHROPIC_API_KEY: "sk-ant-api0xxxxxxxxxxxxxxxxxxxx" };
+
+      await writeEncryptedSeed(woprHome, secrets, key);
+
+      const content = await readFile(path.join(woprHome, "secrets.enc"), "utf-8");
+      expect(content).not.toContain("sk-ant-api0xxxxxxxxxxxxxxxxxxxx");
+    });
+  });
+
+  describe("forwardSecretsToInstance", () => {
+    const originalFetch = globalThis.fetch;
+
+    beforeEach(() => {
+      globalThis.fetch = vi.fn();
+    });
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+    });
+
+    it("forwards body opaquely and returns ok on success", async () => {
+      vi.mocked(globalThis.fetch).mockResolvedValue(new Response(null, { status: 200 }));
+
+      const result = await forwardSecretsToInstance("http://container:3000", "session-token", '{"KEY":"val"}');
+
+      expect(result.ok).toBe(true);
+      expect(result.status).toBe(200);
+      expect(globalThis.fetch).toHaveBeenCalledWith(
+        "http://container:3000/config/secrets",
+        expect.objectContaining({
+          method: "PUT",
+          body: '{"KEY":"val"}',
+          headers: expect.objectContaining({
+            Authorization: "Bearer session-token",
+          }),
+        }),
+      );
+    });
+
+    it("returns error on non-ok response", async () => {
+      vi.mocked(globalThis.fetch).mockResolvedValue(new Response("Forbidden", { status: 403 }));
+
+      const result = await forwardSecretsToInstance("http://container:3000", "token", "{}");
+
+      expect(result.ok).toBe(false);
+      expect(result.status).toBe(403);
+      expect(result.error).toBe("Forbidden");
+    });
+
+    it("returns 502 on network error", async () => {
+      vi.mocked(globalThis.fetch).mockRejectedValue(new Error("Connection refused"));
+
+      const result = await forwardSecretsToInstance("http://container:3000", "token", "{}");
+
+      expect(result.ok).toBe(false);
+      expect(result.status).toBe(502);
+      expect(result.error).toBe("Connection refused");
+    });
+
+    it("returns 502 with fallback message when thrown value is not an Error", async () => {
+      vi.mocked(globalThis.fetch).mockRejectedValue("string error");
+
+      const result = await forwardSecretsToInstance("http://container:3000", "token", "{}");
+
+      expect(result.ok).toBe(false);
+      expect(result.status).toBe(502);
+      expect(result.error).toBe("Failed to forward secrets");
+    });
+  });
+});

package/src/security/key-injection.ts

@@ -0,0 +1,71 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { logger } from "../config/logger.js";
+import { encrypt } from "./encryption.js";
+import type { EncryptedPayload } from "./types.js";
+
+/**
+ * Write an encrypted seed file to an instance's WOPR_HOME volume.
+ * Used during initial provisioning when the instance container isn't running yet.
+ *
+ * The platform writes ciphertext only — it never sees or persists the plaintext keys.
+ * The instance decrypts on first boot using its own derived key (injected as a Docker secret).
+ *
+ * @param woprHome - Absolute path to the instance's WOPR_HOME volume mount.
+ * @param secrets - Key-value map of secrets to encrypt.
+ * @param instanceKey - The 32-byte instance-derived encryption key.
+ * @returns The encrypted payload that was written.
+ */
+export async function writeEncryptedSeed(
+  woprHome: string,
+  secrets: Record<string, string>,
+  instanceKey: Buffer,
+): Promise<EncryptedPayload> {
+  const serialized = JSON.stringify(secrets);
+  const encrypted = encrypt(serialized, instanceKey);
+
+  await mkdir(woprHome, { recursive: true });
+  const seedPath = path.join(woprHome, "secrets.enc");
+  await writeFile(seedPath, JSON.stringify(encrypted), { mode: 0o600 });
+
+  logger.info("Wrote encrypted seed file", { path: seedPath });
+  return encrypted;
+}
+
+/**
+ * Forward secrets opaquely to a running instance container.
+ * The platform acts as a pass-through — it never parses or logs the request body.
+ *
+ * @param instanceUrl - The internal URL of the running instance (e.g., http://container:3000).
+ * @param sessionToken - The user's session token for authentication.
+ * @param opaqueBody - The raw request body string to forward without parsing.
+ * @returns Whether the write succeeded.
+ */
+export async function forwardSecretsToInstance(
+  instanceUrl: string,
+  sessionToken: string,
+  opaqueBody: string,
+): Promise<{ ok: boolean; status: number; error?: string }> {
+  try {
+    const response = await fetch(`${instanceUrl}/config/secrets`, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${sessionToken}`,
+      },
+      body: opaqueBody,
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (response.ok) {
+      return { ok: true, status: response.status };
+    }
+
+    const errorText = await response.text().catch(() => "Unknown error");
+    return { ok: false, status: response.status, error: errorText };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Failed to forward secrets";
+    logger.error("Failed to forward secrets to instance", { error: message });
+    return { ok: false, status: 502, error: message };
+  }
+}

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

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PROVIDER_API_URLS } from "../config/provider-endpoints.js";
+import { PROVIDER_ENDPOINTS, validateProviderKey } from "./key-validation.js";
+
+describe("key-validation", () => {
+  describe("PROVIDER_API_URLS", () => {
+    it("exports a URL for every supported provider", () => {
+      expect(PROVIDER_API_URLS.anthropic).toBe("https://api.anthropic.com/v1/models");
+      expect(PROVIDER_API_URLS.openai).toBe("https://api.openai.com/v1/models");
+      expect(PROVIDER_API_URLS.google).toBe("https://generativelanguage.googleapis.com/v1/models");
+      expect(PROVIDER_API_URLS.discord).toBe("https://discord.com/api/v10/users/@me");
+      expect(PROVIDER_API_URLS.elevenlabs).toBe("https://api.elevenlabs.io/v1/user");
+      expect(PROVIDER_API_URLS.deepgram).toBe("https://api.deepgram.com/v1/projects");
+    });
+  });
+
+  describe("PROVIDER_ENDPOINTS", () => {
+    it("has entries for all supported providers", () => {
+      expect(PROVIDER_ENDPOINTS.anthropic).toEqual(expect.any(Object));
+      expect(PROVIDER_ENDPOINTS.openai).toEqual(expect.any(Object));
+      expect(PROVIDER_ENDPOINTS.google).toEqual(expect.any(Object));
+      expect(PROVIDER_ENDPOINTS.discord).toEqual(expect.any(Object));
+    });
+
+    it("anthropic headers include x-api-key", () => {
+      const headers = PROVIDER_ENDPOINTS.anthropic.headers("test-key");
+      expect(headers["x-api-key"]).toBe("test-key");
+      expect(headers["anthropic-version"]).toBe("2023-06-01");
+    });
+
+    it("openai headers include Bearer token", () => {
+      const headers = PROVIDER_ENDPOINTS.openai.headers("test-key");
+      expect(headers.Authorization).toBe("Bearer test-key");
+    });
+
+    it("google headers include x-goog-api-key", () => {
+      const headers = PROVIDER_ENDPOINTS.google.headers("test-key");
+      expect(headers["x-goog-api-key"]).toBe("test-key");
+    });
+
+    it("discord headers include Bot prefix", () => {
+      const headers = PROVIDER_ENDPOINTS.discord.headers("test-key");
+      expect(headers.Authorization).toBe("Bot test-key");
+    });
+  });
+
+  describe("validateProviderKey", () => {
+    const originalFetch = globalThis.fetch;
+
+    beforeEach(() => {
+      globalThis.fetch = vi.fn();
+    });
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+    });
+
+    it("returns valid=true when provider returns 200", async () => {
+      vi.mocked(globalThis.fetch).mockResolvedValue(new Response(null, { status: 200 }));
+
+      const result = await validateProviderKey("openai", "sk-valid-key");
+      expect(result.valid).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("returns valid=false with error for 401", async () => {
+      vi.mocked(globalThis.fetch).mockResolvedValue(new Response(null, { status: 401 }));
+
+      const result = await validateProviderKey("anthropic", "sk-ant-invalid");
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe("Invalid API key");
+    });
+
+    it("returns valid=false with error for 403", async () => {
+      vi.mocked(globalThis.fetch).mockResolvedValue(new Response(null, { status: 403 }));
+
+      const result = await validateProviderKey("discord", "bad-token");
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe("Invalid API key");
+    });
+
+    it("returns valid=false with status for non-auth errors", async () => {
+      vi.mocked(globalThis.fetch).mockResolvedValue(new Response(null, { status: 500 }));
+
+      const result = await validateProviderKey("openai", "sk-key");
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe("Provider returned status 500");
+    });
+
+    it("returns valid=false on network error", async () => {
+      vi.mocked(globalThis.fetch).mockRejectedValue(new Error("Network timeout"));
+
+      const result = await validateProviderKey("google", "AIza-key");
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe("Network timeout");
+    });
+
+    it("calls the correct provider URL", async () => {
+      vi.mocked(globalThis.fetch).mockResolvedValue(new Response(null, { status: 200 }));
+
+      await validateProviderKey("anthropic", "sk-ant-test");
+      expect(globalThis.fetch).toHaveBeenCalledWith(
+        "https://api.anthropic.com/v1/models",
+        expect.objectContaining({
+          method: "GET",
+          headers: expect.objectContaining({ "x-api-key": "sk-ant-test" }),
+        }),
+      );
+    });
+  });
+});

package/src/security/key-validation.ts

@@ -0,0 +1,84 @@
+import { PROVIDER_API_URLS } from "../config/provider-endpoints.js";
+import type { Provider, ProviderEndpoint, ValidateKeyResponse } from "./types.js";
+
+/**
+ * Provider API endpoints used for key validation.
+ * For CORS-friendly providers, the browser can call these directly.
+ * For CORS-blocked providers (e.g., Anthropic), the platform proxy decrypts
+ * and validates in memory without ever logging the key.
+ * URLs are sourced from PROVIDER_API_URLS; headers are provider-specific.
+ */
+export const PROVIDER_ENDPOINTS: Record<Provider, ProviderEndpoint> = {
+  anthropic: {
+    url: PROVIDER_API_URLS.anthropic,
+    headers: (key) => ({
+      "x-api-key": key,
+      "anthropic-version": "2023-06-01",
+    }),
+  },
+  openai: {
+    url: PROVIDER_API_URLS.openai,
+    headers: (key) => ({
+      Authorization: `Bearer ${key}`,
+    }),
+  },
+  google: {
+    url: PROVIDER_API_URLS.google,
+    headers: (key) => ({
+      "x-goog-api-key": key,
+    }),
+  },
+  discord: {
+    url: PROVIDER_API_URLS.discord,
+    headers: (key) => ({
+      Authorization: `Bot ${key}`,
+    }),
+  },
+  elevenlabs: {
+    url: PROVIDER_API_URLS.elevenlabs,
+    headers: (key) => ({
+      "xi-api-key": key,
+    }),
+  },
+  deepgram: {
+    url: PROVIDER_API_URLS.deepgram,
+    headers: (key) => ({
+      Authorization: `Token ${key}`,
+    }),
+  },
+};
+
+/**
+ * Validate a provider API key by making a lightweight read-only request.
+ * The key is held in memory only for the duration of the fetch and then discarded.
+ *
+ * SECURITY: This function must NEVER log, persist, or return the key itself.
+ */
+export async function validateProviderKey(provider: Provider, key: string): Promise<ValidateKeyResponse> {
+  const endpoint = PROVIDER_ENDPOINTS[provider];
+  if (!endpoint) {
+    return { valid: false, error: `Unknown provider: ${provider}` };
+  }
+
+  try {
+    const response = await fetch(endpoint.url, {
+      method: "GET",
+      headers: endpoint.headers(key),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (response.ok) {
+      return { valid: true };
+    }
+
+    // 401/403 = invalid key; other errors are transient
+    if (response.status === 401 || response.status === 403) {
+      return { valid: false, error: "Invalid API key" };
+    }
+
+    return { valid: false, error: `Provider returned status ${response.status}` };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Validation request failed";
+    return { valid: false, error: message };
+  }
+}