@cosmicdrift/kumiko-bundled-features 0.160.0 → 0.162.0

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

@@ -275,6 +275,7 @@ describe("LoginScreen", () => {
       { reason: "rate_limited", needle: "Zu viele Login-Versuche" },
       { reason: "invalid_body", needle: "Ungültige Eingabe" },
       { reason: "weird_unknown", needle: "Login fehlgeschlagen" },
+      { reason: "mfa_setup_required", needle: "Zwei-Faktor-Authentifizierung erforderlich" },
     ];
     for (const { reason, needle } of cases) {
       const session = makeSessionApi({
@@ -335,11 +336,14 @@ describe("LoginScreen", () => {
   });
 
   test("mfa-setup-required with and without onMfaSetupRequired", async () => {
-    const onMfaSetupRequired = mock<() => void>();
+    const onMfaSetupRequired = mock<(preauthSetupToken: string, accountLabel: string) => void>();
     const sessionOk = makeSessionApi({
       status: "unauthenticated",
       user: null,
-      login: mock<SessionApi["login"]>(async () => ({ kind: "mfa-setup-required" })),
+      login: mock<SessionApi["login"]>(async () => ({
+        kind: "mfa-setup-required",
+        preauthSetupToken: "setup-token-value",
+      })),
     });
     const { unmount } = renderWithProviders(
       <LoginScreen onMfaSetupRequired={onMfaSetupRequired} />,
@@ -349,21 +353,26 @@ describe("LoginScreen", () => {
     fireEvent.change(screen.getByLabelText(/^Passwort/), { target: { value: "x" } });
     fireEvent.click(screen.getByRole("button", { name: "Einloggen" }));
     await waitFor(() => {
-      expect(onMfaSetupRequired).toHaveBeenCalled();
+      expect(onMfaSetupRequired).toHaveBeenCalledWith("setup-token-value", "a@b.c");
     });
     unmount();
 
     const sessionBare = makeSessionApi({
       status: "unauthenticated",
       user: null,
-      login: mock<SessionApi["login"]>(async () => ({ kind: "mfa-setup-required" })),
+      login: mock<SessionApi["login"]>(async () => ({
+        kind: "mfa-setup-required",
+        preauthSetupToken: "setup-token-value",
+      })),
     });
     renderWithProviders(<LoginScreen />, { session: sessionBare });
     fireEvent.change(screen.getByLabelText(/^E-Mail/), { target: { value: "a@b.c" } });
     fireEvent.change(screen.getByLabelText(/^Passwort/), { target: { value: "x" } });
     fireEvent.click(screen.getByRole("button", { name: "Einloggen" }));
     await waitFor(() => {
-      expect(screen.getByRole("alert").textContent).toContain("Zwei-Faktor-Bestätigung");
+      expect(screen.getByRole("alert").textContent).toContain(
+        "Zwei-Faktor-Authentifizierung erforderlich",
+      );
     });
   });
 

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

@@ -53,7 +53,7 @@ export function csrfHeader(): Record<string, string> {
 export type LoginResult =
   | { readonly kind: "success"; readonly data: LoginResponse }
   | { readonly kind: "mfa-challenge"; readonly challengeToken: string }
-  | { readonly kind: "mfa-setup-required" }
+  | { readonly kind: "mfa-setup-required"; readonly preauthSetupToken: string }
   | { readonly kind: "failure"; readonly error: LoginFailure };
 
 // POST /api/auth/login. Success → token + user; MFA-enrolled user → a
@@ -80,6 +80,7 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
     mfaRequired?: boolean;
     challengeToken?: string;
     mfaSetupRequired?: boolean;
+    preauthSetupToken?: string;
     error?:
       | {
           code?: string;
@@ -92,8 +93,8 @@ 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) {
-      return { kind: "mfa-setup-required" };
+    if (body.mfaSetupRequired === true && typeof body.preauthSetupToken === "string") {
+      return { kind: "mfa-setup-required", preauthSetupToken: body.preauthSetupToken };
     }
     if (body.token !== undefined && body.user !== undefined) {
       return { kind: "success", data: { token: body.token, user: body.user } };

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

@@ -23,10 +23,21 @@ export type MfaVerifyComponentProps = {
   readonly onCancel?: () => void;
 };
 
+// Same coupling reasoning as MfaVerifyComponentProps above — generic, not
+// auth-mfa's MfaSetupPreauthScreenProps directly. Apps wire auth-mfa's
+// MfaSetupPreauthScreen in here via EmailPasswordClientOptions.
+export type MfaSetupComponentProps = {
+  readonly preauthSetupToken: string;
+  readonly accountLabel: string;
+  readonly onSuccess?: () => void;
+  readonly onCancel?: () => void;
+};
+
 export type LoginRouteOptions = {
   readonly loginScreen?: ComponentType<LoginScreenProps>;
   readonly loginScreenProps?: LoginScreenProps;
   readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
+  readonly mfaSetupScreen?: ComponentType<MfaSetupComponentProps>;
   /** 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
@@ -51,14 +62,19 @@ export function createLoginRoute(
 ): ComponentType<Record<string, never>> {
   const LoginComponent = opts.loginScreen ?? LoginScreen;
   const MfaVerifyComponent = opts.mfaVerifyScreen;
+  const MfaSetupComponent = opts.mfaSetupScreen;
 
   function LoginRoute(): ReactNode {
-    const { status } = useSession();
+    const { status, refresh } = useSession();
     const { onAuthenticated } = opts;
     // 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);
+    const [setupRequest, setSetupRequest] = useState<{
+      readonly preauthSetupToken: string;
+      readonly accountLabel: string;
+    } | null>(null);
 
     useEffect(() => {
       if (status === "authenticated") onAuthenticated?.();
@@ -85,12 +101,35 @@ export function createLoginRoute(
         />
       );
     }
+    // Pending preauthSetupToken from LoginScreen's onMfaSetupRequired. Same
+    // reasoning as challengeToken — a UI-only transition, not session state.
+    if (setupRequest !== null && MfaSetupComponent) {
+      return (
+        <MfaSetupComponent
+          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();
+          }}
+          onCancel={() => setSetupRequest(null)}
+        />
+      );
+    }
     return (
       <LoginComponent
         {...opts.loginScreenProps}
         onMfaChallenge={
           MfaVerifyComponent ? setChallengeToken : opts.loginScreenProps?.onMfaChallenge
         }
+        onMfaSetupRequired={
+          MfaSetupComponent
+            ? (preauthSetupToken, accountLabel) =>
+                setSetupRequest({ preauthSetupToken, accountLabel })
+            : opts.loginScreenProps?.onMfaSetupRequired
+        }
       />
     );
   }
@@ -101,11 +140,13 @@ 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,
   });
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
@@ -122,8 +163,9 @@ export function makeSessionAuthGate(
   LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
   loginProps?: LoginScreenProps,
   MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
+  MfaSetupComponent?: ComponentType<MfaSetupComponentProps>,
 ): ComponentType<{ children: ReactNode }> {
-  const AuthGate = makeAuthGate(LoginComponent, loginProps, MfaVerifyComponent);
+  const AuthGate = makeAuthGate(LoginComponent, loginProps, MfaVerifyComponent, MfaSetupComponent);
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
       <SessionProvider>

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

@@ -64,9 +64,13 @@ export type LoginScreenProps = {
    *  hang, but apps mounting auth-mfa must wire this. */
   readonly onMfaChallenge?: (challengeToken: string) => void;
   /** Called when the tenant's enforcement policy requires MFA but this
-   *  user has no factor enrolled yet. Apps typically route to an
-   *  enrollment flow. Same fallback behavior as onMfaChallenge when unset. */
-  readonly onMfaSetupRequired?: () => void;
+   *  user has no factor enrolled yet. Carries the preauthSetupToken the
+   *  login response issued plus the typed email (no session to derive it
+   *  from) — apps typically swap this screen out for auth-mfa's
+   *  MfaSetupPreauthScreen(preauthSetupToken, accountLabel). Without a
+   *  handler, the user sees a "setup required, contact your administrator"
+   *  error. */
+  readonly onMfaSetupRequired?: (preauthSetupToken: string, accountLabel: string) => void;
 };
 
 // Map vom Reason-Code des Login-Handlers auf einen i18n-Key plus
@@ -97,6 +101,8 @@ function reasonToKey(failure: LoginFailure): {
       return { key: "auth.errors.invalidBody" };
     case "mfa_not_supported":
       return { key: "auth.errors.mfaNotSupported" };
+    case "mfa_setup_required":
+      return { key: "auth.errors.mfaSetupRequired" };
     default:
       return { key: "auth.errors.loginFailed" };
   }
@@ -144,10 +150,10 @@ export function LoginScreen({
     }
     if (res.kind === "mfa-setup-required") {
       if (onMfaSetupRequired) {
-        onMfaSetupRequired();
+        onMfaSetupRequired(res.preauthSetupToken, email);
         return;
       }
-      setError({ reason: "mfa_not_supported" });
+      setError({ reason: "mfa_setup_required" });
       setFailedLoginEmail(email);
       return;
     }

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

@@ -4,7 +4,12 @@
 
 import { describe, expect, test } from "bun:test";
 import { authFoundationFeature } from "../feature";
-import { EXT_SESSION_STORE, EXT_TOKEN_VERIFIER } from "../types";
+import {
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+} from "../types";
 
 describe("authFoundationFeature — shape", () => {
   test("has the expected name", () => {
@@ -24,10 +29,18 @@ describe("authFoundationFeature — registers extension-point", () => {
   test("declares the sessionStore extension-point", () => {
     expect(authFoundationFeature.registrarExtensions[EXT_SESSION_STORE]).toBeDefined();
   });
+
+  test("declares the tenantResolver extension-point", () => {
+    expect(authFoundationFeature.registrarExtensions[EXT_TENANT_RESOLVER]).toBeDefined();
+  });
+
+  test("declares the tenantExistence extension-point", () => {
+    expect(authFoundationFeature.registrarExtensions[EXT_TENANT_EXISTENCE]).toBeDefined();
+  });
 });
 
 describe("authFoundationFeature — multiplicity boot-check", () => {
-  test("registers a bootCheck per extension-point (tokenVerifier + sessionStore)", () => {
-    expect(authFoundationFeature.bootChecks.length).toBeGreaterThanOrEqual(2);
+  test("registers a bootCheck per extension-point (token/session/tenant×2)", () => {
+    expect(authFoundationFeature.bootChecks.length).toBeGreaterThanOrEqual(4);
   });
 });

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

@@ -17,6 +17,7 @@ function mockStore(): SessionStore {
     revoker: async () => undefined,
     checker: async () => "live",
     massRevoker: async () => 0,
+    revokeAllOthers: async () => 0,
   };
 }
 

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

@@ -0,0 +1,136 @@
+// resolveTenantResolver / resolveTenantExistence + optional multiplicity (#1373).
+
+import { describe, expect, test } from "bun:test";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createRegistry, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  validateTenantExistenceMultiplicity,
+  validateTenantResolverMultiplicity,
+} from "../boot-checks";
+import { authFoundationFeature, resolveTenantExistence, resolveTenantResolver } from "../feature";
+import { resolveAnonymousAccessFromRegistry } from "../resolve-anonymous-access";
+import {
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  type TenantExistenceProvider,
+  type TenantResolverProvider,
+} from "../types";
+
+const fakeDb = {} as DbConnection;
+
+function resolverProvider(
+  entityName: string,
+  trust: "authoritative" | "fallback-only" = "authoritative",
+): ReturnType<typeof defineFeature> {
+  const plugin: TenantResolverProvider = {
+    trust,
+    build: () => async () => "00000000-0000-4000-8000-000000000001",
+  };
+  return defineFeature(`mock-resolver-${entityName}`, (r) => {
+    r.useExtension(EXT_TENANT_RESOLVER, entityName, plugin);
+  });
+}
+
+function existenceProvider(entityName: string): ReturnType<typeof defineFeature> {
+  const plugin: TenantExistenceProvider = {
+    build: () => async () => true,
+  };
+  return defineFeature(`mock-existence-${entityName}`, (r) => {
+    r.useExtension(EXT_TENANT_EXISTENCE, entityName, plugin);
+  });
+}
+
+describe("resolveTenantResolver — optional single provider", () => {
+  test("no provider → null", async () => {
+    const registry = createRegistry([authFoundationFeature]);
+    expect(await resolveTenantResolver({ db: fakeDb, registry })).toBeNull();
+  });
+
+  test("one provider → resolve + trust", async () => {
+    const registry = createRegistry([authFoundationFeature, resolverProvider("subdomain")]);
+    const resolved = await resolveTenantResolver({ db: fakeDb, registry });
+    expect(resolved?.trust).toBe("authoritative");
+    expect(await resolved?.resolve({})).toBe("00000000-0000-4000-8000-000000000001");
+  });
+});
+
+describe("resolveTenantExistence — optional single provider", () => {
+  test("no provider → null", async () => {
+    const registry = createRegistry([authFoundationFeature]);
+    expect(await resolveTenantExistence({ db: fakeDb, registry })).toBeNull();
+  });
+
+  test("one provider → existence fn", async () => {
+    const registry = createRegistry([authFoundationFeature, existenceProvider("db")]);
+    const exists = await resolveTenantExistence({ db: fakeDb, registry });
+    expect(await exists?.("00000000-0000-4000-8000-000000000001")).toBe(true);
+  });
+});
+
+describe("validateTenantResolverMultiplicity", () => {
+  test("0 providers → no throw", () => {
+    const registry = createRegistry([authFoundationFeature]);
+    expect(() => validateTenantResolverMultiplicity([...registry.features.values()])).not.toThrow();
+  });
+
+  test("1 provider → no throw", () => {
+    const registry = createRegistry([authFoundationFeature, resolverProvider("a")]);
+    expect(() => validateTenantResolverMultiplicity([...registry.features.values()])).not.toThrow();
+  });
+
+  test("≥2 providers → throws", () => {
+    const registry = createRegistry([
+      authFoundationFeature,
+      resolverProvider("a"),
+      resolverProvider("b"),
+    ]);
+    expect(() => validateTenantResolverMultiplicity([...registry.features.values()])).toThrow(
+      /2 tenantResolver providers/,
+    );
+  });
+
+  test("malformed (no trust) → throws", () => {
+    const broken = defineFeature("mock-broken-resolver", (r) => {
+      r.useExtension(EXT_TENANT_RESOLVER, "broken", { build: () => () => null });
+    });
+    const registry = createRegistry([authFoundationFeature, broken]);
+    expect(() => validateTenantResolverMultiplicity([...registry.features.values()])).toThrow(
+      /without a valid TenantResolverProvider/,
+    );
+  });
+});
+
+describe("validateTenantExistenceMultiplicity", () => {
+  test("0 providers → no throw", () => {
+    const registry = createRegistry([authFoundationFeature]);
+    expect(() =>
+      validateTenantExistenceMultiplicity([...registry.features.values()]),
+    ).not.toThrow();
+  });
+
+  test("≥2 providers → throws", () => {
+    const registry = createRegistry([
+      authFoundationFeature,
+      existenceProvider("a"),
+      existenceProvider("b"),
+    ]);
+    expect(() => validateTenantExistenceMultiplicity([...registry.features.values()])).toThrow(
+      /2 tenantExistence providers/,
+    );
+  });
+});
+
+describe("resolveAnonymousAccessFromRegistry — fail-closed trust", () => {
+  test("inline tenantResolver without resolverTrust throws", async () => {
+    const registry = createRegistry([authFoundationFeature]);
+    await expect(
+      resolveAnonymousAccessFromRegistry(
+        {
+          tenantResolver: () => "00000000-0000-4000-8000-000000000001" as TenantId,
+        },
+        { db: fakeDb, registry },
+      ),
+    ).rejects.toThrow(/resolverTrust/);
+  });
+});

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

@@ -13,9 +13,13 @@
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import {
   EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
   EXT_TOKEN_VERIFIER,
   isAuthProviderPlugin,
   isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
   tokenShapeKey,
 } from "./types";
 
@@ -89,3 +93,53 @@ export function validateSessionStoreMultiplicity(features: readonly FeatureDefin
     );
   }
 }
+
+// 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.`,
+    );
+  }
+}
+
+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.`,
+    );
+  }
+}

package/src/auth-foundation/feature.ts

@@ -1,41 +1,52 @@
 // kumiko-feature-version: 1
 //
-// auth-foundation — declares the `tokenVerifier` extension point for Bearer-
-// token verification. Provider-features (auth-provider-jwt, auth-provider-
-// pat, ...) register via `r.useExtension(EXT_TOKEN_VERIFIER, "<name>", plugin)`.
+// auth-foundation — declares auth-middleware extension points:
+//   - tokenVerifier (multi, shape-routed)
+//   - sessionStore (single, required when foundation mounts)
+//   - tenantResolver (single, optional)
+//   - tenantExistence (single, optional)
 //
-// **Scaffold only:** not wired into `api/auth-middleware.ts` yet —
-// personal-access-tokens still uses its own direct `patResolver` callback
-// (kumiko-framework#745). A future issue migrates the middleware onto this
-// extension point; #1368 only lays the groundwork (PAT-Plan-Doc Phase-1-
-// Sub-Step-1).
-//
-// **Pattern precedent:** file-foundation/mail-foundation for the extension-
-// point + plugin-registry shape. Diverges on ROUTING: those pick one active
-// provider per tenant via a config-key; auth-foundation has no tenant yet
-// at verify-time, so providers are tried in shape-match order instead (see
-// types.ts).
+// Provider-features register via `r.useExtension(EXT_*, "<name>", plugin)`.
+// Middleware / runProdApp resolve providers from the registry at boot
+// (tokenVerifier/sessionStore) or request-time (tokenVerifier shape match).
 
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
-import { validateSessionStoreMultiplicity, validateTokenVerifierMultiplicity } from "./boot-checks";
+import {
+  validateSessionStoreMultiplicity,
+  validateTenantExistenceMultiplicity,
+  validateTenantResolverMultiplicity,
+  validateTokenVerifierMultiplicity,
+} from "./boot-checks";
 import {
   type AuthProviderBuildDeps,
   EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
   EXT_TOKEN_VERIFIER,
   isAuthProviderPlugin,
   isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
   type SessionStore,
+  type TenantExistsFn,
+  type TenantResolverFn,
+  type TenantResolverTrust,
   tokenShapeMatches,
 } from "./types";
 
-export { EXT_SESSION_STORE, EXT_TOKEN_VERIFIER } from "./types";
+export {
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+} from "./types";
 
 const FEATURE_NAME = "auth-foundation";
 
 export const authFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
   r.describe(
-    "Declares the `tokenVerifier` (Bearer-token auth) and `sessionStore` extension points. Provider-features register a static `shape` plus a `build()` for tokenVerifier — mount together with at least one auth-provider-* feature (e.g. personal-access-tokens) and call `resolveTokenVerifier(deps, rawToken)` to find the matching one; sessions self-registers as the single sessionStore provider.",
+    "Declares auth-middleware extension points: `tokenVerifier` (Bearer), `sessionStore` (revocable JWT sid), optional `tenantResolver` + `tenantExistence` for anonymous multi-tenant. Provider-features register via r.useExtension; mount auth-foundation with the matching provider features.",
   );
   r.uiHints({
     displayLabel: "Auth Provider Foundation",
@@ -49,19 +60,28 @@ export const authFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
       // resolveTokenVerifier looks it up at request-time.
     },
   });
-
-  // Owns EXT_TOKEN_VERIFIER, so its own mount is the trigger — same
-  // convention as tenant-lifecycle/user-data-rights' self-bootCheck.
   r.bootCheck(({ features }) => validateTokenVerifierMultiplicity(features));
 
   r.extendsRegistrar(EXT_SESSION_STORE, {
     onRegister: () => {
-      // No side-effects at register-time — registry stores the usage,
-      // resolveSessionStore looks it up at request-time.
+      // No side-effects at register-time — resolveSessionStore at boot/request.
     },
   });
-
   r.bootCheck(({ features }) => validateSessionStoreMultiplicity(features));
+
+  r.extendsRegistrar(EXT_TENANT_RESOLVER, {
+    onRegister: () => {
+      // Optional — zero providers is fine (single-tenant / header-cookie).
+    },
+  });
+  r.bootCheck(({ features }) => validateTenantResolverMultiplicity(features));
+
+  r.extendsRegistrar(EXT_TENANT_EXISTENCE, {
+    onRegister: () => {
+      // Optional — zero providers skips the existence check.
+    },
+  });
+  r.bootCheck(({ features }) => validateTenantExistenceMultiplicity(features));
 });
 
 /**
@@ -101,3 +121,37 @@ export async function resolveSessionStore(
   }
   return usage.options.build(deps);
 }
+
+export type ResolvedTenantResolver = {
+  readonly resolve: TenantResolverFn;
+  readonly trust: TenantResolverTrust;
+};
+
+/** Optional tenantResolver — null when no provider registered. */
+export async function resolveTenantResolver(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<ResolvedTenantResolver | null> {
+  const usage = deps.registry.getExtensionUsages(EXT_TENANT_RESOLVER)[0];
+  if (!usage) return null;
+  if (!isTenantResolverProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] tenantResolver provider registered without a valid TenantResolverProvider",
+    );
+  }
+  const resolve = await usage.options.build(deps);
+  return { resolve, trust: usage.options.trust };
+}
+
+/** Optional tenantExistence — null when no provider registered. */
+export async function resolveTenantExistence(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<TenantExistsFn | null> {
+  const usage = deps.registry.getExtensionUsages(EXT_TENANT_EXISTENCE)[0];
+  if (!usage) return null;
+  if (!isTenantExistenceProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] tenantExistence provider registered without a valid TenantExistenceProvider",
+    );
+  }
+  return usage.options.build(deps);
+}

package/src/auth-foundation/index.ts

@@ -2,21 +2,35 @@
 
 export {
   authFoundationFeature,
+  type ResolvedTenantResolver,
   resolveSessionStore,
+  resolveTenantExistence,
+  resolveTenantResolver,
   resolveTokenVerifier,
 } from "./feature";
+export { resolveAnonymousAccessFromRegistry } from "./resolve-anonymous-access";
 export {
   type AuthProviderBuildDeps,
   type AuthProviderPlugin,
   type AuthVerifier,
   EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
   EXT_TOKEN_VERIFIER,
   isAuthProviderPlugin,
   isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
+  isTenantResolverTrust,
   isValidTokenShape,
   type SessionMassRevoker,
   type SessionStore,
   type SessionStoreProvider,
+  type TenantExistenceProvider,
+  type TenantExistsFn,
+  type TenantResolverFn,
+  type TenantResolverProvider,
+  type TenantResolverTrust,
   type TokenShape,
   tokenShapeKey,
   tokenShapeMatches,