@wopr-network/platform-core 0.1.0

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

@@ -0,0 +1,217 @@
+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 { createTestDb, truncateAllTables } from "../../test/db.js";
+import { encrypt, generateInstanceKey } from "../encryption.js";
+import type { EncryptedPayload, Provider } from "../types.js";
+import { resolveApiKey } from "./key-resolution.js";
+import { DrizzleKeyResolutionRepository } from "./key-resolution-repository.js";
+import { DrizzleOrgMembershipRepository, resolveApiKeyWithOrgFallback } from "./org-key-resolution.js";
+
+async function insertTenantKey(
+  pool: PGlite,
+  tenantId: string,
+  provider: string,
+  encryptedKey: EncryptedPayload,
+): Promise<void> {
+  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],
+  );
+}
+
+async function insertOrgMembership(pool: PGlite, orgTenantId: string, memberTenantId: string): Promise<void> {
+  await pool.query("INSERT INTO org_memberships (org_tenant_id, member_tenant_id, created_at) VALUES ($1, $2, $3)", [
+    orgTenantId,
+    memberTenantId,
+    Date.now(),
+  ]);
+}
+
+describe("resolveApiKeyWithOrgFallback", () => {
+  let db: PlatformDb;
+  let pool: PGlite;
+  let membershipRepo: DrizzleOrgMembershipRepository;
+  let encryptionKey: Buffer;
+  let orgEncryptionKey: Buffer;
+  const pooled = new Map<Provider, string>();
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    membershipRepo = new DrizzleOrgMembershipRepository(db);
+    encryptionKey = generateInstanceKey();
+    orgEncryptionKey = generateInstanceKey();
+  });
+
+  it("returns personal key when member has one (no org fallback)", async () => {
+    const encrypted = encrypt("sk-personal", encryptionKey);
+    await insertTenantKey(pool, "member-1", "anthropic", encrypted);
+    await insertOrgMembership(pool, "org-1", "member-1");
+
+    const orgEncrypted = encrypt("sk-org", orgEncryptionKey);
+    await insertTenantKey(pool, "org-1", "anthropic", orgEncrypted);
+
+    const result = await resolveApiKeyWithOrgFallback(
+      (tid, prov, encKey) =>
+        resolveApiKey(new DrizzleKeyResolutionRepository(db), tid, prov, encKey, new Map()).then((r) => r?.key ?? null),
+      "member-1",
+      "anthropic",
+      encryptionKey,
+      pooled,
+      (tenantId) => (tenantId === "org-1" ? orgEncryptionKey : encryptionKey),
+      membershipRepo,
+    );
+    expect(result).not.toBeNull();
+    expect(result?.key).toBe("sk-personal");
+    expect(result?.source).toBe("tenant");
+  });
+
+  it("falls back to org key when member has no personal key", async () => {
+    await insertOrgMembership(pool, "org-1", "member-1");
+
+    const orgEncrypted = encrypt("sk-org-key", orgEncryptionKey);
+    await insertTenantKey(pool, "org-1", "anthropic", orgEncrypted);
+
+    const result = await resolveApiKeyWithOrgFallback(
+      (tid, prov, encKey) =>
+        resolveApiKey(new DrizzleKeyResolutionRepository(db), tid, prov, encKey, new Map()).then((r) => r?.key ?? null),
+      "member-1",
+      "anthropic",
+      encryptionKey,
+      pooled,
+      (tenantId) => (tenantId === "org-1" ? orgEncryptionKey : encryptionKey),
+      membershipRepo,
+    );
+    expect(result).not.toBeNull();
+    expect(result?.key).toBe("sk-org-key");
+    expect(result?.source).toBe("org");
+  });
+
+  it("falls back to pooled when neither member nor org has a key", async () => {
+    await insertOrgMembership(pool, "org-1", "member-1");
+
+    const pooledKeys = new Map<Provider, string>([["anthropic", "sk-pooled"]]);
+
+    const result = await resolveApiKeyWithOrgFallback(
+      (tid, prov, encKey) =>
+        resolveApiKey(new DrizzleKeyResolutionRepository(db), tid, prov, encKey, new Map()).then((r) => r?.key ?? null),
+      "member-1",
+      "anthropic",
+      encryptionKey,
+      pooledKeys,
+      () => encryptionKey,
+      membershipRepo,
+    );
+    expect(result).not.toBeNull();
+    expect(result?.key).toBe("sk-pooled");
+    expect(result?.source).toBe("pooled");
+  });
+
+  it("returns null when no key exists anywhere", async () => {
+    const result = await resolveApiKeyWithOrgFallback(
+      (tid, prov, encKey) =>
+        resolveApiKey(new DrizzleKeyResolutionRepository(db), tid, prov, encKey, new Map()).then((r) => r?.key ?? null),
+      "member-1",
+      "anthropic",
+      encryptionKey,
+      pooled,
+      () => encryptionKey,
+      membershipRepo,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("works for tenants not in any org (same as resolveApiKey)", async () => {
+    const encrypted = encrypt("sk-solo", encryptionKey);
+    await insertTenantKey(pool, "solo-tenant", "openai", encrypted);
+
+    const result = await resolveApiKeyWithOrgFallback(
+      (tid, prov, encKey) =>
+        resolveApiKey(new DrizzleKeyResolutionRepository(db), tid, prov, encKey, new Map()).then((r) => r?.key ?? null),
+      "solo-tenant",
+      "openai",
+      encryptionKey,
+      pooled,
+      () => encryptionKey,
+      membershipRepo,
+    );
+    expect(result).not.toBeNull();
+    expect(result?.key).toBe("sk-solo");
+    expect(result?.source).toBe("tenant");
+  });
+
+  it("full chain: personal > org > pooled > null", async () => {
+    const memberKey = generateInstanceKey();
+    const orgKey = generateInstanceKey();
+    const pooledKeys = new Map<Provider, string>([["discord", "pooled-discord"]]);
+    const deriveKey = (tid: string) => (tid === "org-1" ? orgKey : memberKey);
+
+    await insertOrgMembership(pool, "org-1", "m1");
+    await insertTenantKey(pool, "m1", "anthropic", encrypt("personal-anthropic", memberKey));
+    await insertTenantKey(pool, "org-1", "openai", encrypt("org-openai", orgKey));
+
+    const lookupKey = (tid: string, prov: Provider, encKey: Buffer) =>
+      resolveApiKey(new DrizzleKeyResolutionRepository(db), tid, prov, encKey, new Map()).then((r) => r?.key ?? null);
+
+    // anthropic: personal wins
+    const r1 = await resolveApiKeyWithOrgFallback(
+      lookupKey,
+      "m1",
+      "anthropic",
+      memberKey,
+      pooledKeys,
+      deriveKey,
+      membershipRepo,
+    );
+    expect(r1?.source).toBe("tenant");
+    expect(r1?.key).toBe("personal-anthropic");
+
+    // openai: org fallback
+    const r2 = await resolveApiKeyWithOrgFallback(
+      lookupKey,
+      "m1",
+      "openai",
+      memberKey,
+      pooledKeys,
+      deriveKey,
+      membershipRepo,
+    );
+    expect(r2?.source).toBe("org");
+    expect(r2?.key).toBe("org-openai");
+
+    // discord: pooled fallback
+    const r3 = await resolveApiKeyWithOrgFallback(
+      lookupKey,
+      "m1",
+      "discord",
+      memberKey,
+      pooledKeys,
+      deriveKey,
+      membershipRepo,
+    );
+    expect(r3?.source).toBe("pooled");
+    expect(r3?.key).toBe("pooled-discord");
+
+    // google: null
+    const r4 = await resolveApiKeyWithOrgFallback(
+      lookupKey,
+      "m1",
+      "google",
+      memberKey,
+      new Map(),
+      deriveKey,
+      membershipRepo,
+    );
+    expect(r4).toBeNull();
+  });
+});

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

@@ -0,0 +1,76 @@
+import { eq } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { orgMemberships } from "../../db/schema/index.js";
+import type { Provider } from "../types.js";
+
+/** Minimal interface for org membership lookup (provided by consumer). */
+export interface IOrgMembershipRepository {
+  getOrgTenantIdForMember(memberTenantId: string): Promise<string | null>;
+}
+
+export class DrizzleOrgMembershipRepository implements IOrgMembershipRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async getOrgTenantIdForMember(memberTenantId: string): Promise<string | null> {
+    const rows = await this.db
+      .select({ orgTenantId: orgMemberships.orgTenantId })
+      .from(orgMemberships)
+      .where(eq(orgMemberships.memberTenantId, memberTenantId));
+    return rows[0]?.orgTenantId ?? null;
+  }
+}
+
+/** Extended resolution result that includes "org" as a source. */
+export interface OrgResolvedKey {
+  key: string;
+  source: "tenant" | "org" | "pooled";
+  provider: Provider;
+}
+
+/**
+ * Resolve API key with org fallback.
+ *
+ * Resolution order:
+ * 1. Personal tenant BYOK key
+ * 2. Org tenant BYOK key (if member belongs to an org)
+ * 3. Pooled platform key
+ * 4. null
+ *
+ * @param lookupKey - Callback to look up a decrypted key for a given tenantId, provider, and encryption key
+ * @param deriveKey - Function to derive encryption key for a given tenantId
+ */
+export async function resolveApiKeyWithOrgFallback(
+  lookupKey: (tenantId: string, provider: Provider, encKey: Buffer) => Promise<string | null>,
+  tenantId: string,
+  provider: Provider,
+  encryptionKey: Buffer,
+  pooledKeys: Map<Provider, string>,
+  deriveKey: (tenantId: string) => Buffer,
+  orgMembershipRepo: IOrgMembershipRepository,
+): Promise<OrgResolvedKey | null> {
+  // 1. Check personal tenant key
+  const personal = await lookupKey(tenantId, provider, encryptionKey);
+  if (personal) {
+    return { key: personal, source: "tenant", provider };
+  }
+
+  // 2. Check org membership and org key
+  const orgTenantId = await orgMembershipRepo.getOrgTenantIdForMember(tenantId);
+
+  if (orgTenantId) {
+    const orgEncKey = deriveKey(orgTenantId);
+    const orgResult = await lookupKey(orgTenantId, provider, orgEncKey);
+    if (orgResult) {
+      return { key: orgResult, source: "org", provider };
+    }
+  }
+
+  // 3. Pooled key
+  const pooledKey = pooledKeys.get(provider);
+  if (pooledKey) {
+    return { key: pooledKey, source: "pooled", provider };
+  }
+
+  // 4. None
+  return null;
+}

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

