@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

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

@@ -0,0 +1,209 @@
+// KEK-rotation job for `encrypted: true` config values: envelope values
+// wrapped under an older kekVersion get 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.
+//
+// A row whose value isn't a current-cipher envelope (malformed JSON, or
+// any pre-envelope format) isn't a supported input here — cipher.decrypt
+// rejects it, so it's counted `failed` rather than silently treated as
+// already current. There is no legacy single-key decrypt path anymore.
+//
+// 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 rotation appends a normal `.updated` event whose payload carries
+// the NEW envelope: after a full run even a from-scratch rebuild only
+// ever sees the current-KEK envelope.
+
+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;
+};
+
+type RowClassification = "rotate" | "current" | "unrecognized";
+
+function classifyRow(value: string, targetVersion: number): RowClassification {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    // not JSON at all — no supported format decrypts this; let
+    // cipher.decrypt reject it and count the row as failed.
+    return "unrecognized";
+  }
+  if (!isStoredEnvelope(parsed)) return "unrecognized";
+  return parsed.kekVersion === targetVersion ? "current" : "rotate";
+}
+
+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";
+    const classification = classifyRow(row.value, targetVersion);
+    if (classification === "current") {
+      alreadyCurrent++;
+      return "skipped";
+    }
+
+    if (classification === "unrecognized") {
+      // Not a current-cipher envelope (malformed JSON, or any pre-envelope
+      // format) — never a supported re-encrypt input, so fail loudly
+      // instead of relying on cipher.decrypt to reject it. Log only the
+      // row id, never the value (ciphertext-adjacent).
+      ctx.log?.warn?.(
+        `[config:reencrypt] row ${row.id} is not a current-cipher envelope, not re-encryptable`,
+      );
+      return "failed";
+    }
+
+    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

