@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/secrets/__tests__/rotate.integration.ts

@@ -0,0 +1,176 @@
+// Integration test for the rotate-job circuit-breaker. Seeds a handful of
+// rows and feeds the job a provider that always fails to unwrap, then
+// asserts the job bails after maxFailures instead of spraying the log
+// with every row's identical error.
+
+import { randomBytes } from "node:crypto";
+import type { AppContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEnvMasterKeyProvider,
+  encryptValue,
+  type MasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createTestUser,
+  pushTables,
+  setupTestStack,
+  type TestStack,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { eq, sql } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createSecretsFeature } from "../feature";
+import { rotateJob } from "../handlers/rotate.job";
+import { createSecretsContext } from "../secrets-context";
+import { tenantSecretsTable } from "../table";
+
+const admin = createTestUser({
+  id: "00000000-0000-4000-8000-000000000010",
+  tenantId: "00000000-0000-4000-8000-000000000001",
+  roles: ["TenantAdmin"],
+});
+
+// A provider that encrypts happily on wrapDek but always rejects
+// unwrapDek. Simulates "KEK is unreachable / corrupt" — the failure mode
+// the circuit-breaker exists to contain. The returned object carries a
+// `calls` counter so tests can observe how many unwrap attempts happened
+// before the breaker tripped — that's how we tell maxFailures=1 apart
+// from maxFailures=N+rows (both leave the rows on V1, only the call-count
+// differs).
+type BrokenProvider = MasterKeyProvider & { calls(): number };
+function createBrokenUnwrapProvider(): BrokenProvider {
+  const base = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2", // current != stored version so rotation is attempted
+      KUMIKO_SECRETS_MASTER_KEY_V2: randomBytes(32).toString("base64"),
+    },
+  });
+  let callCount = 0;
+  return {
+    wrapDek: base.wrapDek.bind(base),
+    currentVersion: base.currentVersion.bind(base),
+    isAvailable: base.isAvailable.bind(base),
+    unwrapDek: async () => {
+      callCount++;
+      throw new Error("simulated KEK failure");
+    },
+    calls: () => callCount,
+  };
+}
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  // Seeding the table uses a sane V1-only provider so writes land on V1.
+  const seedProvider = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+
+  stack = await setupTestStack({
+    features: [createSecretsFeature()],
+    masterKeyProvider: seedProvider,
+    extraContext: ({ db }) => ({
+      secrets: createSecretsContext({ db, masterKeyProvider: seedProvider }),
+    }),
+  });
+  await pushTables(stack.db, {
+    tenant_secrets: tenantSecretsTable,
+  });
+
+  // Seed 20 V1 rows directly — too many for any maxFailures default.
+  for (let i = 0; i < 20; i++) {
+    const envelope = await encryptValue(`secret-${i}`, seedProvider);
+    await stack.db.insert(tenantSecretsTable).values({
+      tenantId: admin.tenantId,
+      key: `test:secret:k-${i}`,
+      envelope: {
+        ciphertext: envelope.ciphertext.toString("base64"),
+        iv: envelope.iv.toString("base64"),
+        authTag: envelope.authTag.toString("base64"),
+        encryptedDek: envelope.encryptedDek.toString("base64"),
+        kekVersion: envelope.kekVersion,
+      },
+      kekVersion: envelope.kekVersion,
+    });
+  }
+});
+
+afterAll(async () => {
+  // Clean up the seeded fixtures so downstream suites don't see them.
+  await stack.db.delete(tenantSecretsTable).where(eq(tenantSecretsTable.tenantId, admin.tenantId));
+  await stack.cleanup();
+});
+
+type Log = NonNullable<AppContext["log"]>;
+function silentLogger(): Log {
+  const noop = () => {};
+  const logger: Log = {
+    info: noop,
+    warn: noop,
+    error: noop,
+    debug: noop,
+    child: () => logger,
+  };
+  return logger;
+}
+
+type RotateJobCtx = Pick<AppContext, "db" | "masterKeyProvider" | "log">;
+function jobCtx(provider: MasterKeyProvider): Parameters<typeof rotateJob>[1] {
+  const ctx: RotateJobCtx = {
+    db: stack.db,
+    masterKeyProvider: provider,
+    log: silentLogger(),
+  };
+  return ctx as unknown as Parameters<typeof rotateJob>[1];
+}
+
+async function countV1Rows(): Promise<number> {
+  const rows = await stack.db
+    .select({ kekVersion: tenantSecretsTable.kekVersion })
+    .from(tenantSecretsTable)
+    .where(sql`${tenantSecretsTable.tenantId} = ${admin.tenantId}`);
+  return rows.filter((r) => r.kekVersion === 1).length;
+}
+
+describe("rotate-job circuit-breaker", () => {
+  test("bails after maxFailures consecutive errors — doesn't loop through all rows", async () => {
+    const broken = createBrokenUnwrapProvider();
+
+    // maxFailures: 3 means the job gives up after 3 failed rows. Without
+    // the breaker it would attempt all 20 and log 20 warns.
+    await rotateJob({ batchSize: 10, maxFailures: 3 }, jobCtx(broken));
+
+    // All 20 rows still at V1 — the broken provider never let any rewrap
+    // succeed. Plus: the breaker tripped at ≤3 attempts, not 20.
+    expect(await countV1Rows()).toBe(20);
+    expect(broken.calls()).toBeLessThanOrEqual(3);
+  });
+
+  test("maxFailures=1 trips on the very first failure — single attempt then stop", async () => {
+    const broken = createBrokenUnwrapProvider();
+
+    await rotateJob({ batchSize: 10, maxFailures: 1 }, jobCtx(broken));
+
+    // Same end-state (all rows on V1) but the internal counter proves the
+    // breaker fired after exactly one failure instead of draining the batch.
+    expect(await countV1Rows()).toBe(20);
+    expect(broken.calls()).toBe(1);
+  });
+
+  test("maxFailures scales the call budget linearly — higher threshold → more attempts", async () => {
+    // With an all-broken provider the job re-fetches the same rows each
+    // batch (nothing rotated, nothing excluded), so the breaker is
+    // eventually the ONLY thing that stops it. Raising maxFailures from 3
+    // to 25 must raise the call-count accordingly — proves the breaker
+    // honours its parameter rather than silently capping.
+    const broken = createBrokenUnwrapProvider();
+
+    await rotateJob({ batchSize: 10, maxFailures: 25 }, jobCtx(broken));
+
+    expect(await countV1Rows()).toBe(20);
+    expect(broken.calls()).toBe(25);
+  });
+});

