@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.159.1

package/src/auth-email-password/signed-token.ts

@@ -82,4 +82,5 @@ export function verifyToken(
 export const TokenPurpose = {
   passwordReset: "reset",
   emailVerification: "verify",
+  accountUnlock: "unlock",
 } as const;

package/src/auth-email-password/unlock-token.ts

@@ -0,0 +1,28 @@
+// Thin wrapper around signed-token.ts pinning the purpose to "unlock".
+// Mirrors reset-token.ts / verification-token.ts.
+
+import type { Temporal } from "temporal-polyfill";
+import { signToken, TokenPurpose, verifyToken } from "./signed-token";
+
+export type VerifyResult =
+  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+// @wrapper-known semantic-alias
+export function signUnlockToken(
+  userId: string,
+  ttlMinutes: number,
+  secret: string,
+  now?: Temporal.Instant,
+): { token: string; expiresAt: Temporal.Instant } {
+  return signToken(userId, TokenPurpose.accountUnlock, ttlMinutes, secret, now);
+}
+
+// @wrapper-known semantic-alias
+export function verifyUnlockToken(
+  token: string,
+  secret: string,
+  now?: Temporal.Instant,
+): VerifyResult {
+  return verifyToken(token, TokenPurpose.accountUnlock, secret, now);
+}

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

@@ -1,7 +1,7 @@
-import { describe, expect, test } from "bun:test";
-import { screen } from "@testing-library/react";
+import { describe, expect, mock, test } from "bun:test";
+import { fireEvent, screen } from "@testing-library/react";
 import type { ReactNode } from "react";
-import { makeAuthGate } from "../auth-gate";
+import { createLoginRoute, makeAuthGate } from "../auth-gate";
 import { makeSessionApi, renderWithProviders } from "./test-utils";
 
 describe("makeAuthGate", () => {
@@ -48,3 +48,65 @@ describe("makeAuthGate", () => {
     expect(screen.queryByTestId("custom-login")).toBeNull();
   });
 });
+
+describe("createLoginRoute", () => {
+  function CustomLogin(): ReactNode {
+    return <div data-testid="custom-login">custom-login</div>;
+  }
+
+  function LoginWithMfaTrigger({
+    onMfaChallenge,
+  }: {
+    readonly onMfaChallenge?: (challengeToken: string) => void;
+  }): ReactNode {
+    return (
+      <button type="button" data-testid="trigger-mfa" onClick={() => onMfaChallenge?.("token-123")}>
+        trigger
+      </button>
+    );
+  }
+
+  function CustomMfaVerify({ challengeToken }: { readonly challengeToken: string }): ReactNode {
+    return <div data-testid="mfa-verify">{challengeToken}</div>;
+  }
+
+  test("authenticated + onAuthenticated → renders nothing, fires onAuthenticated exactly once", () => {
+    const onAuthenticated = mock(() => {});
+    const LoginRoute = createLoginRoute({ loginScreen: CustomLogin, onAuthenticated });
+    const session = makeSessionApi({ status: "authenticated" });
+    const { container } = renderWithProviders(<LoginRoute />, { session });
+    expect(container.firstChild).toBeNull();
+    expect(onAuthenticated).toHaveBeenCalledTimes(1);
+  });
+
+  test("authenticated without onAuthenticated → falls through to LoginComponent (standalone mount)", () => {
+    const LoginRoute = createLoginRoute({ loginScreen: CustomLogin });
+    const session = makeSessionApi({ status: "authenticated" });
+    renderWithProviders(<LoginRoute />, { session });
+    expect(screen.getByTestId("custom-login")).toBeTruthy();
+  });
+
+  test("onMfaChallenge → renders MfaVerifyComponent with the challenge token", () => {
+    const LoginRoute = createLoginRoute({
+      loginScreen: LoginWithMfaTrigger,
+      mfaVerifyScreen: CustomMfaVerify,
+    });
+    const session = makeSessionApi({ status: "unauthenticated" });
+    renderWithProviders(<LoginRoute />, { session });
+    fireEvent.click(screen.getByTestId("trigger-mfa"));
+    expect(screen.getByTestId("mfa-verify").textContent).toBe("token-123");
+  });
+
+  test("makeAuthGate delegates mfaVerifyScreen wiring to createLoginRoute", () => {
+    const Gate = makeAuthGate(LoginWithMfaTrigger, undefined, CustomMfaVerify);
+    const session = makeSessionApi({ status: "unauthenticated" });
+    renderWithProviders(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+      { session },
+    );
+    fireEvent.click(screen.getByTestId("trigger-mfa"));
+    expect(screen.getByTestId("mfa-verify").textContent).toBe("token-123");
+  });
+});

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

@@ -233,6 +233,39 @@ 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.
+export async function requestAccountUnlock(
+  email: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/request-account-unlock", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ email }),
+  });
+  if (res.ok) return { ok: true };
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
+// POST /api/auth/confirm-account-unlock. Auto-submitted by
+// ConfirmAccountUnlockScreen after parsing `?token=...`. Server collapses
+// every verify failure into `invalid_unlock_token` (anti-enumeration,
+// parallel to reset/verify). Only clears the Redis lockout state, no
+// entity write.
+export async function confirmAccountUnlock(
+  token: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/confirm-account-unlock", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ token }),
+  });
+  if (res.ok) return { ok: true };
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
 // POST /api/auth/signup-request. Always-200 (anti-enumeration; wir
 // sagen nicht ob die Email schon registriert ist). Server schickt
 // Activation-Mail an die Adresse — beim Klick auf den Link landet der

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

