@cosmicdrift/kumiko-bundled-features 0.28.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.28.0",
+  "version": "0.31.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>",
@@ -22,6 +22,7 @@
     "./compliance-profiles": "./src/compliance-profiles/index.ts",
     "./config": "./src/config/index.ts",
     "./data-retention": "./src/data-retention/index.ts",
+    "./readiness": "./src/readiness/index.ts",
     "./jobs": "./src/jobs/index.ts",
     "./tier-engine": "./src/tier-engine/index.ts",
     "./cap-counter": "./src/cap-counter/index.ts",

package/src/auth-email-password/web/__tests__/tenant-switcher.test.tsx

@@ -31,6 +31,26 @@ describe("TenantSwitcher", () => {
     // tenantName-Resolver liefert "Tenant tenant-a" als Trigger-Label
     expect(screen.getByText("Tenant tenant-a")).toBeTruthy();
   });
+  test("renders server-provided membership name without tenantName prop", () => {
+    // /auth/tenants liefert name/key mit — der Switcher braucht keinen
+    // App-Resolver mehr. Fallback-Kette: name > key > UUID-Präfix.
+    const session = makeSessionApi({
+      activeTenantId: "00000000-0000-4000-8000-000000000001",
+      tenants: [
+        {
+          tenantId: "00000000-0000-4000-8000-000000000001",
+          roles: ["Admin"],
+          name: "Status",
+          key: "status",
+        },
+        { tenantId: "00000000-0000-4000-8000-000000000002", roles: ["Admin"], key: "demo" },
+      ],
+    });
+    renderWithProviders(<TenantSwitcher />, { session });
+    // Ohne den Fix wären beide Labels das identische UUID-Präfix "00000000".
+    expect(screen.getByText("Status")).toBeTruthy();
+  });
+
   test("opens dropdown showing all memberships with roles", async () => {
     const user = userEvent.setup();
     const session = makeSessionApi({

package/src/auth-email-password/web/auth-client.ts

@@ -14,6 +14,10 @@ import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-
 export type TenantSummary = {
   readonly tenantId: string;
   readonly roles: readonly string[];
+  /** Display-Name aus /auth/tenants — fehlt nur bei App-eigenen
+   *  membership-Queries ohne tenantName-Anreicherung. */
+  readonly name?: string;
+  readonly key?: string;
 };
 
 export type LoginRequest = {

package/src/auth-email-password/web/tenant-switcher.tsx

@@ -57,8 +57,14 @@ export function TenantSwitcher({ tenantName }: TenantSwitcherProps): ReactNode {
     [activeTenantId, switchTenant],
   );
 
-  const nameOf = (tenantId: string): string =>
-    tenantName !== undefined ? tenantName(tenantId) : tenantId.slice(0, 8);
+  // Label-Priorität: App-eigener Resolver (Prop) > Server-geliefertes
+  // name/key aus /auth/tenants > UUID-Präfix. Letzteres ist nur noch der
+  // Notnagel — bei Seed-Tenants (00000000-…) ist es ununterscheidbar.
+  const nameOf = (tenantId: string): string => {
+    if (tenantName !== undefined) return tenantName(tenantId);
+    const membership = tenants.find((m) => m.tenantId === tenantId);
+    return membership?.name ?? membership?.key ?? tenantId.slice(0, 8);
+  };
 
   // Rendering-Gate: kein User → nix; nur ein Tenant → auch nix
   // (Single-Tenant-Apps brauchen keinen Switcher).

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

@@ -196,6 +196,37 @@ const seedFeature = defineFeature("seeddemo", (r) => {
   });
 });
 
+// Readiness-Scenario: required keys — feature is unusable until the tenant
+// sets real values (mirrors mail-transport-smtp / file-provider-s3).
+const transportFeature = defineFeature("transport", (r) => {
+  r.requires("config");
+  return r.config({
+    keys: {
+      smtpHost: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("Admin"),
+        read: access.admin,
+      }),
+      apiUrl: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("Admin"),
+      }),
+      // Stays unset for the whole suite — read-access tests rely on it.
+      webhookUrl: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("Admin"),
+      }),
+      timeout: createTenantConfig("number", {
+        required: true,
+        write: access.roles("Admin"),
+      }),
+    },
+  });
+});
+
 const testEncryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