package/src/secrets/__tests__/secrets-events.integration.ts

@@ -0,0 +1,125 @@
+// Event-shape contract for the tenantSecret aggregate + the
+// tenantSecretRead side-stream. Executor-based writes (set/delete)
+// produce auto-lifecycle events; get() writes a standalone read-audit
+// event on a fresh aggregate-stream (one-event-per-read). This test
+// pins both paths so a silent rename breaks here, not in a compliance
+// audit query.
+
+import { randomBytes } from "node:crypto";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createEnvMasterKeyProvider,
+  type MasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createTestUser,
+  pushTables,
+  setupTestStack,
+  type TestStack,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createSecretsFeature } from "../feature";
+import {
+  createSecretsContext,
+  secretReadSchema,
+  TENANT_SECRET_READ_EVENT,
+} from "../secrets-context";
+import { tenantSecretsTable } from "../table";
+
+const admin = createTestUser({
+  id: "00000000-0000-4000-8000-000000000010",
+  tenantId: "00000000-0000-4000-8000-000000000001",
+  roles: ["TenantAdmin"],
+});
+
+let stack: TestStack;
+let provider: MasterKeyProvider;
+
+beforeAll(async () => {
+  provider = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+
+  stack = await setupTestStack({
+    features: [createSecretsFeature()],
+    extraContext: ({ db }) => ({
+      secrets: createSecretsContext({ db, masterKeyProvider: provider }),
+    }),
+  });
+  await pushTables(stack.db, { tenantSecretsTable });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.db.delete(eventsTable);
+  await stack.db.delete(tenantSecretsTable);
+});
+
+describe("tenantSecret lifecycle events", () => {
+  test("set-then-list writes one tenantSecret.created event", async () => {
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: "example.api.key", value: "secret-value-xyz" },
+      admin,
+    );
+
+    const created = await stack.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.type, "tenant-secret.created"));
+    expect(created.length).toBe(1);
+    // aggregateType stable; downstream MSPs filter by this.
+    expect(created[0]?.aggregateType).toBe("tenant-secret");
+    // Plaintext never lands on the event-stream — only the envelope.
+    const serialized = JSON.stringify(created[0]?.payload);
+    expect(serialized).not.toContain("secret-value-xyz");
+  });
+
+  test("delete writes a tenantSecret.deleted event on the same stream", async () => {
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: "example.to.delete", value: "one-time" },
+      admin,
+    );
+    await stack.http.writeOk("secrets:write:delete", { key: "example.to.delete" }, admin);
+
+    const events = await stack.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.aggregateType, "tenant-secret"));
+
+    // Exactly 2 events on the same aggregate-stream: created + deleted.
+    expect(events.length).toBe(2);
+    expect(events.map((e) => e.type)).toEqual(["tenant-secret.created", "tenant-secret.deleted"]);
+    const ids = new Set(events.map((e) => e.aggregateId));
+    expect(ids.size).toBe(1);
+  });
+});
+
+describe("tenantSecretRead side-stream", () => {
+  test("read-event type constant is stable", () => {
+    // Downstream compliance exports match on this string. Silent rename
+    // would cost audit continuity.
+    expect(TENANT_SECRET_READ_EVENT).toBe("secrets:event:read");
+  });
+
+  test("read-audit payload conforms to secretReadSchema", () => {
+    // Canonical shape — whoever touches the schema should update this
+    // test in lockstep.
+    expect(() =>
+      secretReadSchema.parse({
+        key: "example.key",
+        userId: admin.id,
+        handlerName: "billing:write:charge",
+      }),
+    ).not.toThrow();
+  });
+});

