@wopr-network/platform-core 0.1.0

package/src/security/redirect-allowlist.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { assertSafeRedirectUrl } from "./redirect-allowlist.js";
+
+describe("assertSafeRedirectUrl", () => {
+  it("allows https://app.wopr.bot paths", () => {
+    expect(() => assertSafeRedirectUrl("https://app.wopr.bot/billing/success")).not.toThrow();
+  });
+
+  it("allows https://app.wopr.bot with query params", () => {
+    expect(() => assertSafeRedirectUrl("https://app.wopr.bot/dashboard?vps=activated")).not.toThrow();
+  });
+
+  it("allows https://wopr.network paths", () => {
+    expect(() => assertSafeRedirectUrl("https://wopr.network/welcome")).not.toThrow();
+  });
+
+  it("allows http://localhost:3000 in dev", () => {
+    expect(() => assertSafeRedirectUrl("http://localhost:3000/billing")).not.toThrow();
+  });
+
+  it("allows http://localhost:3001 in dev", () => {
+    expect(() => assertSafeRedirectUrl("http://localhost:3001/billing")).not.toThrow();
+  });
+
+  it("rejects external domains", () => {
+    expect(() => assertSafeRedirectUrl("https://evil.com/phishing")).toThrow("Invalid redirect URL");
+  });
+
+  it("rejects subdomain spoofing (app.wopr.bot.evil.com)", () => {
+    expect(() => assertSafeRedirectUrl("https://app.wopr.bot.evil.com/phishing")).toThrow("Invalid redirect URL");
+  });
+
+  it("rejects non-URL strings", () => {
+    expect(() => assertSafeRedirectUrl("not-a-url")).toThrow("Invalid redirect URL");
+  });
+
+  it("rejects javascript: URIs", () => {
+    expect(() => assertSafeRedirectUrl("javascript:alert(1)")).toThrow("Invalid redirect URL");
+  });
+
+  it("rejects data: URIs", () => {
+    expect(() => assertSafeRedirectUrl("data:text/html,<h1>pwned</h1>")).toThrow("Invalid redirect URL");
+  });
+
+  it("rejects empty string", () => {
+    expect(() => assertSafeRedirectUrl("")).toThrow("Invalid redirect URL");
+  });
+
+  describe("PLATFORM_UI_URL env-driven entry", () => {
+    beforeEach(() => {
+      process.env.PLATFORM_UI_URL = "https://platform.example.com";
+      vi.resetModules();
+    });
+
+    afterEach(() => {
+      delete process.env.PLATFORM_UI_URL;
+      vi.resetModules();
+    });
+
+    it("allows PLATFORM_UI_URL when set", async () => {
+      const { assertSafeRedirectUrl: assertSafe } = await import("./redirect-allowlist.js");
+      expect(() => assertSafe("https://platform.example.com/dashboard")).not.toThrow();
+    });
+
+    it("rejects URLs not matching PLATFORM_UI_URL", async () => {
+      const { assertSafeRedirectUrl: assertSafe } = await import("./redirect-allowlist.js");
+      expect(() => assertSafe("https://other.example.com/dashboard")).toThrow("Invalid redirect URL");
+    });
+  });
+});

package/src/security/redirect-allowlist.ts

@@ -0,0 +1,35 @@
+const ALLOWED_REDIRECT_ORIGINS: string[] = [
+  "https://app.wopr.bot",
+  "https://wopr.network",
+  ...(process.env.NODE_ENV !== "production" ? ["http://localhost:3000", "http://localhost:3001"] : []),
+  ...(process.env.PLATFORM_UI_URL ? [process.env.PLATFORM_UI_URL] : []),
+  ...(process.env.NODE_ENV !== "production" ? ["https://example.com"] : []),
+];
+
+/**
+ * Throws if `url` is not rooted at one of the allowed origins.
+ * Comparison is scheme + host (origin), not prefix string match,
+ * to prevent bypasses like `https://app.wopr.bot.evil.com`.
+ */
+export function assertSafeRedirectUrl(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error("Invalid redirect URL");
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error("Invalid redirect URL");
+  }
+  const origin = parsed.origin;
+  const allowed = ALLOWED_REDIRECT_ORIGINS.some((o) => {
+    try {
+      return origin === new URL(o).origin;
+    } catch {
+      return false;
+    }
+  });
+  if (!allowed) {
+    throw new Error("Invalid redirect URL");
+  }
+}

