@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/config/resolver.ts

@@ -0,0 +1,283 @@
+import {
+  type DbConnection,
+  type EncryptionProvider,
+  fetchOne,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import type {
+  ConfigKeyDefinition,
+  ConfigResolver,
+  ConfigValueSource,
+  ConfigValueWithSource,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { assertUnreachable, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { and, eq, isNull, or } from "drizzle-orm";
+import { configValuesTable } from "./table";
+
+type ConfigRow = {
+  id: string;
+  key: string;
+  value: string | null;
+  tenantId: string;
+  userId: string | null;
+};
+
+// Re-export so existing call sites that imported ConfigResolver from
+// "../resolver" keep compiling — the shape now lives in the framework.
+export type { ConfigResolver };
+
+export function deserializeValue(
+  raw: string | null,
+  type: ConfigKeyDefinition["type"],
+): string | number | boolean | undefined {
+  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 "boolean":
+      return typeof parsed === "boolean" ? parsed : parsed === "true";
+    case "text":
+    case "select":
+      return String(parsed);
+    default:
+      assertUnreachable(type, "config key type");
+  }
+}
+
+// App-Boot overrides: deploy-time defaults that sit between the
+// tenant/system rows and the feature-declared `default`. Use-case: the
+// framework ships a default of 10 MB for maxUploadSizeMB, but this
+// particular deploy is a photo-app that wants 200 MB — no DB-seed needed,
+// just a single Map at boot.
+//
+// Keys are the fully-qualified names (e.g. "files:config:max-upload-size-mb").
+// Values are the raw primitive — serialization happens as part of the
+// cascade so the boot-code doesn't need to know about JSON encoding.
+//
+// Validation at construction time (buildServer-path): unknown keys,
+// type-mismatches, and bounds violations throw synchronously. See
+// validateAppOverrides below.
+export type AppConfigOverrides = ReadonlyMap<string, string | number | boolean>;
+
+export type ConfigResolverOptions = {
+  encryption?: EncryptionProvider;
+  appOverrides?: AppConfigOverrides;
+};
+
+export function createConfigResolver(options: ConfigResolverOptions = {}): ConfigResolver {
+  const { encryption, appOverrides } = options;
+  async function findRow(
+    key: string,
+    tenantId: string,
+    userId: string | null,
+    db: DbConnection | TenantDb,
+  ): Promise<ConfigRow | null> {
+    const userCond =
+      userId !== null ? eq(configValuesTable.userId, userId) : isNull(configValuesTable.userId);
+
+    const row = await fetchOne<ConfigRow>(
+      db,
+      configValuesTable,
+      eq(configValuesTable.key, key),
+      eq(configValuesTable.tenantId, tenantId),
+      userCond,
+    );
+
+    return row ?? null;
+  }
+
+  return {
+    async get(qualifiedKey, keyDef, tenantId, userId, db) {
+      // get() is a thin wrapper around getWithSource that discards the
+      // source tag. Keeps the hot-path a single implementation.
+      const result = await this.getWithSource(qualifiedKey, keyDef, tenantId, userId, db);
+      return result.value;
+    },
+
+    async getWithSource(
+      qualifiedKey,
+      keyDef,
+      tenantId,
+      userId,
+      db,
+    ): Promise<ConfigValueWithSource> {
+      // Resolution cascade based on scope
+      // user:   userId+tenantId → tenantId → default
+      // tenant: tenantId → SYSTEM_TENANT_ID → default
+      // system: SYSTEM_TENANT_ID → default
+      const lookups: Array<{
+        tenantId: string;
+        userId: string | null;
+        source: ConfigValueSource;
+      }> = [];
+
+      switch (keyDef.scope) {
+        case "user":
+          lookups.push({ tenantId, userId, source: "user-row" });
+          lookups.push({ tenantId, userId: null, source: "tenant-row" });
+          break;
+        case "tenant":
+          lookups.push({ tenantId, userId: null, source: "tenant-row" });
+          lookups.push({ tenantId: SYSTEM_TENANT_ID, userId: null, source: "system-row" });
+          break;
+        case "system":
+          lookups.push({ tenantId: SYSTEM_TENANT_ID, userId: null, source: "system-row" });
+          break;
+        default:
+          assertUnreachable(keyDef.scope, "config scope");
+      }
+
+      for (const lookup of lookups) {
+        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);
+          }
+          return { value: deserializeValue(raw, keyDef.type), source: lookup.source };
+        }
+      }
+
+      // App-Boot-Override: one step above the feature-declared default.
+      // The override only kicks in when no scope-specific row exists —
+      // a tenant-admin that deliberately set a value still wins.
+      if (appOverrides?.has(qualifiedKey)) {
+        return { value: appOverrides.get(qualifiedKey), source: "app-override" };
+      }
+
+      // Computed fallback: plan-based values, feature-flag-Resolver etc.
+      // Called after rows + app-overrides miss, before the static default.
+      if (keyDef.computed) {
+        const value = await keyDef.computed({ tenantId, userId, db });
+        return { value, source: "computed" };
+      }
+
+      if (keyDef.default !== undefined) {
+        return { value: keyDef.default, source: "default" };
+      }
+
+      return { value: undefined, source: "missing" };
+    },
+
+    async getAll(tenantId, userId, db) {
+      // Only load rows relevant to this user/tenant (system + tenant + user scope)
+      const rows = await db
+        .select()
+        .from(configValuesTable)
+        .where(
+          or(
+            // System-level values
+            and(eq(configValuesTable.tenantId, SYSTEM_TENANT_ID), isNull(configValuesTable.userId)),
+            // Tenant-level values
+            and(eq(configValuesTable.tenantId, tenantId), isNull(configValuesTable.userId)),
+            // User-level values
+            and(eq(configValuesTable.tenantId, tenantId), eq(configValuesTable.userId, userId)),
+          ),
+        );
+
+      const result = new Map<string, ConfigRow>();
+      for (const row of rows) {
+        const r = row as ConfigRow;
+        // Higher specificity wins: user > tenant > system. Under the ES
+        // schema system rows carry SYSTEM_TENANT_ID instead of NULL, so the
+        // "tenant set" check compares against the sentinel rather than null.
+        const specificityOf = (candidate: ConfigRow) =>
+          (candidate.userId !== null ? 2 : 0) + (candidate.tenantId !== SYSTEM_TENANT_ID ? 1 : 0);
+        const existing = result.get(r.key);
+        if (!existing || specificityOf(r) > specificityOf(existing)) {
+          result.set(r.key, r);
+        }
+      }
+
+      return result;
+    },
+  };
+}
+
+// Validates an app-override Map against a registry before the resolver
+// ingests it. Call this from buildServer (or the app's boot wiring) with
+// the registry's config keys + the overrides the app-dev provided.
+//
+// Four classes of errors, all thrown eagerly so a typo in boot-code fails
+// immediately instead of silently returning stale defaults in production:
+//   1. unknown key → feature probably renamed or not required
+//   2. type mismatch → wrong primitive (number for a text key, etc.)
+//   3. bounds / options violation → same rule as tenant-admin Set
+//   4. computed conflict → app-override would silently beat plan-based
+//      logic; incompatible paradigm, requires explicit resolution
+//
+// The return is a narrowed Map ready to hand to createConfigResolver.
+export function validateAppOverrides(
+  registry: {
+    getConfigKey: (
+      key: string,
+    ) => import("@cosmicdrift/kumiko-framework/engine").ConfigKeyDefinition | undefined;
+  },
+  overrides: Readonly<Record<string, string | number | boolean>>,
+): AppConfigOverrides {
+  const validated = new Map<string, string | number | boolean>();
+
+  for (const [key, value] of Object.entries(overrides)) {
+    const keyDef = registry.getConfigKey(key);
+    if (!keyDef) {
+      throw new Error(
+        `App-Boot-Override for unknown config key "${key}" — no feature declares it. Typo or missing feature-require?`,
+      );
+    }
+
+    // computed keys encode plan-based business logic ("zahlender Tenant
+    // bekommt 100 MB"). An app-override would silently beat that — the
+    // cascade puts overrides above computed, so the plan becomes invisible.
+    // Force an explicit decision: either drop the override and trust the
+    // computed function, or drop computed if the deploy really wants a
+    // static default for everyone. Mixing silently is a footgun.
+    if (keyDef.computed) {
+      throw new Error(
+        `App-Boot-Override for "${key}": this key has a computed resolver (plan-based / derived). App-overrides would silently bypass that logic — remove the override, or remove the computed resolver if a flat deploy-default is intended.`,
+      );
+    }
+
+    // Per keyDef.type narrow value inline — TS narrowt nicht durch
+    // `typeof value !== typeForKey(...)` (typeForKey returnt string,
+    // kein discriminator). Das vermeidet `value as string|number` casts
+    // unten, weil value innerhalb des Branches schon typed ist.
+    if (keyDef.type === "number") {
+      if (typeof value !== "number") {
+        throw new Error(`App-Boot-Override for "${key}": expected number, got ${typeof value}`);
+      }
+      if (keyDef.bounds) {
+        const { min, max } = keyDef.bounds;
+        if (min !== undefined && value < min) {
+          throw new Error(
+            `App-Boot-Override for "${key}": value ${value} is below bounds.min (${min})`,
+          );
+        }
+        if (max !== undefined && value > max) {
+          throw new Error(
+            `App-Boot-Override for "${key}": value ${value} is above bounds.max (${max})`,
+          );
+        }
+      }
+    } else if (keyDef.type === "boolean") {
+      if (typeof value !== "boolean") {
+        throw new Error(`App-Boot-Override for "${key}": expected boolean, got ${typeof value}`);
+      }
+    } else {
+      // text or select
+      if (typeof value !== "string") {
+        throw new Error(`App-Boot-Override for "${key}": expected string, got ${typeof value}`);
+      }
+      if (keyDef.type === "select" && keyDef.options && !keyDef.options.includes(value)) {
+        throw new Error(
+          `App-Boot-Override for "${key}": value "${value}" is not in options [${keyDef.options.join(", ")}]`,
+        );
+      }
+    }
+
+    validated.set(key, value);
+  }
+
+  return validated;
+}

