@cosmicdrift/kumiko-bundled-features 0.325.1 → 0.326.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.325.1",
+  "version": "0.326.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -134,12 +134,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.325.1",
-    "@cosmicdrift/kumiko-framework": "0.325.1",
-    "@cosmicdrift/kumiko-headless": "0.325.1",
-    "@cosmicdrift/kumiko-renderer": "0.325.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.325.1",
-    "@cosmicdrift/kumiko-types": "0.325.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.326.0",
+    "@cosmicdrift/kumiko-framework": "0.326.0",
+    "@cosmicdrift/kumiko-headless": "0.326.0",
+    "@cosmicdrift/kumiko-renderer": "0.326.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.326.0",
+    "@cosmicdrift/kumiko-types": "0.326.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -168,8 +168,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.325.1",
-    "@cosmicdrift/kumiko-locale-es": "0.325.1",
+    "@cosmicdrift/kumiko-locale-de": "0.326.0",
+    "@cosmicdrift/kumiko-locale-es": "0.326.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/config/__tests__/selected-extensions-query-name.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { createRegistry, SELECTED_EXTENSIONS_QUERY } from "@cosmicdrift/kumiko-framework/engine";
+import { ConfigQueries } from "../constants";
+import { createConfigFeature } from "../feature";
+
+// The framework's generated settings dashboard points visibleWhen at this QN but
+// cannot import bundled-features; if the handler is renamed the panels would
+// silently never show.
+describe("selected-extensions query-name pin", () => {
+  test("framework's SELECTED_EXTENSIONS_QUERY equals the config feature's constant", () => {
+    expect(SELECTED_EXTENSIONS_QUERY).toBe(ConfigQueries.selectedExtensions);
+  });
+
+  test("the QN is a query handler registered by the config feature", () => {
+    const registry = createRegistry([createConfigFeature()]);
+    expect(registry.getAllQueryHandlers().has(SELECTED_EXTENSIONS_QUERY)).toBe(true);
+  });
+});

package/src/config/__tests__/selected-extensions.integration.test.ts