package/src/security/tenant-keys/capability-settings-store.test.ts

@@ -0,0 +1,98 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { CapabilitySettingsStore } from "./capability-settings-store.js";
+
+describe("CapabilitySettingsStore", () => {
+  let db: PlatformDb;
+  let pool: PGlite;
+  let store: CapabilitySettingsStore;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    store = new CapabilitySettingsStore(db);
+  });
+
+  it("returns empty array for tenant with no overrides (platform defaults apply)", async () => {
+    const settings = await store.listForTenant("tenant-no-overrides");
+    expect(settings).toEqual([]);
+  });
+
+  it("upsert sets per-tenant override that listForTenant returns", async () => {
+    await store.upsert("tenant-1", "transcription", "byok");
+
+    const settings = await store.listForTenant("tenant-1");
+    expect(settings).toHaveLength(1);
+    expect(settings[0]).toMatchObject({
+      tenant_id: "tenant-1",
+      capability: "transcription",
+      mode: "byok",
+    });
+    expect(settings[0].updated_at).toBeGreaterThan(0);
+  });
+
+  it("upsert can toggle mode between hosted and byok", async () => {
+    await store.upsert("tenant-2", "image-gen", "byok");
+    let settings = await store.listForTenant("tenant-2");
+    expect(settings[0].mode).toBe("byok");
+
+    await store.upsert("tenant-2", "image-gen", "hosted");
+    settings = await store.listForTenant("tenant-2");
+    expect(settings).toHaveLength(1);
+    expect(settings[0].mode).toBe("hosted");
+  });
+
+  it("upsert overwrites previous mode via onConflictDoUpdate", async () => {
+    await store.upsert("tenant-3", "text-gen", "hosted");
+    const before = await store.listForTenant("tenant-3");
+    const firstUpdatedAt = before[0].updated_at;
+
+    // Small delay so timestamp differs
+    await new Promise((r) => setTimeout(r, 5));
+
+    await store.upsert("tenant-3", "text-gen", "byok");
+    const after = await store.listForTenant("tenant-3");
+    expect(after).toHaveLength(1);
+    expect(after[0].mode).toBe("byok");
+    expect(after[0].updated_at).toBeGreaterThanOrEqual(firstUpdatedAt);
+  });
+
+  it("tenant A overrides do not appear in tenant B list", async () => {
+    await store.upsert("tenant-A", "transcription", "byok");
+    await store.upsert("tenant-A", "image-gen", "byok");
+    await store.upsert("tenant-B", "embeddings", "hosted");
+
+    const settingsA = await store.listForTenant("tenant-A");
+    const settingsB = await store.listForTenant("tenant-B");
+
+    expect(settingsA).toHaveLength(2);
+    expect(settingsA.every((s) => s.tenant_id === "tenant-A")).toBe(true);
+
+    expect(settingsB).toHaveLength(1);
+    expect(settingsB[0].tenant_id).toBe("tenant-B");
+    expect(settingsB[0].capability).toBe("embeddings");
+  });
+
+  it("upsert changes are immediately visible in subsequent reads (no stale cache)", async () => {
+    await store.upsert("tenant-C", "text-gen", "hosted");
+    const read1 = await store.listForTenant("tenant-C");
+    expect(read1[0].mode).toBe("hosted");
+
+    await store.upsert("tenant-C", "text-gen", "byok");
+    const read2 = await store.listForTenant("tenant-C");
+    expect(read2[0].mode).toBe("byok");
+
+    await store.upsert("tenant-C", "image-gen", "byok");
+    const read3 = await store.listForTenant("tenant-C");
+    expect(read3).toHaveLength(2);
+  });
+});

package/src/security/tenant-keys/capability-settings-store.ts

