@stapel/auth-react 1.0.0

package/src/headless/QrLogin.tsx

@@ -0,0 +1,52 @@
+import { useEffect, useMemo } from "react";
+import type { ReactNode } from "react";
+import type { QrType } from "../api/types.js";
+import { createQrLoginFlow } from "../flows/qrLoginFlow.js";
+import type { QrLoginState } from "../flows/qrLoginFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi, useAuthSession } from "../model/context.js";
+
+export interface QrLoginBag {
+  readonly state: QrLoginState;
+  start(
+    type: QrType,
+    redirectUrl: string,
+    allowUnauthenticatedScanner?: boolean
+  ): void;
+  dispose(): void;
+}
+
+/**
+ * Headless QR authentication with background polling (auth-sa.md §8). Render
+ * the `awaitingScan` state's `scanUrl` as a QR image. The poll loop starts on
+ * `start()` and is torn down on unmount. For `login_request`, delivered tokens
+ * are adopted into the session automatically.
+ */
+export function QrLogin(props: {
+  children: (bag: QrLoginBag) => ReactNode;
+  pollIntervalMs?: number;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const session = useAuthSession();
+  const { pollIntervalMs } = props;
+  const flow = useMemo(
+    () =>
+      createQrLoginFlow({
+        api,
+        analytics,
+        onAuthenticated: (tokens) => session.setTokens(tokens),
+        ...(pollIntervalMs !== undefined ? { pollIntervalMs } : {}),
+      }),
+    [api, analytics, session, pollIntervalMs]
+  );
+  const state = useFlow(flow.machine);
+  useEffect(() => () => flow.dispose(), [flow]);
+  return props.children({
+    state,
+    start: (type, redirectUrl, allow) => {
+      void flow.start(type, redirectUrl, allow);
+    },
+    dispose: flow.dispose,
+  });
+}

package/src/headless/TotpSetup.tsx

@@ -0,0 +1,40 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import { createTotpSetupFlow } from "../flows/totpSetupFlow.js";
+import type { TotpSetupState } from "../flows/totpSetupFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi } from "../model/context.js";
+
+export interface TotpSetupBag {
+  readonly state: TotpSetupState;
+  start(): void;
+  confirm(code: string): void;
+  reset(): void;
+}
+
+/**
+ * Headless TOTP enrollment (auth-sa.md §11). Render the `enrolling` state's
+ * `qrUri` as a QR image and `secret` for manual entry; on `done`, surface the
+ * one-time `backupCodes` with a copy/warn affordance (shown ONCE).
+ */
+export function TotpSetup(props: {
+  children: (bag: TotpSetupBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const flow = useMemo(
+    () => createTotpSetupFlow({ api, analytics }),
+    [api, analytics]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    start: () => {
+      void flow.start();
+    },
+    confirm: (code) => {
+      void flow.confirm(code);
+    },
+    reset: flow.reset,
+  });
+}

package/src/headless/VerificationChallenge.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from "react";
+import type { VerificationFactorId } from "../api/types.js";
+import { useFlow } from "../flows/useFlow.js";
+import type { VerificationState } from "../flows/verificationFlow.js";
+import { useVerification } from "../model/context.js";
+
+export interface VerificationChallengeBag {
+  readonly state: VerificationState;
+  chooseFactor(factor: VerificationFactorId): void;
+  submitCode(proof: { code?: string; backup_code?: string }): void;
+  submitPasskey(credential: unknown): void;
+  cancel(): void;
+}
+
+/**
+ * THE FLAGSHIP headless component (frontend-standard §2). Mount it ONCE at the
+ * app root. It renders the app's step-up modal by driving the singleton
+ * {@link VerificationController} that `createAuthRuntime` wired into
+ * `client.onVerificationChallenge`. When any sensitive request 403s with a
+ * verification envelope, `state.step` leaves `"idle"` and this render prop
+ * fires — pick a factor, submit the proof, and core transparently retries the
+ * original request with `X-Verification-Token`.
+ *
+ * Renders nothing while idle, so it is safe to leave mounted:
+ * ```tsx
+ * <VerificationChallenge>
+ *   {({ state, chooseFactor, submitCode, cancel }) => (
+ *     <Modal open={state.step !== "idle"}>… </Modal>
+ *   )}
+ * </VerificationChallenge>
+ * ```
+ */
+export function VerificationChallenge(props: {
+  children: (bag: VerificationChallengeBag) => ReactNode;
+  /** Render even when idle (default false — returns null while idle). */
+  renderWhenIdle?: boolean;
+}): ReactNode {
+  const controller = useVerification();
+  const state = useFlow(controller.machine);
+  if (state.step === "idle" && props.renderWhenIdle !== true) return null;
+  return props.children({
+    state,
+    chooseFactor: (factor) => {
+      void controller.chooseFactor(factor);
+    },
+    submitCode: (proof) => {
+      void controller.submitCode(proof);
+    },
+    submitPasskey: (credential) => {
+      void controller.submitPasskey(credential);
+    },
+    cancel: controller.cancel,
+  });
+}

package/src/headless/misc.tsx

@@ -0,0 +1,151 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import type { OtpChannel } from "../api/types.js";
+import { createAnonymousFlow } from "../flows/anonymousFlow.js";
+import type { AnonymousState } from "../flows/anonymousFlow.js";
+import { createAuthenticatorChangeFlow } from "../flows/authenticatorChangeFlow.js";
+import type { AuthenticatorChangeState } from "../flows/authenticatorChangeFlow.js";
+import { createMagicLinkFlow } from "../flows/magicLinkFlow.js";
+import type { MagicLinkState } from "../flows/magicLinkFlow.js";
+import { createSsoFlow } from "../flows/ssoFlow.js";
+import type { SsoState } from "../flows/ssoFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi, useAuthSession } from "../model/context.js";
+
+// ── Magic link ──────────────────────────────────────────────────────────────
+
+export interface MagicLinkBag {
+  readonly state: MagicLinkState;
+  request(email: string, redirectUrl?: string): void;
+  reset(): void;
+}
+
+/** Headless magic-link request (auth-sa.md §15). */
+export function MagicLink(props: {
+  children: (bag: MagicLinkBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const flow = useMemo(
+    () => createMagicLinkFlow({ api, analytics }),
+    [api, analytics]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    request: (email, redirectUrl) => {
+      void flow.request(email, redirectUrl);
+    },
+    reset: flow.reset,
+  });
+}
+
+// ── Anonymous ────────────────────────────────────────────────────────────────
+
+export interface AnonymousBag {
+  readonly state: AnonymousState;
+  create(deviceId?: string): void;
+  reset(): void;
+}
+
+/** Headless anonymous session (auth-sa.md §6). */
+export function AnonymousSession(props: {
+  children: (bag: AnonymousBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const session = useAuthSession();
+  const flow = useMemo(
+    () =>
+      createAnonymousFlow({
+        api,
+        analytics,
+        onAuthenticated: (r) => session.adopt(r),
+      }),
+    [api, analytics, session]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    create: (deviceId) => {
+      void flow.create(deviceId);
+    },
+    reset: flow.reset,
+  });
+}
+
+// ── SSO discovery ────────────────────────────────────────────────────────────
+
+export interface SsoDiscoveryBag {
+  readonly state: SsoState;
+  lookup(domain: string): void;
+  beginLogin(orgSlug: string): void;
+  reset(): void;
+}
+
+/** Headless SSO domain discovery + login redirect (auth-sa.md §18). */
+export function SsoDiscovery(props: {
+  children: (bag: SsoDiscoveryBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const flow = useMemo(
+    () => createSsoFlow({ api, analytics }),
+    [api, analytics]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    lookup: (domain) => {
+      void flow.lookup(domain);
+    },
+    beginLogin: flow.beginLogin,
+    reset: flow.reset,
+  });
+}
+
+// ── Authenticator change (instant) ───────────────────────────────────────────
+
+export interface AuthenticatorChangeBag {
+  readonly state: AuthenticatorChangeState;
+  startInstant(channel: OtpChannel): void;
+  submitOldCode(code: string): void;
+  requestNew(newValue: string): void;
+  submitNewCode(code: string): void;
+  reset(): void;
+}
+
+/** Headless instant email/phone change (auth-sa.md §9). */
+export function AuthenticatorChange(props: {
+  children: (bag: AuthenticatorChangeBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const session = useAuthSession();
+  const flow = useMemo(
+    () =>
+      createAuthenticatorChangeFlow({
+        api,
+        analytics,
+        onAuthenticated: (r) => session.adopt(r),
+      }),
+    [api, analytics, session]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    startInstant: (channel) => {
+      void flow.startInstant(channel);
+    },
+    submitOldCode: (code) => {
+      void flow.submitOldCode(code);
+    },
+    requestNew: (newValue) => {
+      void flow.requestNew(newValue);
+    },
+    submitNewCode: (code) => {
+      void flow.submitNewCode(code);
+    },
+    reset: flow.reset,
+  });
+}

package/src/i18n/keys.ts

@@ -0,0 +1,94 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+
+/**
+ * auth-react's own translation KEYS (frontend-standard §4.2): headless
+ * components never render literal strings — hosts resolve these via core's
+ * i18n engine (`useT`). Backend error codes (auth-sa.md "Error reference")
+ * flow through the SAME contour: a `StapelApiError.code` like
+ * `error.400.code_expired` is already a key, so the default bundle below ships
+ * English fallbacks for both the backend error codes and auth-react's UI keys.
+ * Point core's `loadLocale` at stapel-translate to override per locale.
+ */
+export const AUTH_I18N_KEYS = {
+  // Flow UI keys (auth-react-owned)
+  otpEnterCode: "auth.otp.enter_code",
+  otpResend: "auth.otp.resend",
+  otpSentTo: "auth.otp.sent_to",
+  passwordLabel: "auth.password.label",
+  totpEnterCode: "auth.totp.enter_code",
+  totpUseBackup: "auth.totp.use_backup",
+  verificationChoose: "auth.verification.choose_factor",
+  verificationSuccess: "auth.verification.success",
+  sessionThisDevice: "auth.session.this_device",
+  sessionSuspicious: "auth.session.suspicious",
+  passkeyNoCredentials: "auth.passkey.no_credentials",
+  unknownError: "auth.error.unknown",
+} as const;
+
+export type AuthI18nKey =
+  (typeof AUTH_I18N_KEYS)[keyof typeof AUTH_I18N_KEYS];
+
+/** English fallback bundle for auth-react UI keys + backend auth error codes. */
+export const authI18nBundleEn: I18nDictionary = {
+  // auth-react UI
+  "auth.otp.enter_code": "Enter the code we sent you",
+  "auth.otp.resend": "Resend code",
+  "auth.otp.sent_to": "Code sent to {target}",
+  "auth.password.label": "Password",
+  "auth.totp.enter_code": "Enter your 6-digit code",
+  "auth.totp.use_backup": "Use a backup code",
+  "auth.verification.choose_factor": "Verify it's you",
+  "auth.verification.success": "Verified",
+  "auth.session.this_device": "This device",
+  "auth.session.suspicious": "Unrecognized sign-in",
+  "auth.passkey.no_credentials":
+    "Couldn't sign in with a passkey on this device. Add one in Security settings after signing in another way, or pick a different sign-in method below.",
+  "auth.error.unknown": "Something went wrong. Please try again.",
+
+  // Backend error codes (auth-sa.md "Error reference")
+  "error.401.invalid_credentials": "Incorrect email or password.",
+  "error.401.account_disabled": "This account has been disabled.",
+  "error.401.refresh_revoked": "Your session ended. Please sign in again.",
+  "error.400.code_expired": "That code has expired. Request a new one.",
+  "error.400.invalid_code": "That code is incorrect.",
+  "error.400.invalid_code_attempts":
+    "That code is incorrect. {attempts_remaining} attempts left.",
+  "error.422.blocked": "Too many attempts. Try again in {retry_after_minutes} min.",
+  "error.429.rate_limit": "Please wait before requesting another code.",
+  "error.400.no_verified_contact": "No verified contact for this method.",
+  "error.400.wrong_password": "Your current password is incorrect.",
+  "error.400.no_password": "This account has no password set.",
+  "error.404.user_for_reset": "No account found for that email or phone.",
+  "error.403.mock_otp_admin": "Admin accounts can't use codes in this environment.",
+  "error.400.code_required": "A code is required.",
+  "error.400.totp_not_pending": "Start two-factor setup first.",
+  "error.423.account_locked":
+    "Account locked. Try again in {retry_after_minutes} min.",
+  "error.429.magic_link_rate": "Too many login-link requests. Try again later.",
+  "error.400.passkey_invalid": "Passkey verification failed.",
+  "error.400.passkey_challenge_expired": "Passkey request expired. Try again.",
+  "error.409.passkey_already_registered": "This passkey is already registered.",
+  "error.400.last_auth_method": "You can't remove your last sign-in method.",
+  "error.400.invalid_redirect_url": "Invalid redirect.",
+  "error.400.magic_link_invalid": "This login link is invalid or has expired.",
+  "error.400.captcha_required": "Please complete the captcha.",
+  "error.400.captcha_invalid": "Captcha verification failed.",
+  "error.403.verification_required": "Additional verification required.",
+  "error.404.verification_challenge_not_found":
+    "This verification expired. Please retry the action.",
+  "error.400.verification_invalid_factor": "That verification option isn't available.",
+  "error.400.verification_failed": "Verification failed. Try again.",
+  "error.423.verification_locked": "Too many attempts. Retry the action later.",
+  "error.404.sso_org_not_found": "Organization not found.",
+  "error.400.sso_not_configured": "SSO isn't configured for this organization.",
+  "error.403.sso_required": "This account must sign in with SSO.",
+};
+
+/**
+ * Register auth-react's key bundle into a core i18n engine (call once at
+ * startup). Registers under the given locale (default `"en"`); a later
+ * `loadLocale` from stapel-translate can layer localized overrides.
+ */
+export function registerAuthI18n(engine: I18nEngine, locale = "en"): void {
+  engine.registerBundle(locale, authI18nBundleEn);
+}

package/src/index.ts

@@ -0,0 +1,229 @@
+/**
+ * `@stapel/auth-react` — the headless React flow pair for stapel-auth
+ * (frontend-standard §2). Business + state only, zero visual opinion. Built on
+ * `@stapel/core`'s StapelClient (verification-403 interception, token refresh,
+ * i18n, analytics, query layer).
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { createAuthApi } from "./api/authApi.js";
+export type { AuthApi } from "./api/authApi.js";
+export {
+  authUrls,
+  validRedirectUrl,
+  safeNextPath,
+  safeScanRedirect,
+} from "./api/urls.js";
+export type { AuthUrls } from "./api/urls.js";
+export { isTotpChallenge } from "./api/types.js";
+export type {
+  AuthStatus,
+  StapelUser,
+  AuthTokens,
+  AuthResponse,
+  TOTPChallengeResponse,
+  LoginResponse,
+  OtpRequestResponse,
+  StatusResponse,
+  OtpChannel,
+  OAuthProviderInfo,
+  RegistrationCapabilities,
+  LoginCapabilities,
+  Capabilities,
+  PasswordChangeMethod,
+  PasswordMethodEntry,
+  PasswordMethods,
+  SecurityStatus,
+  SessionDeviceType,
+  AuthSession as AuthSessionRecord,
+  TotpSetupResponse,
+  TotpSetupConfirmResponse,
+  TotpDisableRequest,
+  VerificationFactorId,
+  VerificationEnvelope,
+  VerificationInitiateResponse,
+  VerificationCompleteResponse,
+  QrType,
+  QrGenerateResponse,
+  QrStatusValue,
+  QrStatusResponse,
+  Passkey,
+  PasskeyRegisterBeginResponse,
+  PasskeyAuthenticateBeginResponse,
+  ChangeOldVerifiedResponse,
+  DelayedChangeInitiatedResponse,
+  DelayedChangeStatus,
+  SsoLookupResponse,
+  AuditEvent,
+  AuditPage,
+  RefreshResponse,
+} from "./api/types.js";
+
+// ── flows (the reusable machine pattern — first instance) ────────────────────
+export { createFlowMachine } from "./flows/createFlowMachine.js";
+export type {
+  FlowMachine,
+  FlowMachineOptions,
+  FlowStateBase,
+} from "./flows/createFlowMachine.js";
+export { useFlow } from "./flows/useFlow.js";
+export { toFlowError, isErrorCode } from "./flows/errors.js";
+export type { FlowError } from "./flows/errors.js";
+
+export { createOtpFlow } from "./flows/otpFlow.js";
+export type { OtpFlow, OtpFlowDeps, OtpState } from "./flows/otpFlow.js";
+export { createPasswordLoginFlow } from "./flows/passwordLoginFlow.js";
+export type {
+  PasswordLoginFlow,
+  PasswordLoginFlowDeps,
+  PasswordLoginState,
+  TotpProof,
+} from "./flows/passwordLoginFlow.js";
+export { createPasswordChangeFlow } from "./flows/passwordChangeFlow.js";
+export type {
+  PasswordChangeFlow,
+  PasswordChangeFlowDeps,
+  PasswordChangeState,
+} from "./flows/passwordChangeFlow.js";
+export { createPasswordResetFlow } from "./flows/passwordResetFlow.js";
+export type {
+  PasswordResetFlow,
+  PasswordResetFlowDeps,
+  PasswordResetState,
+} from "./flows/passwordResetFlow.js";
+export { createVerificationController } from "./flows/verificationFlow.js";
+export type {
+  VerificationController,
+  VerificationControllerDeps,
+  VerificationState,
+} from "./flows/verificationFlow.js";
+export { createTotpSetupFlow } from "./flows/totpSetupFlow.js";
+export type {
+  TotpSetupFlow,
+  TotpSetupFlowDeps,
+  TotpSetupState,
+} from "./flows/totpSetupFlow.js";
+export { createOAuthFlow } from "./flows/oauthFlow.js";
+export type { OAuthFlow, OAuthFlowDeps, OAuthState } from "./flows/oauthFlow.js";
+export { createQrLoginFlow } from "./flows/qrLoginFlow.js";
+export type {
+  QrLoginFlow,
+  QrLoginFlowDeps,
+  QrLoginState,
+} from "./flows/qrLoginFlow.js";
+export {
+  createPasskeyRegistrationFlow,
+  createPasskeyLoginFlow,
+} from "./flows/passkeyFlow.js";
+export type {
+  PasskeyRegistrationFlow,
+  PasskeyRegistrationFlowDeps,
+  PasskeyRegisterState,
+  PasskeyLoginFlow,
+  PasskeyLoginFlowDeps,
+  PasskeyLoginState,
+} from "./flows/passkeyFlow.js";
+export { createMagicLinkFlow } from "./flows/magicLinkFlow.js";
+export type {
+  MagicLinkFlow,
+  MagicLinkFlowDeps,
+  MagicLinkState,
+} from "./flows/magicLinkFlow.js";
+export { createAnonymousFlow } from "./flows/anonymousFlow.js";
+export type {
+  AnonymousFlow,
+  AnonymousFlowDeps,
+  AnonymousState,
+} from "./flows/anonymousFlow.js";
+export { createSsoFlow } from "./flows/ssoFlow.js";
+export type { SsoFlow, SsoFlowDeps, SsoState } from "./flows/ssoFlow.js";
+export { createAuthenticatorChangeFlow } from "./flows/authenticatorChangeFlow.js";
+export type {
+  AuthenticatorChangeFlow,
+  AuthenticatorChangeFlowDeps,
+  AuthenticatorChangeState,
+} from "./flows/authenticatorChangeFlow.js";
+
+// ── model (runtime wiring, session, query hooks) ─────────────────────────────
+export { createAuthRuntime } from "./model/runtime.js";
+export type { AuthRuntime, CreateAuthRuntimeOptions } from "./model/runtime.js";
+export { createAuthSession } from "./model/session.js";
+export type {
+  AuthSession,
+  AuthSessionState,
+  AuthSessionOptions,
+  TeardownReason,
+} from "./model/session.js";
+export {
+  AuthRuntimeContext,
+  useAuthRuntime,
+  useAuthApi,
+  useAuthSession,
+  useVerification,
+  useAuthAnalytics,
+  useAuthSessionState,
+} from "./model/context.js";
+export { authQueryKeys } from "./model/queryKeys.js";
+export {
+  useCapabilities,
+  useMe,
+  useSecurityStatus,
+  usePasswordMethods,
+  useSessions,
+  usePasskeys,
+  useAuditLog,
+  useDelayedChangeStatus,
+  useSsoLookup,
+} from "./model/queries.js";
+export {
+  useLogout,
+  useRevokeSession,
+  useRevokeOtherSessions,
+  useConfirmSession,
+  useRemovePasskey,
+  useDisableTotp,
+  useCancelDelayedChange,
+} from "./model/mutations.js";
+
+// ── headless (renderless components) ─────────────────────────────────────────
+export { AuthProvider } from "./headless/AuthProvider.js";
+export { PasswordlessLogin } from "./headless/PasswordlessLogin.js";
+export type { PasswordlessLoginBag } from "./headless/PasswordlessLogin.js";
+export { PasswordLogin } from "./headless/PasswordLogin.js";
+export type { PasswordLoginBag } from "./headless/PasswordLogin.js";
+export { PasswordReset } from "./headless/PasswordReset.js";
+export type { PasswordResetBag } from "./headless/PasswordReset.js";
+export { PasswordChange } from "./headless/PasswordChange.js";
+export type { PasswordChangeBag } from "./headless/PasswordChange.js";
+export { VerificationChallenge } from "./headless/VerificationChallenge.js";
+export type { VerificationChallengeBag } from "./headless/VerificationChallenge.js";
+export { TotpSetup } from "./headless/TotpSetup.js";
+export type { TotpSetupBag } from "./headless/TotpSetup.js";
+export { QrLogin } from "./headless/QrLogin.js";
+export type { QrLoginBag } from "./headless/QrLogin.js";
+export { PasskeyRegistration, PasskeyLogin } from "./headless/Passkey.js";
+export type {
+  WebauthnBinding,
+  PasskeyRegistrationBag,
+  PasskeyLoginBag,
+} from "./headless/Passkey.js";
+export {
+  MagicLink,
+  AnonymousSession,
+  SsoDiscovery,
+  AuthenticatorChange,
+} from "./headless/misc.js";
+export type {
+  MagicLinkBag,
+  AnonymousBag,
+  SsoDiscoveryBag,
+  AuthenticatorChangeBag,
+} from "./headless/misc.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export {
+  AUTH_I18N_KEYS,
+  authI18nBundleEn,
+  registerAuthI18n,
+} from "./i18n/keys.js";
+export type { AuthI18nKey } from "./i18n/keys.js";

package/src/model/context.tsx

@@ -0,0 +1,51 @@
+import { createContext, useContext, useSyncExternalStore } from "react";
+import type { Context } from "react";
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { VerificationController } from "../flows/verificationFlow.js";
+import type { AuthRuntime } from "./runtime.js";
+import type { AuthSession, AuthSessionState } from "./session.js";
+
+/**
+ * The auth runtime shared through React context by `<AuthProvider>`. Hooks in
+ * `model/` and `headless/` read the wired singletons from here; per-flow
+ * machines are created by the headless components using `useAuthApi()` +
+ * `useAuthAnalytics()`.
+ */
+export const AuthRuntimeContext: Context<AuthRuntime | null> =
+  createContext<AuthRuntime | null>(null);
+
+export function useAuthRuntime(): AuthRuntime {
+  const runtime = useContext(AuthRuntimeContext);
+  if (runtime === null) {
+    throw new Error("Auth hooks must be used within an <AuthProvider>");
+  }
+  return runtime;
+}
+
+export function useAuthApi(): AuthApi {
+  return useAuthRuntime().api;
+}
+
+export function useAuthSession(): AuthSession {
+  return useAuthRuntime().session;
+}
+
+/** The singleton step-up verification controller (one modal per app). */
+export function useVerification(): VerificationController {
+  return useAuthRuntime().verification;
+}
+
+export function useAuthAnalytics(): Analytics | null {
+  return useAuthRuntime().analytics;
+}
+
+/** Reactive session state (user / tokens / status). Re-renders on change. */
+export function useAuthSessionState(): AuthSessionState {
+  const session = useAuthSession();
+  return useSyncExternalStore(
+    session.subscribe,
+    session.getState,
+    session.getState
+  );
+}