@cosmicdrift/kumiko-bundled-features 0.48.1 → 0.51.0

package/src/config/__tests__/backing-secrets.integration.test.ts

@@ -0,0 +1,188 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  access,
+  type ConfigCascade,
+  createSystemConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { createSecretsContext } from "../../secrets/secrets-context";
+import { tenantSecretsTable } from "../../secrets/table";
+import { ConfigHandlers, ConfigQueries } from "../constants";
+import { createConfigAccessorFactory, createConfigFeature } from "../feature";
+import { createConfigResolver } from "../resolver";
+import { configValuesTable } from "../table";
+
+// Proves the generic backing="secrets" dispatch end-to-end over real HTTP:
+// a system-scoped config key with backing:"secrets" stores/reads/clears through
+// the secrets store (envelope-encrypted, system tenant) instead of the
+// config_values projection — while the value is masked in the query handlers
+// yet revealed for the owning feature's internal ctx.config read.
+
+const SYSTEM_TENANT = "00000000-0000-4000-8000-000000000000";
+const API_KEY = "billing:config:api-key";
+const PLAIN_KEY = "billing:config:webhook-path";
+
+const systemAdmin = TestUsers.systemAdmin; // roles ["SystemAdmin"]
+
+const billingFeature = defineFeature("billing", (r) => {
+  r.requires("config");
+  r.config({
+    keys: {
+      // backing:"secrets" — value lives in the secrets store, not config_values.
+      apiKey: createSystemConfig("text", {
+        backing: "secrets",
+        write: access.systemAdmin,
+        read: access.admin,
+      }),
+      // Control: a plain system config key (config_values, no secrets dispatch).
+      webhookPath: createSystemConfig("text", {
+        default: "/hooks",
+        write: access.systemAdmin,
+        read: access.admin,
+      }),
+    },
+  });
+  // Internal-read probe: a handler that reads its own secrets-backed key via
+  // ctx.config — must receive the revealed plaintext, not the mask.
+  r.queryHandler(
+    "peek-api-key",
+    z.object({}),
+    async (_query, ctx) => {
+      if (!ctx.config) throw new Error("ctx.config not wired");
+      return { value: await ctx.config(API_KEY) };
+    },
+    { access: { roles: ["SystemAdmin"] } },
+  );
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const masterKeyProvider = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+
+  stack = await setupTestStack({
+    features: [createConfigFeature(), billingFeature],
+    extraContext: ({ db, registry }) => {
+      const resolver = createConfigResolver();
+      return {
+        configResolver: resolver,
+        _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+        secrets: createSecretsContext({ db, masterKeyProvider }),
+      };
+    },
+  });
+  await unsafePushTables(stack.db, { configValuesTable, tenantSecretsTable });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+type Cascades = Record<string, ConfigCascade>;
+
+describe("config backing=secrets — write dispatch", () => {
+  test("set routes the value into the secrets store, not config_values", async () => {
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: API_KEY, value: "sk-live-abc123", scope: "system" },
+      systemAdmin,
+    );
+
+    const secretRows = await selectMany(stack.db, tenantSecretsTable, {
+      tenantId: SYSTEM_TENANT,
+      key: API_KEY,
+    });
+    expect(secretRows).toHaveLength(1);
+
+    const configRows = await selectMany(stack.db, configValuesTable, { key: API_KEY });
+    expect(configRows).toHaveLength(0);
+  });
+
+  test("the stored secret is an envelope, never the plaintext", async () => {
+    const [row] = await selectMany(stack.db, tenantSecretsTable, {
+      tenantId: SYSTEM_TENANT,
+      key: API_KEY,
+    });
+    // No column of the stored row may carry the plaintext — the secrets
+    // envelope must have encrypted it.
+    expect(JSON.stringify(row)).not.toContain("sk-live-abc123");
+  });
+});
+
+describe("config backing=secrets — read dispatch", () => {
+  test("the owning feature reads the revealed plaintext via ctx.config", async () => {
+    const res = await stack.http.queryOk<{ value: unknown }>(
+      "billing:query:peek-api-key",
+      {},
+      systemAdmin,
+    );
+    // JSON round-trip: set serialized "sk-live-abc123" → resolver reveals +
+    // deserializes back to the original string.
+    expect(res.value).toBe("sk-live-abc123");
+  });
+
+  test("config:query:cascade masks the value AND every level", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [API_KEY] },
+      systemAdmin,
+    );
+    const cascade = res[API_KEY];
+    expect(cascade?.value).toBe("••••••");
+    expect(cascade?.source).toBe("system-row");
+    const systemLevel = cascade?.levels.find((l) => l.source === "system-row");
+    expect(systemLevel?.hasValue).toBe(true);
+    expect(systemLevel?.value).toBe("••••••");
+    expect(JSON.stringify(cascade)).not.toContain("sk-live-abc123");
+  });
+
+  test("config:query:values masks the value", async () => {
+    const res = await stack.http.queryOk<Record<string, { value: unknown; source: string }>>(
+      ConfigQueries.values,
+      {},
+      systemAdmin,
+    );
+    expect(res[API_KEY]?.value).toBe("••••••");
+    expect(res[API_KEY]?.source).toBe("system-row");
+    // The plain control key still resolves transparently.
+    expect(res[PLAIN_KEY]?.value).toBe("/hooks");
+    expect(res[PLAIN_KEY]?.source).toBe("default");
+  });
+});
+
+describe("config backing=secrets — reset dispatch", () => {
+  test("reset clears the secret; the key falls back to unset", async () => {
+    await stack.http.writeOk(ConfigHandlers.reset, { key: API_KEY, scope: "system" }, systemAdmin);
+
+    const secretRows = await selectMany(stack.db, tenantSecretsTable, {
+      tenantId: SYSTEM_TENANT,
+      key: API_KEY,
+    });
+    expect(secretRows).toHaveLength(0);
+
+    const res = await stack.http.queryOk<{ value: unknown }>(
+      "billing:query:peek-api-key",
+      {},
+      systemAdmin,
+    );
+    // No keyDef.default on apiKey → genuinely unset after the secret is gone.
+    expect(res.value).toBeUndefined();
+  });
+});