@@ -0,0 +1,53 @@
+import { eq } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { tenantCapabilitySettings } from "../../db/schema/index.js";
+
+export const ALL_CAPABILITIES = ["transcription", "image-gen", "text-gen", "embeddings"] as const;
+export type CapabilityName = (typeof ALL_CAPABILITIES)[number];
+
+export interface TenantCapabilitySetting {
+  tenant_id: string;
+  capability: string;
+  mode: string;
+  updated_at: number;
+}
+
+/** Repository for tenant capability mode settings (hosted vs byok). */
+export interface ICapabilitySettingsRepository {
+  listForTenant(tenantId: string): Promise<TenantCapabilitySetting[]>;
+  upsert(tenantId: string, capability: string, mode: string): Promise<void>;
+}
+
+export class CapabilitySettingsStore implements ICapabilitySettingsRepository {
+  private readonly db: PlatformDb;
+
+  constructor(db: PlatformDb) {
+    this.db = db;
+  }
+
+  /** Get all capability settings for a tenant. Returns empty array if none set (defaults to hosted). */
+  async listForTenant(tenantId: string): Promise<TenantCapabilitySetting[]> {
+    const rows = await this.db
+      .select()
+      .from(tenantCapabilitySettings)
+      .where(eq(tenantCapabilitySettings.tenantId, tenantId));
+    return rows.map((r) => ({
+      tenant_id: r.tenantId,
+      capability: r.capability,
+      mode: r.mode,
+      updated_at: r.updatedAt,
+    }));
+  }
+
+  /** Set the mode for a specific capability. Upserts. */
+  async upsert(tenantId: string, capability: string, mode: string): Promise<void> {
+    const now = Date.now();
+    await this.db
+      .insert(tenantCapabilitySettings)
+      .values({ tenantId, capability, mode, updatedAt: now })
+      .onConflictDoUpdate({
+        target: [tenantCapabilitySettings.tenantId, tenantCapabilitySettings.capability],
+        set: { mode, updatedAt: now },
+      });
+  }
+}

package/src/security/tenant-keys/index.ts

@@ -0,0 +1,10 @@
+export type { IKeyResolutionRepository } from "./key-resolution-repository.js";
+export { DrizzleKeyResolutionRepository } from "./key-resolution-repository.js";
+export type { ResolvedKey } from "./key-resolution.js";
+export { resolveApiKey, buildPooledKeysMap } from "./key-resolution.js";
+export type { TenantApiKey, ITenantKeyRepository } from "./tenant-key-repository.js";
+export { TenantKeyRepository } from "./tenant-key-repository.js";
+export type { CapabilityName, TenantCapabilitySetting, ICapabilitySettingsRepository } from "./capability-settings-store.js";
+export { ALL_CAPABILITIES, CapabilitySettingsStore } from "./capability-settings-store.js";
+export type { IOrgMembershipRepository, OrgResolvedKey } from "./org-key-resolution.js";
+export { DrizzleOrgMembershipRepository, resolveApiKeyWithOrgFallback } from "./org-key-resolution.js";