package/src/config/table.ts

@@ -0,0 +1,35 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+// Config values are event-sourced. Each (key, scope) is its own aggregate
+// stream — lifecycle events `configValue.created / .updated / .deleted`
+// flow through createEventStoreExecutor, which writes the stream + this
+// projection in one TX. Reads stay O(1) against the projection.
+//
+// System-scope rows use SYSTEM_TENANT_ID (not null) — buildBaseColumns
+// (via buildDrizzleTable) forces tenant_id NOT NULL, so die pre-ES "NULL
+// means system" convention is replaced with a fixed sentinel. Der unique
+// index über (key, tenant_id, user_id) prevent duplicate writes at the DB
+// level — deklariert via entity.indexes.
+//
+// Single-Source-of-Truth: `configValueEntity`. Die DB-Tabelle wird über
+// buildDrizzleTable aus der EntityDefinition abgeleitet, der unique-Index
+// ist via entity.indexes deklariert. Plural-Re-Export `configValuesTable`
+// dient handlers (`reset.write.ts` etc.) als typisierte Drizzle-Table-Ref.
+export const configValueEntity = createEntity({
+  table: "read_config_values",
+  fields: {
+    key: createTextField({ required: true }),
+    // value is JSON-encoded primitive (or encrypted blob). Nullable so a
+    // deleted-then-recreated stream can signal "reset to default" without
+    // breaking the null-vs-missing distinction the resolver already draws.
+    value: createTextField({}),
+    // user-scope row: userId populated. tenant- / system-scope: null.
+    userId: createTextField({}),
+  },
+  indexes: [
+    { unique: true, columns: ["key", "tenantId", "userId"], name: "read_config_values_unique" },
+  ],
+});
+
+export const configValuesTable = buildDrizzleTable("config-value", configValueEntity);

