@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

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

@@ -10,15 +10,10 @@
 // nicht den ersten valid-call beim Mount und den zweiten als invalid-
 // Banner sehen.
 
-import { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type ReactNode, useEffect, useRef, useState } from "react";
 import { verifyEmail } from "./auth-client";
-import {
-  AuthCard,
-  authButtonClass,
-  authMutedLinkClass,
-  parseUrlToken,
-} from "./auth-form-primitives";
+import { AuthCard, useUrlToken } from "./auth-form-primitives";
 
 export type VerifyEmailScreenProps = {
   readonly title?: string;
@@ -36,7 +31,8 @@ export function VerifyEmailScreen({
   loginHref = "/login",
 }: VerifyEmailScreenProps): ReactNode {
   const t = useTranslation();
-  const [token] = useState(() => tokenProp ?? parseUrlToken());
+  const { Link } = usePrimitives();
+  const token = useUrlToken(tokenProp);
   const [status, setStatus] = useState<Status>(token === "" ? "missing-token" : "verifying");
   const startedRef = useRef(false);
 
@@ -55,9 +51,9 @@ export function VerifyEmailScreen({
       <AuthCard title={title ?? t("auth.verifyEmail.errorTitle")}>
         <div className="p-6 pt-0 flex flex-col gap-4">
           <p className="text-sm text-muted-foreground">{t("auth.verifyEmail.missingToken")}</p>
-          <a href={loginHref} className={authMutedLinkClass}>
+          <Link href={loginHref} variant="muted">
             {t("auth.verifyEmail.goToLogin")}
-          </a>
+          </Link>
         </div>
       </AuthCard>
     );
@@ -80,9 +76,9 @@ export function VerifyEmailScreen({
       <AuthCard title={title ?? t("auth.verifyEmail.successTitle")}>
         <div className="p-6 pt-0 flex flex-col gap-4">
           <p className="text-sm text-muted-foreground">{t("auth.verifyEmail.successBody")}</p>
-          <a href={loginHref} className={authButtonClass}>
+          <Link href={loginHref} variant="button">
             {t("auth.verifyEmail.goToLogin")}
-          </a>
+          </Link>
         </div>
       </AuthCard>
     );
@@ -93,9 +89,9 @@ export function VerifyEmailScreen({
     <AuthCard title={title ?? t("auth.verifyEmail.errorTitle")}>
       <div className="p-6 pt-0 flex flex-col gap-4">
         <p className="text-sm text-muted-foreground">{t("auth.verifyEmail.errorBody")}</p>
-        <a href={loginHref} className={authMutedLinkClass}>
+        <Link href={loginHref} variant="muted">
           {t("auth.verifyEmail.goToLogin")}
-        </a>
+        </Link>
       </div>
     </AuthCard>
   );

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

@@ -0,0 +1,46 @@
+// feature.ts contract tests — pin the public surface of the Plugin-API-
+// shaped auth-foundation. Provider-specific verification logic is tested in
+// each provider-feature's own __tests__.
+
+import { describe, expect, test } from "bun:test";
+import { authFoundationFeature } from "../feature";
+import {
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+} from "../types";
+
+describe("authFoundationFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(authFoundationFeature.name).toBe("auth-foundation");
+  });
+
+  test("has no hard requirements — no config-key, unlike file/mail-foundation", () => {
+    expect(authFoundationFeature.requires).toEqual([]);
+  });
+});
+
+describe("authFoundationFeature — registers extension-point", () => {
+  test("declares the tokenVerifier extension-point", () => {
+    expect(authFoundationFeature.registrarExtensions[EXT_TOKEN_VERIFIER]).toBeDefined();
+  });
+
+  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 (token/session/tenant×2)", () => {
+    expect(authFoundationFeature.bootChecks.length).toBeGreaterThanOrEqual(4);
+  });
+});

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