package/src/secrets/__tests__/secrets.integration.ts

@@ -0,0 +1,118 @@
+// Feature-level integration test for secrets. Pins that the CRUD handlers
+// actually encrypt end-to-end: set stores an envelope (no plaintext), list
+// returns the redactedPreview only, get decrypts back. The sample
+// (samples/secrets-demo) shows the broader rotation + cross-feature flow;
+// this test covers just the feature's own handlers.
+
+import { randomBytes } from "node:crypto";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createEnvMasterKeyProvider,
+  type MasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createTestUser,
+  pushTables,
+  setupTestStack,
+  type TestStack,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { and, eq } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createSecretsFeature } from "../feature";
+import { createSecretsContext } from "../secrets-context";
+import { type StoredEnvelope, tenantSecretsTable } from "../table";
+
+const admin = createTestUser({
+  id: "00000000-0000-4000-8000-000000000010",
+  tenantId: "00000000-0000-4000-8000-000000000001",
+  roles: ["TenantAdmin"],
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const provider: MasterKeyProvider = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+
+  stack = await setupTestStack({
+    features: [createSecretsFeature()],
+    extraContext: ({ db }) => ({
+      secrets: createSecretsContext({ db, masterKeyProvider: provider }),
+    }),
+  });
+  // Post-ES: the pre-ES audit table is gone — read-audit rides on the
+  // events-table as tenantSecretRead domain-events. Only the projection
+  // table (tenant_secrets) still needs an explicit push here, since it
+  // belongs to an ES entity (and entity-tables aren't auto-pushed by
+  // setupTestStack).
+  await pushTables(stack.db, { tenant_secrets: tenantSecretsTable });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("secrets feature — CRUD round-trip", () => {
+  test("set + list + delete over HTTP", async () => {
+    // SET: encrypts and stores
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: "api.key.x", value: "this-is-secret-value-xyz" },
+      admin,
+    );
+
+    // LIST: preview only, never plaintext
+    const list = await stack.http.queryOk<
+      Array<{ key: string; redactedPreview: string | null; kekVersion: number }>
+    >("secrets:query:list", {}, admin);
+    const row = list.find((r) => r.key === "api.key.x");
+    expect(row).toBeDefined();
+    expect(row?.redactedPreview).not.toBe("this-is-secret-value-xyz");
+    expect(row?.kekVersion).toBe(1);
+
+    // DB row holds an envelope, no plaintext
+    const [dbRow] = await stack.db
+      .select()
+      .from(tenantSecretsTable)
+      .where(
+        and(
+          eq(tenantSecretsTable.tenantId, admin.tenantId),
+          eq(tenantSecretsTable.key, "api.key.x"),
+        ),
+      );
+    if (!dbRow) throw new Error("row missing");
+    const env = dbRow.envelope as StoredEnvelope;
+    expect(env.ciphertext).toBeTruthy();
+    expect(env.kekVersion).toBe(1);
+    expect(JSON.stringify(dbRow)).not.toContain("this-is-secret-value-xyz");
+
+    // DELETE: removes row
+    await stack.http.writeOk("secrets:write:delete", { key: "api.key.x" }, admin);
+    const afterDelete = await stack.http.queryOk<Array<{ key: string }>>(
+      "secrets:query:list",
+      {},
+      admin,
+    );
+    expect(afterDelete.some((r) => r.key === "api.key.x")).toBe(false);
+  });
+
+  test("delete on missing key returns 404", async () => {
+    const err = await stack.http.writeErr("secrets:write:delete", { key: "never.set.this" }, admin);
+    expect(err.code).toBe("not_found");
+  });
+
+  test("non-TenantAdmin cannot set", async () => {
+    const user = createTestUser({
+      id: "00000000-0000-4000-8000-000000000099",
+      tenantId: admin.tenantId,
+      roles: ["User"],
+    });
+    const err = await stack.http.writeErr("secrets:write:set", { key: "attack", value: "x" }, user);
+    expect(err.code).toBe("access_denied");
+  });
+});

