@cosmicdrift/kumiko-bundled-features 0.150.0 → 0.151.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.150.0",
+  "version": "0.151.1",
   "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>",
@@ -115,11 +115,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.150.0",
-    "@cosmicdrift/kumiko-framework": "0.150.0",
-    "@cosmicdrift/kumiko-headless": "0.150.0",
-    "@cosmicdrift/kumiko-renderer": "0.150.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.150.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.151.1",
+    "@cosmicdrift/kumiko-framework": "0.151.1",
+    "@cosmicdrift/kumiko-headless": "0.151.1",
+    "@cosmicdrift/kumiko-renderer": "0.151.1",
+    "@cosmicdrift/kumiko-renderer-web": "0.151.1",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/auth-email-password/web/auth-gate.tsx

@@ -9,7 +9,7 @@
 // (nur `{ children }`-Prop). Der Sample kann so einen eigenen Login-
 // Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
 
-import { type ComponentType, type ReactNode, useState } from "react";
+import { type ComponentType, type ReactNode, useEffect, useState } from "react";
 import { LoginScreen, type LoginScreenProps } from "./login-screen";
 import { SessionProvider, useSession } from "./session";
 
@@ -23,41 +23,84 @@ export type MfaVerifyComponentProps = {
   readonly onCancel?: () => void;
 };
 
