@cosmicdrift/kumiko-bundled-features 0.110.0 → 0.111.0

package/src/config/handlers/reencrypt.job.ts

@@ -0,0 +1,197 @@
+// Re-encrypt job for `encrypted: true` config values. Two jobs in one,
+// because format detection makes them the same loop:
+//   - MIGRATION: legacy CONFIG_ENCRYPTION_KEY values (base64 blob, no key
+//     id) → envelope format under the current master key. After a clean
+//     run the legacy key can be dropped from the environment.
+//   - KEK-ROTATION: envelope values wrapped under an older kekVersion →
+//     re-encrypted under provider.currentVersion(). Config has no
+//     kek_version column (values live in a TEXT column), so unlike the
+//     secrets rotate job the version check parses the stored JSON.
+//
+// Idempotent: a re-run skips rows already on the current version. Every
+// write goes through the event-store executor (config values are
+// entity-backed — raw UPDATEs would be wiped by a projection rebuild),
+// so each migration appends a normal `.updated` event whose payload
+// carries the NEW envelope: after a full run even a from-scratch rebuild
+// no longer needs the legacy key for the final state.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { type EnvelopeCipher, isStoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
+import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared";
+import { configValueEntity, configValuesTable } from "../table";
+
+const DEFAULT_MAX_FAILURES = 10;
+const SCAN_SLICE_SIZE = 100;
+const SYSTEM_ROLES = ["system"] as const;
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+export type ReencryptJobPayload = {
+  readonly maxDurationMs?: number;
+  readonly maxFailures?: number;
+};
+
+export type ReencryptJobResult = {
+  readonly migrated: number;
+  readonly failed: number;
+  readonly alreadyCurrent: number;
+  readonly stoppedReason: ChunkedMigrationStopReason;
+};
+
+function needsReencrypt(value: string, targetVersion: number): boolean {
+  // legacy single-key format (base64 — can never start with "{")
+  if (!value.startsWith("{")) return true;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!isStoredEnvelope(parsed)) return true;
+    return parsed.kekVersion !== targetVersion;
+  } catch {
+    // malformed JSON — let the decrypt attempt surface the real error
+    return true;
+  }
+}
+
+export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+  const payload = rawPayload as ReencryptJobPayload; // @cast-boundary engine-payload
+  const maybeCipher = ctx.configEncryption;
+  if (!maybeCipher) {
+    throw new InternalError({
+      message:
+        "[config:reencrypt] ctx.configEncryption missing — provide a master key " +
+        "(KUMIKO_SECRETS_MASTER_KEY_V<n>) so the boot wires the envelope cipher.",
+    });
+  }
+  // hoisted function declarations below capture these — pin the narrowed
+  // type explicitly so TS keeps it inside the closures
+  const cipher: EnvelopeCipher = maybeCipher;
+  const provider = ctx.masterKeyProvider;
+  if (!provider) {
+    throw new InternalError({
+      message:
+        "[config:reencrypt] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+    });
+  }
+  if (!ctx.db) {
+    throw new InternalError({
+      message: "[config:reencrypt] ctx.db missing — job context requires a database connection.",
+    });
+  }
+  if (!ctx.registry) {
+    throw new InternalError({
+      message: "[config:reencrypt] ctx.registry missing — job context requires the registry.",
+    });
+  }
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
+
+  const encryptedKeys = [...ctx.registry.getAllConfigKeys()]
+    .filter(([, def]) => def.encrypted === true)
+    .map(([key]) => key);
+
+  const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+
+  const tdbCache = new Map<TenantId, TenantDb>();
+  function tdbFor(tenantId: TenantId): TenantDb {
+    let existing = tdbCache.get(tenantId);
+    if (!existing) {
+      existing = createTenantDb(db, tenantId, "system");
+      tdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  type ConfigRow = {
+    id: string;
+    key: string;
+    value: string | null;
+    tenantId: string;
+    version: number;
+  };
+
+  let alreadyCurrent = 0;
+  const targetVersion = provider.currentVersion();
+
+  // ponytail: one full candidate scan — config rows are operator-scale
+  // (tenants × encrypted keys), cursor pagination when that ever changes.
+  // Served to the shared loop in slices so its deadline/signal/failure
+  // checks run between chunks, not only once.
+  let pending: ConfigRow[] | undefined;
+  async function nextBatch(): Promise<readonly ConfigRow[]> {
+    if (pending === undefined) {
+      pending =
+        encryptedKeys.length === 0
+          ? []
+          : [
+              ...(await selectMany<ConfigRow>(db, configValuesTable, {
+                key: { in: encryptedKeys },
+              })),
+            ];
+    }
+    const slice = pending;
+    return slice.splice(0, SCAN_SLICE_SIZE);
+  }
+
+  async function migrateRow(row: ConfigRow): Promise<"migrated" | "skipped" | "failed"> {
+    if (row.value === null || row.value === undefined) return "skipped";
+    if (!needsReencrypt(row.value, targetVersion)) {
+      alreadyCurrent++;
+      return "skipped";
+    }
+
+    // decrypt failure (missing legacy key, unknown kekVersion, tamper)
+    // throws → counted as failed via onRowError; the row stays untouched —
+    // never write anything we couldn't read.
+    const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+    const plaintext = await cipher.decrypt(row.value, { tenantId });
+    const reencrypted = await cipher.encrypt(plaintext, { tenantId });
+
+    const actor: SessionUser = { id: "system", tenantId, roles: SYSTEM_ROLES };
+    const result = await executor.update(
+      { id: row.id, version: row.version, changes: { value: reencrypted } },
+      actor,
+      tdbFor(tenantId),
+    );
+
+    // version_conflict == a concurrent config:set beat us; the row now
+    // holds a fresh envelope written by the set handler — already fine.
+    if (!result.isSuccess) {
+      if (result.error.code === "version_conflict") return "skipped";
+      ctx.log?.warn?.(`[config:reencrypt] executor rejected row ${row.id}`, {
+        code: result.error.code,
+      });
+      return "failed";
+    }
+    return "migrated";
+  }
+
+  const outcome = await runChunkedMigration<ConfigRow>({
+    nextBatch,
+    migrateRow,
+    maxFailures,
+    deadlineAt: deadline,
+    signal: ctx.signal,
+    onRowError: (row, err) => {
+      ctx.log?.warn?.(`[config:reencrypt] failed to re-encrypt row ${row.id}`, { err });
+    },
+  });
+
+  const result: ReencryptJobResult = {
+    migrated: outcome.migrated,
+    failed: outcome.failed,
+    alreadyCurrent,
+    stoppedReason: outcome.stoppedReason,
+  };
+  ctx.log?.info?.(`[config:reencrypt] complete: ${JSON.stringify(result)}`);
+};

package/src/config/handlers/set.write.ts

@@ -88,8 +88,8 @@ export const setWrite = defineWriteHandler({
 
     let serialized = JSON.stringify(event.payload.value);
     if (keyDef.encrypted) {
-      const encryption = requireConfigEncryption(ctx, "config:write:set");
-      serialized = encryption.encrypt(serialized);
+      const cipher = requireConfigEncryption(ctx, "config:write:set");
+      serialized = await cipher.encrypt(serialized, { tenantId });
     }
 
     const existing = await findConfigRow(db, event.payload.key, tenantId, userId);

package/src/config/index.ts

@@ -1,6 +1,7 @@
-import type { DbConnection, EncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { seedConfigValues } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import { configValueEntity, configValuesTable } from "./table";
 
 export {
@@ -30,8 +31,8 @@ export { configValuesTable } from "./table";
 export function seedAllConfigValues(
   registry: Registry,
   db: DbConnection,
-  encryption?: EncryptionProvider,
+  cipher?: EnvelopeCipher,
 ): Promise<{ created: number; skipped: number }> {
   const seeds = registry.getAllConfigSeeds();
-  return seedConfigValues(seeds, configValuesTable, configValueEntity, registry, db, encryption);
+  return seedConfigValues(seeds, configValuesTable, configValueEntity, registry, db, cipher);
 }

package/src/config/resolver.ts

@@ -1,5 +1,5 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbConnection, EncryptionProvider, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
   ConfigCascade,
   ConfigCascadeLevel,
@@ -12,6 +12,7 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import { assertUnreachable, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import { selectConfigRowsForKeys, selectConfigRowsForScope } from "./db/queries/resolver";
 import { configValuesTable } from "./table";
@@ -63,10 +64,33 @@ export function deserializeValue(
 export type AppConfigOverrides = ReadonlyMap<string, string | number | boolean>;
 
 export type ConfigResolverOptions = {
-  encryption?: EncryptionProvider;
+  // Envelope cipher for `encrypted: true` keys. run{Prod,Dev}App wire it
+  // automatically from the secrets master key — apps only pass their own
+  // to override (tests, custom providers).
+  cipher?: EnvelopeCipher;
   appOverrides?: AppConfigOverrides;
 };
 
+// Decrypt gate for encrypted keys: an encrypted row without a cipher MUST
+// throw — passing the ciphertext through as the "value" (the pre-envelope
+// behavior) silently feeds base64 garbage to whatever consumes the key
+// (e.g. an SMTP password) and is a debugging nightmare.
+async function decryptEncrypted(
+  cipher: EnvelopeCipher | undefined,
+  raw: string,
+  qualifiedKey: string,
+): Promise<string> {
+  if (!cipher) {
+    throw new InternalError({
+      message:
+        `[config] key "${qualifiedKey}" is encrypted but no cipher is wired — the boot must ` +
+        `provide a master key (KUMIKO_SECRETS_MASTER_KEY_V<n>) or pass ConfigResolverOptions.cipher.`,
+      i18nKey: "config.errors.cipher_missing",
+    });
+  }
+  return cipher.decrypt(raw);
+}
+
 // backing="secrets" keys store their value in the secrets store (flat per
 // (tenant,key) at SYSTEM_TENANT_ID), not in config_values. Both read paths
 // (getWithSource + buildCascade) route the system rung here. Missing reader =
@@ -101,7 +125,7 @@ async function buildCascade(
     userId: string | null,
   ) => Promise<ConfigRow | null> | ConfigRow | null,
   appOverrides: AppConfigOverrides | undefined,
-  encryption: EncryptionProvider | undefined,
+  cipher: EnvelopeCipher | undefined,
   secretsReader: ConfigSecretsReader | undefined,
 ): Promise<ConfigCascade> {
   type Lookup = {
@@ -179,8 +203,8 @@ async function buildCascade(
     const row = await fetchRow(lookup.tenantId, lookup.userId);
     if (row?.value !== null && row?.value !== undefined) {
       let raw = row.value;
-      if (keyDef.encrypted && encryption) {
-        raw = encryption.decrypt(raw);
+      if (keyDef.encrypted) {
+        raw = await decryptEncrypted(cipher, raw, qualifiedKey);
       }
       if (activeIndex === -1) activeIndex = levels.length;
       levels.push({
@@ -265,7 +289,7 @@ async function buildCascade(
 }
 
 export function createConfigResolver(options: ConfigResolverOptions = {}): ConfigResolver {
-  const { encryption, appOverrides } = options;
+  const { cipher, appOverrides } = options;
   async function findRow(
     key: string,
     tenantId: string,
@@ -356,8 +380,8 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
         const row = await findRow(qualifiedKey, lookup.tenantId, lookup.userId, db);
         if (row?.value !== null && row?.value !== undefined) {
           let raw = row.value;
-          if (keyDef.encrypted && encryption) {
-            raw = encryption.decrypt(raw);
+          if (keyDef.encrypted) {
+            raw = await decryptEncrypted(cipher, raw, qualifiedKey);
           }
           return { value: deserializeValue(raw, keyDef.type), source: lookup.source };
         }
@@ -470,7 +494,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
         db,
         (tid, uid) => findRow(qualifiedKey, tid, uid, db),
         appOverrides,
-        encryption,
+        cipher,
         secretsReader,
       );
     },
@@ -512,7 +536,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
           (tid, uid) =>
             keyRows.find((r) => r.tenantId === tid && (r.userId ?? null) === uid) ?? null,
           appOverrides,
-          encryption,
+          cipher,
           secretsReader,
         );
         result.set(key, cascade);

package/src/file-foundation/__tests__/file-foundation.integration.test.ts

@@ -4,7 +4,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
@@ -18,6 +18,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import {
   createMutableMasterKeyProvider,
+  createTestEnvelopeCipher,
   type MutableMasterKeyProvider,
 } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
@@ -73,8 +74,8 @@ let providerRef: MutableMasterKeyProvider;
 const testEncryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(testEncryptionKey);
-  resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(testEncryptionKey);
+  resolver = createConfigResolver({ cipher: encryption });
 
   const initialKp = createEnvMasterKeyProvider({
     env: {

package/src/jobs/__tests__/job-system-user.integration.test.ts

@@ -1,10 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import {
-  createEncryptionProvider,
-  createTenantDb,
-  type DbConnection,
-} from "@cosmicdrift/kumiko-framework/db";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createRegistry,
@@ -26,7 +22,7 @@ import {
   TestUsers,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { bridgeStub, sleep } from "@cosmicdrift/kumiko-framework/testing";
+import { bridgeStub, createTestEnvelopeCipher, sleep } from "@cosmicdrift/kumiko-framework/testing";
 import { ConfigHandlers } from "../../config/constants";
 import { createConfigAccessor, createConfigFeature } from "../../config/feature";
 import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
@@ -107,8 +103,8 @@ beforeAll(async () => {
   await createEventsTable(db);
   await createArchivedStreamsTable(db);
 
-  const encryption = createEncryptionProvider(testEncryptionKey);
-  resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(testEncryptionKey);
+  resolver = createConfigResolver({ cipher: encryption });
 
   registry = createRegistry([configFeature, billingFeature]);
 

package/src/mail-foundation/__tests__/mail-foundation.integration.test.ts

@@ -10,7 +10,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
@@ -24,6 +24,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import {
   createMutableMasterKeyProvider,
+  createTestEnvelopeCipher,
   type MutableMasterKeyProvider,
 } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
@@ -87,8 +88,8 @@ let providerRef: MutableMasterKeyProvider;
 const testEncryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(testEncryptionKey);
-  resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(testEncryptionKey);
+  resolver = createConfigResolver({ cipher: encryption });
 
   // Master-key for the secrets-feature. Production env shape:
   //   KUMIKO_SECRETS_MASTER_KEY_V1=<base64 32 bytes>

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -5,7 +5,6 @@ import {
   type PatResolver,
 } from "@cosmicdrift/kumiko-framework/api";
 import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -14,7 +13,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { deleteRows } from "@cosmicdrift/kumiko-framework/testing";
+import { createTestEnvelopeCipher, deleteRows } from "@cosmicdrift/kumiko-framework/testing";
 import { Temporal } from "temporal-polyfill";
 import { AuthHandlers } from "../../auth-email-password/constants";
 import { createAuthEmailPasswordFeature } from "../../auth-email-password/feature";
@@ -73,8 +72,8 @@ async function mintToken(
 }
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/readiness/__tests__/readiness.integration.test.ts

@@ -6,7 +6,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
@@ -18,6 +18,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config";
 import { createConfigAccessorFactory } from "../../config/feature";
 import { createConfigResolver } from "../../config/resolver";
@@ -133,8 +134,8 @@ let stack: TestStack;
 let db: DbConnection;
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  const resolver = createConfigResolver({ cipher: encryption });
   const masterKeyProvider = createEnvMasterKeyProvider({
     env: {
       KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),