package/src/secrets/feature.ts

@@ -0,0 +1,84 @@
+import {
+  defineFeature,
+  type FeatureDefinition,
+  type HandlerContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { deleteWrite } from "./handlers/delete.write";
+import { listQuery } from "./handlers/list.query";
+import { rotateJob } from "./handlers/rotate.job";
+import { setWrite } from "./handlers/set.write";
+import { secretReadSchema } from "./secrets-context";
+import { tenantSecretEntity } from "./table";
+
+export {
+  createSecretsContext,
+  type SecretsContext,
+  type SecretsContextOptions,
+  TENANT_SECRET_READ_EVENT,
+} from "./secrets-context";
+export { type StoredEnvelope, type StoredMetadata, tenantSecretsTable } from "./table";
+
+// AppContext carries ctx.secrets via extraContext. requireSecretsContext
+// wraps that raw context so every `.get(...)` call auto-includes the
+// current user + handler as audit metadata — feature code can't forget
+// to log the read (silent bypass of audit was the v1 gap).
+export function requireSecretsContext(ctx: HandlerContext, handlerName: string): SecretsContext {
+  if (!ctx.secrets) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.secrets missing — pass ` +
+        "createSecretsContext({db, masterKeyProvider}) via extraContext.secrets at boot.",
+    });
+  }
+  const raw = ctx.secrets;
+  const userId = ctx._userId;
+  if (!userId) {
+    throw new InternalError({
+      message: `[${handlerName}] ctx._userId missing — cannot audit secret reads without a caller identity.`,
+    });
+  }
+  return {
+    get: (tenantId, key, overrideAudit) =>
+      raw.get(tenantId, key, overrideAudit ?? { userId, handlerName }),
+    set: raw.set.bind(raw),
+    delete: raw.delete.bind(raw),
+  };
+}
+
+export function createSecretsFeature(): FeatureDefinition {
+  return defineFeature("secrets", (r) => {
+    // ES entity: set/delete go through the executor, `tenantSecret.created/
+    // .updated/.deleted` events land on the aggregate stream. Reads fire a
+    // separate `tenantSecretRead` event per call (see secrets-context.get
+    // for the one-event-per-read rationale).
+    r.entity("tenant-secret", tenantSecretEntity);
+
+    // Read-audit domain-event. Registered here so ops tools + MSPs can
+    // discover the type; secrets-context.get parses payloads against
+    // `secretReadSchema` at write time because the low-level append() path
+    // skips ctx.appendEvent's schema-validation guard.
+    r.defineEvent("read", secretReadSchema);
+
+    // Per-tenant handlers (set/delete/list) run in the default tenant-scope,
+    // giving them the automatic ctx.db tenant-filter as extra defense.
+    // The rotation job deliberately reaches for ctx.db as DbConnection
+    // (raw, cross-tenant) because rotation is a deployment-wide operation —
+    // no feature-wide r.systemScope() needed.
+    r.writeHandler(setWrite);
+    r.writeHandler(deleteWrite);
+    r.queryHandler(listQuery);
+    // Manual-only by design: ops triggers rotation after a KEK version flip.
+    // BullMQ delivers to exactly one worker, so running it against a busy
+    // table on multiple instances is still safe.
+    r.job("rotate", { trigger: { manual: true } }, rotateJob);
+
+    // Pre-ES had a separate `retention-cleanup` job scrubbing the audit
+    // table on a compliance-driven schedule (90d default). Post-ES the
+    // read-audit lives on the events-table as tenantSecretRead events;
+    // retention for those flows through the framework-wide `pruneEvents`
+    // ops-tool (see docs/plans/architecture/event-dispatcher.md §retention).
+    // No per-feature retention-job anymore.
+  });
+}