-export function makeAuthGate(
-  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
-  loginProps?: LoginScreenProps,
-  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
-): ComponentType<{ children: ReactNode }> {
-  function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
+export type LoginRouteOptions = {
+  readonly loginScreen?: ComponentType<LoginScreenProps>;
+  readonly loginScreenProps?: LoginScreenProps;
+  readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
+  /** Called once the session becomes authenticated. makeAuthGate ignores
+   *  this (it renders `children` on its own authenticated branch instead);
+   *  standalone routes — no parent gate, e.g. an anonymous apex/marketing
+   *  surface — use it to redirect. */
+  readonly onAuthenticated?: () => void;
+};
+
+// The one sanctioned way to render a login flow that correctly completes
+// an MFA challenge — makeAuthGate below is just this wrapped for the
+// `{ children }` gate shape. Also exported directly for apps that render
+// their own standalone login route outside any gate (createPublicSurface
+// apex pages stack providers, not gates — see auth-mount.tsx recipes).
+// Handing an app raw LoginScreen + telling it to hand-roll the challenge-
+// token swap itself is exactly how kumiko-framework#266's login-time MFA
+// step went missing in a real apex surface; this makes that mistake
+// structurally unavailable — there is no lower-level piece left to misuse.
+export function createLoginRoute(
+  opts: LoginRouteOptions = {},
+): ComponentType<Record<string, never>> {
+  const LoginComponent = opts.loginScreen ?? LoginScreen;
+  const MfaVerifyComponent = opts.mfaVerifyScreen;
+
+  function LoginRoute(): ReactNode {
     const { status } = useSession();
     // Pending challenge-token from LoginScreen's onMfaChallenge. Lives here
     // (not in SessionState) because it's a UI-only transition — the server
     // never considers this session authenticated until verify succeeds.
     const [challengeToken, setChallengeToken] = useState<string | null>(null);
 
+    useEffect(() => {
+      if (status === "authenticated") opts.onAuthenticated?.();
+    }, [status]);
+
     if (status === "loading") {
       return (
         <div className="min-h-screen flex items-center justify-center text-muted-foreground text-sm" />
       );
     }
-    if (status === "unauthenticated") {
-      if (challengeToken !== null && MfaVerifyComponent) {
-        return (
-          <MfaVerifyComponent
-            challengeToken={challengeToken}
-            onSuccess={() => setChallengeToken(null)}
-            onCancel={() => setChallengeToken(null)}
-          />
-        );
-      }
+    if (status === "authenticated") return null;
+    if (challengeToken !== null && MfaVerifyComponent) {
       return (
-        <LoginComponent
-          {...loginProps}
-          onMfaChallenge={MfaVerifyComponent ? setChallengeToken : loginProps?.onMfaChallenge}
+        <MfaVerifyComponent
+          challengeToken={challengeToken}
+          onSuccess={() => setChallengeToken(null)}
+          onCancel={() => setChallengeToken(null)}
         />
       );
     }
-    return <>{children}</>;
+    return (
+      <LoginComponent
+        {...opts.loginScreenProps}
+        onMfaChallenge={
+          MfaVerifyComponent ? setChallengeToken : opts.loginScreenProps?.onMfaChallenge
+        }
+      />
+    );
+  }
+  return LoginRoute;
+}
+
+export function makeAuthGate(
+  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
+  loginProps?: LoginScreenProps,
+  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
+): ComponentType<{ children: ReactNode }> {
+  const LoginRoute = createLoginRoute({
+    loginScreen: LoginComponent,
+    loginScreenProps: loginProps,
+    mfaVerifyScreen: MfaVerifyComponent,
+  });
+  function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
+    const { status } = useSession();
+    if (status === "authenticated") return <>{children}</>;
+    return <LoginRoute />;
   }
   return AuthGate;
 }

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

@@ -27,8 +27,8 @@ export {
 } from "./auth-client";
 export type { AuthCardProps, AuthShellRenderer } from "./auth-form-primitives";
 export { AuthCard, AuthShellProvider, useAuthShell } from "./auth-form-primitives";
-export type { MfaVerifyComponentProps } from "./auth-gate";
-export { makeAuthGate, makeSessionAuthGate } from "./auth-gate";
+export type { LoginRouteOptions, MfaVerifyComponentProps } from "./auth-gate";
+export { createLoginRoute, makeAuthGate, makeSessionAuthGate } from "./auth-gate";
 export type {
   EmailPasswordClientFeature,
   EmailPasswordClientOptions,
@@ -40,8 +40,6 @@ export type { ForgotPasswordScreenProps } from "./forgot-password-screen";
 export { ForgotPasswordScreen } from "./forgot-password-screen";
 export type { InviteAcceptScreenProps } from "./invite-accept-screen";
 export { InviteAcceptScreen } from "./invite-accept-screen";
-export type { LoginScreenProps } from "./login-screen";
-export { LoginScreen } from "./login-screen";
 export type { ResetPasswordScreenProps } from "./reset-password-screen";
 export { ResetPasswordScreen } from "./reset-password-screen";
 export type { SessionApi, SessionState, SessionStatus } from "./session";

package/src/auth-mfa/feature.ts

@@ -84,7 +84,7 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
     // the app boots clean and the first MFA login dies at runtime on an
     // unknown handler instead of failing at mount time.
     r.requires("tenant");
-    r.config({ keys: { required: mfaRequiredConfigKey() } });
+    r.configKey("required", mfaRequiredConfigKey());
 
     // Dormant custom-screen — the client maps MFA_ENABLE_SCREEN_ID to
     // MfaEnableScreen (see personal-access-tokens/feature.ts for the same

package/src/auth-mfa/web/mfa-enable-screen.tsx

@@ -9,6 +9,13 @@
 
 import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
+// qrcode's package.json#browser remap avoids Node-only deps (yargs/pngjs)
+// for bundlers that honor it — Metro doesn't, hence the explicit subpath.
+// @types/qrcode only covers the main "qrcode" entry, not this subpath, and
+// TypeScript can't auto-discover an ambient .d.ts sibling from inside a
+// node_modules package (consuming apps typecheck this raw .tsx source).
+// Apps mounting MfaEnableScreen need their own local ambient shim — see
+// qrcode-browser.d.ts in this directory for the declaration to copy.
 import QRCode from "qrcode/lib/browser";
 import { type ReactNode, useState } from "react";
 // kumiko-lint-ignore cross-feature-import client-only hook, the feature's server barrel has no web/ re-export

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

@@ -131,17 +131,34 @@ const ordersFeature = defineFeature("orders", (r) => {
   });
 });
 
+// r.configKey() shorthand — single-key sibling of r.config({keys}), same
+// wiring end-to-end (registry → resolver → ctx.config). No seeds needed here.
+const configKeyDemoFeature = defineFeature("configkeydemo", (r) => {
+  r.requires("config");
+  const betaEnabled = r.configKey(
+    "betaEnabled",
+    createTenantConfig("boolean", { default: false, write: access.roles("Admin") }),
+  );
+  return { betaEnabled };
+});
+
 // Probe feature: a real writeHandler reads two configs through ctx.config
 // so the dispatcher-wiring path is exercised end-to-end (not just the
 // factory in isolation). Captures the resolved values for the test to assert.
