@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.160.0

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/,
+    );
+  });
+});

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

@@ -0,0 +1,91 @@
+// Multiplicity boot-check for auth-foundation's `tokenVerifier` extension
+// point (#1368). 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).
+
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  EXT_SESSION_STORE,
+  EXT_TOKEN_VERIFIER,
+  isAuthProviderPlugin,
+  isSessionStoreProvider,
+  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) {
+    throw new Error(
+      "[auth-foundation] no tokenVerifier providers registered — mount at least one " +
+        "auth-provider-* feature (e.g. auth-provider-jwt) 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.`,
+      );
+    }
+  }
+}
+
+// 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 {
+  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)) {
+        throw new Error(
+          `[auth-foundation] sessionStore provider "${usage.entityName}" (feature "${feature.name}") ` +
+            `registered without a valid SessionStoreProvider — options must have a { build } shape.`,
+        );
+      }
+      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.`,
+    );
+  }
+}

package/src/auth-foundation/feature.ts

@@ -0,0 +1,103 @@
+// 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)`.
+//
+// **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).
+
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { validateSessionStoreMultiplicity, validateTokenVerifierMultiplicity } from "./boot-checks";
+import {
+  type AuthProviderBuildDeps,
+  EXT_SESSION_STORE,
+  EXT_TOKEN_VERIFIER,
+  isAuthProviderPlugin,
+  isSessionStoreProvider,
+  type SessionStore,
+  tokenShapeMatches,
+} from "./types";
+
+export { EXT_SESSION_STORE, 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.",
+  );
+  r.uiHints({
+    displayLabel: "Auth Provider Foundation",
+    category: "identity",
+    recommended: false,
+  });
+
+  r.extendsRegistrar(EXT_TOKEN_VERIFIER, {
+    onRegister: () => {
+      // No side-effects at register-time — registry stores the usage,
+      // 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.
+    },
+  });
+
+  r.bootCheck(({ features }) => validateSessionStoreMultiplicity(features));
+});
+
+/**
+ * Tries every registered tokenVerifier provider's shape against `rawToken`
+ * in registration order and calls the first match's verifier. Returns null
+ * when no provider's shape matches, or when the matching provider's
+ * verifier rejects the token.
+ */
+export async function resolveTokenVerifier(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+  rawToken: string,
+): Promise<SessionUser | null> {
+  const usages = deps.registry.getExtensionUsages(EXT_TOKEN_VERIFIER);
+  for (const usage of usages) {
+    if (!isAuthProviderPlugin(usage.options)) continue;
+    if (!tokenShapeMatches(usage.options.shape, rawToken)) continue;
+    const verify = await usage.options.build(deps);
+    return verify(rawToken);
+  }
+  return null;
+}
+
+/**
+ * Resolves the single registered sessionStore provider. Assumes
+ * validateSessionStoreMultiplicity already ran at boot — a missing provider
+ * here means the app booted without going through the framework's boot
+ * validator, not a runtime state resolveSessionStore should model.
+ */
+export async function resolveSessionStore(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<SessionStore> {
+  const usage = deps.registry.getExtensionUsages(EXT_SESSION_STORE)[0];
+  if (!usage || !isSessionStoreProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] no sessionStore provider registered — did the boot validator run?",
+    );
+  }
+  return usage.options.build(deps);
+}

package/src/auth-foundation/index.ts

@@ -0,0 +1,23 @@
+// Public API of the auth-foundation bundled-feature.
+
+export {
+  authFoundationFeature,
+  resolveSessionStore,
+  resolveTokenVerifier,
+} from "./feature";
+export {
+  type AuthProviderBuildDeps,
+  type AuthProviderPlugin,
+  type AuthVerifier,
+  EXT_SESSION_STORE,
+  EXT_TOKEN_VERIFIER,
+  isAuthProviderPlugin,
+  isSessionStoreProvider,
+  isValidTokenShape,
+  type SessionMassRevoker,
+  type SessionStore,
+  type SessionStoreProvider,
+  type TokenShape,
+  tokenShapeKey,
+  tokenShapeMatches,
+} from "./types";

package/src/auth-foundation/types.ts