package/src/security/tenant-keys/key-resolution-repository.test.ts

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { tenantApiKeys } from "../../db/schema/tenant-api-keys.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import type { Provider } from "../types.js";
+import { DrizzleKeyResolutionRepository } from "./key-resolution-repository.js";
+
+let db: PlatformDb;
+let pool: PGlite;
+
+async function insertKey(tenantId: string, provider: Provider, encryptedKey: string): Promise<void> {
+  const now = Date.now();
+  await db
+    .insert(tenantApiKeys)
+    .values({ id: randomUUID(), tenantId, provider, label: "", encryptedKey, createdAt: now, updatedAt: now });
+}
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+});
+
+afterAll(async () => {
+  await pool.close();
+});
+
+describe("DrizzleKeyResolutionRepository", () => {
+  let repo: DrizzleKeyResolutionRepository;
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    repo = new DrizzleKeyResolutionRepository(db);
+  });
+
+  it("returns the encrypted key for a matching tenant and provider", async () => {
+    const payload = JSON.stringify({ iv: "aaa", authTag: "bbb", ciphertext: "ccc" });
+    await insertKey("tenant-1", "anthropic", payload);
+
+    const result = await repo.findEncryptedKey("tenant-1", "anthropic");
+
+    expect(result).not.toBeNull();
+    expect(result?.encryptedKey).toBe(payload);
+  });
+
+  it("returns null when no key exists for the tenant", async () => {
+    const result = await repo.findEncryptedKey("nonexistent-tenant", "anthropic");
+    expect(result).toBeNull();
+  });
+
+  it("returns null when no key exists for the provider", async () => {
+    const payload = JSON.stringify({ iv: "aaa", authTag: "bbb", ciphertext: "ccc" });
+    await insertKey("tenant-1", "anthropic", payload);
+
+    const result = await repo.findEncryptedKey("tenant-1", "openai");
+    expect(result).toBeNull();
+  });
+
+  it("isolates keys between tenants (cross-tenant isolation)", async () => {
+    const payloadA = JSON.stringify({ iv: "aaa", authTag: "bbb", ciphertext: "tenant-a-secret" });
+    const payloadB = JSON.stringify({ iv: "xxx", authTag: "yyy", ciphertext: "tenant-b-secret" });
+    await insertKey("tenant-a", "anthropic", payloadA);
+    await insertKey("tenant-b", "anthropic", payloadB);
+
+    const resultA = await repo.findEncryptedKey("tenant-a", "anthropic");
+    const resultB = await repo.findEncryptedKey("tenant-b", "anthropic");
+
+    expect(resultA).not.toBeNull();
+    expect(resultB).not.toBeNull();
+    expect(resultA?.encryptedKey).toBe(payloadA);
+    expect(resultB?.encryptedKey).toBe(payloadB);
+    expect(resultA?.encryptedKey).not.toBe(resultB?.encryptedKey);
+  });
+
+  it("tenant A cannot see tenant B keys", async () => {
+    const payload = JSON.stringify({ iv: "aaa", authTag: "bbb", ciphertext: "only-for-b" });
+    await insertKey("tenant-b", "openai", payload);
+
+    const result = await repo.findEncryptedKey("tenant-a", "openai");
+    expect(result).toBeNull();
+  });
+
+  it("returns correct key when tenant has multiple providers", async () => {
+    const anthropicPayload = JSON.stringify({ iv: "a1", authTag: "a2", ciphertext: "anthropic-key" });
+    const openaiPayload = JSON.stringify({ iv: "o1", authTag: "o2", ciphertext: "openai-key" });
+    await insertKey("tenant-1", "anthropic", anthropicPayload);
+    await insertKey("tenant-1", "openai", openaiPayload);
+
+    const anthropicResult = await repo.findEncryptedKey("tenant-1", "anthropic");
+    const openaiResult = await repo.findEncryptedKey("tenant-1", "openai");
+
+    expect(anthropicResult?.encryptedKey).toBe(anthropicPayload);
+    expect(openaiResult?.encryptedKey).toBe(openaiPayload);
+  });
+});

package/src/security/tenant-keys/key-resolution-repository.ts

@@ -0,0 +1,31 @@
+import { and, eq } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { tenantApiKeys } from "../../db/schema/index.js";
+import type { Provider } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Interface
+// ---------------------------------------------------------------------------
+
+/** Repository for looking up tenant BYOK keys by tenant + provider. */
+export interface IKeyResolutionRepository {
+  findEncryptedKey(tenantId: string, provider: Provider): Promise<{ encryptedKey: string } | null>;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export class DrizzleKeyResolutionRepository implements IKeyResolutionRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async findEncryptedKey(tenantId: string, provider: Provider): Promise<{ encryptedKey: string } | null> {
+    const row = (
+      await this.db
+        .select({ encryptedKey: tenantApiKeys.encryptedKey })
+        .from(tenantApiKeys)
+        .where(and(eq(tenantApiKeys.tenantId, tenantId), eq(tenantApiKeys.provider, provider)))
+    )[0];
+    return row ?? null;
+  }
+}

package/src/security/tenant-keys/key-resolution.test.ts

