@cosmicdrift/kumiko-framework 0.113.1 → 1.0.0

package/src/pipeline/__tests__/rebuild-poison-quarantine.integration.test.ts

@@ -1,274 +0,0 @@
-// #760 — poison-event quarantine during projection rebuild.
-//
-// A single historical event whose apply throws used to abort the WHOLE
-// rebuild (tx rollback, status failed) with no recovery path short of
-// hand-editing the event. With quarantine mode the rebuild confines each
-// apply to a savepoint: the poison event is skipped, recorded into
-// kumiko_rebuild_dead_letters, and the replay completes.
-//
-// Covers both rebuild flavors:
-//   - single-stream: RebuildDeps.errorPolicy.skipApplyErrors (per run)
-//   - MSP: MspErrorMode.rebuild.skipApplyErrors (per definition — declared
-//     API that was previously never honored by rebuildMultiStreamProjection)
-// and both poison flavors:
-//   - JS throw (no SQL executed)
-//   - SQL error (aborts the tx → proves the savepoint is load-bearing)
-
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
-import { integer as pgInteger, table as pgTable, uuid as pgUuid } from "../../db/dialect";
-import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { asRawClient } from "../../db/query";
-import { buildEntityTable } from "../../db/table-builder";
-import { createTenantDb, type TenantDb } from "../../db/tenant-db";
-import { createEntity, createTextField, defineApply, defineFeature } from "../../engine";
-import type { ProjectionDefinition } from "../../engine/types";
-import { append, createEventsTable } from "../../event-store";
-import { listRebuildDeadLetters } from "../../event-store/rebuild-dead-letter";
-import {
-  createProjectionStateTable,
-  getConsumerState,
-  getProjectionState,
-  rebuildMultiStreamProjection,
-  rebuildProjection,
-} from "../../pipeline";
-import {
-  setupTestStack,
-  type TestStack,
-  TestUsers,
-  unsafeCreateEntityTable,
-  unsafePushTables,
-} from "../../stack";
-
-// --- Fixtures ---
-
-const POISON_JS = "poison-js";
-const POISON_SQL = "poison-sql";
-
-const itemEntity = createEntity({
-  table: "read_poison_items",
-  fields: {
-    groupId: createTextField({ required: true }),
-    name: createTextField({ required: true }),
-  },
-});
-const itemTable = buildEntityTable("poison-item", itemEntity);
-
-const counterTable = pgTable("read_poison_counter", {
-  groupId: pgUuid("group_id").primaryKey(),
-  tenantId: pgUuid("tenant_id").notNull(),
-  itemCount: pgInteger("item_count").notNull().default(0),
-});
-
-const mspCounterTable = pgTable("read_poison_msp_counter", {
-  groupId: pgUuid("group_id").primaryKey(),
-  tenantId: pgUuid("tenant_id").notNull(),
-  itemCount: pgInteger("item_count").notNull().default(0),
-});
-
-async function bump(tx: unknown, tableName: string, groupId: string, tenantId: string) {
-  await asRawClient(tx).unsafe(
-    `INSERT INTO "${tableName}" (group_id, tenant_id, item_count) VALUES ($1::uuid, $2::uuid, 1) ON CONFLICT (group_id) DO UPDATE SET item_count = "${tableName}".item_count + 1`,
-    [groupId, tenantId],
-  );
-}
-
-// Poison by payload marker. POISON_SQL runs a genuinely failing statement so
-// the surrounding tx would be in 25P02 without the savepoint.
-async function applyOrPoison(
-  tx: unknown,
-  tableName: string,
-  payload: { groupId: string; name: string },
-  tenantId: string,
-): Promise<void> {
-  if (payload.name === POISON_JS) throw new Error("intentional js poison");
-  if (payload.name === POISON_SQL) {
-    await asRawClient(tx).unsafe(
-      `INSERT INTO "${tableName}" (group_id, tenant_id, item_count) VALUES ('not-a-uuid', $1::uuid, 1)`,
-      [tenantId],
-    );
-    return;
-  }
-  await bump(tx, tableName, payload.groupId, tenantId);
-}
-
-type ItemPayload = { groupId: string; name: string };
-
-const poisonProjection: ProjectionDefinition = {
-  name: "poison-counter",
-  source: "poison-item",
-  table: counterTable,
-  apply: {
-    "poison-item.created": defineApply<ItemPayload>(async (event, tx) => {
-      await applyOrPoison(tx, "read_poison_counter", event.payload, event.tenantId);
-    }),
-  },
-};
-
-const MSP_EVENT_SHORT = "poison-noted";
-
-const feature = defineFeature("poisontest", (r) => {
-  r.entity("poison-item", itemEntity);
-  r.projection(poisonProjection);
-  const noted = r.defineEvent(MSP_EVENT_SHORT, z.object({ groupId: z.uuid(), name: z.string() }));
-  r.multiStreamProjection({
-    name: "poison-msp-counter",
-    table: mspCounterTable,
-    errorMode: { rebuild: { skipApplyErrors: true } },
-    apply: {
-      [noted.name]: async (event, tx) => {
-        const p = event.payload as ItemPayload; // @cast-boundary engine-payload
-        await applyOrPoison(tx, "read_poison_msp_counter", p, event.tenantId);
-      },
-    },
-  });
-});
-
-const admin = TestUsers.admin;
-const PROJECTION = "poisontest:projection:poison-counter";
-const MSP = "poisontest:projection:poison-msp-counter";
-const MSP_EVENT = "poisontest:event:poison-noted";
-const GROUP = "00000000-0000-4000-8000-00000000cafe";
-
-let stack: TestStack;
-let tdb: TenantDb;
-
-const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "poison-item" });
-
-beforeAll(async () => {
-  stack = await setupTestStack({ features: [feature] });
-  await unsafeCreateEntityTable(stack.db, itemEntity, "poison-item");
-  await createEventsTable(stack.db);
-  await createProjectionStateTable(stack.db);
-  await unsafePushTables(stack.db, {
-    poisonCounter: counterTable,
-    poisonMspCounter: mspCounterTable,
-  });
-  tdb = createTenantDb(stack.db, admin.tenantId);
-});
-
-afterAll(async () => {
-  await stack.cleanup();
-});
-
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(
-    `TRUNCATE kumiko_events, read_poison_items, read_poison_counter, read_poison_msp_counter, kumiko_projections RESTART IDENTITY CASCADE`,
-  );
-  await asRawClient(stack.db).unsafe(`DROP TABLE IF EXISTS kumiko_rebuild_dead_letters`);
-  if (stack.eventDispatcher) await stack.eventDispatcher.ensureRegistered();
-});
-
-async function createItem(name: string): Promise<void> {
-  await executor.create({ groupId: GROUP, name }, admin, tdb);
-}
-
-async function getCount(table: string): Promise<number | undefined> {
-  const rows = (await asRawClient(stack.db).unsafe(
-    `SELECT item_count FROM "${table}" WHERE group_id = $1::uuid`,
-    [GROUP],
-  )) as ReadonlyArray<{ item_count: number }>;
-  return rows[0]?.item_count;
-}
-
-describe("rebuildProjection — poison event, strict default (#760)", () => {
-  test("apply throw aborts the rebuild: status failed, no dead letters", async () => {
-    await createItem("good-1");
-    await createItem(POISON_JS);
-    await createItem("good-2");
-
-    await expect(
-      rebuildProjection(PROJECTION, { db: stack.db, registry: stack.registry }),
-    ).rejects.toThrow("intentional js poison");
-
-    const state = await getProjectionState(stack.db, PROJECTION);
-    expect(state?.status).toBe("failed");
-    // Strict mode never provisions/records dead letters.
-    const rows = (await asRawClient(stack.db).unsafe(
-      `SELECT to_regclass('public.kumiko_rebuild_dead_letters') AS t`,
-    )) as ReadonlyArray<{ t: string | null }>;
-    expect(rows[0]?.t).toBeNull();
-  });
-});
-
-describe("rebuildProjection — quarantine mode (#760)", () => {
-  test("js- and sql-poison events are skipped, recorded, and the rebuild completes", async () => {
-    await createItem("good-1");
-    await createItem(POISON_JS);
-    // sql-poison proves the savepoint: without it the failed statement puts
-    // the whole rebuild tx into 25P02 and every later apply fails too.
-    await createItem(POISON_SQL);
-    await createItem("good-2");
-
-    const result = await rebuildProjection(PROJECTION, {
-      db: stack.db,
-      registry: stack.registry,
-      errorPolicy: { skipApplyErrors: true },
-    });
-
-    expect(result.eventsSkipped).toBe(2);
-    expect(result.eventsProcessed).toBe(4);
-    expect(await getCount("read_poison_counter")).toBe(2);
-
-    const state = await getProjectionState(stack.db, PROJECTION);
-    expect(state?.status).toBe("idle");
-
-    const deadLetters = await listRebuildDeadLetters(stack.db, { projectionName: PROJECTION });
-    expect(deadLetters).toHaveLength(2);
-    const messages = deadLetters.map((d) => d.errorMessage).sort();
-    expect(messages[0]).toContain("poison");
-    expect(deadLetters.every((d) => d.eventType === "poison-item.created")).toBe(true);
-    expect(deadLetters.every((d) => d.aggregateType === "poison-item")).toBe(true);
-  });
-
-  test("clean run in quarantine mode: zero skipped, no dead letters", async () => {
-    await createItem("good-1");
-    await createItem("good-2");
-
-    const result = await rebuildProjection(PROJECTION, {
-      db: stack.db,
-      registry: stack.registry,
-      errorPolicy: { skipApplyErrors: true },
-    });
-
-    expect(result.eventsSkipped).toBe(0);
-    expect(await getCount("read_poison_counter")).toBe(2);
-    expect(await listRebuildDeadLetters(stack.db, { projectionName: PROJECTION })).toHaveLength(0);
-  });
-});
-
-describe("rebuildMultiStreamProjection — errorMode.rebuild.skipApplyErrors (#760)", () => {
-  async function appendMspEvent(name: string, expectedVersion: number): Promise<void> {
-    await append(stack.db, {
-      aggregateId: GROUP,
-      aggregateType: "poison-note",
-      tenantId: admin.tenantId,
-      expectedVersion,
-      type: MSP_EVENT,
-      payload: { groupId: GROUP, name },
-      metadata: { userId: admin.id },
-    });
-  }
-
-  test("declared rebuild policy is honored: poison skipped + recorded, cursor advanced", async () => {
-    await appendMspEvent("good-1", 0);
-    await appendMspEvent(POISON_SQL, 1);
-    await appendMspEvent("good-2", 2);
-
-    const result = await rebuildMultiStreamProjection(MSP, {
-      db: stack.db,
-      registry: stack.registry,
-    });
-
-    expect(result.eventsSkipped).toBe(1);
-    expect(result.eventsProcessed).toBe(3);
-    expect(await getCount("read_poison_msp_counter")).toBe(2);
-
-    const deadLetters = await listRebuildDeadLetters(stack.db, { projectionName: MSP });
-    expect(deadLetters).toHaveLength(1);
-    expect(deadLetters[0]?.eventType).toBe(MSP_EVENT);
-
-    const consumer = await getConsumerState(stack.db, MSP);
-    expect(consumer?.lastProcessedEventId).toBe(result.lastProcessedEventId);
-  });
-});