@@ -1,16 +1,27 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configuredPiiSubjectKms,
+  encryptPiiValueForSubject,
+  type KmsContext,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import {
   ConfigScopes,
   defineWriteHandler,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  InternalError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { requireConfigEncryption } from "../feature";
 import { configValueEntity, configValuesTable } from "../table";
 import {
   findConfigRow,
   prepareConfigWrite,
+  resolvePiiSubject,
   validateBounds,
   validatePattern,
   validateScope,
@@ -47,6 +58,19 @@ export const setWrite = defineWriteHandler({
     const scopeError = validateScope(scope, keyDef.scope, event.payload.key);
     if (scopeError) return writeFailure(scopeError);
 
+    // A piiEncrypted key can never be defined with scope="system" (boot-
+    // rejected), but an admin override write can still target scope=
+    // "system" for a tenant/user-scoped key (validateScope allows any
+    // requestedScope <= definedScope) — system-row has no subject.
+    if (keyDef.piiEncrypted && scope === ConfigScopes.system) {
+      return writeFailure(
+        new UnprocessableError("invalid_scope", {
+          i18nKey: "config.errors.invalidScope",
+          details: { key: event.payload.key, definedScope: keyDef.scope, requestedScope: scope },
+        }),
+      );
+    }
+
     const typeError = validateType(event.payload.value, keyDef);
     if (typeError) return writeFailure(typeError);
 
@@ -88,8 +112,36 @@ 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 });
+    } else if (keyDef.piiEncrypted) {
+      const kms = configuredPiiSubjectKms();
+      if (!kms) {
+        throw new InternalError({
+          message:
+            `[config:write:set] key "${event.payload.key}" declares piiEncrypted=true but no ` +
+            `PII subject-KMS is configured — pass one via runProdApp({ kms }) / ` +
+            `configurePiiSubjectKms(adapter) at boot.`,
+        });
+      }
+      // scope="system" was already rejected above — narrow accordingly.
+      const subject = resolvePiiSubject(
+        scope as Exclude<typeof scope, "system">, // @cast-boundary runtime-checked above
+        tenantId,
+        userId,
+      );
+      const kmsCtx: KmsContext = {
+        requestId: requestContext.get()?.requestId ?? "config:write:set",
+        tenantId,
+        userId: String(event.user.id),
+      };
+      serialized = await encryptPiiValueForSubject(
+        kms,
+        subject,
+        serialized,
+        kmsCtx,
+        event.payload.key,
+      );
     }
 
     const existing = await findConfigRow(db, event.payload.key, tenantId, userId);

package/src/config/handlers/values.query.ts

@@ -3,6 +3,7 @@ import {
   type ConfigScope,
   type ConfigValueSource,
   defineQueryHandler,
+  isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
@@ -63,7 +64,7 @@ export const valuesQuery = defineQueryHandler({
       // key so the plaintext (which the resolver revealed for internal reads)
       // never reaches the UI response.
       let value: string | number | boolean | undefined;
-      if (keyDef.encrypted || keyDef.backing === "secrets") {
+      if (isEncryptedAtRest(keyDef)) {
         value = cascade.value !== undefined ? MASKED : undefined;
       } else {
         value = cascade.value;

package/src/config/i18n.ts

@@ -0,0 +1,9 @@
+type LocalizedString = { readonly de: string; readonly en: string };
+
+/** Server boot keys for the auto-generated Settings-Hub (mirrors web/i18n.ts). */
+export const CONFIG_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "config.settings.title": { de: "Einstellungen", en: "Settings" },
+  "config.settings.system": { de: "Plattform", en: "Platform" },
+  "config.settings.tenant": { de: "Organisation", en: "Organization" },
+  "config.settings.user": { de: "Persönlich", en: "Personal" },
+};

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 {
@@ -22,7 +23,7 @@ export {
 } from "./handlers/readiness.query";
 export type { AppConfigOverrides, ConfigResolver } from "./resolver";
 export { buildEnvConfigOverrides, createConfigResolver, validateAppOverrides } from "./resolver";
-export { configValuesTable } from "./table";
+export { configValueEntity, configValuesTable } from "./table";
 
 // Boot helper for runDevApp / runProdApp: pulls every ConfigSeedDef from
 // the registry and writes the matching system/tenant/user rows via the
@@ -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,17 +1,23 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbConnection, EncryptionProvider, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiValueForSubject,
+  type KmsContext,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
   ConfigCascade,
   ConfigCascadeLevel,
   ConfigKeyDefinition,
   ConfigResolver,
   ConfigSecretsReader,
-  ConfigStoredRowWithSource,
   ConfigValueSource,
   ConfigValueWithSource,
 } 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";
@@ -35,8 +41,13 @@ export function deserializeValue(
   if (raw === null || raw === undefined) return undefined;
   const parsed = parseJsonOrThrow<unknown>(raw, `config value (type=${type})`);
   switch (type) {
-    case "number":
-      return typeof parsed === "number" ? parsed : Number(parsed);
+    case "number": {
+      const n = typeof parsed === "number" ? parsed : Number(parsed);
+      if (!Number.isFinite(n)) {
+        throw new Error(`config value (type=number): "${raw}" does not deserialize to a number.`);
+      }
+      return n;
+    }
     case "boolean":
       return typeof parsed === "boolean" ? parsed : parsed === "true";
     case "text":
@@ -63,10 +74,51 @@ 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);
+}
+
+// Decrypt gate for piiEncrypted keys, mirroring decryptEncrypted above.
+// The subject lives inside the ciphertext (kumiko-pii:v1:<subject>:...),
+// so unlike the write side, no scope/subject resolution is needed here —
+// same call works for a user-row or a tenant-row value.
+async function decryptPiiEncrypted(raw: string, qualifiedKey: string): Promise<string> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) {
+    throw new InternalError({
+      message:
+        `[config] key "${qualifiedKey}" is piiEncrypted but no PII subject-KMS is wired — the ` +
+        `boot must configure one via runProdApp({ kms }) / configurePiiSubjectKms(adapter).`,
+      i18nKey: "config.errors.cipher_missing",
+    });
+  }
+  const kmsCtx: KmsContext = { requestId: requestContext.get()?.requestId ?? "config:resolver" };
+  return decryptPiiValueForSubject(kms, raw, kmsCtx, qualifiedKey);
+}
+
 // 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 +153,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 +231,10 @@ 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);
+      } else if (keyDef.piiEncrypted) {
+        raw = await decryptPiiEncrypted(raw, qualifiedKey);
       }
       if (activeIndex === -1) activeIndex = levels.length;
       levels.push({
@@ -265,7 +319,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 +410,10 @@ 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);
+          } else if (keyDef.piiEncrypted) {
+            raw = await decryptPiiEncrypted(raw, qualifiedKey);
           }
           return { value: deserializeValue(raw, keyDef.type), source: lookup.source };
         }
@@ -384,12 +440,12 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       return { value: undefined, source: "missing" };
     },
 