package/src/config/__tests__/cascade.integration.test.ts

@@ -23,7 +23,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import { ConfigHandlers, ConfigQueries } from "../constants";
 import { createConfigAccessorFactory, createConfigFeature } from "../feature";
-import { type ConfigResolver, createConfigResolver } from "../resolver";
+import { buildEnvConfigOverrides, type ConfigResolver, createConfigResolver } from "../resolver";
 import { configValueEntity, configValuesTable } from "../table";
 
 let stack: TestStack;
@@ -47,6 +47,13 @@ const cascadeFeature = defineFeature("cascade-test", (r) => {
         read: access.all,
         write: access.all,
       }),
+      // User-scope key whose only stored row is a system-row (via seed).
+      // Exercises the user → tenant → SYSTEM_TENANT_ID cascade rung.
+      userInheritKey: createUserConfig("text", {
+        default: "DEFAULT_USER_INHERIT",
+        read: access.all,
+        write: access.all,
+      }),
       systemKey: createSystemConfig("text", {
         default: "DEFAULT_SYSTEM",
         read: access.systemAdmin,
@@ -69,10 +76,20 @@ const cascadeFeature = defineFeature("cascade-test", (r) => {
         read: access.all,
         write: access.all,
       }),
+      // End-to-end seam key: a plain scope factory carrying an `env` binding
+      // so buildEnvConfigOverrides reads it off the real registry under the
+      // qualified name define-feature assigns.
+      envKey: createSystemConfig("text", {
+        env: "CASCADE_ENV_VALUE",
+        default: "DEFAULT_ENV",
+        read: access.all,
+        write: access.all,
+      }),
     },
     seeds: {
       tenantKey: createTenantSeed({ value: "SEED_TENANT" }),
       systemKey: createSystemSeed({ value: "SEED_SYSTEM" }),
+      userInheritKey: createSystemSeed({ value: "SEED_SYSTEM_FOR_USER" }),
     },
   });
 });
@@ -81,10 +98,12 @@ const configFeature = createConfigFeature();
 
 const TENANT_KEY = "cascade-test:config:tenant-key";
 const USER_KEY = "cascade-test:config:user-key";
+const USER_INHERIT_KEY = "cascade-test:config:user-inherit-key";
 const SYSTEM_KEY = "cascade-test:config:system-key";
 const NUMBER_KEY = "cascade-test:config:number-key";
 const BOOLEAN_KEY = "cascade-test:config:boolean-key";
 const COMPUTED_KEY = "cascade-test:config:computed-key";