package/src/secrets/__tests__/envelope-cipher.test.ts

@@ -1,87 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { randomBytes } from "node:crypto";
-import { createEncryptionProvider } from "../../db/encryption";
-import { createEnvMasterKeyProvider } from "../env-master-key-provider";
-import { createEnvelopeCipher } from "../envelope-cipher";
-import { isStoredEnvelope } from "../stored-envelope";
-
-function makeProvider(currentVersion = 1) {
-  return createEnvMasterKeyProvider({
-    env: {
-      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: String(currentVersion),
-      [`KUMIKO_SECRETS_MASTER_KEY_V${currentVersion}`]: randomBytes(32).toString("base64"),
-    },
-  });
-}
-
-describe("envelope-cipher — encrypt/decrypt", () => {
-  test("round-trips plaintext through the JSON envelope format", async () => {
-    const cipher = createEnvelopeCipher(makeProvider());
-    const stored = await cipher.encrypt("s3cret-smtp-pass");
-
-    expect(stored.startsWith("{")).toBe(true);
-    const parsed: unknown = JSON.parse(stored);
-    expect(isStoredEnvelope(parsed)).toBe(true);
-
-    expect(await cipher.decrypt(stored)).toBe("s3cret-smtp-pass");
-  });
-
-  test("stored value carries the kekVersion for later rotation", async () => {
-    const cipher = createEnvelopeCipher(makeProvider(7));
-    const stored = await cipher.encrypt("x");
-    expect((JSON.parse(stored) as { kekVersion: number }).kekVersion).toBe(7);
-  });
-
-  test("tampered ciphertext fails GCM authentication", async () => {
-    const cipher = createEnvelopeCipher(makeProvider());
-    const stored = JSON.parse(await cipher.encrypt("payload")) as Record<string, unknown>;
-    const cipherBytes = Buffer.from(stored["ciphertext"] as string, "base64");
-    cipherBytes[0] = (cipherBytes[0] ?? 0) ^ 0xff;
-    const tampered = JSON.stringify({ ...stored, ciphertext: cipherBytes.toString("base64") });
-    await expect(cipher.decrypt(tampered)).rejects.toThrow();
-  });
-});
-
-describe("envelope-cipher — legacy fallback", () => {
-  test("decrypts legacy single-key values when the legacy provider is configured", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const legacyStored = legacy.encrypt("pre-envelope value");
-    // legacy wire format is base64 — never starts with "{"
-    expect(legacyStored.startsWith("{")).toBe(false);
-
-    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
-    expect(await cipher.decrypt(legacyStored)).toBe("pre-envelope value");
-  });
-
-  test("throws with a remediation message when a legacy value has no legacy key", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const legacyStored = legacy.encrypt("orphaned");
-
-    const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt(legacyStored)).rejects.toThrow(/legacy/);
-  });
-
-  test("never encrypts into the legacy format even when a legacy key is present", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
-    const stored = await cipher.encrypt("always-envelope");
-    expect(stored.startsWith("{")).toBe(true);
-  });
-});
-
-describe("envelope-cipher — malformed input", () => {
-  test("rejects invalid JSON that looks like an envelope", async () => {
-    const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt("{garbage")).rejects.toThrow(/not valid JSON/);
-  });
-
-  test("rejects JSON that is not a StoredEnvelope", async () => {
-    const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt('{"foo":"bar"}')).rejects.toThrow(/not a StoredEnvelope/);
-  });
-
-  test("empty string routes to the legacy branch and throws without a legacy key", async () => {
-    const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt("")).rejects.toThrow(/legacy/);
-  });
-});