package/src/config/write-helpers.ts

@@ -0,0 +1,268 @@
+// Shared helpers for the config feature's write + query handlers.
+// Extracted from set.write.ts so reset.write.ts + values.query.ts don't
+// have to cross-import from another handler file.
+
+import { type DbConnection, fetchOne, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ConfigKeyDefinition,
+  type ConfigScope,
+  ConfigScopes,
+  type Registry,
+  type SessionUser,
+  SYSTEM_ROLE,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  type KumikoError,
+  NotFoundError,
+  UnprocessableError,
+  ValidationError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { assertUnreachable } from "@cosmicdrift/kumiko-framework/utils";
+import { eq, isNull } from "drizzle-orm";
+import { ConfigErrors } from "./constants";
+import { configValuesTable } from "./table";
+
+export type ConfigRowLookup = {
+  readonly id: string;
+  readonly version: number;
+  readonly value: string | null;
+};
+
+// Locate an existing config_values row by the (key, tenant, user) triple —
+// the effective natural key. System-scope rows carry SYSTEM_TENANT_ID on
+// the tenant_id column (the post-ES projection is NOT NULL), so callers
+// hand in that sentinel directly instead of null. userId stays nullable
+// because tenant-scope rows have no user.
+export async function findConfigRow(
+  db: DbConnection | TenantDb,
+  key: string,
+  tenantId: TenantId,
+  userId: string | null,
+): Promise<ConfigRowLookup | null> {
+  const userCond =
+    userId !== null ? eq(configValuesTable.userId, userId) : isNull(configValuesTable.userId);
+  const row = await fetchOne<ConfigRowLookup>(
+    db,
+    configValuesTable,
+    eq(configValuesTable.key, key),
+    eq(configValuesTable.tenantId, tenantId),
+    userCond,
+  );
+  if (!row) return null;
+  return {
+    id: row.id,
+    version: row.version,
+    value: row.value ?? null,
+  };
+}
+
+// Three-stage pre-write gate that set + reset both need: resolve the key
+// definition (404 when unknown), check the user's roles can write it (403),
+// and map the target scope to the (tenantId | null, userId | null) pair the
+// resolver expects. Handler-specific follow-ups (scope-compat check, value
+// type check) stay inline in the handler that needs them.
+export type PrepareConfigWriteArgs = {
+  readonly registry: Registry;
+  readonly user: SessionUser;
+  readonly key: string;
+  // When omitted (or explicit `undefined`), falls back to `keyDef.scope`.
+  readonly scope?: ConfigScope | undefined;
+};
+
+export type PrepareConfigWriteResult =
+  | { readonly ok: false; readonly failure: WriteFailure }
+  | {
+      readonly ok: true;
+      readonly keyDef: ConfigKeyDefinition;
+      readonly scope: ConfigScope;
+      // Non-null even for system-scope (SYSTEM_TENANT_ID sentinel) — the
+      // projection column is NOT NULL and callers should never have to
+      // bridge null → sentinel themselves.
+      readonly tenantId: TenantId;
+      readonly userId: string | null;
+    };
+
+export function prepareConfigWrite(args: PrepareConfigWriteArgs): PrepareConfigWriteResult {
+  const { registry, user, key, scope: requestedScope } = args;
+
+  const keyDef = registry.getConfigKey(key);
+  if (!keyDef) {
+    return {
+      ok: false,
+      failure: writeFailure(
+        new NotFoundError("configKey", key, { i18nKey: "config.errors.unknownKey" }),
+      ),
+    };
+  }
+
+  const writeError = checkWriteAccess(keyDef, user.roles);
+  if (writeError) return { ok: false, failure: writeFailure(writeError) };
+
+  const scope = requestedScope ?? keyDef.scope;
+  const { tenantId, userId } = resolveScopeIds(scope, user.tenantId, user.id);
+  return { ok: true, keyDef, scope, tenantId, userId };
+}
+
+export function hasConfigAccess(
+  accessList: readonly string[],
+  userRoles: readonly string[],
+): boolean {
+  if (accessList.includes("all")) return true;
+  return userRoles.some((role) => accessList.includes(role));
+}
+
+export function checkWriteAccess(
+  keyDef: ConfigKeyDefinition,
+  userRoles: readonly string[],
+): KumikoError | null {
+  if (keyDef.access.write.includes(SYSTEM_ROLE)) {
+    // Pre-ES the system-only block was absolute — out-of-band writes went
+    // through resolver.set, bypassing the whole access layer. Post-ES
+    // every write flows through this handler + executor, so the escape
+    // hatch becomes explicit: SYSTEM_ROLE (jobs / seeds / framework-
+    // internal work) may write; everyone else is rejected.
+    if (userRoles.includes(SYSTEM_ROLE)) return null;
+    return new AccessDeniedError({
+      message: "config key is system-only",
+      i18nKey: "config.errors.systemOnly",
+      details: { reason: ConfigErrors.systemOnly },
+    });
+  }
+  if (!hasConfigAccess(keyDef.access.write, userRoles)) {
+    return new AccessDeniedError({
+      message: "config write access denied",
+      details: { requiredRoles: keyDef.access.write },
+    });
+  }
+  return null;
+}
+
+export function validateScope(
+  requestedScope: ConfigScope,
+  definedScope: ConfigScope,
+  key: string,
+): KumikoError | null {
+  const levels: Record<ConfigScope, number> = {
+    [ConfigScopes.system]: 0,
+    [ConfigScopes.tenant]: 1,
+    [ConfigScopes.user]: 2,
+  };
+  if (levels[requestedScope] > levels[definedScope]) {
+    return new UnprocessableError("invalid_scope", {
+      i18nKey: "config.errors.invalidScope",
+      details: { key, definedScope, requestedScope },
+    });
+  }
+  return null;
+}
+
+export function resolveScopeIds(
+  scope: ConfigScope,
+  tenantId: TenantId,
+  userId: string,
+): { tenantId: TenantId; userId: string | null } {
+  switch (scope) {
+    case ConfigScopes.system:
+      return { tenantId: SYSTEM_TENANT_ID, userId: null };
+    case ConfigScopes.tenant:
+      return { tenantId, userId: null };
+    case ConfigScopes.user:
+      return { tenantId, userId };
+    default:
+      assertUnreachable(scope, "config scope");
+  }
+}
+
+export function validateType(
+  value: string | number | boolean,
+  keyDef: ConfigKeyDefinition,
+): KumikoError | null {
+  switch (keyDef.type) {
+    case "number":
+      if (typeof value !== "number") return typeMismatch("number", typeof value);
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") return typeMismatch("boolean", typeof value);
+      break;
+    case "text":
+      if (typeof value !== "string") return typeMismatch("string", typeof value);
+      break;
+    case "select":
+      if (typeof value !== "string") return typeMismatch("string", typeof value);
+      if (keyDef.options && !keyDef.options.includes(value)) {
+        return new ValidationError({
+          fields: [
+            {
+              path: "value",
+              code: "invalid_option",
+              i18nKey: "errors.validation.invalid_option",
+              params: { value, options: keyDef.options },
+            },
+          ],
+        });
+      }
+      break;
+    default:
+      assertUnreachable(keyDef.type, "config key type");
+  }
+  return null;
+}
+
+function typeMismatch(expected: string, actual: string): KumikoError {
+  return new ValidationError({
+    fields: [
+      {
+        path: "value",
+        code: "invalid_type",
+        i18nKey: "errors.validation.invalid_type",
+        params: { expected, received: actual },
+      },
+    ],
+  });
+}
+
+// Bounds enforcement for numeric config keys. Returns null when OK or when
+// bounds don't apply (non-number key, no bounds declared, or upstream
+// type-validation would already reject non-numeric values).
+export function validateBounds(
+  value: string | number | boolean,
+  keyDef: ConfigKeyDefinition,
+): KumikoError | null {
+  if (keyDef.type !== "number" || !keyDef.bounds) return null;
+  // skip: validateType runs first and catches non-numeric values
+  if (typeof value !== "number") return null;
+
+  const { min, max } = keyDef.bounds;
+
+  if (min !== undefined && value < min) {
+    return new ValidationError({
+      fields: [
+        {
+          path: "value",
+          code: "out_of_bounds",
+          i18nKey: "errors.validation.out_of_bounds",
+          params: { value, min, max: max ?? null },
+        },
+      ],
+    });
+  }
+  if (max !== undefined && value > max) {
+    return new ValidationError({
+      fields: [
+        {
+          path: "value",
+          code: "out_of_bounds",
+          i18nKey: "errors.validation.out_of_bounds",
+          params: { value, min: min ?? null, max },
+        },
+      ],
+    });
+  }
+
+  return null;
+}