@@ -212,6 +243,7 @@ beforeAll(async () => {
       integrationFeature,
       probeFeature,
       seedFeature,
+      transportFeature,
     ],
     // Wire `ctx.config()` for real handlers: pass the resolver-bound factory
     // so the dispatcher can mint a per-user accessor inside buildHandlerContext.
@@ -690,6 +722,87 @@ describe("config.schema query handler", () => {
   });
 });
 
+// --- config.readiness query ---
+
+describe("config.readiness query handler", () => {
+  type Missing = { missing: Array<{ key: string; scope: string; type: string }> };
+
+  test("lists required keys without a usable value — and only those", async () => {
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, tenantAdmin);
+
+    const keys = missing.map((m) => m.key);
+    expect(keys).toContain("transport:config:smtp-host");
+    expect(keys).toContain("transport:config:api-url");
+    expect(keys).toContain("transport:config:timeout");
+    // Non-required keys never show up, configured or not.
+    expect(keys).not.toContain("app:config:mail-server");
+    expect(keys).not.toContain("orders:config:max-order-count");
+  });
+
+  test("whitespace-only text value still counts as missing (requireNonEmpty-Parität)", async () => {
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "transport:config:api-url", value: "   " },
+      tenantAdmin,
+    );
+
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, tenantAdmin);
+    expect(missing.map((m) => m.key)).toContain("transport:config:api-url");
+  });
+
+  test("a real value clears the key from the missing list", async () => {
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "transport:config:api-url", value: "https://api.example.com" },
+      tenantAdmin,
+    );
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "transport:config:timeout", value: 30 },
+      tenantAdmin,
+    );
+
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, tenantAdmin);
+    const keys = missing.map((m) => m.key);
+    expect(keys).not.toContain("transport:config:api-url");
+    expect(keys).not.toContain("transport:config:timeout");
+    // Untouched required keys stay missing.
+    expect(keys).toContain("transport:config:smtp-host");
+  });
+
+  test("filters by read access", async () => {
+    const { missing } = await stack.http.queryOk<Missing>(ConfigQueries.readiness, {}, normalUser);
+
+    const keys = missing.map((m) => m.key);
+    // read: all (tenant-scope default) → visible to a plain User
+    expect(keys).toContain("transport:config:webhook-url");
+    // read: admin-only → hidden from a plain User even though unset
+    expect(keys).not.toContain("transport:config:smtp-host");
+  });
+
+  test("readiness is per-tenant: another tenant still sees the keys as missing", async () => {
+    const { missing } = await stack.http.queryOk<Missing>(
+      ConfigQueries.readiness,
+      {},
+      otherTenantAdmin,
+    );
+
+    const keys = missing.map((m) => m.key);
+    expect(keys).toContain("transport:config:api-url");
+    expect(keys).toContain("transport:config:timeout");
+  });
+
+  test("schema query exposes the required flag for UI rendering", async () => {
+    const schema = await stack.http.queryOk<Record<string, { required?: boolean }>>(
+      ConfigQueries.schema,
+      {},
+      tenantAdmin,
+    );
+    expect(schema["transport:config:smtp-host"]?.required).toBe(true);
+    expect(schema["app:config:mail-server"]?.required).toBeUndefined();
+  });
+});
+
 // --- Type validation ---
 
 describe("type validation", () => {

package/src/config/constants.ts

@@ -12,6 +12,7 @@ export const ConfigQueries = {
   cascade: "config:query:cascade",
   values: "config:query:values",
   schema: "config:query:schema",
+  readiness: "config:query:readiness",
 } as const;
 
 // Error codes

package/src/config/feature.ts

@@ -13,6 +13,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { cascadeQuery } from "./handlers/cascade.query";
+import { readinessQuery } from "./handlers/readiness.query";
 import { resetWrite } from "./handlers/reset.write";
 import { schemaQuery } from "./handlers/schema.query";
 import { setWrite } from "./handlers/set.write";
@@ -45,6 +46,7 @@ export function createConfigFeature(): FeatureDefinition {
       cascade: r.queryHandler(cascadeQuery),
       values: r.queryHandler(valuesQuery),
       schema: r.queryHandler(schemaQuery),
+      readiness: r.queryHandler(readinessQuery),
     };
 
     return { handlers, queries };

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

@@ -0,0 +1,96 @@
+import {
+  type ConfigKeyType,
+  type ConfigScope,
+  defineQueryHandler,
+  type HandlerContext,
+  type SessionUser,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { requireConfigResolver } from "../feature";
+import { hasConfigAccess } from "../write-helpers";
+
+export type ReadinessMissingKey = {
+  readonly key: string;
+  readonly scope: ConfigScope;
+  readonly type: ConfigKeyType;
+};
+
+// Mirrors requireNonEmpty in foundation-shared/config-helpers.ts: required
+// text keys ship default "" and count as unset while empty/whitespace.
+function isUnset(value: string | number | boolean | undefined, type: ConfigKeyType): boolean {
+  if (value === undefined) return true;
+  return type === "text" && typeof value === "string" && value.trim().length === 0;
+}
+
+// Whether a required key/secret counts for THIS tenant right now. Keys of
+// provider-features under a selector-declared extension point count only
+// while their provider is the selected one — an SMTP password is no gap
+// for a tenant running the inmemory transport.
+export type RequiredKeyGate = (qualifiedName: string) => boolean;
+
+// Builds the per-tenant gate from r.extensionSelector declarations: resolve
+// each selector through the config cascade, mark every provider-feature
+// registered under that point as counted/uncounted. Features without a
+// selector-gated registration always count.
+export async function buildProviderSelectionGate(
+  ctx: HandlerContext,
+  callerQn: string,
+  user: SessionUser,
+): Promise<RequiredKeyGate> {
+  const resolver = requireConfigResolver(ctx, callerQn);
+  const countsByFeature = new Map<string, boolean>();
+  for (const [extensionName, selectorKey] of ctx.registry.getAllExtensionSelectors()) {
+    const keyDef = ctx.registry.getConfigKey(selectorKey);
+    if (!keyDef) continue; // registry-build already failed this; defensive
+    const value = await resolver.get(selectorKey, keyDef, user.tenantId, user.id, ctx.db);
+    const selected = typeof value === "string" ? value.trim() : "";
+    for (const usage of ctx.registry.getExtensionUsages(extensionName)) {
+      if (usage.featureName === undefined) continue;
+      const owner = toKebab(usage.featureName);
+      const isSelected = usage.entityName === selected;
+      countsByFeature.set(owner, (countsByFeature.get(owner) ?? false) || isSelected);
+    }
+  }
+  return (qualifiedName) => countsByFeature.get(qualifiedName.split(":")[0] ?? "") ?? true;
+}
+
+// Core of config:query:readiness, exported through the config barrel so the
+// readiness rollup-feature reuses the exact same cascade + access filter.
+// Resolved through the same cascade as ctx.config() so readiness can never
+// drift from what the owning feature's build-fn will see. Note:
+// required+encrypted assumes encryption is wired — resolver.get decrypts
+// stored values, same prerequisite as any ctx.config() read of that key.
+export async function collectMissingRequiredConfig(
+  ctx: HandlerContext,
+  callerQn: string,
+  user: SessionUser,
+  gate?: RequiredKeyGate,
+): Promise<ReadinessMissingKey[]> {
+  const resolver = requireConfigResolver(ctx, callerQn);
+  const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user));
+  const missing: ReadinessMissingKey[] = [];
+  for (const [qualifiedKey, keyDef] of ctx.registry.getAllConfigKeys()) {
+    if (keyDef.required !== true) continue;
+    if (!effectiveGate(qualifiedKey)) continue;
+    if (!hasConfigAccess(keyDef.access.read, user.roles)) continue;
+    const value = await resolver.get(qualifiedKey, keyDef, user.tenantId, user.id, ctx.db);
+    if (isUnset(value, keyDef.type)) {
+      missing.push({ key: qualifiedKey, scope: keyDef.scope, type: keyDef.type });
+    }
+  }
+  return missing;
+}
+
+// No boolean "ready" verdict on purpose — config readiness says nothing
+// about secrets. readiness:query:status (readiness feature) rolls both up.
+export const readinessQuery = defineQueryHandler({
+  name: "readiness",
+  schema: z.object({}),
+  // Per-key read access enforced via hasConfigAccess inside the handler.
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const missing = await collectMissingRequiredConfig(ctx, "config:query:readiness", query.user);
+    return { missing };
+  },
+});