package/src/secrets/handlers/delete.write.ts

@@ -0,0 +1,20 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { requireSecretsContext } from "../feature";
+
+export const deleteWrite = defineWriteHandler({
+  name: "delete",
+  schema: z.object({
+    key: z.string().min(1).max(100),
+  }),
+  access: { roles: ["TenantAdmin"] },
+  handler: async (event, ctx) => {
+    const secrets = requireSecretsContext(ctx, "secrets:write:delete");
+    const removed = await secrets.delete(event.user.tenantId, event.payload.key, {
+      deletedBy: event.user.id,
+    });
+    if (!removed) return failNotFound("tenant-secret", event.payload.key);
+    return { isSuccess: true, data: { key: event.payload.key } };
+  },
+});

package/src/secrets/handlers/list.query.ts

@@ -0,0 +1,38 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { tenantSecretsTable } from "../table";
+
+// Lists all secrets for the current tenant. Returns redactedPreview, never
+// the plaintext. Decryption would be pointless here anyway — this is the
+// TenantAdmin UI, not feature code that needs the value.
+export const listQuery = defineQueryHandler({
+  name: "list",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin"] },
+  handler: async (event, ctx) => {
+    const rows = await ctx.db.raw
+      .select({
+        key: tenantSecretsTable.key,
+        kekVersion: tenantSecretsTable.kekVersion,
+        metadata: tenantSecretsTable.metadata,
+        lastRotatedAt: tenantSecretsTable.lastRotatedAt,
+        // Post-ES the projection uses the framework base-columns — `inserted_at`
+        // replaces the legacy `created_at`. Response stays on the `createdAt`
+        // key so Admin-UIs don't have to re-map.
+        createdAt: tenantSecretsTable.insertedAt,
+      })
+      .from(tenantSecretsTable)
+      .where(eq(tenantSecretsTable.tenantId, event.user.tenantId))
+      .orderBy(tenantSecretsTable.key);
+
+    return rows.map((r) => ({
+      key: r.key,
+      redactedPreview: r.metadata.redactedPreview ?? null,
+      hint: r.metadata.hint ?? null,
+      kekVersion: r.kekVersion,
+      lastRotatedAt: r.lastRotatedAt,
+      createdAt: r.createdAt,
+    }));
+  },
+});