@@ -0,0 +1,95 @@
+// @runtime client
+// ConfirmAccountUnlockScreen — reads `?token=...` from the URL, auto-posts
+// it to /api/auth/confirm-account-unlock on mount, shows success/error.
+// Idempotent server-side (clearLockoutState is a no-op when already
+// unlocked), so no re-submit risk. Mirrors VerifyEmailScreen 1:1.
+//
+// useEffect with empty deps + a once-guard so React Strict Mode's double
+// useEffect dispatch in dev fires the confirm call only once.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { confirmAccountUnlock } from "./auth-client";
+import { AuthCard, useUrlToken } from "./auth-form-primitives";
+
+export type ConfirmAccountUnlockScreenProps = {
+  readonly title?: string;
+  /** Override for the token from the URL. Default: parsed from `?token=...`. */
+  readonly token?: string;
+  /** href for the "go to sign in" link. Default "/login". */
+  readonly loginHref?: string;
+};
+
+type Status = "verifying" | "success" | "error" | "missing-token";
+
+export function ConfirmAccountUnlockScreen({
+  title,
+  token: tokenProp,
+  loginHref = "/login",
+}: ConfirmAccountUnlockScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Link } = usePrimitives();
+  const token = useUrlToken(tokenProp);
+  const [status, setStatus] = useState<Status>(token === "" ? "missing-token" : "verifying");
+  const startedRef = useRef(false);
+
+  useEffect(() => {
+    if (status !== "verifying") return;
+    if (startedRef.current) return;
+    startedRef.current = true;
+    void (async () => {
+      const res = await confirmAccountUnlock(token);
+      setStatus(res.ok ? "success" : "error");
+    })();
+  }, [status, token]);
+
+  if (status === "missing-token") {
+    return (
+      <AuthCard title={title ?? t("auth.unlockAccount.errorTitle")}>
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.missingToken")}</p>
+          <Link href={loginHref} variant="muted">
+            {t("auth.unlockAccount.goToLogin")}
+          </Link>
+        </div>
+      </AuthCard>
+    );
+  }
+
+  if (status === "verifying") {
+    return (
+      <AuthCard>
+        <div className="p-6">
+          <p className="text-sm text-muted-foreground" role="status">
+            {t("auth.unlockAccount.verifying")}
+          </p>
+        </div>
+      </AuthCard>
+    );
+  }
+
+  if (status === "success") {
+    return (
+      <AuthCard title={title ?? t("auth.unlockAccount.successTitle")}>
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.successBody")}</p>
+          <Link href={loginHref} variant="button">
+            {t("auth.unlockAccount.goToLogin")}
+          </Link>
+        </div>
+      </AuthCard>
+    );
+  }
+
+  // status === "error"
+  return (
+    <AuthCard title={title ?? t("auth.unlockAccount.errorTitle")}>
+      <div className="p-6 pt-0 flex flex-col gap-4">
+        <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.errorBody")}</p>
+        <Link href={loginHref} variant="muted">
+          {t("auth.unlockAccount.goToLogin")}
+        </Link>
+      </div>
+    </AuthCard>
+  );
+}

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