@@ -0,0 +1,247 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import {
+  access,
+  createTenantConfig,
+  defineFeature,
+  selectablePluginIds,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { ConfigHandlers, ConfigQueries } from "../constants";
+import { createConfigAccessorFactory, createConfigFeature } from "../feature";
+import { createConfigResolver } from "../resolver";
+import { configValuesTable } from "../table";
+
+const SELECTOR_KEY = "probe-transport:config:provider";
+const OPEN_SELECTOR_KEY = "probe-open-transport:config:provider";
+
+const transportFoundation = defineFeature("probe-transport", (r) => {
+  r.requires("config");
+  r.extendsRegistrar("probeTransport", { onRegister: () => undefined });
+  const keys = r.config({
+    keys: {
+      provider: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin"),
+        read: access.roles("TenantAdmin"),
+      }),
+    },
+  });
+  r.extensionSelector("probeTransport", keys.provider);
+});
+
+const openFoundation = defineFeature("probe-open-transport", (r) => {
+  r.requires("config");
+  r.extendsRegistrar("probeOpenTransport", { onRegister: () => undefined });
+  const keys = r.config({
+    keys: {
+      provider: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin"),
+        read: access.all,
+      }),
+    },
+  });
+  r.extensionSelector("probeOpenTransport", keys.provider);
+});
+
+const platformFoundation = defineFeature("probe-platform-transport", (r) => {
+  r.requires("config");
+  r.extendsRegistrar("probePlatformTransport", { onRegister: () => undefined });
+  const keys = r.config({
+    keys: {
+      provider: createTenantConfig("text", {
+        default: "",
+        inheritedToTenant: false,
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+    },
+  });
+  r.extensionSelector("probePlatformTransport", keys.provider);
+});
+
+const platformPlugin = defineFeature("probe-platform-plugin", (r) => {
+  r.useExtension("probePlatformTransport", "platform-smtp");
+});
+
+const pluginX = defineFeature("probe-plugin-x", (r) => {
+  r.useExtension("probeTransport", "x");
+});
+const pluginY = defineFeature("probe-plugin-y", (r) => {
+  r.useExtension("probeTransport", "y");
+});
+const openPlugin = defineFeature("probe-open-plugin", (r) => {
+  r.useExtension("probeOpenTransport", "open");
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const resolver = createConfigResolver({
+    cipher: createTestEnvelopeCipher(randomBytes(32).toString("base64")),
+  });
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      transportFoundation,
+      openFoundation,
+      platformFoundation,
+      platformPlugin,
+      pluginX,
+      pluginY,
+      openPlugin,
+    ],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function tenantAdmin(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin"],
+  });
+}
+
+function plainUser(tenantNumber: number) {
+  return createTestUser({
+    id: 100 + tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["User"],
+  });
+}
+
+describe("config:write:set — extension selector validation", () => {
+  test("registry lists the mounted plugin ids the write is validated against", () => {
+    expect(selectablePluginIds(stack.registry, "probeTransport")).toEqual(["x", "y"]);
+  });
+
+  test("unknown plugin id is rejected with 422 and its i18n key", async () => {
+    const err = await stack.http.writeErr(
+      ConfigHandlers.set,
+      { key: SELECTOR_KEY, value: "nope" },
+      tenantAdmin(701),
+    );
+    expect(err).toMatchObject({
+      httpStatus: 422,
+      code: "unprocessable",
+      i18nKey: "config.errors.unknownExtensionPlugin",
+    });
+  });
+
+  test("mounted plugin id and the empty string are accepted", async () => {
+    const admin = tenantAdmin(702);
+    await stack.http.writeOk(ConfigHandlers.set, { key: SELECTOR_KEY, value: "x" }, admin);
+    await stack.http.writeOk(ConfigHandlers.set, { key: SELECTOR_KEY, value: "" }, admin);
+  });
+});
+
+describe("config:query:config-value:selected-extensions", () => {
+  test("returns the caller's own tenant selection, never another tenant's", async () => {
+    const adminA = tenantAdmin(711);
+    const adminB = tenantAdmin(712);
+    await stack.http.writeOk(ConfigHandlers.set, { key: SELECTOR_KEY, value: "x" }, adminA);
+
+    const seenByA = await stack.http.queryOk<Record<string, string>>(
+      ConfigQueries.selectedExtensions,
+      {},
+      adminA,
+    );
+    const seenByB = await stack.http.queryOk<Record<string, string>>(
+      ConfigQueries.selectedExtensions,
+      {},
+      adminB,
+    );
+    expect(seenByA).toEqual({ probeTransport: "x" });
+    expect(seenByB).toEqual({});
+
+    await stack.http.writeOk(ConfigHandlers.set, { key: SELECTOR_KEY, value: "y" }, adminB);
+    const afterB = await stack.http.queryOk<Record<string, string>>(
+      ConfigQueries.selectedExtensions,
+      {},
+      adminB,
+    );
+    expect(afterB).toEqual({ probeTransport: "y" });
+    expect(
+      await stack.http.queryOk<Record<string, string>>(
+        ConfigQueries.selectedExtensions,
+        {},
+        adminA,
+      ),
+    ).toEqual({
+      probeTransport: "x",
+    });
+  });
+
+  test("omits selectors the caller may not read", async () => {
+    const admin = tenantAdmin(713);
+    await stack.http.writeOk(ConfigHandlers.set, { key: SELECTOR_KEY, value: "x" }, admin);
+    await stack.http.writeOk(ConfigHandlers.set, { key: OPEN_SELECTOR_KEY, value: "open" }, admin);
+
+    const seenByAdmin = await stack.http.queryOk<Record<string, string>>(
+      ConfigQueries.selectedExtensions,
+      {},
+      admin,
+    );
+    expect(seenByAdmin).toEqual({ probeTransport: "x", probeOpenTransport: "open" });
+
+    const seenByUser = await stack.http.queryOk<Record<string, string>>(
+      ConfigQueries.selectedExtensions,
+      {},
+      plainUser(713),
+    );
+    expect(seenByUser).toEqual({ probeOpenTransport: "open" });
+  });
+
+  test("hides an inheritedToTenant:false platform selection from tenant-side callers", async () => {
+    const systemAdmin = createTestUser({
+      id: 715,
+      tenantId: testTenantId(715),
+      roles: ["SystemAdmin"],
+    });
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "probe-platform-transport:config:provider", value: "platform-smtp", scope: "system" },
+      systemAdmin,
+    );
+
+    const seenByTenantAdmin = await stack.http.queryOk<Record<string, string>>(
+      ConfigQueries.selectedExtensions,
+      {},
+      tenantAdmin(715),
+    );
+    expect(seenByTenantAdmin).toEqual({});
+
+    const seenBySystemAdmin = await stack.http.queryOk<Record<string, string>>(
+      ConfigQueries.selectedExtensions,
+      {},
+      systemAdmin,
+    );
+    expect(seenBySystemAdmin["probePlatformTransport"]).toBe("platform-smtp");
+  });
+
+  test("rejects a payload with extra fields such as tenantId", async () => {
+    const err = await stack.http.queryErr(
+      ConfigQueries.selectedExtensions,
+      { tenantId: testTenantId(999) },
+      tenantAdmin(714),
+    );
+    expect(err.httpStatus).toBe(400);
+  });
+});

