@stapel/auth-react 1.0.0

package/src/flows/verificationFlow.ts

@@ -0,0 +1,341 @@
+import type {
+  Analytics,
+  VerificationChallenge,
+  VerificationChallengeHandler,
+  VerificationOutcome,
+} from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type {
+  VerificationEnvelope,
+  VerificationFactorId,
+} from "../api/types.js";
+import { createFlowMachine } from "./createFlowMachine.js";
+import type { FlowMachine } from "./createFlowMachine.js";
+import { toFlowError } from "./errors.js";
+import type { FlowError } from "./errors.js";
+
+/**
+ * THE FLAGSHIP CROSS-MODULE FLOW (frontend-standard §2).
+ *
+ * `@stapel/core`'s client intercepts a `403` whose body carries a
+ * `verification` envelope and calls `onVerificationChallenge(challenge)`,
+ * awaiting a {@link VerificationOutcome}. This controller *is* that handler: it
+ * parks a React flow-machine on the challenge, drives the user through one
+ * interchangeable factor (`otp_email` / `otp_phone` / `totp` / `passkey`), and
+ * resolves the awaited promise with `{ retry: true, token }` so core replays
+ * the original request with `X-Verification-Token`. Cancelling resolves
+ * `{ retry: false }` and the original 403 propagates.
+ *
+ * Wire it once:
+ * ```ts
+ * const verification = createVerificationController({ api });
+ * const client = createStapelClient({
+ *   baseUrl,
+ *   onVerificationChallenge: verification.handler,
+ * });
+ * // render <VerificationChallenge controller={verification}> at the app root
+ * ```
+ *
+ * Lifecycle safety: exactly one challenge is live at a time. It self-releases
+ * on `expires_at` (an abandoned modal resolves `retry:false` instead of hanging
+ * the core request forever and wedging future challenges), and a factor whose
+ * `initiate` fails recoverably returns to the picker so a different factor is
+ * still choosable — only a 404 (challenge gone) ends the whole challenge.
+ *
+ * WebAuthn note: the `passkey` factor is **flow-complete but its browser
+ * binding is a thin TODO** — the machine surfaces `session_key` + `options`
+ * and accepts a finished credential via `submitPasskey`; calling
+ * `navigator.credentials.get()` is the host's (or an injected `webauthnGet`)
+ * responsibility. See MODULE.md.
+ */
+export type VerificationState =
+  | { readonly step: "idle" }
+  | {
+      readonly step: "picking";
+      readonly challenge: VerificationEnvelope;
+      /** Set when a prior factor's initiate failed recoverably — pick another. */
+      readonly error?: FlowError;
+    }
+  | {
+      readonly step: "initiating";
+      readonly challenge: VerificationEnvelope;
+      readonly factor: VerificationFactorId;
+    }
+  | {
+      readonly step: "awaitingCode";
+      readonly challenge: VerificationEnvelope;
+      readonly factor: "otp_email" | "otp_phone" | "totp";
+      readonly target: string | null;
+    }
+  | {
+      readonly step: "awaitingPasskey";
+      readonly challenge: VerificationEnvelope;
+      readonly sessionKey: string;
+      readonly options: Record<string, unknown>;
+    }
+  | {
+      readonly step: "verifying";
+      readonly challenge: VerificationEnvelope;
+      readonly factor: VerificationFactorId;
+    }
+  | { readonly step: "verified"; readonly token: string }
+  | {
+      readonly step: "factorError";
+      readonly challenge: VerificationEnvelope;
+      readonly factor: VerificationFactorId;
+      readonly target: string | null;
+      readonly error: FlowError;
+    }
+  | { readonly step: "unavailable"; readonly error: FlowError }
+  | { readonly step: "expired" };
+
+export interface VerificationController {
+  readonly machine: FlowMachine<VerificationState>;
+  /** The handler wired into `createStapelClient({ onVerificationChallenge })`. */
+  readonly handler: VerificationChallengeHandler;
+  /** Choose one of the challenge's factors and initiate it. */
+  chooseFactor(factor: VerificationFactorId): Promise<void>;
+  /** Submit an OTP/TOTP code (or a TOTP backup code). */
+  submitCode(proof: { code?: string; backup_code?: string }): Promise<void>;
+  /** Submit a finished WebAuthn assertion for the `passkey` factor. */
+  submitPasskey(credential: unknown): Promise<void>;
+  /** Abandon the challenge — resolves the awaited outcome with `retry:false`. */
+  cancel(): void;
+}
+
+export interface VerificationControllerDeps {
+  /** Lazy-friendly: a thunk breaks the client↔controller wiring cycle. */
+  readonly api: AuthApi | (() => AuthApi);
+  readonly analytics?: Analytics | null;
+  /**
+   * Optional WebAuthn binding. When provided, choosing the `passkey` factor
+   * auto-calls it with the server `options` and submits the result — the host
+   * needs no passkey code. Thin by design; omit to drive it manually.
+   */
+  readonly webauthnGet?: (
+    options: Record<string, unknown>
+  ) => Promise<unknown>;
+}
+
+const NOT_FOUND_STATUS = 404;
+const LOCKED_STATUS = 423;
+
+function asEnvelope(challenge: VerificationChallenge): VerificationEnvelope {
+  return {
+    challenge_id: challenge.challenge_id,
+    scope: typeof challenge.scope === "string" ? challenge.scope : "",
+    factors: (challenge.factors ?? []) as readonly VerificationFactorId[],
+    expires_at:
+      typeof challenge["expires_at"] === "number"
+        ? (challenge["expires_at"] as number)
+        : 0,
+  };
+}
+
+export function createVerificationController(
+  deps: VerificationControllerDeps
+): VerificationController {
+  const machine = createFlowMachine<VerificationState>({
+    id: "auth.verification",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+  const api = (): AuthApi =>
+    typeof deps.api === "function" ? deps.api() : deps.api;
+
+  // The awaited outcome for the in-flight core request. Exactly one challenge
+  // is handled at a time; a second arriving while one is active is declined.
+  let resolveOutcome: ((outcome: VerificationOutcome) => void) | null = null;
+  // Self-release timer: without it, a user who abandons the modal (never
+  // cancels) leaves the core `await onVerificationChallenge(...)` hanging
+  // forever AND — because `resolveOutcome` stays set — wedges every FUTURE
+  // challenge into `retry:false`. The envelope's `expires_at` bounds this.
+  let expiryTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function clearExpiry(): void {
+    if (expiryTimer !== null) {
+      clearTimeout(expiryTimer);
+      expiryTimer = null;
+    }
+  }
+
+  function settle(outcome: VerificationOutcome): void {
+    clearExpiry();
+    const resolve = resolveOutcome;
+    resolveOutcome = null;
+    resolve?.(outcome);
+  }
+
+  function scheduleExpiry(envelope: VerificationEnvelope): void {
+    clearExpiry();
+    if (!envelope.expires_at) return; // no bound advertised
+    const fire = (): void => {
+      if (resolveOutcome === null) return; // already settled
+      machine.to({ step: "expired" });
+      settle({ retry: false });
+    };
+    const delayMs = envelope.expires_at * 1000 - Date.now();
+    if (delayMs <= 0) {
+      fire();
+      return;
+    }
+    expiryTimer = setTimeout(fire, delayMs);
+  }
+
+  const handler: VerificationChallengeHandler = (challenge) => {
+    if (resolveOutcome !== null) {
+      // Already busy with another challenge — decline the new one.
+      return Promise.resolve({ retry: false });
+    }
+    const envelope = asEnvelope(challenge);
+    return new Promise<VerificationOutcome>((resolve) => {
+      resolveOutcome = resolve;
+      machine.to({ step: "picking", challenge: envelope });
+      scheduleExpiry(envelope);
+    });
+  };
+
+  function currentChallenge(): VerificationEnvelope | null {
+    const s = machine.getState();
+    if ("challenge" in s) return s.challenge;
+    return null;
+  }
+
+  function foldUnavailable(error: FlowError): VerificationState | null {
+    if (error.status === NOT_FOUND_STATUS || error.status === LOCKED_STATUS) {
+      return { step: "unavailable", error };
+    }
+    return null;
+  }
+
+  async function chooseFactor(factor: VerificationFactorId): Promise<void> {
+    const challenge = currentChallenge();
+    if (challenge === null) return;
+
+    await machine.run(
+      { step: "initiating", challenge, factor },
+      () => api().verificationInitiate(challenge.challenge_id, factor),
+      {
+        resolve: (r): VerificationState => {
+          if (factor === "passkey") {
+            const sessionKey = String(r.data["session_key"] ?? "");
+            const options = (r.data["options"] ?? {}) as Record<string, unknown>;
+            return {
+              step: "awaitingPasskey",
+              challenge,
+              sessionKey,
+              options,
+            };
+          }
+          const target =
+            typeof r.data["target"] === "string"
+              ? (r.data["target"] as string)
+              : null;
+          return { step: "awaitingCode", challenge, factor, target };
+        },
+        reject: (error): VerificationState => {
+          const flowError = toFlowError(error);
+          // A 404 means the whole challenge is gone — restart the original
+          // action; release the core request.
+          if (flowError.status === NOT_FOUND_STATUS) {
+            settle({ retry: false });
+            return { step: "unavailable", error: flowError };
+          }
+          // Any other initiate failure (a locked/invalid factor, network) is
+          // factor-scoped: keep the challenge alive and return to the picker so
+          // the user can choose a DIFFERENT factor. A 423-locked email factor
+          // must not kill an available TOTP factor. Do NOT settle — the expiry
+          // timer still bounds abandonment.
+          return { step: "picking", challenge, error: flowError };
+        },
+      }
+    );
+
+    // Auto-drive the passkey factor when a binding is injected (thin seam).
+    const after = machine.getState();
+    if (after.step === "awaitingPasskey" && deps.webauthnGet) {
+      try {
+        const credential = await deps.webauthnGet(after.options);
+        await submitPasskey(credential);
+      } catch (error) {
+        machine.to({
+          step: "factorError",
+          challenge,
+          factor: "passkey",
+          target: null,
+          error: toFlowError(error),
+        });
+      }
+    }
+  }
+
+  async function complete(
+    challenge: VerificationEnvelope,
+    factor: VerificationFactorId,
+    target: string | null,
+    body: Record<string, unknown>
+  ): Promise<void> {
+    await machine.run(
+      { step: "verifying", challenge, factor },
+      () => api().verificationComplete(challenge.challenge_id, body),
+      {
+        resolve: (r): VerificationState => {
+          settle({ retry: true, token: r.verification_token });
+          return { step: "verified", token: r.verification_token };
+        },
+        reject: (error): VerificationState => {
+          const flowError = toFlowError(error);
+          const unavailable = foldUnavailable(flowError);
+          if (unavailable) {
+            settle({ retry: false });
+            return unavailable;
+          }
+          // Recoverable (wrong code) — stay in the flow for a retry.
+          return { step: "factorError", challenge, factor, target, error: flowError };
+        },
+      }
+    );
+  }
+
+  async function submitCode(proof: {
+    code?: string;
+    backup_code?: string;
+  }): Promise<void> {
+    const s = machine.getState();
+    let challenge: VerificationEnvelope;
+    let factor: VerificationFactorId;
+    let target: string | null;
+    if (s.step === "awaitingCode") {
+      ({ challenge, factor, target } = s);
+    } else if (s.step === "factorError" && s.factor !== "passkey") {
+      ({ challenge, factor, target } = s);
+    } else {
+      return;
+    }
+    await complete(challenge, factor, target, { factor, ...proof });
+  }
+
+  async function submitPasskey(credential: unknown): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "awaitingPasskey") return;
+    await complete(s.challenge, "passkey", null, {
+      factor: "passkey",
+      session_key: s.sessionKey,
+      credential,
+    });
+  }
+
+  function cancel(): void {
+    settle({ retry: false });
+    machine.to({ step: "idle" });
+  }
+
+  return {
+    machine,
+    handler,
+    chooseFactor,
+    submitCode,
+    submitPasskey,
+    cancel,
+  };
+}