@@ -0,0 +1,173 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { encrypt, generateInstanceKey } from "../encryption.js";
+import type { EncryptedPayload, Provider } from "../types.js";
+import { buildPooledKeysMap, resolveApiKey } from "./key-resolution.js";
+import { DrizzleKeyResolutionRepository } from "./key-resolution-repository.js";
+
+async function insertTenantKey(
+  pool: PGlite,
+  tenantId: string,
+  provider: string,
+  encryptedKey: EncryptedPayload,
+): Promise<void> {
+  const { randomUUID } = await import("node:crypto");
+  const now = Date.now();
+  await pool.query(
+    "INSERT INTO tenant_api_keys (id, tenant_id, provider, label, encrypted_key, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6, $7)",
+    [randomUUID(), tenantId, provider, "", JSON.stringify(encryptedKey), now, now],
+  );
+}
+
+let db: PlatformDb;
+let pool: PGlite;
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+});
+
+afterAll(async () => {
+  await pool.close();
+});
+
+describe("resolveApiKey", () => {
+  let encryptionKey: Buffer;
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    encryptionKey = generateInstanceKey();
+  });
+
+  it("returns tenant BYOK key when one is stored", async () => {
+    const encrypted = encrypt("sk-ant-tenant-key", encryptionKey);
+    await insertTenantKey(pool, "t1", "anthropic", encrypted);
+
+    const pooled = new Map<Provider, string>([["anthropic", "sk-ant-pooled"]]);
+    const result = await resolveApiKey(
+      new DrizzleKeyResolutionRepository(db),
+      "t1",
+      "anthropic",
+      encryptionKey,
+      pooled,
+    );
+    expect(result).not.toBeNull();
+    expect(result?.key).toBe("sk-ant-tenant-key");
+    expect(result?.source).toBe("tenant");
+    expect(result?.provider).toBe("anthropic");
+  });
+
+  it("falls back to pooled key when no tenant key stored", async () => {
+    const pooled = new Map<Provider, string>([["openai", "sk-pooled-openai"]]);
+    const result = await resolveApiKey(new DrizzleKeyResolutionRepository(db), "t1", "openai", encryptionKey, pooled);
+    expect(result).not.toBeNull();
+    expect(result?.key).toBe("sk-pooled-openai");
+    expect(result?.source).toBe("pooled");
+    expect(result?.provider).toBe("openai");
+  });
+
+  it("returns null when neither tenant nor pooled key exists", async () => {
+    const pooled = new Map<Provider, string>();
+    const result = await resolveApiKey(
+      new DrizzleKeyResolutionRepository(db),
+      "t1",
+      "anthropic",
+      encryptionKey,
+      pooled,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("resolves different providers independently", async () => {
+    const encrypted = encrypt("my-google-key", encryptionKey);
+    await insertTenantKey(pool, "t1", "google", encrypted);
+
+    const pooled = new Map<Provider, string>([["anthropic", "sk-ant-pooled"]]);
+
+    const googleResult = await resolveApiKey(
+      new DrizzleKeyResolutionRepository(db),
+      "t1",
+      "google",
+      encryptionKey,
+      pooled,
+    );
+    expect(googleResult?.source).toBe("tenant");
+    expect(googleResult?.key).toBe("my-google-key");
+
+    const anthropicResult = await resolveApiKey(
+      new DrizzleKeyResolutionRepository(db),
+      "t1",
+      "anthropic",
+      encryptionKey,
+      pooled,
+    );
+    expect(anthropicResult?.source).toBe("pooled");
+    expect(anthropicResult?.key).toBe("sk-ant-pooled");
+
+    const discordResult = await resolveApiKey(
+      new DrizzleKeyResolutionRepository(db),
+      "t1",
+      "discord",
+      encryptionKey,
+      pooled,
+    );
+    expect(discordResult).toBeNull();
+  });
+
+  it("isolates keys between tenants", async () => {
+    const encrypted = encrypt("t1-anthropic-key", encryptionKey);
+    await insertTenantKey(pool, "t1", "anthropic", encrypted);
+
+    const pooled = new Map<Provider, string>([["anthropic", "sk-ant-pooled"]]);
+
+    const t1Result = await resolveApiKey(
+      new DrizzleKeyResolutionRepository(db),
+      "t1",
+      "anthropic",
+      encryptionKey,
+      pooled,
+    );
+    expect(t1Result?.source).toBe("tenant");
+
+    const t2Result = await resolveApiKey(
+      new DrizzleKeyResolutionRepository(db),
+      "t2",
+      "anthropic",
+      encryptionKey,
+      pooled,
+    );
+    expect(t2Result?.source).toBe("pooled");
+  });
+});
+
+describe("buildPooledKeysMap", () => {
+  it("reads keys from environment variables", () => {
+    const env = {
+      ANTHROPIC_API_KEY: "sk-ant-test",
+      OPENAI_API_KEY: "sk-openai-test",
+      GOOGLE_API_KEY: "google-test",
+      DISCORD_BOT_TOKEN: "discord-test",
+    };
+    const keys = buildPooledKeysMap(env);
+    expect(keys.get("anthropic")).toBe("sk-ant-test");
+    expect(keys.get("openai")).toBe("sk-openai-test");
+    expect(keys.get("google")).toBe("google-test");
+    expect(keys.get("discord")).toBe("discord-test");
+  });
+
+  it("ignores missing env vars", () => {
+    const keys = buildPooledKeysMap({});
+    expect(keys.size).toBe(0);
+  });
+
+  it("trims whitespace from values", () => {
+    const keys = buildPooledKeysMap({ ANTHROPIC_API_KEY: "  sk-ant-test  " });
+    expect(keys.get("anthropic")).toBe("sk-ant-test");
+  });
+
+  it("ignores empty values", () => {
+    const keys = buildPooledKeysMap({ ANTHROPIC_API_KEY: "  " });
+    expect(keys.size).toBe(0);
+  });
+});

package/src/security/tenant-keys/key-resolution.ts

@@ -0,0 +1,87 @@
+import { decrypt } from "../encryption.js";
+import type { Provider } from "../types.js";
+import type { IKeyResolutionRepository } from "./key-resolution-repository.js";
+
+/** Result of resolving which API key to use. */
+export interface ResolvedKey {
+  /** The plaintext API key. */
+  key: string;
+  /** Where the key came from. */
+  source: "tenant" | "pooled";
+  /** The provider the key is for. */
+  provider: Provider;
+}
+
+/**
+ * Resolve which API key to use for a given tenant and provider.
+ *
+ * Resolution order:
+ * 1. If the tenant has a BYOK key stored, decrypt and return it.
+ * 2. Otherwise, fall back to the pooled (platform-level) key from env vars.
+ * 3. If neither exists, return null.
+ *
+ * SECURITY: The decrypted key is returned to the caller and must be discarded
+ * after use. This function does not log, persist, or cache the plaintext key.
+ *
+ * @param repo - Repository for looking up tenant BYOK keys
+ * @param tenantId - The tenant requesting the key
+ * @param provider - The AI provider (anthropic, openai, google, discord)
+ * @param encryptionKey - The 32-byte key used to decrypt the stored BYOK key
+ * @param pooledKeys - Map of provider -> pooled API key (from env vars)
+ */
+export async function resolveApiKey(
+  repo: IKeyResolutionRepository,
+  tenantId: string,
+  provider: Provider,
+  encryptionKey: Buffer,
+  pooledKeys: Map<Provider, string>,
+): Promise<ResolvedKey | null> {
+  // 1. Check for tenant BYOK key
+  const row = await repo.findEncryptedKey(tenantId, provider);
+
+  if (row) {
+    const payload = JSON.parse(row.encryptedKey);
+    const plaintext = decrypt(payload, encryptionKey);
+    return { key: plaintext, source: "tenant", provider };
+  }
+
+  // 2. Fall back to pooled key
+  const pooledKey = pooledKeys.get(provider);
+  if (pooledKey) {
+    return { key: pooledKey, source: "pooled", provider };
+  }
+
+  // 3. No key available
+  return null;
+}
+
+/**
+ * Build a pooled keys map from environment variables.
+ *
+ * Reads:
+ * - ANTHROPIC_API_KEY
+ * - OPENAI_API_KEY
+ * - GOOGLE_API_KEY
+ * - DISCORD_BOT_TOKEN
+ */
+export function buildPooledKeysMap(
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): Map<Provider, string> {
+  const keys = new Map<Provider, string>();
+
+  const mapping: [string, Provider][] = [
+    ["ANTHROPIC_API_KEY", "anthropic"],
+    ["OPENAI_API_KEY", "openai"],
+    ["GOOGLE_API_KEY", "google"],
+    ["DISCORD_BOT_TOKEN", "discord"],
+  ];
+
+  for (const [envVar, provider] of mapping) {
+    const val = env[envVar]?.trim();
+    if (val) {
+      keys.set(provider, val);
+    }
+  }
+
+  return keys;
+}