package/src/config/index.ts

@@ -15,6 +15,11 @@ export {
   createConfigAccessorFactory,
   createConfigFeature,
 } from "./feature";
+export type { ReadinessMissingKey, RequiredKeyGate } from "./handlers/readiness.query";
+export {
+  buildProviderSelectionGate,
+  collectMissingRequiredConfig,
+} from "./handlers/readiness.query";
 export type { AppConfigOverrides, ConfigResolver } from "./resolver";
 export { createConfigResolver, validateAppOverrides } from "./resolver";
 export { configValuesTable } from "./table";

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

@@ -167,7 +167,7 @@ describe("scenario 1: happy path", () => {
 // --- Scenario 2: validation errors ---
 
 describe("scenario 2: validation errors", () => {
-  test("missing bucket → factory throws with hint instead of cryptic SDK error", async () => {
+  test("missing bucket → 422 unconfigured naming the key, not a cryptic SDK error", async () => {
     const admin = adminFor(502);
 
     await selectS3Provider(admin);
@@ -183,9 +183,13 @@ describe("scenario 2: validation errors", () => {
 
     const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
     expect(JSON.stringify(error)).toMatch(/'bucket' is empty/);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.i18nKey).toBe("errors.unconfigured");
+    expect(error.details).toMatchObject({ feature: "file-provider-s3", key: "bucket" });
   });
 
-  test("missing secret-access-key → factory throws naming the secret", async () => {
+  test("missing secret-access-key → 422 unconfigured naming the secret", async () => {
     const admin = adminFor(503);
 
     await selectS3Provider(admin);
@@ -196,6 +200,12 @@ describe("scenario 2: validation errors", () => {
 
     const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
     expect(JSON.stringify(error)).toMatch(/s3-secret-access-key/);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.details).toMatchObject({
+      feature: "file-provider-s3",
+      key: S3_SECRET_ACCESS_KEY.name,
+    });
   });
 });
 

package/src/file-foundation/feature.ts

@@ -111,6 +111,9 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
       }),
     },
   });
+  // Readiness gating: provider-plugins' required keys/secrets count only
+  // while their plugin is the one this key selects.
+  r.extensionSelector("fileProvider", configKeys.provider);
 
   return { configKeys };
 });

package/src/file-provider-s3/feature.ts

@@ -26,6 +26,7 @@ import { createS3Provider } from "@cosmicdrift/kumiko-bundled-features/files-pro
 import {
   requireDefined,
   requireNonEmpty,
+  requireSecretSet,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
@@ -56,16 +57,21 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
       return `${plaintext.slice(0, 4)}...${plaintext.slice(-4)}`;
     },
     scope: "tenant",
+    // required: true ↔ the missing-secret throw in readSecretAccessKey — keep in sync.
+    required: true,
   });
 