-const probe: { orders: number | undefined; push: boolean | undefined } = {
+const probe: {
+  orders: number | undefined;
+  push: boolean | undefined;
+  betaEnabled: boolean | undefined;
+} = {
   orders: undefined,
   push: undefined,
+  betaEnabled: undefined,
 };
 const probeFeature = defineFeature("probe", (r) => {
   r.requires("config");
   r.requires("orders");
   r.requires("notifications");
+  r.requires("configkeydemo");
 
   r.writeHandler(
     "read-config",
@@ -150,7 +167,11 @@ const probeFeature = defineFeature("probe", (r) => {
       if (!ctx.config) throw new Error("ctx.config not wired — _configAccessorFactory missing");
       probe.orders = await ctx.config(ordersFeature.exports.maxOrderCount);
       probe.push = await ctx.config(notificationsFeature.exports.pushEnabled);
-      return { isSuccess: true, data: { orders: probe.orders, push: probe.push } };
+      probe.betaEnabled = await ctx.config(configKeyDemoFeature.exports.betaEnabled);
+      return {
+        isSuccess: true,
+        data: { orders: probe.orders, push: probe.push, betaEnabled: probe.betaEnabled },
+      };
     },
     { access: { openToAll: true } },
   );
@@ -267,6 +288,7 @@ beforeAll(async () => {
       notificationsFeature,
       ordersFeature,
       integrationFeature,
+      configKeyDemoFeature,
       probeFeature,
       seedFeature,
       transportFeature,
@@ -781,12 +803,38 @@ describe("ctx.config() in handler context", () => {
     // Reset so prior test order doesn't pollute the assertion.
     probe.orders = undefined;
     probe.push = undefined;
+    probe.betaEnabled = undefined;
     await stack.http.writeOk("probe:write:read-config", {}, tenantAdmin);
     // The probe handler ran ctx.config(handle) for both keys — typeof
     // catches the regression where the handle path silently returns the
     // broad union instead of the narrowed primitive.
     expect(typeof probe.orders).toBe("number");
     expect(typeof probe.push).toBe("boolean");
+    // r.configKey()'s handle goes through the exact same ctx.config() path.
+    // (value-level check — true vs. false — is covered by the next test,
+    // which reads via configFn without the narrowing hazard of a plain
+    // `undefined`-initialized probe field.)
+    expect(typeof probe.betaEnabled).toBe("boolean");
+  });
+
+  test("r.configKey() value is settable/readable via ctx.config, same as r.config", async () => {
+    expect(configKeyDemoFeature.exports.betaEnabled.name).toBe("configkeydemo:config:beta-enabled");
+
+    const configFn = createConfigAccessor(
+      stack.registry,
+      resolver,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+    expect(await configFn(configKeyDemoFeature.exports.betaEnabled)).toBe(false);
+
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: "configkeydemo:config:beta-enabled", value: true },
+      tenantAdmin,
+    );
+    expect(await configFn(configKeyDemoFeature.exports.betaEnabled)).toBe(true);
   });
 });
 

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

@@ -21,10 +21,10 @@ describe("fileFoundationFeature — shape", () => {
 
 describe("fileFoundationFeature.exports — typed handles", () => {
   test("exposes only the provider-selector config-key", () => {
-    const keys = fileFoundationFeature.exports.configKeys;
-    expect(keys.provider).toBeDefined();
-    expect((keys as Record<string, unknown>)["bucket"]).toBeUndefined();
-    expect((keys as Record<string, unknown>)["region"]).toBeUndefined();
+    expect(fileFoundationFeature.exports.providerConfigKey).toBeDefined();
+    expect(fileFoundationFeature.exports.providerConfigKey.name).toBe(
+      "file-foundation:config:provider",
+    );
   });
 });
 

package/src/file-foundation/feature.ts

@@ -54,18 +54,17 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
     },
   });
 
-  const configKeys = r.config({
-    keys: {
-      provider: createTenantConfig("text", {
-        default: "",
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-      }),
-    },
-  });
+  const providerConfigKey = r.configKey(
+    "provider",
+    createTenantConfig("text", {
+      default: "",
+      write: access.roles("TenantAdmin", "SystemAdmin"),
+      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+    }),
+  );
   // Readiness gating: provider-plugins' required keys/secrets count only
   // while their plugin is the one this key selects.
-  r.extensionSelector(EXT_FILE_PROVIDER, configKeys.provider);
+  r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
 
-  return { configKeys };
+  return { providerConfigKey };
 });

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

