@cosmicdrift/kumiko-bundled-features 0.165.0 → 2.0.0

package/src/auth-email-password/web/__tests__/request-account-unlock-screen.test.tsx

@@ -3,12 +3,16 @@ import { fireEvent, screen, waitFor } from "@testing-library/react";
 import { RequestAccountUnlockScreen } from "../request-account-unlock-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("RequestAccountUnlockScreen", () => {
   test("renders title + email input + submit (de)", () => {
@@ -33,6 +37,8 @@ describe("RequestAccountUnlockScreen", () => {
         "/api/auth/request-account-unlock",
         expect.objectContaining({
           method: "POST",
+          headers: expect.objectContaining({ "Content-Type": "application/json" }),
+          credentials: "same-origin",
           body: JSON.stringify({ email: "user@example.com" }),
         }),
       );
@@ -54,7 +60,7 @@ describe("RequestAccountUnlockScreen", () => {
     );
   });
 
-  test("429 with retryAfterSeconds → accountLockedRetry banner", async () => {
+  test("429 with retryAfterSeconds → requestUnlock.rateLimited banner (#1333)", async () => {
     globalThis.fetch = mock(
       async () =>
         new Response(JSON.stringify({ error: { details: { retryAfterSeconds: 180 } } }), {

package/src/auth-email-password/web/__tests__/reset-password-screen.test.tsx

@@ -3,12 +3,16 @@ import { fireEvent, screen, waitFor } from "@testing-library/react";
 import { ResetPasswordScreen } from "../reset-password-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("ResetPasswordScreen", () => {
   test("ohne Token in URL UND ohne token-Prop → missing-token-Page", () => {

package/src/auth-email-password/web/__tests__/verify-email-screen.test.tsx

@@ -3,12 +3,16 @@ import { screen, waitFor } from "@testing-library/react";
 import { VerifyEmailScreen } from "../verify-email-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("VerifyEmailScreen", () => {
   test("ohne Token → missing-token-Page", () => {

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

@@ -34,8 +34,24 @@ export type LoginResponse = {
   };
 };
 
+// Reason codes the login-handler is known to emit today (login-screen.tsx's
+// reasonToKey maps every one of these to an i18n key). The server can also
+// send a reason this client doesn't know about yet (rolling deploys, a new
+// enforcement policy) — `string & {}` keeps that open while still giving
+// autocomplete/typo-checking on the known set, instead of collapsing both
+// to plain `string` (coding-standards: no magic strings without a union).
+export type KnownLoginFailureReason =
+  | "invalid_credentials"
+  | "no_membership"
+  | "account_locked"
+  | "email_not_verified"
+  | "rate_limited"
+  | "invalid_body"
+  | "mfa_not_supported"
+  | "mfa_setup_required";
+
 export type LoginFailure = {
-  readonly reason: string;
+  readonly reason: KnownLoginFailureReason | (string & {});
   readonly message?: string;
   readonly retryAfterSeconds?: number;
 };
@@ -93,8 +109,14 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
     if (body.mfaRequired === true && typeof body.challengeToken === "string") {
       return { kind: "mfa-challenge", challengeToken: body.challengeToken };
     }
-    if (body.mfaSetupRequired === true && typeof body.preauthSetupToken === "string") {
-      return { kind: "mfa-setup-required", preauthSetupToken: body.preauthSetupToken };
+    if (body.mfaSetupRequired === true) {
+      // Older servers / mounts may set the flag without minting a preauth token —
+      // surface an explicit failure (login-screen maps mfa_setup_required) instead
+      // of falling through to generic login_failed.
+      if (typeof body.preauthSetupToken === "string") {
+        return { kind: "mfa-setup-required", preauthSetupToken: body.preauthSetupToken };
+      }
+      return { kind: "failure", error: { reason: "mfa_setup_required" } };
     }
     if (body.token !== undefined && body.user !== undefined) {
       return { kind: "success", data: { token: body.token, user: body.user } };
@@ -167,10 +189,10 @@ async function parseTokenFailure(res: Response): Promise<AuthTokenFailure> {
   return { reason };
 }
 
-// POST /api/auth/request-password-reset. 200 silent-success: auch wenn
-// die Email nicht existiert, sieht der caller `{ ok: true }` — kein
-// account-enumeration. Server triggert Mail nur intern wenn user
-// gefunden. 429 → typed rate-limit-Failure. 5xx → unknown-error.
+// POST /api/auth/request-password-reset. 200 silent-success: even if the
+// email doesn't exist, the caller sees `{ ok: true }` — no account
+// enumeration. Server only triggers the mail internally when a user is
+// found. 429 → typed rate-limit failure. 5xx → unknown-error.
 export async function requestPasswordReset(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
@@ -204,7 +226,7 @@ export async function resetPassword(
 }
 
 // POST /api/auth/request-email-verification. Same silent-success
-// semantik wie request-password-reset. 429 → rate-limit-Failure.
+// semantics as request-password-reset. 429 → rate-limit failure.
 export async function requestEmailVerification(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
@@ -234,8 +256,8 @@ export async function verifyEmail(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
-// POST /api/auth/request-account-unlock. Same silent-success semantik wie
-// request-password-reset. 429 → rate-limit-Failure.
+// POST /api/auth/request-account-unlock. Same silent-success semantics as
+// request-password-reset. 429 → rate-limit failure.
 export async function requestAccountUnlock(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {

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

@@ -109,10 +109,17 @@ export function createLoginRoute(
           preauthSetupToken={setupRequest.preauthSetupToken}
           accountLabel={setupRequest.accountLabel}
           onSuccess={() => {
-            setSetupRequest(null);
             // MfaSetupPreauthScreen has no session to refresh itself with
             // (it runs pre-auth) — the gate owns the session, so it refreshes.
-            void refresh();
+            // Keep setupRequest until refresh settles: clearing first would
+            // dump the user back on the login form with no retry if refresh
+            // rejects (cookie+JWT already minted server-side).
+            void refresh().then(
+              () => setSetupRequest(null),
+              () => {
+                // leave setupRequest set so the user can cancel/retry
+              },
+            );
           }}
           onCancel={() => setSetupRequest(null)}
         />
@@ -136,18 +143,10 @@ export function createLoginRoute(
   return LoginRoute;
 }
 
-export function makeAuthGate(
-  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
-  loginProps?: LoginScreenProps,
-  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
-  MfaSetupComponent?: ComponentType<MfaSetupComponentProps>,
-): ComponentType<{ children: ReactNode }> {
-  const LoginRoute = createLoginRoute({
-    loginScreen: LoginComponent,
-    loginScreenProps: loginProps,
-    mfaVerifyScreen: MfaVerifyComponent,
-    mfaSetupScreen: MfaSetupComponent,
-  });
+export function makeAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+  children: ReactNode;
+}> {
+  const LoginRoute = createLoginRoute(opts);
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
     if (status === "authenticated") return <>{children}</>;
@@ -159,13 +158,10 @@ export function makeAuthGate(
 // SessionProvider + AuthGate as one gate, so a public gate in front (e.g.
 // /calculator) doesn't mount the session bootstrap — createKumikoApp stacks
 // providers outside all gates, so SessionProvider can't be a provider anymore.
-export function makeSessionAuthGate(
-  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
-  loginProps?: LoginScreenProps,
-  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
-  MfaSetupComponent?: ComponentType<MfaSetupComponentProps>,
-): ComponentType<{ children: ReactNode }> {
-  const AuthGate = makeAuthGate(LoginComponent, loginProps, MfaVerifyComponent, MfaSetupComponent);
+export function makeSessionAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+  children: ReactNode;
+}> {
+  const AuthGate = makeAuthGate(opts);
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
       <SessionProvider>

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

@@ -8,7 +8,11 @@
 import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 import { defaultTranslations, mergeTranslations } from "../i18n";
-import { type MfaVerifyComponentProps, makeSessionAuthGate } from "./auth-gate";
+import {
+  type MfaSetupComponentProps,
+  type MfaVerifyComponentProps,
+  makeSessionAuthGate,
+} from "./auth-gate";
 import type { LoginScreenProps } from "./login-screen";
 
 export type EmailPasswordClientOptions = {
@@ -24,6 +28,10 @@ export type EmailPasswordClientOptions = {
    *  auth-mfa simply don't pass this — LoginScreen's built-in fallback
    *  error covers that case. */
   readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
+  /** auth-mfa's MfaSetupPreauthScreen, wired in from the app the same way
+   *  as mfaVerifyScreen above. Apps not mounting auth-mfa simply don't
+   *  pass this. */
+  readonly mfaSetupScreen?: ComponentType<MfaSetupComponentProps>;
   /** Key-Overrides pro Locale. Wird mit den Default-Bundles (de/en)
    *  aus `translations.ts` gemerged — jeder hier gesetzte Key gewinnt.
    *  Für Branding ("Sign in" → "Login to Acme") oder weitere Sprachen
@@ -49,7 +57,12 @@ export function emailPasswordClient(
     name: "auth-email-password",
     providers: [],
     gates: [
-      makeSessionAuthGate(options.loginScreen, options.loginScreenProps, options.mfaVerifyScreen),
+      makeSessionAuthGate({
+        loginScreen: options.loginScreen,
+        loginScreenProps: options.loginScreenProps,
+        mfaVerifyScreen: options.mfaVerifyScreen,
+        mfaSetupScreen: options.mfaSetupScreen,
+      }),
     ],
     translations,
   };

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

@@ -29,7 +29,11 @@ export {
 } from "./auth-client";
 export type { AuthCardProps, AuthShellRenderer } from "./auth-form-primitives";
 export { AuthCard, AuthShellProvider, useAuthShell } from "./auth-form-primitives";
-export type { LoginRouteOptions, MfaVerifyComponentProps } from "./auth-gate";
+export type {
+  LoginRouteOptions,
+  MfaSetupComponentProps,
+  MfaVerifyComponentProps,
+} from "./auth-gate";
 export { createLoginRoute, makeAuthGate, makeSessionAuthGate } from "./auth-gate";
 export type {
   EmailPasswordClientFeature,

package/src/auth-email-password/web/login-screen.tsx

@@ -11,7 +11,11 @@
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
-import { type LoginFailure, requestEmailVerification } from "./auth-client";
+import {
+  type KnownLoginFailureReason,
+  type LoginFailure,
+  requestEmailVerification,
+} from "./auth-client";
 import { AuthCard } from "./auth-form-primitives";
 import { useSession } from "./session";
 
@@ -144,7 +148,7 @@ export function LoginScreen({
         onMfaChallenge(res.challengeToken);
         return;
       }
-      setError({ reason: "mfa_not_supported" });
+      setError({ reason: "mfa_not_supported" satisfies KnownLoginFailureReason });
       setFailedLoginEmail(email);
       return;
     }
@@ -153,7 +157,7 @@ export function LoginScreen({
         onMfaSetupRequired(res.preauthSetupToken, email);
         return;
       }
-      setError({ reason: "mfa_setup_required" });
+      setError({ reason: "mfa_setup_required" satisfies KnownLoginFailureReason });
       setFailedLoginEmail(email);
       return;
     }

package/src/auth-email-password/web/request-account-unlock-screen.tsx

@@ -50,7 +50,7 @@ export function RequestAccountUnlockScreen({
             : undefined;
         setError(
           minutes !== undefined
-            ? t("auth.errors.accountLockedRetry", { minutes })
+            ? t("auth.requestUnlock.rateLimited", { minutes })
             : t("auth.errors.rateLimited"),
         );
       } else {

package/src/auth-foundation/__tests__/session-store.test.ts

@@ -44,11 +44,9 @@ describe("resolveSessionStore — finds the single registered provider", () => {
 });
 
 describe("validateSessionStoreMultiplicity", () => {
-  test("0 providers registered → throws (fail-fast, nothing to store sessions in)", () => {
+  test("0 providers registered → does not throw (valid: PAT-only / machine-API deployments mount no sessionStore)", () => {
     const registry = createRegistry([authFoundationFeature]);
-    expect(() => validateSessionStoreMultiplicity([...registry.features.values()])).toThrow(
-      /no sessionStore provider registered/,
-    );
+    expect(() => validateSessionStoreMultiplicity([...registry.features.values()])).not.toThrow();
   });
 
   test("exactly 1 provider → no throw", () => {

package/src/auth-foundation/__tests__/tenant-providers.test.ts

@@ -134,3 +134,27 @@ describe("resolveAnonymousAccessFromRegistry — fail-closed trust", () => {
     ).rejects.toThrow(/resolverTrust/);
   });
 });
+
+describe("resolveAnonymousAccessFromRegistry — opt-in only (#1452)", () => {
+  test("a mounted tenantResolver provider alone does not make anonymousAccess defined", async () => {
+    const registry = createRegistry([authFoundationFeature, resolverProvider("subdomain")]);
+    const result = await resolveAnonymousAccessFromRegistry(undefined, { db: fakeDb, registry });
+    expect(result).toBeUndefined();
+  });
+
+  test("a mounted tenantExists provider alone does not make anonymousAccess defined", async () => {
+    const registry = createRegistry([authFoundationFeature, existenceProvider("db")]);
+    const result = await resolveAnonymousAccessFromRegistry(undefined, { db: fakeDb, registry });
+    expect(result).toBeUndefined();
+  });
+
+  test("an app that explicitly opts in still gets providers merged", async () => {
+    const registry = createRegistry([authFoundationFeature, resolverProvider("subdomain")]);
+    const result = await resolveAnonymousAccessFromRegistry(
+      { defaultTenantId: undefined },
+      { db: fakeDb, registry },
+    );
+    expect(result?.tenantResolver).toBeDefined();
+    expect(result?.resolverTrust).toBe("authoritative");
+  });
+});

package/src/auth-foundation/__tests__/token-verifier.test.ts

@@ -8,7 +8,13 @@ import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { createRegistry, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { validateTokenVerifierMultiplicity } from "../boot-checks";
 import { authFoundationFeature, resolveTokenVerifier } from "../feature";
-import { type AuthProviderPlugin, EXT_TOKEN_VERIFIER } from "../types";
+import {
+  type AuthProviderPlugin,
+  EXT_SESSION_STORE,
+  EXT_TOKEN_VERIFIER,
+  type SessionStore,
+  type SessionStoreProvider,
+} from "../types";
 
 // Mock providers never read `deps.db` — a real provider (personal-access-
 // tokens/resolver.ts) does a point-read + live-role-resolution against it.
@@ -38,6 +44,23 @@ function jwtProvider(entityName = "jwt-mock"): ReturnType<typeof defineFeature>
   });
 }
 
+function mockStore(): SessionStore {
+  return {
+    creator: async () => "sid-1",
+    revoker: async () => undefined,
+    checker: async () => "live",
+    massRevoker: async () => 0,
+    revokeAllOthers: async () => 0,
+  };
+}
+
+function storeProvider(entityName = "mock-store"): ReturnType<typeof defineFeature> {
+  const plugin: SessionStoreProvider = { build: () => mockStore() };
+  return defineFeature(`mock-${entityName}`, (r) => {
+    r.useExtension(EXT_SESSION_STORE, entityName, plugin);
+  });
+}
+
 describe("resolveTokenVerifier — middleware finds the matching provider", () => {
   test("routes a prefixed token to the prefix-shape provider", async () => {
     const registry = createRegistry([authFoundationFeature, prefixProvider("pat-mock", "kpat_")]);
@@ -65,13 +88,23 @@ describe("resolveTokenVerifier — middleware finds the matching provider", () =
 });
 
 describe("validateTokenVerifierMultiplicity", () => {
-  test("0 providers registered → throws (fail-fast, no provider to route to)", () => {
+  test("0 tokenVerifier + 0 sessionStore → throws (neither auth path mounted)", () => {
     const registry = createRegistry([authFoundationFeature]);
     expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).toThrow(
-      /no tokenVerifier providers registered/,
+      /no tokenVerifier providers and no sessionStore registered/,
     );
   });
 
+  test("0 tokenVerifier + sessionStore → no throw (session-only / #1570)", () => {
+    const registry = createRegistry([authFoundationFeature, storeProvider()]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).not.toThrow();
+  });
+
+  test("tokenVerifier alone (PAT-only) → no throw", () => {
+    const registry = createRegistry([authFoundationFeature, prefixProvider("pat-mock", "kpat_")]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).not.toThrow();
+  });
+
   test("1 provider per shape → no throw", () => {
     const registry = createRegistry([
       authFoundationFeature,

package/src/auth-foundation/boot-checks.ts

@@ -1,14 +1,16 @@
 // Multiplicity boot-check for auth-foundation's `tokenVerifier` extension
-// point (#1368). Two static-shape conflicts a boot-check CAN catch (a
+// point (#1368, #1570). Two static-shape conflicts a boot-check CAN catch (a
 // runtime shape-match predicate's overlap can't be proven at boot): a
 // malformed plugin registration, and two providers both claiming the same
-// shape (resolveTokenVerifier can't tell them apart). Zero registered
-// providers is ALSO caught here — fail-fast at boot ("you mounted the
-// foundation but forgot a provider") rather than a runtime 401 nobody
-// can attribute, unlike file-foundation/mail-foundation which defer that
-// check to request-time (their provider is picked from tenant config,
-// which doesn't exist at boot; auth-foundation's providers are static
-// per-deployment, so boot is the right time to catch it).
+// shape (resolveTokenVerifier can't tell them apart). Zero tokenVerifier
+// providers is OK when ≥1 sessionStore is mounted (session-only cookie
+// apps never use Bearer routing). Zero of both is caught here — fail-fast
+// at boot ("you mounted the foundation but forgot sessions or a provider")
+// rather than a runtime 401 nobody can attribute, unlike
+// file-foundation/mail-foundation which defer that check to request-time
+// (their provider is picked from tenant config, which doesn't exist at
+// boot; auth-foundation's providers are static per-deployment, so boot is
+// the right time to catch it).
 
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -43,9 +45,18 @@ export function validateTokenVerifierMultiplicity(features: readonly FeatureDefi
   }
 
   if (namesByShape.size === 0) {
+    // Session-only apps (email-password + sessions) never hit tokenVerifier —
+    // cookie JWT auth uses sessionStore alone (#1570 / phronexsis#296).
+    for (const feature of features) {
+      for (const usage of feature.extensionUsages) {
+        // skip: sessionStore present — tokenVerifier optional for cookie-session apps.
+        if (usage.extensionName === EXT_SESSION_STORE) return;
+      }
+    }
     throw new Error(
-      "[auth-foundation] no tokenVerifier providers registered — mount at least one " +
-        "auth-provider-* feature (e.g. auth-provider-jwt) alongside auth-foundation.",
+      "[auth-foundation] no tokenVerifier providers and no sessionStore registered — mount " +
+        "at least one auth-provider-* feature (e.g. auth-provider-jwt / personal-access-tokens) " +
+        "or a sessionStore (e.g. sessions) alongside auth-foundation.",
     );
   }
 
@@ -60,86 +71,80 @@ export function validateTokenVerifierMultiplicity(features: readonly FeatureDefi
   }
 }
 
-// Multiplicity boot-check for the `sessionStore` extension point (#1370).
-// Single-provider, unlike tokenVerifier — no shape to route on, so exactly
-// one registration is required; 0 or ≥2 both fail boot.
-export function validateSessionStoreMultiplicity(features: readonly FeatureDefinition[]): void {
+// Shared by the three single-provider extension points below: collect every
+// registration for `ext`, validating each usage's options against `guard`,
+// then fail boot on ≥2 (resolve*() has no way to route between them). Zero
+// registrations is NOT checked here — it's valid for all three (a
+// machine-API-only auth-foundation with PAT-bearer auth and no browser
+// sessions, single-tenant deployments with no tenantResolver, etc.); the
+// runtime already models "extension point unmounted" as a legal
+// configuration (run-prod-app.ts only wires sessions when
+// EXT_SESSION_STORE has ≥1 usage), and resolve*() throws its own clear
+// error if a caller requests a provider that was never registered.
+function validateSingleProvider(
+  features: readonly FeatureDefinition[],
+  opts: {
+    readonly ext: string;
+    readonly label: string;
+    readonly guard: (options: unknown) => boolean;
+    readonly shapeHint: string;
+  },
+): void {
+  const { ext, label, guard, shapeHint } = opts;
   const names: string[] = [];
 
   for (const feature of features) {
     for (const usage of feature.extensionUsages) {
-      if (usage.extensionName !== EXT_SESSION_STORE) continue;
-      if (!isSessionStoreProvider(usage.options)) {
+      if (usage.extensionName !== ext) continue;
+      if (!guard(usage.options)) {
         throw new Error(
-          `[auth-foundation] sessionStore provider "${usage.entityName}" (feature "${feature.name}") ` +
-            `registered without a valid SessionStoreProvider — options must have a { build } shape.`,
+          `[auth-foundation] ${label} provider "${usage.entityName}" (feature "${feature.name}") ` +
+            `registered without a valid ${shapeHint}.`,
         );
       }
       names.push(usage.entityName);
     }
   }
 
-  if (names.length === 0) {
-    throw new Error(
-      "[auth-foundation] no sessionStore provider registered — mount a feature that " +
-        "registers one via r.useExtension(EXT_SESSION_STORE, ...) alongside auth-foundation.",
-    );
-  }
-
   if (names.length >= 2) {
     throw new Error(
-      `[auth-foundation] ${names.length} sessionStore providers registered (${names.join(", ")}) — ` +
-        `only one sessionStore provider may be mounted at a time.`,
+      `[auth-foundation] ${names.length} ${label} providers registered (${names.join(", ")}) — ` +
+        `only one ${label} provider may be mounted at a time.`,
     );
   }
 }
 
+// Multiplicity boot-check for the `sessionStore` extension point (#1370).
+// Single-provider, unlike tokenVerifier — no shape to route on, so ≥2 fails
+// boot. Zero registrations is a valid configuration (see
+// validateSingleProvider doc) — a pure machine API using auth-foundation for
+// PAT-bearer auth alone can mount it without also pulling in the whole
+// sessions feature.
+export function validateSessionStoreMultiplicity(features: readonly FeatureDefinition[]): void {
+  validateSingleProvider(features, {
+    ext: EXT_SESSION_STORE,
+    label: "sessionStore",
+    guard: isSessionStoreProvider,
+    shapeHint: "SessionStoreProvider — options must have a { build } shape",
+  });
+}
+
 // Optional single-provider (#1373). Zero registrations = OK (single-tenant /
 // header-cookie path). ≥2 or malformed = boot fail.
 export function validateTenantResolverMultiplicity(features: readonly FeatureDefinition[]): void {
-  const names: string[] = [];
-
-  for (const feature of features) {
-    for (const usage of feature.extensionUsages) {
-      if (usage.extensionName !== EXT_TENANT_RESOLVER) continue;
-      if (!isTenantResolverProvider(usage.options)) {
-        throw new Error(
-          `[auth-foundation] tenantResolver provider "${usage.entityName}" (feature "${feature.name}") ` +
-            `registered without a valid TenantResolverProvider — options must have { trust, build }.`,
-        );
-      }
-      names.push(usage.entityName);
-    }
-  }
-
-  if (names.length >= 2) {
-    throw new Error(
-      `[auth-foundation] ${names.length} tenantResolver providers registered (${names.join(", ")}) — ` +
-        `only one tenantResolver provider may be mounted at a time.`,
-    );
-  }
+  validateSingleProvider(features, {
+    ext: EXT_TENANT_RESOLVER,
+    label: "tenantResolver",
+    guard: isTenantResolverProvider,
+    shapeHint: "TenantResolverProvider — options must have { trust, build }",
+  });
 }
 
 export function validateTenantExistenceMultiplicity(features: readonly FeatureDefinition[]): void {
-  const names: string[] = [];
-
-  for (const feature of features) {
-    for (const usage of feature.extensionUsages) {
-      if (usage.extensionName !== EXT_TENANT_EXISTENCE) continue;
-      if (!isTenantExistenceProvider(usage.options)) {
-        throw new Error(
-          `[auth-foundation] tenantExistence provider "${usage.entityName}" (feature "${feature.name}") ` +
-            `registered without a valid TenantExistenceProvider — options must have a { build } shape.`,
-        );
-      }
-      names.push(usage.entityName);
-    }
-  }
-
-  if (names.length >= 2) {
-    throw new Error(
-      `[auth-foundation] ${names.length} tenantExistence providers registered (${names.join(", ")}) — ` +
-        `only one tenantExistence provider may be mounted at a time.`,
-    );
-  }
+  validateSingleProvider(features, {
+    ext: EXT_TENANT_EXISTENCE,
+    label: "tenantExistence",
+    guard: isTenantExistenceProvider,
+    shapeHint: "TenantExistenceProvider — options must have a { build } shape",
+  });
 }

package/src/auth-foundation/resolve-anonymous-access.ts

@@ -6,8 +6,6 @@
 import type {
   AnonymousAccessConfig,
   AnonymousAccessResolved,
-  TenantExists,
-  TenantResolver,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
 import { resolveTenantExistence, resolveTenantResolver } from "./feature";
@@ -22,7 +20,12 @@ export async function resolveAnonymousAccessFromRegistry(
     resolveTenantExistence(deps),
   ]);
 
-  if (!base && !tenantResolver && !tenantExists) return undefined;
+  // Anonymous access is app opt-in only: a mounted routing provider
+  // (EXT_TENANT_RESOLVER/EXT_TENANT_EXISTENCE) alone must never make
+  // anonymousAccess become defined for an app that never set it — that
+  // would upgrade every roles:["anonymous"] handler to reachable without
+  // a JWT the moment such a routing feature is mounted (#1452).
+  if (!base) return undefined;
 
   // Fail-closed (#1374 security): inline tenantResolver without trust is the
   // old ambiguous config — providers always carry trust; test stacks must too.
@@ -45,10 +48,15 @@ export async function resolveAnonymousAccessFromRegistry(
     ...(base ?? {}),
     ...(tenantResolver
       ? {
-          tenantResolver: tenantResolver.resolve as TenantResolver,
+          // No cast: TenantResolverFn's `(c: unknown) => string | null`
+          // and the framework's TenantResolver `(c: Context) => TenantId
+          // | null` are structurally identical (TenantId is a plain
+          // string alias, no brand) — `unknown` is a supertype of
+          // Context, so this is already sound by parameter contravariance.
+          tenantResolver: tenantResolver.resolve,
           resolverTrust: tenantResolver.trust,
         }
       : {}),
-    ...(tenantExists ? { tenantExists: tenantExists as TenantExists } : {}),
+    ...(tenantExists ? { tenantExists } : {}),
   };
 }