package/src/config/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.326.0",
+    "type": "breaking",
+    "title": "Extension-selector settings render as one tenant screen",
+    "detail": "BREAKING: an extension-selector key now renders as a select of the mounted plugin ids, and\n`config:write:set` rejects every value except a mounted plugin id or \"\" with 422\n`config.errors.unknownExtensionPlugin`.\n\nThe owner's tenant screen `<owner>-tenant` is now a dashboard; its former configEdit moved\nto `<owner>-tenant-selection`. Plugin features under a masked selector lose their tenant nav\nentry: their `<plugin>-tenant` screen stays as a nav-less embedded panel (a direct deep link\nstill resolves), and their secrets move from the global `secrets` screen into\n`<plugin>-tenant-secrets` panels. A plugin feature registered under more than one selector\nregistration keeps the previous behaviour.\n\nGenerated hub screens need the new key `config.settings.extensionSelectorHint` (shipped in\nthe config and secrets bundles, en/de/es).",
+    "migration": "Links, tests or screenshots that open `<plugin>-tenant` through the nav or expect a configEdit\nat `<owner>-tenant` should open `<owner>-tenant` (now the dashboard) and look for the plugin\npanels there. Tenant rows or scripts that write a selector value naming no mounted plugin must\nwrite a mounted plugin id or \"\" instead. No new translation keys are required from apps."
+  },
   {
     "version": "0.271.0",
     "type": "improvement",

package/src/config/constants.ts

@@ -15,6 +15,7 @@ export const ConfigQueries = {
   values: "config:query:values",
   schema: "config:query:schema",
   readiness: "config:query:readiness",
+  selectedExtensions: "config:query:config-value:selected-extensions",
 } as const;
 
 // Error codes
@@ -25,4 +26,5 @@ export const ConfigErrors = {
   systemScopeWriteDenied: "system_scope_write_denied",
   typeError: "type_error",
   invalidOption: "invalid_option",
+  unknownExtensionPlugin: "unknown_extension_plugin",
 } as const;

package/src/config/feature.ts

@@ -19,6 +19,7 @@ import { readinessQuery } from "./handlers/readiness.query";
 import { reencryptJob } from "./handlers/reencrypt.job";
 import { resetWrite } from "./handlers/reset.write";
 import { schemaQuery } from "./handlers/schema.query";
+import { selectedExtensionsQuery } from "./handlers/selected-extensions.query";
 import { setWrite } from "./handlers/set.write";
 import { valuesQuery } from "./handlers/values.query";
 import { CONFIG_FEATURE_I18N } from "./i18n";
@@ -56,6 +57,7 @@ export function createConfigFeature(): FeatureDefinition {
       values: r.queryHandler(valuesQuery),
       schema: r.queryHandler(schemaQuery),
       readiness: r.queryHandler(readinessQuery),
+      selectedExtensions: r.queryHandler(selectedExtensionsQuery),
     };
 
     // KEK-rotation for encrypted values. Manual trigger — ops runs it once

package/src/config/handlers/selected-extensions.query.ts

@@ -0,0 +1,71 @@
+import {
+  type ConfigKeyDefinition,
+  defineQueryHandler,
+  isEncryptedAtRest,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { requireConfigResolver, requireSystemDb } from "../feature";
+import { redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
+import { hasConfigAccess } from "../write-helpers";
+
+// Flat `{ [extensionName]: selectedPluginId }` so a settings dashboard can show
+// panels per selected provider (visibleWhen field = extension name).
+export const selectedExtensionsQuery = defineQueryHandler({
+  name: "config-value:selected-extensions",
+  description:
+    "Returns, per extension point with a config selector, the plugin id the caller's tenant has selected; use it to show only the settings of the active provider.",
+  schema: z.object({}).strict(),
+  // UI plumbing for panel visibility; config:query:values already gives the agent these values.
+  agent: { expose: false },
+  // Per-key read access enforced via hasConfigAccess inside the handler.
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call selected-extensions; the handler only returns " +
+        "selectors whose config key the caller's roles may read, resolved for the caller's own tenant",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own selector values, hit on every settings page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
+  handler: async (query, ctx) => {
+    const db = requireSystemDb(
+      ctx,
+      "config:query:config-value:selected-extensions",
+      query.user.tenantId,
+    );
+    const resolver = requireConfigResolver(ctx, "config:query:config-value:selected-extensions");
+    const readableSelectors = new Map<string, ConfigKeyDefinition>();
+    const extensionBySelectorKey = new Map<string, string>();
+    for (const [extensionName, selectorKey] of ctx.registry.getAllExtensionSelectors()) {
+      const keyDef = ctx.registry.getConfigKey(selectorKey);
+      if (!keyDef || !hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+      if (isEncryptedAtRest(keyDef)) continue;
+      readableSelectors.set(selectorKey, keyDef);
+      extensionBySelectorKey.set(selectorKey, extensionName);
+    }
+    const cascades = await resolver.getCascadeBatch(
+      [...readableSelectors.keys()],
+      readableSelectors,
+      query.user.tenantId,
+      query.user.id,
+      db,
+      ctx.secrets,
+    );
+    const selected: Record<string, string> = {};
+    for (const [selectorKey, keyDef] of readableSelectors) {
+      const rawCascade = cascades.get(selectorKey);
+      if (!rawCascade) continue;
+      const cascade = shouldRedactInherited(keyDef, query.user.roles)
+        ? redactInheritedCascade(rawCascade)
+        : rawCascade;
+      const pluginId = typeof cascade.value === "string" ? cascade.value.trim() : "";
+      const extensionName = extensionBySelectorKey.get(selectorKey);
+      if (pluginId !== "" && extensionName !== undefined) selected[extensionName] = pluginId;
+    }
+    return selected;
+  },
+});

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

@@ -23,6 +23,7 @@ import {
   prepareConfigWrite,
   resolvePiiSubject,
   validateBounds,
+  validateExtensionPlugin,
   validatePattern,
   validateScope,
   validateType,
@@ -82,6 +83,13 @@ export const setWrite = defineWriteHandler({
     const typeError = validateType(event.payload.value, keyDef);
     if (typeError) return writeFailure(typeError);
 
+    const pluginError = validateExtensionPlugin(
+      ctx.registry,
+      event.payload.key,
+      event.payload.value,
+    );
+    if (pluginError) return writeFailure(pluginError);
+
     // 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

package/src/config/web/i18n.ts

@@ -25,6 +25,9 @@ export const defaultTranslations: TranslationsByLocale = {
     "config.errors.systemOnly": "This value can only be set by the system.",
     "config.errors.invalidScope": "This scope is not allowed for this key.",
     "config.errors.unknownKey": "Unknown configuration key.",
+    "config.errors.unknownExtensionPlugin": "This provider is not available.",
+    "config.settings.extensionSelectorHint":
+      "Save the provider selection to show its settings below.",
     // Required by every generated screen (screenTitleKey, required-surface-keys.ts) —
     // the secrets screen has a fixed id ("secrets"), so the framework ships its
     // title translation directly instead of asking every app to declare it.

package/src/config/write-helpers.ts

@@ -9,10 +9,12 @@ import {
   type ConfigKeyDefinition,
   type ConfigScope,
   ConfigScopes,
+  extensionSelectorTargets,
   type Registry,
   type SessionUser,
   SYSTEM_ROLE,
   SYSTEM_TENANT_ID,
+  selectablePluginIds,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -220,6 +222,23 @@ export function resolvePiiSubject(
   return { kind: "tenant", tenantId };
 }
 
+// An extension-selector key may only name a mounted plugin (or "" to clear) —
+// otherwise the settings screen would show no panel for a typo'd value.
+export function validateExtensionPlugin(
+  registry: Registry,
+  key: string,
+  value: string | number | boolean,
+): KumikoError | null {
+  const extensionName = extensionSelectorTargets(registry).get(key);
+  if (extensionName === undefined || value === "") return null;
+  const allowed = selectablePluginIds(registry, extensionName);
+  if (typeof value === "string" && allowed.includes(value)) return null;
+  return new UnprocessableError(ConfigErrors.unknownExtensionPlugin, {
+    i18nKey: "config.errors.unknownExtensionPlugin",
+    details: { key, value, allowed },
+  });
+}
+
 export function validateType(
   value: string | number | boolean,
   keyDef: ConfigKeyDefinition,

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

@@ -97,6 +97,7 @@ const testProbeFeature = defineFeature("file-test", (r) => {
 let stack: TestStack;
 let db: DbConnection;
 let resolver: ConfigResolver;
+let envOverrides: Map<string, string | number | boolean>;
 let providerRef: MutableMasterKeyProvider;
 
 const testEncryptionKey = randomBytes(32).toString("base64");
@@ -125,13 +126,14 @@ beforeAll(async () => {
     ],
     masterKeyProvider: providerRef,
     extraContext: ({ db, registry }) => {
+      envOverrides = new Map(
+        buildEnvConfigOverrides(registry, { [FILE_STORAGE_PROVIDER_ENV]: ENV_SELECTED_PROVIDER }),
+      );
       // No app-side resolver rebuild: the provider key declares
       // env: FILE_STORAGE_PROVIDER, so the generic ENV bridge selects it.
       resolver = createConfigResolver({
         cipher: encryption,
-        appOverrides: buildEnvConfigOverrides(registry, {
-          [FILE_STORAGE_PROVIDER_ENV]: ENV_SELECTED_PROVIDER,
-        }),
+        appOverrides: envOverrides,
       });
       return {
         configResolver: resolver,
@@ -384,9 +386,19 @@ describe("scenario 5: ENV-bridged provider selection", () => {
     ).toBe(FILE_STORAGE_PROVIDER_BOOT_SENTINEL);
 
     const admin = adminFor(508);
-    await setConfig(admin, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL);
+    // The sentinel names no mounted plugin, so a tenant row can no longer hold it;
+    // it reaches the cascade the way production delivers it, as an app override.
+    const rejected = await stack.http.writeErr(
+      "config:write:set",
+      { key: FILE_PROVIDER_CONFIG_KEY, value: FILE_STORAGE_PROVIDER_BOOT_SENTINEL },
+      admin,
+    );
+    expect(rejected.i18nKey).toBe("config.errors.unknownExtensionPlugin");
+    envOverrides.set(FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL);
 
-    const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
+    const error = await stack.http
+      .writeErr(TEST_HANDLER_QN, {}, admin)
+      .finally(() => envOverrides.set(FILE_PROVIDER_CONFIG_KEY, ENV_SELECTED_PROVIDER));
     // The factory throw surfaces as internal_error; the original message sits
     // in details.causeMessage.
     expect(JSON.stringify(error)).toMatch(