@@ -0,0 +1,77 @@
+// resolveSessionStore + the sessionStore multiplicity boot-check (#1370).
+// Mock providers registered via r.useExtension(EXT_SESSION_STORE, ...) in
+// throwaway test-features — no real sessions provider exists yet.
+
+import { describe, expect, test } from "bun:test";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { validateSessionStoreMultiplicity } from "../boot-checks";
+import { authFoundationFeature, resolveSessionStore } from "../feature";
+import { EXT_SESSION_STORE, type SessionStore, type SessionStoreProvider } from "../types";
+
+const fakeDb = {} as DbConnection; // @cast-boundary test fixture, unused by mock providers
+
+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("resolveSessionStore — finds the single registered provider", () => {
+  test("returns the built SessionStore", async () => {
+    const registry = createRegistry([authFoundationFeature, storeProvider()]);
+    const store = await resolveSessionStore({ db: fakeDb, registry });
+    expect(await store.checker("sid-1", "u1")).toBe("live");
+  });
+
+  test("no provider registered → throws", async () => {
+    const registry = createRegistry([authFoundationFeature]);
+    await expect(resolveSessionStore({ db: fakeDb, registry })).rejects.toThrow(
+      /no sessionStore provider registered/,
+    );
+  });
+});
+
+describe("validateSessionStoreMultiplicity", () => {
+  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()])).not.toThrow();
+  });
+
+  test("exactly 1 provider → no throw", () => {
+    const registry = createRegistry([authFoundationFeature, storeProvider()]);
+    expect(() => validateSessionStoreMultiplicity([...registry.features.values()])).not.toThrow();
+  });
+
+  test("≥2 providers → throws a conflict error", () => {
+    const registry = createRegistry([
+      authFoundationFeature,
+      storeProvider("store-a"),
+      storeProvider("store-b"),
+    ]);
+    expect(() => validateSessionStoreMultiplicity([...registry.features.values()])).toThrow(
+      /2 sessionStore providers registered/,
+    );
+  });
+
+  test("malformed registration (no build) → throws a malformed-plugin error", () => {
+    const broken = defineFeature("mock-broken", (r) => {
+      r.useExtension(EXT_SESSION_STORE, "broken", {});
+    });
+    const registry = createRegistry([authFoundationFeature, broken]);
+    expect(() => validateSessionStoreMultiplicity([...registry.features.values()])).toThrow(
+      /without a valid SessionStoreProvider/,
+    );
+  });
+});

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

@@ -0,0 +1,160 @@
+// 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/);
+  });
+});
+
+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

@@ -0,0 +1,150 @@
+// resolveTokenVerifier + the tokenVerifier multiplicity boot-check (#1368).
+// Mock providers registered via r.useExtension(EXT_TOKEN_VERIFIER, ...) in
+// throwaway test-features — no real JWT/PAT provider exists yet.
+
+import { describe, expect, test } from "bun:test";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+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_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.
+const fakeDb = {} as DbConnection; // @cast-boundary test fixture, unused by mock providers
+
+function jwtLikeUser(): SessionUser {
+  return { id: "u-jwt", tenantId: "t1", roles: ["User"] } as SessionUser; // @cast-boundary test fixture
+}
+
+function prefixProvider(entityName: string, prefix: string): ReturnType<typeof defineFeature> {
+  const plugin: AuthProviderPlugin = {
+    shape: { kind: "prefix", prefix },
+    build: () => async (rawToken) => (rawToken === `${prefix}valid` ? jwtLikeUser() : null),
+  };
+  return defineFeature(`mock-${entityName}`, (r) => {
+    r.useExtension(EXT_TOKEN_VERIFIER, entityName, plugin);
+  });
+}
+
+function jwtProvider(entityName = "jwt-mock"): ReturnType<typeof defineFeature> {
+  const plugin: AuthProviderPlugin = {
+    shape: { kind: "jwt" },
+    build: () => async () => jwtLikeUser(),
+  };
+  return defineFeature(`mock-${entityName}`, (r) => {
+    r.useExtension(EXT_TOKEN_VERIFIER, entityName, plugin);
+  });
+}
+
+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_")]);
+    const user = await resolveTokenVerifier({ db: fakeDb, registry }, "kpat_valid");
+    expect(user?.id).toBe("u-jwt");
+  });
+
+  test("routes a dot-separated token to the jwt-shape provider", async () => {
+    const registry = createRegistry([authFoundationFeature, jwtProvider()]);
+    const user = await resolveTokenVerifier({ db: fakeDb, registry }, "header.payload.sig");
+    expect(user?.id).toBe("u-jwt");
+  });
+
+  test("no provider's shape matches → null", async () => {
+    const registry = createRegistry([authFoundationFeature, prefixProvider("pat-mock", "kpat_")]);
+    const user = await resolveTokenVerifier({ db: fakeDb, registry }, "not-a-pat-token");
+    expect(user).toBeNull();
+  });
+
+  test("no providers registered at all → null", async () => {
+    const registry = createRegistry([authFoundationFeature]);
+    const user = await resolveTokenVerifier({ db: fakeDb, registry }, "anything");
+    expect(user).toBeNull();
+  });
+});
+
+describe("validateTokenVerifierMultiplicity", () => {
+  test("0 tokenVerifier + 0 sessionStore → throws (neither auth path mounted)", () => {
+    const registry = createRegistry([authFoundationFeature]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).toThrow(
+      /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,
+      jwtProvider(),
+      prefixProvider("pat-mock", "kpat_"),
+    ]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).not.toThrow();
+  });
+
+  test("≥2 providers claiming the same shape → throws a conflict error", () => {
+    const registry = createRegistry([
+      authFoundationFeature,
+      jwtProvider("jwt-mock-a"),
+      jwtProvider("jwt-mock-b"),
+    ]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).toThrow(
+      /same shape "jwt"/,
+    );
+  });
+
+  test("wrong-shape registration → throws a malformed-plugin error", () => {
+    const broken = defineFeature("mock-broken", (r) => {
+      r.useExtension(EXT_TOKEN_VERIFIER, "broken", { shape: { kind: "prefix" } });
+    });
+    const registry = createRegistry([authFoundationFeature, broken]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).toThrow(
+      /without a valid AuthProviderPlugin/,
+    );
+  });
+
+  test("malformed shape (build present, prefix missing) → throws a malformed-plugin error", () => {
+    const broken = defineFeature("mock-broken-shape", (r) => {
+      r.useExtension(EXT_TOKEN_VERIFIER, "broken-shape", {
+        shape: { kind: "prefix" },
+        build: () => async () => null,
+      });
+    });
+    const registry = createRegistry([authFoundationFeature, broken]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).toThrow(
+      /without a valid AuthProviderPlugin/,
+    );
+  });
+});

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