package/src/secrets/envelope-cipher.ts

@@ -1,81 +0,0 @@
-// String-in/string-out envelope encryption for TEXT-column stores (config
-// values, entity fields). The stored string is JSON of StoredEnvelope; the
-// kekVersion inside makes every value rotatable via the MasterKeyProvider
-// keyring — unlike the legacy createEncryptionProvider format (raw
-// base64(iv+tag+ct), no key id), which this cipher still DECRYPTS through
-// the optional legacy provider so pre-envelope rows stay readable until a
-// re-encrypt job has migrated them.
-
-import type { EncryptionProvider } from "../db/encryption";
-import { InternalError } from "../errors/classes";
-import type { DekCache } from "./dek-cache";
-import { createDekCache, withDekCache } from "./dek-cache";
-import { decryptValue, encryptValue } from "./envelope";
-import { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope } from "./stored-envelope";
-import type { KeyScope, MasterKeyProvider } from "./types";
-
-export type EnvelopeCipherOptions = {
-  // Decrypt-only fallback for legacy createEncryptionProvider ciphertexts
-  // (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY era). Never used for encrypt.
-  readonly legacy?: EncryptionProvider;
-  // Shared DEK cache — pass the app-wide instance so config/entity reads
-  // amortise KEK unwraps together with ctx.secrets.
-  readonly dekCache?: DekCache;
-};
-
-export type EnvelopeCipher = {
-  encrypt(plaintext: string, scope?: KeyScope): Promise<string>;
-  decrypt(stored: string, scope?: KeyScope): Promise<string>;
-};
-
-// Format detection: envelope values are JSON objects, so they start with
-// "{" — a character the base64 alphabet of the legacy format can never
-// produce. No version byte or prefix marker needed.
-function isEnvelopeFormat(stored: string): boolean {
-  return stored.startsWith("{");
-}
-
-export function createEnvelopeCipher(
-  provider: MasterKeyProvider,
-  opts: EnvelopeCipherOptions = {},
-): EnvelopeCipher {
-  const cached = withDekCache(provider, opts.dekCache ?? createDekCache());
-
-  return {
-    async encrypt(plaintext, scope) {
-      const envelope = await encryptValue(plaintext, provider, scope);
-      return JSON.stringify(encodeStoredEnvelope(envelope));
-    },
-
-    async decrypt(stored, scope) {
-      if (isEnvelopeFormat(stored)) {
-        let parsed: unknown;
-        try {
-          parsed = JSON.parse(stored);
-        } catch {
-          throw new InternalError({
-            message: "[envelope-cipher] stored value looks like an envelope but is not valid JSON",
-            i18nKey: "secrets.errors.envelope_malformed",
-          });
-        }
-        if (!isStoredEnvelope(parsed)) {
-          throw new InternalError({
-            message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
-            i18nKey: "secrets.errors.envelope_malformed",
-          });
-        }
-        return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
-      }
-
-      if (!opts.legacy) {
-        throw new InternalError({
-          message:
-            "[envelope-cipher] value is in the legacy single-key format but no legacy key is configured — " +
-            "provision the legacy key (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY) or run the re-encrypt job first",
-          i18nKey: "secrets.errors.legacy_key_missing",
-        });
-      }
-      return opts.legacy.decrypt(stored);
-    },
-  };
-}