package/src/headless/AuthProvider.tsx

@@ -0,0 +1,30 @@
+import { useEffect } from "react";
+import type { ReactElement, ReactNode } from "react";
+import { AuthRuntimeContext } from "../model/context.js";
+import type { AuthRuntime } from "../model/runtime.js";
+
+/**
+ * Provides the wired {@link AuthRuntime} to every auth hook and headless
+ * component below it, and restores any persisted session once on mount. Bring
+ * your own visual shell — this component renders nothing of its own.
+ *
+ * ```tsx
+ * const runtime = createAuthRuntime({ baseUrl: "/auth/api", storage });
+ * // give runtime.client to core's <StapelConfigProvider config={{ client }}>
+ * <AuthProvider runtime={runtime}>{app}</AuthProvider>
+ * ```
+ */
+export function AuthProvider(props: {
+  runtime: AuthRuntime;
+  children: ReactNode;
+}): ReactElement {
+  const { runtime } = props;
+  useEffect(() => {
+    void runtime.session.restore();
+  }, [runtime]);
+  return (
+    <AuthRuntimeContext.Provider value={runtime}>
+      {props.children}
+    </AuthRuntimeContext.Provider>
+  );
+}

package/src/headless/Passkey.tsx

@@ -0,0 +1,97 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import {
+  createPasskeyLoginFlow,
+  createPasskeyRegistrationFlow,
+} from "../flows/passkeyFlow.js";
+import type {
+  PasskeyLoginState,
+  PasskeyRegisterState,
+} from "../flows/passkeyFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi, useAuthSession } from "../model/context.js";
+
+/**
+ * Optional WebAuthn binding injected into the passkey headless components.
+ * THIN by design (auth-sa.md §17): when omitted, the host performs the
+ * `navigator.credentials.*` ceremony and calls `submit*` with the result.
+ */
+export type WebauthnBinding = (
+  options: Record<string, unknown>
+) => Promise<unknown>;
+
+export interface PasskeyRegistrationBag {
+  readonly state: PasskeyRegisterState;
+  begin(deviceName?: string): void;
+  submitCredential(credential: unknown): void;
+  reset(): void;
+}
+
+/** Headless passkey registration (auth-sa.md §17, requires auth). */
+export function PasskeyRegistration(props: {
+  children: (bag: PasskeyRegistrationBag) => ReactNode;
+  webauthnCreate?: WebauthnBinding;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const { webauthnCreate } = props;
+  const flow = useMemo(
+    () =>
+      createPasskeyRegistrationFlow({
+        api,
+        analytics,
+        ...(webauthnCreate !== undefined ? { webauthnCreate } : {}),
+      }),
+    [api, analytics, webauthnCreate]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    begin: (deviceName) => {
+      void flow.begin(deviceName);
+    },
+    submitCredential: (credential) => {
+      void flow.submitCredential(credential);
+    },
+    reset: flow.reset,
+  });
+}
+
+export interface PasskeyLoginBag {
+  readonly state: PasskeyLoginState;
+  begin(email?: string): void;
+  submitAssertion(credential: unknown): void;
+  reset(): void;
+}
+
+/** Headless passkey login (auth-sa.md §17, no auth required). */
+export function PasskeyLogin(props: {
+  children: (bag: PasskeyLoginBag) => ReactNode;
+  webauthnGet?: WebauthnBinding;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const session = useAuthSession();
+  const { webauthnGet } = props;
+  const flow = useMemo(
+    () =>
+      createPasskeyLoginFlow({
+        api,
+        analytics,
+        onAuthenticated: (r) => session.adopt(r),
+        ...(webauthnGet !== undefined ? { webauthnGet } : {}),
+      }),
+    [api, analytics, session, webauthnGet]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    begin: (email) => {
+      void flow.begin(email);
+    },
+    submitAssertion: (credential) => {
+      void flow.submitAssertion(credential);
+    },
+    reset: flow.reset,
+  });
+}