@@ -0,0 +1,107 @@
+// kumiko-feature-version: 1
+//
+// Type contracts for auth-foundation's `tokenVerifier` extension point.
+// Provider-features (future: auth-provider-jwt, auth-provider-pat) register
+// an AuthProviderPlugin via `r.useExtension(EXT_TOKEN_VERIFIER, "<name>", plugin)`.
+//
+// **Shape-match routing:** unlike file-foundation/mail-foundation (one active
+// provider per tenant, chosen via a config-key), token verification happens
+// BEFORE the tenant is known — there's nothing to select on. Every registered
+// provider declares a static `shape` (how to recognize its own tokens by
+// looking at the raw bearer value); `resolveTokenVerifier` tries each
+// provider's shape in turn and calls the first match's verifier.
+
+import type {
+  SessionChecker,
+  SessionCreator,
+  SessionRevoker,
+} from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+
+export const EXT_TOKEN_VERIFIER = "tokenVerifier";
+
+/**
+ * Deps available to a provider's `build()`. DB access only — a hot-path
+ * resolver (see personal-access-tokens/resolver.ts) needs a raw-DB handle
+ * for a point-read + live-role-resolution, not a per-request ctx (there is
+ * no tenant/session yet at verify-time).
+ */
+export type AuthProviderBuildDeps = {
+  readonly db: DbConnection;
+};
+
+/** How to recognize this provider's tokens by looking at the raw bearer value. */
+export type TokenShape =
+  | { readonly kind: "jwt" }
+  | { readonly kind: "prefix"; readonly prefix: string };
+
+export type AuthVerifier = (rawToken: string) => Promise<SessionUser | null>;
+
+export type AuthProviderPlugin = {
+  readonly shape: TokenShape;
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<AuthVerifier> | AuthVerifier;
+};
+
+export function isValidTokenShape(shape: unknown): shape is TokenShape {
+  if (typeof shape !== "object" || shape === null || !("kind" in shape)) return false;
+  const kind = (shape as { kind: unknown }).kind;
+  if (kind === "jwt") return true;
+  if (kind === "prefix") {
+    const prefix = "prefix" in shape ? (shape as { prefix: unknown }).prefix : undefined;
+    return typeof prefix === "string" && prefix.length > 0;
+  }
+  return false;
+}
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind. Mirrors file-foundation's isFileProviderPlugin.
+export function isAuthProviderPlugin(o: unknown): o is AuthProviderPlugin {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function" &&
+    "shape" in o &&
+    isValidTokenShape((o as { shape: unknown }).shape)
+  );
+}
+
+export function tokenShapeMatches(shape: TokenShape, rawToken: string): boolean {
+  if (shape.kind === "prefix") return rawToken.startsWith(shape.prefix);
+  return rawToken.split(".").length === 3;
+}
+
+/** Static discriminator used by the multiplicity boot-check to detect two providers claiming the same shape. */
+export function tokenShapeKey(shape: TokenShape): string {
+  return shape.kind === "jwt" ? "jwt" : `prefix:${shape.prefix}`;
+}
+
+// Session-store extension point (#1370). Unlike EXT_TOKEN_VERIFIER, this is
+// single-provider — sessions have no per-provider shape to route on, so
+// exactly one implementation must be registered (boot-fails on 0 or ≥2).
+
+export const EXT_SESSION_STORE = "sessionStore";
+
+/** Mass-revoke every live session for a user. Used by password-change and "sign out everywhere". */
+export type SessionMassRevoker = (userId: string) => Promise<number>;
+
+export type SessionStore = {
+  readonly creator: SessionCreator;
+  readonly revoker: SessionRevoker;
+  readonly checker: SessionChecker;
+  readonly massRevoker: SessionMassRevoker;
+};
+
+export type SessionStoreProvider = {
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<SessionStore> | SessionStore;
+};
+
+export function isSessionStoreProvider(o: unknown): o is SessionStoreProvider {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function"
+  );
+}

package/src/auth-mfa/__tests__/errors-i18n-parity.test.ts

@@ -28,4 +28,12 @@ describe("auth-mfa errors.ts i18nKey / client-bundle parity", () => {
       expect(defaultTranslations["de"]?.[key]).toBeDefined();
     });
   }
+
+  // Client-only key: mfa-enable-screen.tsx sets this directly (not via a
+  // DispatcherError), so it isn't covered by the failures loop above.
+  test("client-only auth.mfa.errors.setupFailed is registered in en/de translations", () => {
+    const key = "auth.mfa.errors.setupFailed";
+    expect(defaultTranslations["en"]?.[key]).toBeDefined();
+    expect(defaultTranslations["de"]?.[key]).toBeDefined();
+  });
 });