@@ -0,0 +1,143 @@
+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 type { EncryptedPayload } from "../types.js";
+import { TenantKeyRepository } from "./tenant-key-repository.js";
+
+const fakeEncrypted: EncryptedPayload = {
+  iv: "aabbccdd",
+  authTag: "11223344",
+  ciphertext: "deadbeef",
+};
+
+describe("TenantKeyRepository", () => {
+  let db: PlatformDb;
+  let pool: PGlite;
+  let store: TenantKeyRepository;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    store = new TenantKeyRepository(db);
+  });
+
+  describe("upsert", () => {
+    it("inserts a new key and returns the id", async () => {
+      const id = await store.upsert("t1", "anthropic", fakeEncrypted, "My Key");
+      expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+
+      const record = await store.get("t1", "anthropic");
+      expect(record).not.toBeNull();
+      expect(record?.label).toBe("My Key");
+      expect(record?.tenant_id).toBe("t1");
+      expect(record?.provider).toBe("anthropic");
+    });
+
+    it("updates an existing key for the same tenant+provider", async () => {
+      const id1 = await store.upsert("t1", "anthropic", fakeEncrypted, "Old");
+      const id2 = await store.upsert("t1", "anthropic", { ...fakeEncrypted, ciphertext: "newdata" }, "New");
+
+      // Same ID reused
+      expect(id2).toBe(id1);
+
+      const record = await store.get("t1", "anthropic");
+      expect(record?.label).toBe("New");
+      expect(JSON.parse(record?.encrypted_key ?? "{}").ciphertext).toBe("newdata");
+    });
+
+    it("sets created_at and updated_at timestamps", async () => {
+      await store.upsert("t1", "openai", fakeEncrypted);
+      const record = await store.get("t1", "openai");
+      expect(record?.created_at).toBeGreaterThan(0);
+      expect(record?.updated_at).toBeGreaterThan(0);
+    });
+  });
+
+  describe("get", () => {
+    it("returns undefined for non-existent key", async () => {
+      expect(await store.get("t1", "anthropic")).toBeUndefined();
+    });
+
+    it("returns the full record including encrypted_key", async () => {
+      await store.upsert("t1", "anthropic", fakeEncrypted);
+      const record = await store.get("t1", "anthropic");
+      expect(record?.encrypted_key).toBeTruthy();
+      const parsed = JSON.parse(record?.encrypted_key ?? "{}");
+      expect(parsed.iv).toBe(fakeEncrypted.iv);
+      expect(parsed.authTag).toBe(fakeEncrypted.authTag);
+      expect(parsed.ciphertext).toBe(fakeEncrypted.ciphertext);
+    });
+  });
+
+  describe("listForTenant", () => {
+    it("returns empty array when tenant has no keys", async () => {
+      expect(await store.listForTenant("t1")).toEqual([]);
+    });
+
+    it("returns metadata only (no encrypted_key)", async () => {
+      await store.upsert("t1", "anthropic", fakeEncrypted, "Ant Key");
+      await store.upsert("t1", "openai", fakeEncrypted, "OAI Key");
+
+      const keys = await store.listForTenant("t1");
+      expect(keys).toHaveLength(2);
+
+      for (const key of keys) {
+        expect(key).not.toHaveProperty("encrypted_key");
+        expect(key.tenant_id).toBe("t1");
+      }
+    });
+
+    it("does not return other tenants' keys", async () => {
+      await store.upsert("t1", "anthropic", fakeEncrypted);
+      await store.upsert("t2", "openai", fakeEncrypted);
+
+      const keys = await store.listForTenant("t1");
+      expect(keys).toHaveLength(1);
+      expect(keys[0].provider).toBe("anthropic");
+    });
+  });
+
+  describe("delete", () => {
+    it("returns false when no key exists", async () => {
+      expect(await store.delete("t1", "anthropic")).toBe(false);
+    });
+
+    it("deletes a key and returns true", async () => {
+      await store.upsert("t1", "anthropic", fakeEncrypted);
+      expect(await store.delete("t1", "anthropic")).toBe(true);
+      expect(await store.get("t1", "anthropic")).toBeUndefined();
+    });
+
+    it("does not delete other tenants' keys", async () => {
+      await store.upsert("t1", "anthropic", fakeEncrypted);
+      await store.upsert("t2", "anthropic", fakeEncrypted);
+
+      await store.delete("t1", "anthropic");
+      expect(await store.get("t2", "anthropic")).not.toBeNull();
+    });
+  });
+
+  describe("deleteAllForTenant", () => {
+    it("returns 0 when tenant has no keys", async () => {
+      expect(await store.deleteAllForTenant("t1")).toBe(0);
+    });
+
+    it("deletes all keys for a tenant", async () => {
+      await store.upsert("t1", "anthropic", fakeEncrypted);
+      await store.upsert("t1", "openai", fakeEncrypted);
+      await store.upsert("t2", "anthropic", fakeEncrypted);
+
+      expect(await store.deleteAllForTenant("t1")).toBe(2);
+      expect(await store.listForTenant("t1")).toHaveLength(0);
+      expect(await store.listForTenant("t2")).toHaveLength(1);
+    });
+  });
+});

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