package/src/headless/PasswordChange.tsx

@@ -0,0 +1,46 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import type { OtpChannel } from "../api/types.js";
+import { createPasswordChangeFlow } from "../flows/passwordChangeFlow.js";
+import type { PasswordChangeState } from "../flows/passwordChangeFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi } from "../model/context.js";
+
+export interface PasswordChangeBag {
+  readonly state: PasswordChangeState;
+  changeWithPassword(oldPassword: string, newPassword: string): void;
+  requestOtp(method: OtpChannel): void;
+  submitOtp(code: string, newPassword: string): void;
+  reset(): void;
+}
+
+/**
+ * Headless authenticated password change (auth-sa.md §4). Pair with
+ * `usePasswordMethods()` to decide which tabs to render; call
+ * `changeWithPassword` for the old-password tab or `requestOtp`/`submitOtp`
+ * for the email/SMS tabs.
+ */
+export function PasswordChange(props: {
+  children: (bag: PasswordChangeBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const flow = useMemo(
+    () => createPasswordChangeFlow({ api, analytics }),
+    [api, analytics]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    changeWithPassword: (oldPassword, newPassword) => {
+      void flow.changeWithPassword(oldPassword, newPassword);
+    },
+    requestOtp: (method) => {
+      void flow.requestOtp(method);
+    },
+    submitOtp: (code, newPassword) => {
+      void flow.submitOtp(code, newPassword);
+    },
+    reset: flow.reset,
+  });
+}

package/src/headless/PasswordLogin.tsx

@@ -0,0 +1,49 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import { createPasswordLoginFlow } from "../flows/passwordLoginFlow.js";
+import type {
+  PasswordLoginState,
+  TotpProof,
+} from "../flows/passwordLoginFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi, useAuthSession } from "../model/context.js";
+
+export interface PasswordLoginBag {
+  readonly state: PasswordLoginState;
+  login(loginId: string, password: string): void;
+  submitTotp(proof: TotpProof): void;
+  reset(): void;
+}
+
+/**
+ * Headless password login with the TOTP step-up branch (auth-sa.md §3 + §11).
+ * When `state.step === "totpRequired"`, render a TOTP input and call
+ * `submitTotp({ code })` (or `{ backup_code }`).
+ */
+export function PasswordLogin(props: {
+  children: (bag: PasswordLoginBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const session = useAuthSession();
+  const flow = useMemo(
+    () =>
+      createPasswordLoginFlow({
+        api,
+        analytics,
+        onAuthenticated: (r) => session.adopt(r),
+      }),
+    [api, analytics, session]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    login: (loginId, password) => {
+      void flow.login(loginId, password);
+    },
+    submitTotp: (proof) => {
+      void flow.submitTotp(proof);
+    },
+    reset: flow.reset,
+  });
+}

package/src/headless/PasswordReset.tsx

@@ -0,0 +1,51 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import type { OtpChannel } from "../api/types.js";
+import { createPasswordResetFlow } from "../flows/passwordResetFlow.js";
+import type { PasswordResetState } from "../flows/passwordResetFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi, useAuthSession } from "../model/context.js";
+
+export interface PasswordResetBag {
+  readonly state: PasswordResetState;
+  request(channel: OtpChannel, value: string): void;
+  resend(): void;
+  submit(code: string, newPassword: string): void;
+  reset(): void;
+}
+
+/**
+ * Headless unauthenticated password reset (auth-sa.md §5). The `codeSent`
+ * human-wait collects the code AND the new password together, then the user
+ * lands in a fresh session (`authenticated`).
+ */
+export function PasswordReset(props: {
+  children: (bag: PasswordResetBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const session = useAuthSession();
+  const flow = useMemo(
+    () =>
+      createPasswordResetFlow({
+        api,
+        analytics,
+        onAuthenticated: (r) => session.adopt(r),
+      }),
+    [api, analytics, session]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    request: (channel, value) => {
+      void flow.request(channel, value);
+    },
+    resend: () => {
+      void flow.resend();
+    },
+    submit: (code, newPassword) => {
+      void flow.submit(code, newPassword);
+    },
+    reset: flow.reset,
+  });
+}

package/src/headless/PasswordlessLogin.tsx

@@ -0,0 +1,60 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import type { OtpChannel } from "../api/types.js";
+import { createOtpFlow } from "../flows/otpFlow.js";
+import type { OtpState } from "../flows/otpFlow.js";
+import { useFlow } from "../flows/useFlow.js";
+import { useAuthAnalytics, useAuthApi, useAuthSession } from "../model/context.js";
+
+/** Render-prop bag for {@link PasswordlessLogin}. */
+export interface PasswordlessLoginBag {
+  readonly state: OtpState;
+  requestCode(channel: OtpChannel, value: string, captchaToken?: string): void;
+  resend(captchaToken?: string): void;
+  submitCode(code: string): void;
+  reset(): void;
+}
+
+/**
+ * Headless Email/Phone OTP login (auth-sa.md §1–2). Owns an `otpFlow` machine
+ * and hands its state + actions to a render prop — you supply the markup.
+ *
+ * ```tsx
+ * <PasswordlessLogin>
+ *   {({ state, requestCode, submitCode }) =>
+ *     state.step === "codeSent"
+ *       ? <CodeForm onSubmit={submitCode} />
+ *       : <EmailForm onSubmit={(e) => requestCode("email", e)} />}
+ * </PasswordlessLogin>
+ * ```
+ */
+export function PasswordlessLogin(props: {
+  children: (bag: PasswordlessLoginBag) => ReactNode;
+}): ReactNode {
+  const api = useAuthApi();
+  const analytics = useAuthAnalytics();
+  const session = useAuthSession();
+  const flow = useMemo(
+    () =>
+      createOtpFlow({
+        api,
+        analytics,
+        onAuthenticated: (r) => session.adopt(r),
+      }),
+    [api, analytics, session]
+  );
+  const state = useFlow(flow.machine);
+  return props.children({
+    state,
+    requestCode: (channel, value, captchaToken) => {
+      void flow.requestCode(channel, value, captchaToken);
+    },
+    resend: (captchaToken) => {
+      void flow.resend(captchaToken);
+    },
+    submitCode: (code) => {
+      void flow.submitCode(code);
+    },
+    reset: flow.reset,
+  });
+}