package/src/secrets/stored-envelope.ts

@@ -1,46 +0,0 @@
-// Canonical at-rest form of an Envelope: every Buffer as base64, ready for
-// jsonb columns (secrets feature) or JSON-stringified TEXT columns
-// (EnvelopeCipher for config values / entity fields). One wire shape for
-// every envelope-encrypted store in the framework.
-
-import type { Envelope } from "./types";
-
-export type StoredEnvelope = {
-  readonly ciphertext: string; // base64
-  readonly iv: string; // base64
-  readonly authTag: string; // base64
-  readonly encryptedDek: string; // base64
-  readonly kekVersion: number;
-};
-
-export function encodeStoredEnvelope(envelope: Envelope): StoredEnvelope {
-  return {
-    ciphertext: envelope.ciphertext.toString("base64"),
-    iv: envelope.iv.toString("base64"),
-    authTag: envelope.authTag.toString("base64"),
-    encryptedDek: envelope.encryptedDek.toString("base64"),
-    kekVersion: envelope.kekVersion,
-  };
-}
-
-export function decodeStoredEnvelope(stored: StoredEnvelope): Envelope {
-  return {
-    ciphertext: Buffer.from(stored.ciphertext, "base64"),
-    iv: Buffer.from(stored.iv, "base64"),
-    authTag: Buffer.from(stored.authTag, "base64"),
-    encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
-    kekVersion: stored.kekVersion,
-  };
-}
-
-export function isStoredEnvelope(value: unknown): value is StoredEnvelope {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>; // @cast-boundary parse-boundary after typeof check
-  return (
-    typeof v["ciphertext"] === "string" &&
-    typeof v["iv"] === "string" &&
-    typeof v["authTag"] === "string" &&
-    typeof v["encryptedDek"] === "string" &&
-    typeof v["kekVersion"] === "number"
-  );
-}