@@ -18,7 +18,9 @@ export type {
   VerifyEmailFailure,
 } from "./auth-client";
 export {
+  confirmAccountUnlock,
   confirmSignup,
+  requestAccountUnlock,
   requestEmailVerification,
   requestPasswordReset,
   requestSignup,
@@ -34,6 +36,8 @@ export type {
   EmailPasswordClientOptions,
 } from "./client-plugin";
 export { emailPasswordClient } from "./client-plugin";
+export type { ConfirmAccountUnlockScreenProps } from "./confirm-account-unlock-screen";
+export { ConfirmAccountUnlockScreen } from "./confirm-account-unlock-screen";
 export type { DefaultTopbarActionsProps } from "./default-topbar-actions";
 export { DefaultTopbarActions } from "./default-topbar-actions";
 export type { ForgotPasswordScreenProps } from "./forgot-password-screen";
@@ -42,6 +46,8 @@ export type { InviteAcceptScreenProps } from "./invite-accept-screen";
 export { InviteAcceptScreen } from "./invite-accept-screen";
 export type { AuthLegalLink, LoginScreenProps } from "./login-screen";
 export { LoginScreen } from "./login-screen";
+export type { RequestAccountUnlockScreenProps } from "./request-account-unlock-screen";
+export { RequestAccountUnlockScreen } from "./request-account-unlock-screen";
 export type { ResetPasswordScreenProps } from "./reset-password-screen";
 export { ResetPasswordScreen } from "./reset-password-screen";
 export type { SessionApi, SessionState, SessionStatus } from "./session";

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

@@ -40,6 +40,13 @@ export type LoginScreenProps = {
    *  Link. Apps die den Reset-Flow NICHT anbieten (z.B. nur Magic-Link),
    *  setzen das einfach nicht — Login bleibt minimalistisch. */
   readonly forgotPasswordHref?: string;
+  /** Optional href to RequestAccountUnlockScreen (#1266). When set, an
+   *  account_locked login error renders an "Unlock account?" link inline —
+   *  the account-lockout escape hatch, since forgotPasswordHref does NOT
+   *  help here: the lockout gate blocks login before password verify even
+   *  runs, so it also blocks the post-reset login. Apps without
+   *  accountUnlock configured just leave this unset. */
+  readonly unlockAccountHref?: string;
   /** Optional href zum SignupScreen. Wenn gesetzt rendert die LoginScreen
    *  einen "Account erstellen"-Link. Apps die kein Self-Signup wollen
    *  (closed-invite-only) setzen das einfach nicht. */
@@ -100,6 +107,7 @@ export function LoginScreen({
   subtitle,
   submitLabel,
   forgotPasswordHref,
+  unlockAccountHref,
   signupHref,
   legalLinks,
   onMfaChallenge,
@@ -229,6 +237,13 @@ export function LoginScreen({
                       </Button>
                     </span>
                   )}
+                {error.reason === "account_locked" && unlockAccountHref !== undefined && (
+                  <span className="self-start">
+                    <Link href={unlockAccountHref} variant="default">
+                      {t("auth.login.unlockAccount")}
+                    </Link>
+                  </span>
+                )}
                 {resendStatus.kind === "rateLimited" && (
                   <span className="text-xs">{t("auth.login.resendRateLimited")}</span>
                 )}

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

@@ -0,0 +1,112 @@
+// @runtime client
+// RequestAccountUnlockScreen — form with an email input. Submit triggers
+// /api/auth/request-account-unlock (silent-success, no account
+// enumeration). UI unconditionally shows an "if your account is locked,
+// a mail is on its way" confirmation — even when the server internally
+// knows the email doesn't exist or isn't locked. Mirrors
+// ForgotPasswordScreen 1:1.
+//
+// The app is responsible for mounting this screen under a URL (e.g.
+// /unlock-account) and for reaching it — LoginScreen can render a link
+// to the app route on accountLocked errors.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type FormEvent, type ReactNode, useState } from "react";
+import { requestAccountUnlock } from "./auth-client";
+import { AuthCard } from "./auth-form-primitives";
+
+export type RequestAccountUnlockScreenProps = {
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  /** href for the "back to sign in" link in success + form state. App-
+   *  specific — default "/login". */
+  readonly loginHref?: string;
+};
+
+export function RequestAccountUnlockScreen({
+  title,
+  subtitle,
+  loginHref = "/login",
+}: RequestAccountUnlockScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
+  const [email, setEmail] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [done, setDone] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // guard:dup-ok — same submit pattern as forgot-password-screen, but different API endpoint and state
+  const doSubmit = async (): Promise<void> => {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const res = await requestAccountUnlock(email);
+      if (res.ok) {
+        setDone(true);
+      } else if (res.error.reason === "rate_limited") {
+        const minutes =
+          res.error.retryAfterSeconds !== undefined
+            ? Math.ceil(res.error.retryAfterSeconds / 60)
+            : undefined;
+        setError(
+          minutes !== undefined
+            ? t("auth.errors.accountLockedRetry", { minutes })
+            : t("auth.errors.rateLimited"),
+        );
+      } else {
+        setError(t("auth.errors.unknownError"));
+      }
+    } catch {
+      setError(t("auth.errors.unknownError"));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void doSubmit();
+  };
+
+  const effectiveTitle = title ?? t("auth.requestUnlock.title");
+
+  return (
+    <AuthCard title={effectiveTitle} subtitle={subtitle}>
+      {done ? (
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <Banner variant="info">
+            <p className="font-medium text-foreground">{t("auth.requestUnlock.successTitle")}</p>
+            <p className="mt-1">{t("auth.requestUnlock.successBody")}</p>
+          </Banner>
+          <Link href={loginHref} variant="muted">
+            {t("auth.requestUnlock.backToLogin")}
+          </Link>
+        </div>
+      ) : (
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.requestUnlock.intro")}</p>
+          <Form onSubmit={onSubmit}>
+            <Field id="unlock-email" label={t("auth.requestUnlock.email")} required>
+              <Input
+                kind="text"
+                id="unlock-email"
+                name="unlock-email"
+                value={email}
+                onChange={setEmail}
+                disabled={submitting}
+                required
+              />
+            </Field>
+            {error !== null && <Banner variant="error">{error}</Banner>}
+            <Button type="submit" loading={submitting} disabled={submitting}>
+              {submitting ? t("auth.requestUnlock.submitting") : t("auth.requestUnlock.submit")}
+            </Button>
+          </Form>
+          <Link href={loginHref} variant="muted" className="self-center">
+            {t("auth.requestUnlock.backToLogin")}
+          </Link>
+        </div>
+      )}
+    </AuthCard>
+  );
+}

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

@@ -0,0 +1,33 @@
+// 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_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();
+  });
+});
+
+describe("authFoundationFeature — multiplicity boot-check", () => {
+  test("registers a bootCheck per extension-point (tokenVerifier + sessionStore)", () => {
+    expect(authFoundationFeature.bootChecks.length).toBeGreaterThanOrEqual(2);
+  });
+});

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

@@ -0,0 +1,78 @@
+// 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,
+  };
+}
+
+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 → throws (fail-fast, nothing to store sessions in)", () => {
+    const registry = createRegistry([authFoundationFeature]);
+    expect(() => validateSessionStoreMultiplicity([...registry.features.values()])).toThrow(
+      /no sessionStore provider registered/,
+    );
+  });
+
+  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__/token-verifier.test.ts

@@ -0,0 +1,117 @@
+// 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_TOKEN_VERIFIER } 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);
+  });
+}
+
+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 providers registered → throws (fail-fast, no provider to route to)", () => {
+    const registry = createRegistry([authFoundationFeature]);
+    expect(() => validateTokenVerifierMultiplicity([...registry.features.values()])).toThrow(
+      /no tokenVerifier providers registered/,
+    );
+  });
+
+  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/,
+    );
+  });
+});