+  // required: true ↔ the requireNonEmpty calls in buildS3Provider — keep in sync.
   const configKeys = r.config({
     keys: {
       bucket: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
       }),
       region: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
@@ -80,6 +86,7 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
         write: access.roles("TenantAdmin", "SystemAdmin"),
       }),
       accessKeyId: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
@@ -161,10 +168,5 @@ async function buildS3Provider(
 async function readSecretAccessKey(ctx: FileProviderContext, tenantId: string): Promise<string> {
   const secrets = requireSecretsContext(ctx, FEATURE_NAME);
   const branded = await secrets.get(tenantId, S3_SECRET_ACCESS_KEY);
-  if (!branded) {
-    throw new Error(
-      `${FEATURE_NAME}: ${S3_SECRET_ACCESS_KEY.name} not set for tenant ${tenantId} — Tenant-Admin must set it via /api/write/secrets:write:set`,
-    );
-  }
-  return branded.reveal();
+  return requireSecretSet(branded, FEATURE_NAME, S3_SECRET_ACCESS_KEY.name).reveal();
 }

package/src/foundation-shared/__tests__/config-helpers.test.ts

@@ -7,6 +7,7 @@
 // unterschieden werden.
 
 import { describe, expect, test } from "bun:test";
+import { InternalError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import { requireDefined, requireNonEmpty } from "../config-helpers";
 
 describe("requireDefined", () => {
@@ -16,6 +17,10 @@ describe("requireDefined", () => {
     );
   });
 
+  test("undefined → wirft InternalError (500): Dev-Bug, kein Tenant-Gap", () => {
+    expect(() => requireDefined(undefined, "ai-foundation", "apiKey")).toThrow(InternalError);
+  });
+
   test("defined Wert → unverändert zurück", () => {
     expect(requireDefined("sk-123", "ai-foundation", "apiKey")).toBe("sk-123");
   });
@@ -48,6 +53,18 @@ describe("requireNonEmpty", () => {
     );
   });
 
+  test("leerer String → wirft UnconfiguredError (422, code unconfigured, typed details)", () => {
+    try {
+      requireNonEmpty("", "file-foundation", "bucket");
+      throw new Error("expected requireNonEmpty to throw");
+    } catch (err) {
+      if (!(err instanceof UnconfiguredError)) throw err;
+      expect(err.code).toBe("unconfigured");
+      expect(err.httpStatus).toBe(422);
+      expect(err.details).toMatchObject({ feature: "file-foundation", key: "bucket" });
+    }
+  });
+
   test("leerer String mit custom uiHint → Hint landet in der Message", () => {
     expect(() =>
       requireNonEmpty("", "ai-foundation", "model", "Choose a model in Settings → AI."),

package/src/foundation-shared/config-helpers.ts

@@ -19,11 +19,16 @@
 //     across foundations live here. Per-foundation transport/provider-
 //     factories stay in their own package.
 
+import { InternalError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+
 /**
  * Narrow `value | undefined` → `value` with a clear message that names
  * which config key resolved to nothing. Use for keys whose `undefined`
  * means a registry misconfiguration (no value + no default).
  *
+ * Throws InternalError (500): `undefined` here is a developer bug, not a
+ * tenant-configuration gap — contrast requireNonEmpty.
+ *
  * Foundation-Pattern: this is the wrap-helper around `await ctx.config(
  * featureFoundationFeature.exports.configKeys.someKey)` — the call-site
  * stays a single line per key.
@@ -34,9 +39,9 @@
  */
 export function requireDefined<T>(value: T | undefined, featureName: string, label: string): T {
   if (value === undefined) {
-    throw new Error(
-      `${featureName}: '${label}' config key resolved to undefined — registry misconfigured (no value + no default)`,
-    );
+    throw new InternalError({
+      message: `${featureName}: '${label}' config key resolved to undefined — registry misconfigured (no value + no default)`,
+    });
   }
   return value;
 }
@@ -54,6 +59,9 @@ export function requireDefined<T>(value: T | undefined, featureName: string, lab
  * Whitespace is trimmed: a whitespace-only value counts as empty, and the
  * returned string has surrounding whitespace removed — so a stray " host "
  * never reaches the SDK as-is.
+ *
+ * Throws UnconfiguredError (422, code "unconfigured") so clients can route
+ * the user to the settings screen instead of a generic 500.
  */
 export function requireNonEmpty(
   value: string | undefined,
@@ -63,9 +71,27 @@ export function requireNonEmpty(
 ): string {
   const trimmed = requireDefined(value, featureName, label).trim();
   if (trimmed.length === 0) {
-    throw new Error(
-      `${featureName}: '${label}' is empty — tenant must configure it before use. ${uiHint}`,
-    );
+    throw new UnconfiguredError({ feature: featureName, key: label, hint: uiHint });
   }
   return trimmed;
 }
+
+/**
+ * Narrow a `ctx.secrets.get()` result → set secret. The secrets-counterpart
+ * to requireNonEmpty: a missing secret is a tenant-configuration gap, not a
+ * crash — same 422 contract, so clients route to the settings screen.
+ *
+ * `key` is the secret's qualified name (`HANDLE.name`) so the error names
+ * exactly what `secrets:write:set` expects.
+ */
+export function requireSecretSet<T>(
+  value: T | undefined,
+  featureName: string,
+  key: string,
+  uiHint = "Set via secrets:write:set or the tenant-admin UI.",
+): T {
+  if (value === undefined) {
+    throw new UnconfiguredError({ feature: featureName, key, hint: uiHint });
+  }
+  return value;
+}

package/src/foundation-shared/index.ts

@@ -1,4 +1,4 @@
 // Public API of foundation-shared — utilities consumed by the per-tenant
 // Foundation packages (ai-foundation, mail-foundation, file-foundation).
 
-export { requireDefined, requireNonEmpty } from "./config-helpers";
+export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers";

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

@@ -188,7 +188,7 @@ describe("scenario 2: validation errors", () => {
     expect(JSON.stringify(error)).toMatch(/'host' is empty/);
   });
 
-  test("missing password secret → factory throws naming the secret", async () => {
+  test("missing password secret → 422 unconfigured naming the secret", async () => {
     const admin = adminFor(403);
 
     await selectSmtpProvider(admin);
@@ -201,6 +201,12 @@ describe("scenario 2: validation errors", () => {
 
     const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
     expect(JSON.stringify(error)).toMatch(/smtp-password/);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.details).toMatchObject({
+      feature: "mail-transport-smtp",
+      key: SMTP_PASSWORD.name,
+    });
   });
 });
 

package/src/mail-foundation/feature.ts

@@ -96,6 +96,9 @@ export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
       }),
     },
   });
+  // Readiness gating: transport-plugins' required keys/secrets count only
+  // while their plugin is the one this key selects.
+  r.extensionSelector("mailTransport", configKeys.provider);
 
   return {
     /** Config-key-handle for the provider-selector. */

package/src/mail-transport-smtp/feature.ts

@@ -32,6 +32,7 @@ import {
 import {
   requireDefined,
   requireNonEmpty,
+  requireSecretSet,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import type { MailTransportPlugin } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
@@ -68,11 +69,15 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
       return `${plaintext.slice(0, 3)}...${plaintext.slice(-2)}`;
     },
     scope: "tenant",
+    // required: true ↔ the missing-secret throw in readPassword — keep in sync.
+    required: true,
   });
 
+  // required: true ↔ the requireNonEmpty calls in buildSmtpTransport — keep in sync.
   const configKeys = r.config({
     keys: {
       host: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
@@ -87,11 +92,13 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
         write: access.roles("TenantAdmin", "SystemAdmin"),
       }),
       from: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
       }),
       authUser: createTenantConfig("text", {
+        required: true,
         default: "",
         write: access.roles("TenantAdmin", "SystemAdmin"),
         read: access.roles("TenantAdmin", "SystemAdmin"),
@@ -176,10 +183,5 @@ async function buildSmtpTransport(ctx: HandlerContext, tenantId: string): Promis
 async function readPassword(ctx: HandlerContext, tenantId: string): Promise<string> {
   const secrets = requireSecretsContext(ctx, FEATURE_NAME);
   const branded = await secrets.get(tenantId, SMTP_PASSWORD);
-  if (!branded) {
-    throw new Error(
-      `${FEATURE_NAME}: ${SMTP_PASSWORD.name} not set for tenant ${tenantId} — Tenant-Admin must set it via /api/write/secrets:write:set`,
-    );
-  }
-  return branded.reveal();
+  return requireSecretSet(branded, FEATURE_NAME, SMTP_PASSWORD.name).reveal();
 }