@@ -0,0 +1,130 @@
+import { randomUUID } from "node:crypto";
+import { and, eq } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { tenantApiKeys } from "../../db/schema/index.js";
+import type { EncryptedPayload } from "../types.js";
+
+/** A stored tenant API key record. */
+export interface TenantApiKey {
+  id: string;
+  tenant_id: string;
+  provider: string;
+  /** Label for display (e.g. "My Anthropic key"). Never contains the key itself. */
+  label: string;
+  /** AES-256-GCM encrypted key payload (JSON-serialized EncryptedPayload). */
+  encrypted_key: string;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface ITenantKeyRepository {
+  upsert(tenantId: string, provider: string, encryptedKey: EncryptedPayload, label?: string): Promise<string>;
+  get(tenantId: string, provider: string): Promise<TenantApiKey | undefined>;
+  listForTenant(tenantId: string): Promise<Omit<TenantApiKey, "encrypted_key">[]>;
+  delete(tenantId: string, provider: string): Promise<boolean>;
+  deleteAllForTenant(tenantId: string): Promise<number>;
+}
+
+/** CRUD store for tenant API keys using Drizzle ORM. */
+export class TenantKeyRepository implements ITenantKeyRepository {
+  private readonly db: PlatformDb;
+
+  constructor(db: PlatformDb) {
+    this.db = db;
+  }
+
+  /** Store or replace a tenant's key for a provider. Returns the record ID. */
+  async upsert(tenantId: string, provider: string, encryptedKey: EncryptedPayload, label = ""): Promise<string> {
+    const now = Date.now();
+    const serialized = JSON.stringify(encryptedKey);
+
+    const existing = await this.db
+      .select({ id: tenantApiKeys.id })
+      .from(tenantApiKeys)
+      .where(and(eq(tenantApiKeys.tenantId, tenantId), eq(tenantApiKeys.provider, provider)))
+      .limit(1);
+
+    if (existing.length > 0) {
+      await this.db
+        .update(tenantApiKeys)
+        .set({ encryptedKey: serialized, label, updatedAt: now })
+        .where(eq(tenantApiKeys.id, existing[0].id));
+      return existing[0].id;
+    }
+
+    const id = randomUUID();
+    await this.db.insert(tenantApiKeys).values({
+      id,
+      tenantId,
+      provider,
+      label,
+      encryptedKey: serialized,
+      createdAt: now,
+      updatedAt: now,
+    });
+    return id;
+  }
+
+  /** Get a tenant's key record for a provider. Returns undefined if none stored. */
+  async get(tenantId: string, provider: string): Promise<TenantApiKey | undefined> {
+    const rows = await this.db
+      .select()
+      .from(tenantApiKeys)
+      .where(and(eq(tenantApiKeys.tenantId, tenantId), eq(tenantApiKeys.provider, provider)))
+      .limit(1);
+
+    if (rows.length === 0) return undefined;
+    const r = rows[0];
+    return {
+      id: r.id,
+      tenant_id: r.tenantId,
+      provider: r.provider,
+      label: r.label,
+      encrypted_key: r.encryptedKey,
+      created_at: r.createdAt,
+      updated_at: r.updatedAt,
+    };
+  }
+
+  /** List all key records for a tenant. Never returns plaintext keys. */
+  async listForTenant(tenantId: string): Promise<Omit<TenantApiKey, "encrypted_key">[]> {
+    const rows = await this.db
+      .select({
+        id: tenantApiKeys.id,
+        tenantId: tenantApiKeys.tenantId,
+        provider: tenantApiKeys.provider,
+        label: tenantApiKeys.label,
+        createdAt: tenantApiKeys.createdAt,
+        updatedAt: tenantApiKeys.updatedAt,
+      })
+      .from(tenantApiKeys)
+      .where(eq(tenantApiKeys.tenantId, tenantId));
+
+    return rows.map((r) => ({
+      id: r.id,
+      tenant_id: r.tenantId,
+      provider: r.provider,
+      label: r.label,
+      created_at: r.createdAt,
+      updated_at: r.updatedAt,
+    }));
+  }
+
+  /** Delete a tenant's key for a provider. Returns true if a row was deleted. */
+  async delete(tenantId: string, provider: string): Promise<boolean> {
+    const result = await this.db
+      .delete(tenantApiKeys)
+      .where(and(eq(tenantApiKeys.tenantId, tenantId), eq(tenantApiKeys.provider, provider)))
+      .returning({ id: tenantApiKeys.id });
+    return result.length > 0;
+  }
+
+  /** Delete all keys for a tenant. Returns the number of rows deleted. */
+  async deleteAllForTenant(tenantId: string): Promise<number> {
+    const result = await this.db
+      .delete(tenantApiKeys)
+      .where(eq(tenantApiKeys.tenantId, tenantId))
+      .returning({ id: tenantApiKeys.id });
+    return result.length;
+  }
+}

package/src/security/types.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+/**
+ * Provider identifier — any non-empty string.
+ * Consumers (e.g., wopr-platform) can narrow this with their own enum.
+ */
+export const providerSchema = z.string().min(1);
+export type Provider = z.infer<typeof providerSchema>;
+
+/** Request body for the encrypted key validation proxy. */
+export const validateKeyRequestSchema = z.object({
+  provider: providerSchema,
+  encryptedKey: z.string().min(1, "Encrypted key payload is required"),
+});
+export type ValidateKeyRequest = z.infer<typeof validateKeyRequestSchema>;
+
+/** Response from key validation. */
+export interface ValidateKeyResponse {
+  valid: boolean;
+  error?: string;
+}
+
+/** Request body for writing secrets to a running instance. */
+export const writeSecretsRequestSchema = z
+  .record(z.string().min(1), z.string().min(1))
+  .refine((obj) => Object.keys(obj).length > 0, { message: "At least one secret is required" });
+export type WriteSecretsRequest = z.infer<typeof writeSecretsRequestSchema>;
+
+/** Encrypted payload structure stored as secrets.enc. */
+export interface EncryptedPayload {
+  /** AES-256-GCM initialization vector (hex). */
+  iv: string;
+  /** AES-256-GCM auth tag (hex). */
+  authTag: string;
+  /** Encrypted ciphertext (hex). */
+  ciphertext: string;
+}
+
+/** Provider validation endpoint configuration. */
+export interface ProviderEndpoint {
+  url: string;
+  headers: (key: string) => Record<string, string>;
+}