@@ -29,11 +29,10 @@ describe("mailFoundationFeature — shape", () => {
 
 describe("mailFoundationFeature.exports — typed handles", () => {
   test("exposes only the provider-selector config-key", () => {
-    const keys = mailFoundationFeature.exports.configKeys;
-    expect(keys.provider).toBeDefined();
-    // No host/port/from/authUser — those live in the provider-plugin.
-    expect((keys as Record<string, unknown>)["host"]).toBeUndefined();
-    expect((keys as Record<string, unknown>)["port"]).toBeUndefined();
+    expect(mailFoundationFeature.exports.providerConfigKey).toBeDefined();
+    expect(mailFoundationFeature.exports.providerConfigKey.name).toBe(
+      "mail-foundation:config:provider",
+    );
   });
 });
 

package/src/mail-foundation/feature.ts

@@ -130,32 +130,31 @@ export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
     },
   });
 
-  const configKeys = r.config({
-    keys: {
-      // Provider-selector. Default empty so the boot-validator throws
-      // if a tenant tries to send mail without first picking + setting
-      // up a provider — better than a silent fallback.
-      // The actual list of valid values lives in the registered plugins,
-      // not here — Designer-UI can render `getExtensionUsages
-      // ("mailTransport").map(u => u.entityName)` as the option-list.
-      provider: createTenantConfig("text", {
-        default: "",
-        // required: ohne gewählten Provider wirft createTransportForTenant —
-        // readiness meldete vorher ready:true und der erste Mail-Send
-        // lieferte den UnconfiguredError (280/1).
-        required: true,
-        write: access.roles("TenantAdmin", "SystemAdmin"),
-        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-      }),
-    },
-  });
+  // Provider-selector. Default empty so the boot-validator throws if a
+  // tenant tries to send mail without first picking + setting up a
+  // provider — better than a silent fallback. The actual list of valid
+  // values lives in the registered plugins, not here — Designer-UI can
+  // render `getExtensionUsages("mailTransport").map(u => u.entityName)`
+  // as the option-list.
+  const providerConfigKey = r.configKey(
+    "provider",
+    createTenantConfig("text", {
+      default: "",
+      // required: ohne gewählten Provider wirft createTransportForTenant —
+      // readiness meldete vorher ready:true und der erste Mail-Send
+      // lieferte den UnconfiguredError (280/1).
+      required: true,
+      write: access.roles("TenantAdmin", "SystemAdmin"),
+      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+    }),
+  );
   // Readiness gating: transport-plugins' required keys/secrets count only
   // while their plugin is the one this key selects.
-  r.extensionSelector("mailTransport", configKeys.provider);
+  r.extensionSelector("mailTransport", providerConfigKey);
 
   return {
     /** Config-key-handle for the provider-selector. */
-    configKeys,
+    providerConfigKey,
   };
 });
 
@@ -190,7 +189,7 @@ export async function createTransportForTenant(
   }
 
   const provider = requireDefined(
-    await ctxConfig(mailFoundationFeature.exports.configKeys.provider),
+    await ctxConfig(mailFoundationFeature.exports.providerConfigKey),
     FEATURE_NAME,
     "provider",
   ) as string; // @cast-boundary engine-payload

package/src/user-data-rights/feature.ts

@@ -161,14 +161,13 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
     // "single-user" via appOverrides (TENANT_MODEL_CONFIG_KEY) so the forget
     // pipeline may erase the tenant's data as that user's personal data — still
     // gated by a runtime sole-member check in run-forget-cleanup.
-    r.config({
-      keys: {
-        tenantModel: createSystemConfig("select", {
-          default: "multi-user",
-          options: ["single-user", "multi-user"],
-        }),
-      },
-    });
+    r.configKey(
+      "tenantModel",
+      createSystemConfig("select", {
+        default: "multi-user",
+        options: ["single-user", "multi-user"],
+      }),
+    );
 
     // S2.U3 Atom 1b — ExportJob-Lifecycle-Entity.
     r.entity("export-job", exportJobEntity);