+const ENV_KEY = "cascade-test:config:env-key";
 
 beforeAll(async () => {
   resolver = createConfigResolver();
@@ -225,6 +244,36 @@ describe("getCascade", () => {
     expect(tenantLevel?.isActive).toBe(false);
   });
 
+  test("user-scope key falls through to system-row when no user/tenant row exists", async () => {
+    // No user-row, no tenant-row for this key — only a seeded system-row.
+    // Before the user-cascade gained a SYSTEM_TENANT_ID rung, this resolved
+    // straight to the static default, skipping the operator-set system value.
+    const keyDef = stack.registry.getConfigKey(USER_INHERIT_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await resolver.getCascade(
+      USER_INHERIT_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    const userLevel = cascade.levels.find((l) => l.source === "user-row");
+    expect(userLevel?.hasValue).toBe(false);
+    const tenantLevel = cascade.levels.find((l) => l.source === "tenant-row");
+    expect(tenantLevel?.hasValue).toBe(false);
+
+    const systemLevel = cascade.levels.find((l) => l.source === "system-row");
+    expect(systemLevel).toBeDefined();
+    expect(systemLevel?.hasValue).toBe(true);
+    expect(systemLevel?.value).toBe("SEED_SYSTEM_FOR_USER");
+    expect(systemLevel?.isActive).toBe(true);
+
+    expect(cascade.value).toBe("SEED_SYSTEM_FOR_USER");
+    expect(cascade.source).toBe("system-row");
+  });
+
   test("system-scope key with system-row + default", async () => {
     const keyDef = stack.registry.getConfigKey(SYSTEM_KEY);
     expect(keyDef).toBeDefined();
@@ -279,6 +328,35 @@ describe("getCascadeBatch", () => {
     );
     expect(cascades.size).toBe(0);
   });
+
+  test("user-scope key resolves its system-row via the batch preload", async () => {
+    // The batch path preloads rows with selectConfigRowsForKeys (no scope
+    // gate) and matches them per (tenantId, userId) in buildCascade. This
+    // pins that a user-scope key's system-row is preloaded AND surfaced —
+    // the single-key path proves the lookup, this proves the preload feeds it.
+    const keyDef = stack.registry.getConfigKey(USER_INHERIT_KEY);
+    expect(keyDef).toBeDefined();
+    const keyDefs = new Map<string, ConfigKeyDefinition<ConfigKeyType>>([
+      [USER_INHERIT_KEY, keyDef!],
+    ]);
+
+    const cascades = await resolver.getCascadeBatch(
+      [USER_INHERIT_KEY],
+      keyDefs,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    const cascade = cascades.get(USER_INHERIT_KEY);
+    expect(cascade).toBeDefined();
+    const systemLevel = cascade?.levels.find((l) => l.source === "system-row");
+    expect(systemLevel?.hasValue).toBe(true);
+    expect(systemLevel?.value).toBe("SEED_SYSTEM_FOR_USER");
+    expect(systemLevel?.isActive).toBe(true);
+    expect(cascade?.value).toBe("SEED_SYSTEM_FOR_USER");
+    expect(cascade?.source).toBe("system-row");
+  });
 });
 
 describe("cascade levels — non-DB sources", () => {
@@ -330,6 +408,38 @@ describe("cascade levels — non-DB sources", () => {
     expect(cascade.value).toBe(true);
     expect(cascade.source).toBe("app-override");
   });
+
+  test("end-to-end: env-declared key bridges through the real registry to the resolver", async () => {
+    // The single flow none of the per-layer tests cover: a key declared via
+    // createSystemConfig({ env }) on the REAL registry → its qualified
+    // name (define-feature-assigned) → buildEnvConfigOverrides emits exactly
+    // that key off getAllConfigKeys → resolver resolves it as app-override.
+    // A mismatch in key-qualification across registry/bridge/resolver would
+    // leave the per-layer stub/registry tests green and only break on the
+    // first real consumer. This pins the seam at a real qualified string.
+    const keyDef = stack.registry.getConfigKey(ENV_KEY);
+    expect(keyDef).toBeDefined();
+    expect(keyDef?.env).toBe("CASCADE_ENV_VALUE");
+
+    const overrides = buildEnvConfigOverrides(stack.registry, {
+      CASCADE_ENV_VALUE: "from-env",
+    });
+    expect(overrides.get(ENV_KEY)).toBe("from-env");
+
+    const envResolver = createConfigResolver({ appOverrides: overrides });
+    const result = await envResolver.getWithSource(
+      ENV_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    // No stored rows for this key → the env-bridged override wins over the
+    // declared default ("DEFAULT_ENV").
+    expect(result.source).toBe("app-override");
+    expect(result.value).toBe("from-env");
+  });
 });
 
 describe("reset cycle regression", () => {

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

@@ -181,6 +181,22 @@ const integrationFeature = defineFeature("integration", (r) => {
 
 const configFeature = createConfigFeature();
 
+// Pattern-validated text key (managed-cms phase 3 core change): set.write runs
+// keyDef.pattern as a hard-reject gate, same posture as bounds. The regex
+// allows empty (clear) | a CSS hex color.
+const patternFeature = defineFeature("patterned", (r) => {
+  r.requires("config");
+  r.config({
+    keys: {
+      hexColor: createTenantConfig("text", {
+        default: "",
+        write: access.roles("Admin"),
+        pattern: { regex: "^$|^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" },
+      }),
+    },
+  });
+});
+
 // Scenario 11: Config seeding — feature with deploy-time defaults
 const seedFeature = defineFeature("seeddemo", (r) => {
   r.requires("config");
@@ -244,6 +260,7 @@ beforeAll(async () => {
       probeFeature,
       seedFeature,
       transportFeature,
+      patternFeature,
     ],
     // Wire `ctx.config()` for real handlers: pass the resolver-bound factory
     // so the dispatcher can mint a per-user accessor inside buildHandlerContext.
@@ -1460,3 +1477,46 @@ describe("scenario 11: config seeding", () => {
     expect(await configFn(SEED_THEME)).toBe("red");
   });
 });
+
+// --- Pattern validation (text keys) ---
+
+describe("pattern validation", () => {
+  const HEX_KEY = "patterned:config:hex-color";
+  const admin = createTestUser({ id: 99, roles: ["Admin"] });
+
+  test("valid value passes the regex", async () => {
+    const res = await stack.http.writeOk<{ value: string }>(
+      "config:write:set",
+      { key: HEX_KEY, value: "#abc123" },
+      admin,
+    );
+    expect(res).toMatchObject({ value: "#abc123" });
+  });
+
+  test("empty value passes (allow-empty branch)", async () => {
+    const res = await stack.http.writeOk<{ value: string }>(
+      "config:write:set",
+      { key: HEX_KEY, value: "" },
+      admin,
+    );
+    expect(res).toMatchObject({ value: "" });
+  });
+
+  test("non-matching value is hard-rejected with invalid_format", async () => {
+    const error = await stack.http.writeErr(
+      "config:write:set",
+      { key: HEX_KEY, value: "tomato" },
+      admin,
+    );
+    expectErrorIncludes(error, "invalid_format");
+  });
+
+  test("style-breakout attempt is rejected (no CSS injection survives)", async () => {
+    const error = await stack.http.writeErr(
+      "config:write:set",
+      { key: HEX_KEY, value: "#fff;}</style><script>" },
+      admin,
+    );
+    expectErrorIncludes(error, "invalid_format");
+  });
+});

package/src/config/__tests__/env-overrides.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type ConfigKeyDefinition,
+  createSystemConfig,
+  createTenantConfig,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { buildEnvConfigOverrides } from "../resolver";
+
+// Registry stub exposing the two methods buildEnvConfigOverrides reads:
+// getAllConfigKeys (iterate declared keys) + getConfigKey (validate).
+function registryStub(keys: Record<string, ConfigKeyDefinition>) {
+  const map: ReadonlyMap<string, ConfigKeyDefinition> = new Map(Object.entries(keys));
+  return {
+    getAllConfigKeys: () => map,
+    getConfigKey: (key: string) => keys[key],
+  };
+}
+
+describe("buildEnvConfigOverrides", () => {
+  test("bridges a set env var into the override map (number, coerced)", () => {
+    const reg = registryStub({
+      "billing:config:timeout": createSystemConfig("number", {
+        env: "BILLING_TIMEOUT",
+      }),
+    });
+    const result = buildEnvConfigOverrides(reg, { BILLING_TIMEOUT: "42" });
+    expect(result.get("billing:config:timeout")).toBe(42);
+    expect(result.size).toBe(1);
+  });
+
+  test("text value passes through verbatim", () => {
+    const reg = registryStub({
+      "app:config:url": createSystemConfig("text", { env: "SERVICE_URL" }),
+    });
+    const result = buildEnvConfigOverrides(reg, { SERVICE_URL: "https://x.test" });
+    expect(result.get("app:config:url")).toBe("https://x.test");
+  });
+
+  test("boolean coercion accepts true/false/1/0 case-insensitively", () => {
+    const reg = registryStub({
+      "a:config:flag": createSystemConfig("boolean", { env: "FLAG" }),
+    });
+    expect(buildEnvConfigOverrides(reg, { FLAG: "true" }).get("a:config:flag")).toBe(true);
+    expect(buildEnvConfigOverrides(reg, { FLAG: "1" }).get("a:config:flag")).toBe(true);
+    expect(buildEnvConfigOverrides(reg, { FLAG: "TRUE" }).get("a:config:flag")).toBe(true);
+    expect(buildEnvConfigOverrides(reg, { FLAG: "false" }).get("a:config:flag")).toBe(false);
+    expect(buildEnvConfigOverrides(reg, { FLAG: "0" }).get("a:config:flag")).toBe(false);
+  });
+
+  test("boolean coercion rejects a non-boolean string (fail-fast at boot)", () => {
+    const reg = registryStub({
+      "a:config:flag": createSystemConfig("boolean", { env: "FLAG" }),
+    });
+    expect(() => buildEnvConfigOverrides(reg, { FLAG: "maybe" })).toThrow(
+      /expects a boolean.*got "maybe"/i,
+    );
+  });
+
+  test("number coercion rejects a non-numeric string", () => {
+    const reg = registryStub({
+      "a:config:n": createSystemConfig("number", { env: "N" }),
+    });
+    expect(() => buildEnvConfigOverrides(reg, { N: "abc" })).toThrow(
+      /expects a number.*got "abc"/i,
+    );
+  });
+
+  test("number coercion trims whitespace", () => {
+    const reg = registryStub({
+      "a:config:n": createSystemConfig("number", { env: "N" }),
+    });
+    expect(buildEnvConfigOverrides(reg, { N: "  5 " }).get("a:config:n")).toBe(5);
+  });
+
+  test("undefined env var → key skipped (falls through to its cascade)", () => {
+    const reg = registryStub({
+      "a:config:x": createSystemConfig("text", { env: "MISSING" }),
+    });
+    const result = buildEnvConfigOverrides(reg, {});
+    expect(result.size).toBe(0);
+  });
+
+  test("empty-string env var → skipped (must not clobber a declared default)", () => {
+    const reg = registryStub({
+      "a:config:x": createSystemConfig("text", { env: "EMPTY" }),
+    });
+    const result = buildEnvConfigOverrides(reg, { EMPTY: "" });
+    expect(result.size).toBe(0);
+  });
+
+  test("keys without an env field are ignored even if a same-named var exists", () => {
+    const reg = registryStub({
+      "a:config:no-env": createSystemConfig("text", {}),
+    });
+    // No env declared → never bridged, regardless of the environment.
+    const result = buildEnvConfigOverrides(reg, {
+      A_CONFIG_NO_ENV: "value",
+      "a:config:no-env": "v",
+    });
+    expect(result.size).toBe(0);
+  });
+
+  test("select value must be one of the declared options", () => {
+    const reg = registryStub({
+      "a:config:theme": createSystemConfig("select", {
+        env: "THEME",
+        options: ["light", "dark"],
+      }),
+    });
+    expect(buildEnvConfigOverrides(reg, { THEME: "dark" }).get("a:config:theme")).toBe("dark");
+    expect(() => buildEnvConfigOverrides(reg, { THEME: "purple" })).toThrow(/not in options/i);
+  });
+
+  test("number env value outside bounds fails (validateAppOverrides gate)", () => {
+    const reg = registryStub({
+      "a:config:n": createSystemConfig("number", {
+        env: "N",
+        bounds: { min: 1, max: 100 },
+      }),
+    });
+    expect(() => buildEnvConfigOverrides(reg, { N: "999" })).toThrow(/above bounds\.max/i);
+  });
+
+  test("bridges only the env-declaring keys out of a mixed registry", () => {
+    const reg = registryStub({
+      "a:config:bridged": createSystemConfig("number", { env: "BRIDGED" }),
+      "a:config:plain": createTenantConfig("text", {}),
+      "a:config:unset": createSystemConfig("text", { env: "UNSET" }),
+    });
+    const result = buildEnvConfigOverrides(reg, { BRIDGED: "7" });
+    expect(result.size).toBe(1);
+    expect(result.get("a:config:bridged")).toBe(7);
+  });
+});