-    // NOTE: getAll / getAllWithSource read only config_values rows and do NOT
-    // dispatch to the secrets store (unlike get/getCascade/getWithSource). A
-    // backing="secrets" key has no config_values row, so it is simply ABSENT
-    // from the result map — never a stale/undefined value. Callers needing a
-    // secrets-backed value must use get/getCascade; these bulk readers are for
-    // the config_values-backed keys only.
+    // NOTE: getAll reads only config_values rows and does NOT dispatch to the
+    // secrets store (unlike get/getCascade/getWithSource). A backing="secrets"
+    // key has no config_values row, so it is simply ABSENT from the result map
+    // — never a stale/undefined value. Callers needing a secrets-backed value
+    // must use get/getCascade; this bulk reader is for config_values-backed
+    // keys only.
     async getAll(tenantId, userId, db) {
       // Only load rows relevant to this user/tenant (system + tenant + user scope)
       const rows = await selectConfigRowsForScope(db, SYSTEM_TENANT_ID, tenantId, userId);
@@ -410,48 +466,6 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       return result;
     },
 
-    async getAllWithSource(tenantId, userId, db) {
-      // Load ALL potentially relevant rows (user + tenant + system)
-      const rows = await selectConfigRowsForScope(db, SYSTEM_TENANT_ID, tenantId, userId);
-
-      const result = new Map<string, ConfigStoredRowWithSource>();
-
-      // Group rows by key so we can determine the winner and its source
-      const groups = new Map<string, ConfigRow[]>();
-      for (const r of rows) {
-        const g = groups.get(r.key) ?? [];
-        g.push(r);
-        groups.set(r.key, g);
-      }
-
-      for (const [key, keyRows] of groups) {
-        const specificityOf = (candidate: ConfigRow) =>
-          (candidate.userId !== null ? 2 : 0) + (candidate.tenantId !== SYSTEM_TENANT_ID ? 1 : 0);
-
-        const first = keyRows[0];
-        if (!first) continue;
-        let winner: ConfigRow = first;
-        for (const r of keyRows) {
-          if (specificityOf(r) > specificityOf(winner)) {
-            winner = r;
-          }
-        }
-
-        let source: ConfigValueSource;
-        if (winner.userId !== null) {
-          source = "user-row";
-        } else if (winner.tenantId !== SYSTEM_TENANT_ID) {
-          source = "tenant-row";
-        } else {
-          source = "system-row";
-        }
-
-        result.set(key, { ...winner, source });
-      }
-
-      return result;
-    },
-
     async getCascade(
       qualifiedKey,
       keyDef,
@@ -470,7 +484,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
         db,
         (tid, uid) => findRow(qualifiedKey, tid, uid, db),
         appOverrides,
-        encryption,
+        cipher,
         secretsReader,
       );
     },
@@ -512,7 +526,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/config/table.ts

@@ -25,7 +25,7 @@ export const configValueEntity = createEntity({
     // breaking the null-vs-missing distinction the resolver already draws.
     value: createTextField({}),
     // user-scope row: userId populated. tenant- / system-scope: null.
-    userId: createTextField({}),
+    userId: createTextField({ allowPlaintext: "pseudonymous-fk" }),
   },
   indexes: [
     { unique: true, columns: ["key", "tenantId", "userId"], name: "read_config_values_unique" },

package/src/config/write-helpers.ts

@@ -3,6 +3,7 @@
 // have to cross-import from another handler file.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigKeyDefinition,
@@ -198,6 +199,27 @@ export function resolveScopeIds(
   }
 }
 
+// The subject a piiEncrypted config value is encrypted under, for the scope
+// actually written to (kumiko-platform#231/#459). Pure — no I/O — so a bug
+// here (e.g. picking the writer's identity instead of the row's target,
+// see entity fields' explicit userOwned.ownerField for why that
+// distinction matters) is caught by a fast unit test, not only the DB-
+// backed integration test. Caller has already rejected scope="system"
+// (no subject exists for it).
+export function resolvePiiSubject(
+  scope: Exclude<ConfigScope, "system">,
+  tenantId: TenantId,
+  userId: string | null,
+): SubjectId {
+  if (scope === ConfigScopes.user) {
+    if (userId === null) {
+      throw new Error('resolvePiiSubject: scope="user" but userId is null');
+    }
+    return { kind: "user", userId };
+  }
+  return { kind: "tenant", tenantId };
+}
+
 export function validateType(
   value: string | number | boolean,
   keyDef: ConfigKeyDefinition,