@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/config/constants.ts

@@ -0,0 +1,23 @@
+// Feature name
+export const CONFIG_FEATURE = "config" as const;
+
+// Qualified write handler names (QN format: scope:type:name)
+export const ConfigHandlers = {
+  set: "config:write:set",
+  reset: "config:write:reset",
+} as const;
+
+// Qualified query handler names (QN format: scope:type:name)
+export const ConfigQueries = {
+  values: "config:query:values",
+  schema: "config:query:schema",
+} as const;
+
+// Error codes
+export const ConfigErrors = {
+  unknownKey: "unknown_config_key",
+  systemOnly: "config_key_is_system_only",
+  invalidScope: "invalid_scope",
+  typeError: "type_error",
+  invalidOption: "invalid_option",
+} as const;

package/src/config/feature.ts

@@ -0,0 +1,117 @@
+import type { DbConnection, EncryptionProvider, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ConfigAccessor,
+  type ConfigAccessorFactory,
+  type ConfigKeyHandle,
+  type ConfigKeyType,
+  type ConfigValue,
+  defineFeature,
+  type FeatureDefinition,
+  type HandlerContext,
+  type Registry,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { resetWrite } from "./handlers/reset.write";
+import { schemaQuery } from "./handlers/schema.query";
+import { setWrite } from "./handlers/set.write";
+import { valuesQuery } from "./handlers/values.query";
+import type { ConfigResolver } from "./resolver";
+import { configValueEntity } from "./table";
+
+export type ConfigContext = { readonly config: ConfigAccessor };
+
+export function createConfigFeature(): FeatureDefinition {
+  return defineFeature("config", (r) => {
+    r.systemScope();
+
+    // One aggregate stream per (key, scope) pair — the executor handles the
+    // lifecycle events `configValue.created / .updated / .deleted` plus the
+    // projection write in one TX. Subscribers that need config-change
+    // semantics listen to those auto-events via r.multiStreamProjection
+    // (see docs/plans/architecture/event-sourcing-pivot.md §4.7).
+    r.entity("config-value", configValueEntity);
+
+    const handlers = {
+      set: r.writeHandler(setWrite),
+      reset: r.writeHandler(resetWrite),
+    };
+
+    const queries = {
+      values: r.queryHandler(valuesQuery),
+      schema: r.queryHandler(schemaQuery),
+    };
+
+    return { handlers, queries };
+  });
+}
+
+export function createConfigAccessor(
+  registry: Registry,
+  resolver: ConfigResolver,
+  tenantId: TenantId,
+  userId: string,
+  db: DbConnection | TenantDb,
+): ConfigAccessor {
+  async function configAccessor(
+    qualifiedKey: string,
+  ): Promise<string | number | boolean | undefined>;
+  async function configAccessor<T extends ConfigKeyType>(
+    handle: ConfigKeyHandle<T>,
+  ): Promise<ConfigValue<T> | undefined>;
+  async function configAccessor(
+    keyOrHandle: string | ConfigKeyHandle<ConfigKeyType>,
+  ): Promise<string | number | boolean | undefined> {
+    const qualifiedKey = typeof keyOrHandle === "string" ? keyOrHandle : keyOrHandle.name;
+    const keyDef = registry.getConfigKey(qualifiedKey);
+    if (!keyDef) return undefined;
+    return resolver.get(qualifiedKey, keyDef, tenantId, userId, db);
+  }
+  return configAccessor;
+}
+
+// Pass to the test-stack / server-boot as `_configAccessorFactory` —
+// `buildHandlerContext` mints a per-user `ctx.config` from this.
+export function createConfigAccessorFactory(
+  registry: Registry,
+  resolver: ConfigResolver,
+): ConfigAccessorFactory {
+  return ({ user, db }) => createConfigAccessor(registry, resolver, user.tenantId, user.id, db);
+}
+
+// Single point of truth for "this handler needs the resolver". Throws a
+// proper InternalError (with i18n) instead of bare Error, and points the
+// caller at the boot wiring step that's missing — so a future debug
+// session reads "config feature not wired into AppContext" instead of a
+// generic "configResolver missing".
+export function requireConfigResolver(ctx: HandlerContext, handlerName: string): ConfigResolver {
+  if (!ctx.configResolver) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.configResolver missing — pass createConfigAccessorFactory's ` +
+        `output via extraContext._configAccessorFactory and the resolver via ` +
+        `extraContext.configResolver at boot.`,
+    });
+  }
+  return ctx.configResolver;
+}
+
+// Mirror of requireConfigResolver for the encryption round-trip side.
+// Only keys declared `encrypted: true` need this — the setter calls it
+// lazily so apps that never wire encryption still boot (and only crash
+// if a handler tries to write an encrypted key without the provider in
+// place, pointing at the exact wiring gap).
+export function requireConfigEncryption(
+  ctx: HandlerContext,
+  handlerName: string,
+): EncryptionProvider {
+  if (!ctx.configEncryption) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.configEncryption missing — at least one config key declares ` +
+        `encrypted: true, so the boot wiring must pass an EncryptionProvider via ` +
+        `extraContext.configEncryption (same instance the resolver was built with).`,
+    });
+  }
+  return ctx.configEncryption;
+}

package/src/config/handlers/__tests__/prepare-config-write.test.ts

@@ -0,0 +1,209 @@
+import {
+  access,
+  type ConfigKeyDefinition,
+  ConfigScopes,
+  createSystemConfig,
+  createTenantConfig,
+  createUserConfig,
+  type Registry,
+  type SessionUser,
+  SYSTEM_ROLE,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { describe, expect, test } from "vitest";
+import { prepareConfigWrite, validateBounds } from "../../write-helpers";
+
+// Minimal Registry stub — only getConfigKey is exercised by prepareConfigWrite.
+function registryStub(keys: Record<string, unknown>): Registry {
+  return {
+    getConfigKey: (name: string) => keys[name] as never,
+    // biome-ignore lint/suspicious/noExplicitAny: the other Registry methods aren't touched by prepareConfigWrite — cast documents the intent.
+  } as any;
+}
+
+// Minimal user shape — prepareConfigWrite reads roles / tenantId / id.
+function userStub(
+  roles: readonly string[],
+  tenantId = "tenant-1" as TenantId,
+  id = "user-1",
+): SessionUser {
+  return { id, tenantId, roles } as SessionUser;
+}
+
+// Built via the public factory (same path a feature-dev takes in r.config).
+// Kept const so a test that asserts `result.keyDef === TENANT_KEY_DEF`
+// actually compares to the stable reference.
+const TENANT_KEY_DEF = createTenantConfig("text", { write: access.roles("Admin") });
+
+describe("prepareConfigWrite", () => {
+  test("returns NotFound failure when the key is not registered", () => {
+    const result = prepareConfigWrite({
+      registry: registryStub({}),
+      user: userStub(["Admin"]),
+      key: "unknown:key",
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.failure.isSuccess).toBe(false);
+    expect(result.failure.error.code).toBe("not_found");
+    expect(result.failure.error.i18nKey).toBe("config.errors.unknownKey");
+  });
+
+  test("returns AccessDenied when the user's roles do not include the key's write roles", () => {
+    const result = prepareConfigWrite({
+      registry: registryStub({ "ns:config:foo": TENANT_KEY_DEF }),
+      user: userStub(["ReadOnly"]),
+      key: "ns:config:foo",
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.failure.error.code).toBe("access_denied");
+  });
+
+  test("returns AccessDenied (system-only) when the key's write access is SYSTEM_ROLE", () => {
+    const systemKey = createTenantConfig("text", { write: access.system });
+    const result = prepareConfigWrite({
+      registry: registryStub({ "ns:config:secret": systemKey }),
+      user: userStub(["SystemAdmin"]),
+      key: "ns:config:secret",
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.failure.error.i18nKey).toBe("config.errors.systemOnly");
+  });
+
+  test("system-only key is writable by a caller that actually carries SYSTEM_ROLE", () => {
+    // Post-ES escape hatch: out-of-band writes (jobs, seeds, framework-
+    // internal flows) used to bypass checkWriteAccess via resolver.set.
+    // The handler is the only write path now, so SYSTEM_ROLE must flow
+    // through — otherwise billing/quota/session-cleanup jobs can't touch
+    // system-only config anymore. Non-system roles stay blocked by the
+    // test above.
+    const systemKey = createTenantConfig("text", { write: access.system });
+    const result = prepareConfigWrite({
+      registry: registryStub({ "ns:config:secret": systemKey }),
+      user: userStub([SYSTEM_ROLE]),
+      key: "ns:config:secret",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    expect(result.keyDef).toBe(systemKey);
+  });
+
+  test("system-only key stays blocked for Admin even when they also carry other roles", () => {
+    // Regression guard: don't let "Admin + Billing" accidentally pass the
+    // system-only gate because role aggregation loosens the check.
+    const systemKey = createTenantConfig("text", { write: access.system });
+    const result = prepareConfigWrite({
+      registry: registryStub({ "ns:config:secret": systemKey }),
+      user: userStub(["Admin", "Billing"]),
+      key: "ns:config:secret",
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.failure.error.i18nKey).toBe("config.errors.systemOnly");
+  });
+
+  test("ok-path falls back to the key's declared scope when no scope is passed", () => {
+    const result = prepareConfigWrite({
+      registry: registryStub({ "ns:config:foo": TENANT_KEY_DEF }),
+      user: userStub(["Admin"]),
+      key: "ns:config:foo",
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    expect(result.scope).toBe(ConfigScopes.tenant);
+    expect(result.tenantId).toBe("tenant-1");
+    expect(result.userId).toBeNull();
+    expect(result.keyDef).toBe(TENANT_KEY_DEF);
+  });
+
+  test("ok-path: scope=system maps tenantId to SYSTEM_TENANT_ID, userId to null", () => {
+    // Default system-scope write role is "system" (programmatic-only) —
+    // override to admin so a SystemAdmin can actually trigger this path.
+    // System-scope rows carry the SYSTEM_TENANT_ID sentinel on tenant_id
+    // (the projection column is NOT NULL post-ES).
+    const systemKey = createSystemConfig("text", { write: access.admin });
+    const result = prepareConfigWrite({
+      registry: registryStub({ "ns:config:foo": systemKey }),
+      user: userStub(["SystemAdmin"]),
+      key: "ns:config:foo",
+      scope: ConfigScopes.system,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    expect(result.tenantId).toBe(SYSTEM_TENANT_ID);
+    expect(result.userId).toBeNull();
+  });
+
+  test("ok-path: scope=user maps both tenantId and userId from the caller", () => {
+    const userKey = createUserConfig("text");
+    const result = prepareConfigWrite({
+      registry: registryStub({ "ns:config:foo": userKey }),
+      user: userStub(["Admin"], "t-99" as TenantId, "u-99"),
+      key: "ns:config:foo",
+      scope: ConfigScopes.user,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    expect(result.tenantId).toBe("t-99");
+    expect(result.userId).toBe("u-99");
+  });
+});
+
+describe("validateBounds", () => {
+  const numberKey = createTenantConfig("number", {
+    default: 10,
+    bounds: { min: 1, max: 100 },
+  });
+
+  test("returns null for value inside bounds", () => {
+    expect(validateBounds(50, numberKey)).toBeNull();
+    expect(validateBounds(1, numberKey)).toBeNull(); // boundary min
+    expect(validateBounds(100, numberKey)).toBeNull(); // boundary max
+  });
+
+  test("returns out_of_bounds error when value is below min", () => {
+    const err = validateBounds(0, numberKey);
+    expect(err).not.toBeNull();
+    expect(err?.code).toBe("validation_error");
+    const details = err?.details as { fields: Array<{ code: string; params: unknown }> };
+    expect(details.fields[0]?.code).toBe("out_of_bounds");
+    expect(details.fields[0]?.params).toMatchObject({ value: 0, min: 1, max: 100 });
+  });
+
+  test("returns out_of_bounds error when value is above max", () => {
+    const err = validateBounds(101, numberKey);
+    expect(err).not.toBeNull();
+    const details = err?.details as { fields: Array<{ params: unknown }> };
+    expect(details.fields[0]?.params).toMatchObject({ value: 101, min: 1, max: 100 });
+  });
+
+  test("returns null when bounds declared with only min (no max)", () => {
+    // Spread on a factory-produced def is the idiomatic way to tweak a
+    // single field without re-stating the whole declaration.
+    const minOnly: ConfigKeyDefinition = { ...numberKey, bounds: { min: 1 } };
+    expect(validateBounds(9999, minOnly)).toBeNull();
+    expect(validateBounds(0, minOnly)).not.toBeNull();
+  });
+
+  test("returns null when bounds declared with only max (no min)", () => {
+    const maxOnly: ConfigKeyDefinition = { ...numberKey, bounds: { max: 100 } };
+    expect(validateBounds(-9999, maxOnly)).toBeNull();
+    expect(validateBounds(101, maxOnly)).not.toBeNull();
+  });
+
+  test("returns null for keys without bounds declared (unrestricted)", () => {
+    const { bounds: _bounds, ...unrestricted } = numberKey;
+    expect(validateBounds(99999, unrestricted)).toBeNull();
+    expect(validateBounds(-99999, unrestricted)).toBeNull();
+  });
+
+  test("returns null for non-number key types (bounds only applies to number)", () => {
+    const textKey = createTenantConfig("text");
+    // Even if bounds were somehow present on a text key, non-number values
+    // are unreachable here — validateType runs first and rejects them.
+    expect(validateBounds("any", textKey)).toBeNull();
+  });
+});

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

@@ -0,0 +1,45 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { ConfigScopes, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { configValueEntity, configValuesTable } from "../table";
+import { findConfigRow, prepareConfigWrite } from "../write-helpers";
+
+const scopeEnum = z.enum([ConfigScopes.system, ConfigScopes.tenant, ConfigScopes.user]);
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+export const resetWrite = defineWriteHandler({
+  name: "reset",
+  schema: z.object({
+    key: z.string(),
+    scope: scopeEnum.optional(),
+  }),
+  // Per-key access enforcement lives inside the handler via checkWriteAccess.
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+
+    const prep = prepareConfigWrite({
+      registry: ctx.registry,
+      user: event.user,
+      key: event.payload.key,
+      scope: event.payload.scope,
+    });
+    if (!prep.ok) return prep.failure;
+    const { scope, tenantId, userId } = prep;
+
+    const existing = await findConfigRow(db, event.payload.key, tenantId, userId);
+
+    // No-op when there is nothing to reset. Pre-ES this path silently did
+    // nothing too — keep the contract intact so callers can reset
+    // idempotently without a 404 dance.
+    if (existing) {
+      const result = await executor.delete({ id: existing.id }, event.user, db);
+      if (!result.isSuccess) return result;
+    }
+
+    return { isSuccess: true, data: { key: event.payload.key, scope } };
+  },
+});

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

@@ -0,0 +1,22 @@
+import { type ConfigKeyDefinition, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { hasConfigAccess } from "../write-helpers";
+
+export const schemaQuery = defineQueryHandler({
+  name: "schema",
+  schema: z.object({}),
+  // Per-key read access enforced via hasConfigAccess inside the handler.
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const registry = ctx.registry;
+    const allKeys = registry.getAllConfigKeys();
+    const result: Record<string, ConfigKeyDefinition> = {};
+
+    for (const [qualifiedKey, keyDef] of allKeys) {
+      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+      result[qualifiedKey] = keyDef;
+    }
+
+    return result;
+  },
+});

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

@@ -0,0 +1,93 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { ConfigScopes, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { requireConfigEncryption } from "../feature";
+import { configValueEntity, configValuesTable } from "../table";
+import {
+  findConfigRow,
+  prepareConfigWrite,
+  validateBounds,
+  validateScope,
+  validateType,
+} from "../write-helpers";
+
+const scopeEnum = z.enum([ConfigScopes.system, ConfigScopes.tenant, ConfigScopes.user]);
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+export const setWrite = defineWriteHandler({
+  name: "set",
+  schema: z.object({
+    key: z.string(),
+    value: z.union([z.string(), z.number(), z.boolean()]),
+    scope: scopeEnum.optional(),
+  }),
+  // Per-key access enforcement lives inside the handler via checkWriteAccess.
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+
+    const prep = prepareConfigWrite({
+      registry: ctx.registry,
+      user: event.user,
+      key: event.payload.key,
+      scope: event.payload.scope,
+    });
+    if (!prep.ok) return prep.failure;
+    const { keyDef, scope, tenantId, userId } = prep;
+
+    const scopeError = validateScope(scope, keyDef.scope, event.payload.key);
+    if (scopeError) return writeFailure(scopeError);
+
+    const typeError = validateType(event.payload.value, keyDef);
+    if (typeError) return writeFailure(typeError);
+
+    // Bounds enforcement: hard-reject (not silent-clamp). A caller that
+    // sends 9999 for a bounds.max=1000 key should see a 422 and fix their
+    // input — silent clamping would make `get` return a different value
+    // than what was sent, which is a UX trap with no upside.
+    const boundsError = validateBounds(event.payload.value, keyDef);
+    if (boundsError) return writeFailure(boundsError);
+
+    let serialized = JSON.stringify(event.payload.value);
+    if (keyDef.encrypted) {
+      const encryption = requireConfigEncryption(ctx, "config:write:set");
+      serialized = encryption.encrypt(serialized);
+    }
+
+    const existing = await findConfigRow(db, event.payload.key, tenantId, userId);
+
+    if (existing) {
+      const result = await executor.update(
+        {
+          id: existing.id,
+          version: existing.version,
+          changes: { value: serialized },
+        },
+        event.user,
+        db,
+      );
+      if (!result.isSuccess) return result;
+    } else {
+      const result = await executor.create(
+        {
+          key: event.payload.key,
+          value: serialized,
+          tenantId,
+          userId,
+        },
+        event.user,
+        db,
+      );
+      if (!result.isSuccess) return result;
+    }
+
+    return {
+      isSuccess: true,
+      data: { key: event.payload.key, value: event.payload.value, scope },
+    };
+  },
+});

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

@@ -0,0 +1,43 @@
+import { type ConfigScope, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { requireConfigResolver } from "../feature";
+import { deserializeValue } from "../resolver";
+import { hasConfigAccess } from "../write-helpers";
+
+export const valuesQuery = defineQueryHandler({
+  name: "values",
+  schema: z.object({}),
+  // Per-key read access enforced via hasConfigAccess inside the handler.
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const db = ctx.db;
+    const registry = ctx.registry;
+    const resolver = requireConfigResolver(ctx, "config:query:values");
+
+    const allKeys = registry.getAllConfigKeys();
+    const storedValues = await resolver.getAll(query.user.tenantId, query.user.id, db);
+
+    const result: Record<
+      string,
+      { value: string | number | boolean | undefined; scope: ConfigScope }
+    > = {};
+
+    for (const [qualifiedKey, keyDef] of allKeys) {
+      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+
+      const stored = storedValues.get(qualifiedKey);
+      let value: string | number | boolean | undefined;
+      if (keyDef.encrypted) {
+        value = stored ? "••••••" : undefined;
+      } else if (stored?.value !== null && stored?.value !== undefined) {
+        value = deserializeValue(stored.value, keyDef.type);
+      } else {
+        value = keyDef.default;
+      }
+
+      result[qualifiedKey] = { value, scope: keyDef.scope };
+    }
+
+    return result;
+  },
+});

package/src/config/index.ts

@@ -0,0 +1,15 @@
+export {
+  CONFIG_FEATURE,
+  ConfigErrors,
+  ConfigHandlers,
+  ConfigQueries,
+} from "./constants";
+export type { ConfigContext } from "./feature";
+export {
+  createConfigAccessor,
+  createConfigAccessorFactory,
+  createConfigFeature,
+} from "./feature";
+export type { AppConfigOverrides, ConfigResolver } from "./resolver";
+export { createConfigResolver, validateAppOverrides } from "./resolver";
+export { configValuesTable } from "./table";