@@ -0,0 +1,150 @@
+// Multiplicity boot-check for auth-foundation's `tokenVerifier` extension
+// 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 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 {
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+  isAuthProviderPlugin,
+  isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
+  tokenShapeKey,
+} from "./types";
+
+export function validateTokenVerifierMultiplicity(features: readonly FeatureDefinition[]): void {
+  const namesByShape = new Map<string, string[]>();
+
+  for (const feature of features) {
+    for (const usage of feature.extensionUsages) {
+      if (usage.extensionName !== EXT_TOKEN_VERIFIER) continue;
+      if (!isAuthProviderPlugin(usage.options)) {
+        throw new Error(
+          `[auth-foundation] tokenVerifier provider "${usage.entityName}" (feature "${feature.name}") ` +
+            `registered without a valid AuthProviderPlugin — options must have a { shape, build } shape.`,
+        );
+      }
+      const key = tokenShapeKey(usage.options.shape);
+      const names = namesByShape.get(key) ?? [];
+      names.push(usage.entityName);
+      namesByShape.set(key, names);
+    }
+  }
+
+  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 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.",
+    );
+  }
+
+  for (const [key, names] of namesByShape) {
+    if (names.length >= 2) {
+      throw new Error(
+        `[auth-foundation] ${names.length} tokenVerifier providers claim the same shape "${key}" ` +
+          `(${names.join(", ")}) — resolveTokenVerifier can't route between them unambiguously. ` +
+          `Give each provider a distinct shape.`,
+      );
+    }
+  }
+}
+
+// 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) continue;
+      if (!guard(usage.options)) {
+        throw new Error(
+          `[auth-foundation] ${label} provider "${usage.entityName}" (feature "${feature.name}") ` +
+            `registered without a valid ${shapeHint}.`,
+        );
+      }
+      names.push(usage.entityName);
+    }
+  }
+
+  if (names.length >= 2) {
+    throw new Error(
+      `[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 {
+  validateSingleProvider(features, {
+    ext: EXT_TENANT_RESOLVER,
+    label: "tenantResolver",
+    guard: isTenantResolverProvider,
+    shapeHint: "TenantResolverProvider — options must have { trust, build }",
+  });
+}
+
+export function validateTenantExistenceMultiplicity(features: readonly FeatureDefinition[]): void {
+  validateSingleProvider(features, {
+    ext: EXT_TENANT_EXISTENCE,
+    label: "tenantExistence",
+    guard: isTenantExistenceProvider,
+    shapeHint: "TenantExistenceProvider — options must have a { build } shape",
+  });
+}