@stapel/auth-react 1.0.0

package/src/api/urls.ts

@@ -0,0 +1,99 @@
+/**
+ * URL builders for the **browser-redirect** auth endpoints (auth-sa.md §7/§8/
+ * §15/§18). These must never be called with `fetch` — they are full-page
+ * navigations. Callers do `window.location.assign(authUrls(...).xyz)`.
+ *
+ * Plus the two open-redirect defence helpers of auth-sa.md §19.2. Every new
+ * `?somewhere=` parameter that ends up in `location.href`/`navigate()` must
+ * pass through one of these rather than trust raw input.
+ */
+
+function trimBase(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+export interface AuthUrls {
+  /** Server-side OAuth redirect (auth-sa.md §7 option A). */
+  oauthAuthorize(provider: string, redirectUri: string): string;
+  /** Enterprise SSO login redirect (auth-sa.md §18.1 step 2). */
+  ssoLogin(orgSlug: string): string;
+  /** The URL embedded in a QR image — opened by the scanner's browser only. */
+  qrScan(key: string): string;
+  /** SP metadata URL surfaced to a customer's IT admin (auth-sa.md §18.4). */
+  ssoSamlMetadata(orgSlug: string): string;
+}
+
+/** Build the browser-redirect URLs against a client base URL (e.g. `/auth/api`). */
+export function authUrls(baseUrl: string): AuthUrls {
+  const base = trimBase(baseUrl);
+  return {
+    oauthAuthorize: (provider, redirectUri) =>
+      `${base}/oauth/${provider}/authorize/?redirect_uri=${encodeURIComponent(
+        redirectUri
+      )}`,
+    ssoLogin: (orgSlug) => `${base}/sso/${orgSlug}/login/`,
+    qrScan: (key) => `${base}/qr/${key}/scan/`,
+    ssoSamlMetadata: (orgSlug) => `${base}/sso/${orgSlug}/saml/metadata/`,
+  };
+}
+
+/**
+ * `redirect_url` for magic-link / QR generation must be a **relative** path
+ * starting with a single `/` (auth-sa.md §8/§15 — open-redirect defence).
+ * Returns the path unchanged when valid, else `null`.
+ */
+export function validRedirectUrl(raw: string): string | null {
+  if (raw.length === 0) return null;
+  if (!raw.startsWith("/")) return null;
+  if (raw.startsWith("//")) return null;
+  return raw;
+}
+
+/**
+ * auth-sa.md §19.2 `safeNextPath`: accept a relative path (single leading `/`,
+ * not `//`) or a same-origin absolute URL reduced to `pathname+search+hash`.
+ * Anything cross-origin / unrecognised returns `null`; callers fall back to a
+ * safe default (e.g. `/app`).
+ */
+export function safeNextPath(
+  raw: string | null | undefined,
+  origin?: string
+): string | null {
+  if (raw == null || raw.length === 0) return null;
+  if (raw.startsWith("/") && !raw.startsWith("//")) return raw;
+  const selfOrigin =
+    origin ??
+    (typeof window !== "undefined" ? window.location.origin : undefined);
+  if (selfOrigin === undefined) return null;
+  try {
+    const url = new URL(raw, selfOrigin);
+    if (url.origin !== selfOrigin) return null;
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * auth-sa.md §19.2 `safeScanRedirect`: accept only same-origin URLs whose path
+ * starts with `/auth/api/qr/` (the QR scan-flow continuation). Used for
+ * `?redirect=` on `/sign-in`.
+ */
+export function safeScanRedirect(
+  raw: string | null | undefined,
+  origin?: string
+): string | null {
+  if (raw == null || raw.length === 0) return null;
+  const selfOrigin =
+    origin ??
+    (typeof window !== "undefined" ? window.location.origin : undefined);
+  if (selfOrigin === undefined) return null;
+  try {
+    const url = new URL(raw, selfOrigin);
+    if (url.origin !== selfOrigin) return null;
+    if (!url.pathname.startsWith("/auth/api/qr/")) return null;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}

package/src/flows/anonymousFlow.ts

@@ -0,0 +1,57 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse } 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";
+
+/**
+ * Anonymous session for onboarding-before-signup (auth-sa.md §6). A single
+ * call; passing the same `device_id` within 60 s dedups to the same anonymous
+ * user. A later email/phone verify upgrades or merges this session.
+ */
+export type AnonymousState =
+  | { readonly step: "idle" }
+  | { readonly step: "creating" }
+  | { readonly step: "authenticated"; readonly result: AuthResponse }
+  | { readonly step: "error"; readonly error: FlowError };
+
+export interface AnonymousFlow {
+  readonly machine: FlowMachine<AnonymousState>;
+  create(deviceId?: string): Promise<void>;
+  reset(): void;
+}
+
+export interface AnonymousFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  readonly onAuthenticated?: (result: AuthResponse) => void;
+}
+
+export function createAnonymousFlow(deps: AnonymousFlowDeps): AnonymousFlow {
+  const machine = createFlowMachine<AnonymousState>({
+    id: "auth.anonymous",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function create(deviceId?: string): Promise<void> {
+    await machine.run({ step: "creating" }, () => deps.api.anonymous(deviceId), {
+      resolve: (result): AnonymousState => {
+        deps.onAuthenticated?.(result);
+        return { step: "authenticated", result };
+      },
+      reject: (error): AnonymousState => ({
+        step: "error",
+        error: toFlowError(error),
+      }),
+    });
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, create, reset };
+}

package/src/flows/authenticatorChangeFlow.ts

@@ -0,0 +1,160 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse, OtpChannel } 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";
+
+/**
+ * Authenticator (email/phone) change — INSTANT strategy (auth-sa.md §9). A
+ * four-hop human-wait chain proving the *old* value, then setting the *new*:
+ * request-old → verify-old (mints a `change_token`) → request-new → verify-new
+ * (→ `MODIFIED` session). The DELAYED strategy (14-day wait, no old access) is
+ * plain CRUD — use `api.changeDelayedInitiate/Status/Cancel` or the
+ * `useDelayedChangeStatus` model hook directly.
+ */
+export type AuthenticatorChangeState =
+  | { readonly step: "idle" }
+  | { readonly step: "requestingOld"; readonly channel: OtpChannel }
+  | { readonly step: "oldCodeSent"; readonly channel: OtpChannel; readonly target: string }
+  | { readonly step: "verifyingOld"; readonly channel: OtpChannel }
+  | {
+      readonly step: "oldVerified";
+      readonly channel: OtpChannel;
+      readonly changeToken: string;
+    }
+  | {
+      readonly step: "requestingNew";
+      readonly channel: OtpChannel;
+      readonly changeToken: string;
+      readonly newValue: string;
+    }
+  | {
+      readonly step: "newCodeSent";
+      readonly channel: OtpChannel;
+      readonly changeToken: string;
+      readonly newValue: string;
+      readonly target: string;
+    }
+  | {
+      readonly step: "verifyingNew";
+      readonly channel: OtpChannel;
+      readonly changeToken: string;
+      readonly newValue: string;
+    }
+  | { readonly step: "changed"; readonly result: AuthResponse }
+  | { readonly step: "error"; readonly error: FlowError };
+
+export interface AuthenticatorChangeFlow {
+  readonly machine: FlowMachine<AuthenticatorChangeState>;
+  startInstant(channel: OtpChannel): Promise<void>;
+  submitOldCode(code: string): Promise<void>;
+  requestNew(newValue: string): Promise<void>;
+  submitNewCode(code: string): Promise<void>;
+  reset(): void;
+}
+
+export interface AuthenticatorChangeFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  readonly onAuthenticated?: (result: AuthResponse) => void;
+}
+
+export function createAuthenticatorChangeFlow(
+  deps: AuthenticatorChangeFlowDeps
+): AuthenticatorChangeFlow {
+  const machine = createFlowMachine<AuthenticatorChangeState>({
+    id: "auth.authenticator_change",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function startInstant(channel: OtpChannel): Promise<void> {
+    await machine.run(
+      { step: "requestingOld", channel },
+      () => deps.api.changeInstantRequestOld(channel),
+      {
+        resolve: (r): AuthenticatorChangeState => ({
+          step: "oldCodeSent",
+          channel,
+          target: r.target,
+        }),
+        reject: (error): AuthenticatorChangeState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function submitOldCode(code: string): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "oldCodeSent") return;
+    const { channel } = s;
+    await machine.run(
+      { step: "verifyingOld", channel },
+      () => deps.api.changeInstantVerifyOld(channel, code),
+      {
+        resolve: (r): AuthenticatorChangeState => ({
+          step: "oldVerified",
+          channel,
+          changeToken: r.change_token,
+        }),
+        reject: (error): AuthenticatorChangeState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function requestNew(newValue: string): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "oldVerified") return;
+    const { channel, changeToken } = s;
+    await machine.run(
+      { step: "requestingNew", channel, changeToken, newValue },
+      () => deps.api.changeInstantRequestNew(channel, newValue, changeToken),
+      {
+        resolve: (r): AuthenticatorChangeState => ({
+          step: "newCodeSent",
+          channel,
+          changeToken,
+          newValue,
+          target: r.target,
+        }),
+        reject: (error): AuthenticatorChangeState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function submitNewCode(code: string): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "newCodeSent") return;
+    const { channel, changeToken, newValue } = s;
+    await machine.run(
+      { step: "verifyingNew", channel, changeToken, newValue },
+      () => deps.api.changeInstantVerifyNew(channel, newValue, code, changeToken),
+      {
+        resolve: (result): AuthenticatorChangeState => {
+          deps.onAuthenticated?.(result);
+          return { step: "changed", result };
+        },
+        reject: (error): AuthenticatorChangeState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, startInstant, submitOldCode, requestNew, submitNewCode, reset };
+}

package/src/flows/createFlowMachine.ts

@@ -0,0 +1,126 @@
+import { trackFlowStep } from "@stapel/core";
+import type { Analytics } from "@stapel/core";
+
+/**
+ * The shared flow-machine primitive — the FIRST INSTANCE of the pattern every
+ * later `@stapel/<module>-react` pair copies (frontend-standard §2, "flows/").
+ *
+ * A flow is a tiny state container whose state is a discriminated union keyed
+ * by a `step` string. Three things earn this primitive its keep across every
+ * auth journey:
+ *
+ *  1. **Typed transitions** — `to(next)` replaces state and notifies React via
+ *     `useSyncExternalStore` (see `useFlow`).
+ *  2. **Human-wait vs async steps** — a step with no pending work is just a
+ *     resting state the machine waits in for user input (`to`). Async steps go
+ *     through `run`, which parks the machine in a `pending` step, awaits the
+ *     task, then transitions to a success/failure step. `run` never throws:
+ *     rejections are folded into a state, so hosts render errors instead of
+ *     catching them. `run` is also **staleness-guarded**: if a newer `to`
+ *     happens while the task is in flight (double-submit, cancel, navigate,
+ *     challenge expiry), the late result is dropped — it never clobbers the
+ *     newer state nor runs its resolve/reject side effects.
+ *  3. **Auto-instrumentation** — every transition emits
+ *     `flow.<id>.<step>` (`started`), and every `run` emits `completed` /
+ *     `failed` for its pending step (analytics-standard §1.2). Funnels exist
+ *     without hand-written tracking.
+ */
+export interface FlowStateBase {
+  readonly step: string;
+}
+
+export interface FlowMachine<S extends FlowStateBase> {
+  /** Analytics flow id — the `<id>` in `flow.<id>.<step>`. */
+  readonly id: string;
+  getState(): S;
+  subscribe(listener: () => void): () => void;
+  /** Transition to a resting/human-wait state; emits `<step>` started. */
+  to(next: S): void;
+  /**
+   * Run an async step. Parks in `pending` immediately, awaits `task`, then
+   * transitions via `resolve`/`reject`. Emits `completed`/`failed` for the
+   * pending step. Resolves once the terminal transition is applied — it does
+   * not reject.
+   */
+  run<T>(
+    pending: S,
+    task: () => Promise<T>,
+    handlers: {
+      readonly resolve: (result: T) => S;
+      readonly reject: (error: unknown) => S;
+    }
+  ): Promise<void>;
+}
+
+export interface FlowMachineOptions<S extends FlowStateBase> {
+  /** Analytics flow id (e.g. `"auth.otp"`). */
+  readonly id: string;
+  readonly initial: S;
+  /** Facade for auto-instrumentation. Omit to disable tracking. */
+  readonly analytics?: Analytics | null;
+}
+
+export function createFlowMachine<S extends FlowStateBase>(
+  options: FlowMachineOptions<S>
+): FlowMachine<S> {
+  const { id, analytics } = options;
+  let state = options.initial;
+  const listeners = new Set<() => void>();
+
+  function emit(step: string, phase: "started" | "completed" | "failed"): void {
+    if (analytics) trackFlowStep(analytics, id, step, phase);
+  }
+
+  function notify(): void {
+    for (const listener of listeners) listener();
+  }
+
+  // Monotonic transition counter — the staleness epoch. Every `to` bumps it; a
+  // `run` captures it after parking in `pending` and only applies its terminal
+  // transition if no newer `to` happened while the task was in flight.
+  let generation = 0;
+
+  function to(next: S): void {
+    state = next;
+    generation += 1;
+    emit(next.step, "started");
+    notify();
+  }
+
+  async function run<T>(
+    pending: S,
+    task: () => Promise<T>,
+    handlers: {
+      readonly resolve: (result: T) => S;
+      readonly reject: (error: unknown) => S;
+    }
+  ): Promise<void> {
+    to(pending);
+    // Epoch of THIS run's pending transition. If it advances before the task
+    // settles (double-submit, cancel, navigate, expiry), the late result is
+    // stale and must NOT clobber the newer state — nor run its resolve/reject
+    // side effects. Analytics still fires so funnels stay honest.
+    const epoch = generation;
+    try {
+      const result = await task();
+      emit(pending.step, "completed");
+      if (generation === epoch) to(handlers.resolve(result));
+    } catch (error) {
+      emit(pending.step, "failed");
+      if (generation === epoch) to(handlers.reject(error));
+    }
+  }
+
+  return {
+    id,
+    getState: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    to,
+    run,
+  };
+}

package/src/flows/errors.ts

@@ -0,0 +1,29 @@
+import { StapelApiError } from "@stapel/core";
+
+/**
+ * Normalized error shape carried by flow error states. `code` is the backend
+ * `localizable_error` i18n key (auth-sa.md "Error reference"); `params` feed
+ * `{param}` interpolation (e.g. `retry_after_minutes`, `attempts_remaining`).
+ */
+export interface FlowError {
+  readonly code: string;
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly status: number | undefined;
+}
+
+/** Fold any thrown value into a {@link FlowError} for a flow error state. */
+export function toFlowError(error: unknown): FlowError {
+  if (error instanceof StapelApiError) {
+    return { code: error.code, params: error.params, status: error.status };
+  }
+  return {
+    code: "auth.error.unknown",
+    params: {},
+    status: undefined,
+  };
+}
+
+/** Convenience predicate: did this error carry a specific backend code? */
+export function isErrorCode(error: FlowError, code: string): boolean {
+  return error.code === code;
+}

package/src/flows/magicLinkFlow.ts

@@ -0,0 +1,68 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import { validRedirectUrl } from "../api/urls.js";
+import { createFlowMachine } from "./createFlowMachine.js";
+import type { FlowMachine } from "./createFlowMachine.js";
+import { toFlowError } from "./errors.js";
+import type { FlowError } from "./errors.js";
+
+/**
+ * Magic-link request (auth-sa.md §15). Only the *request* is a frontend flow:
+ * the email link points directly at the backend (`/auth/api/magic/verify/`),
+ * so there is no `/magic-login` page — the browser opens the link and the
+ * backend redirects (TOTP / conflict / success handled by the `/login` route
+ * consumers, not this flow). Always resolves `sent` on 200 regardless of
+ * whether the email exists (enumeration protection); only rate-limit /
+ * validation errors surface.
+ */
+export type MagicLinkState =
+  | { readonly step: "idle" }
+  | { readonly step: "requesting"; readonly email: string }
+  | { readonly step: "sent"; readonly email: string }
+  | { readonly step: "invalidRedirect"; readonly email: string }
+  | { readonly step: "error"; readonly email: string; readonly error: FlowError };
+
+export interface MagicLinkFlow {
+  readonly machine: FlowMachine<MagicLinkState>;
+  /** `redirectUrl` must be a relative path (`/...`); rejected client-side otherwise. */
+  request(email: string, redirectUrl?: string): Promise<void>;
+  reset(): void;
+}
+
+export interface MagicLinkFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+}
+
+export function createMagicLinkFlow(deps: MagicLinkFlowDeps): MagicLinkFlow {
+  const machine = createFlowMachine<MagicLinkState>({
+    id: "auth.magic_link",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function request(email: string, redirectUrl?: string): Promise<void> {
+    if (redirectUrl !== undefined && validRedirectUrl(redirectUrl) === null) {
+      machine.to({ step: "invalidRedirect", email });
+      return;
+    }
+    await machine.run(
+      { step: "requesting", email },
+      () => deps.api.magicRequest(email, redirectUrl),
+      {
+        resolve: (): MagicLinkState => ({ step: "sent", email }),
+        reject: (error): MagicLinkState => ({
+          step: "error",
+          email,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, request, reset };
+}

package/src/flows/oauthFlow.ts

@@ -0,0 +1,114 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse } from "../api/types.js";
+import { isTotpChallenge } 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";
+
+/**
+ * OAuth client-side token exchange (auth-sa.md §7 option B). For the
+ * server-side redirect (option A, recommended for web) use
+ * `authUrls(base).oauthAuthorize(provider, redirectUri)` — no flow needed, the
+ * backend sets cookies on return.
+ *
+ * The exchange can answer with the same TOTP `oneOf` union as password login
+ * (only when `OAUTH_STEP_UP` is enabled server-side), so this flow carries the
+ * identical `totpRequired` branch — completed via the same
+ * `/totp/challenge/verify/` endpoint.
+ */
+export type OAuthState =
+  | { readonly step: "idle" }
+  | { readonly step: "exchanging"; readonly provider: string }
+  | {
+      readonly step: "totpRequired";
+      readonly challengeToken: string;
+      readonly expiresIn: number;
+    }
+  | { readonly step: "verifyingTotp"; readonly challengeToken: string; readonly expiresIn: number }
+  | { readonly step: "authenticated"; readonly result: AuthResponse }
+  | { readonly step: "error"; readonly provider: string; readonly error: FlowError }
+  | {
+      readonly step: "totpError";
+      readonly challengeToken: string;
+      readonly expiresIn: number;
+      readonly error: FlowError;
+    };
+
+export interface OAuthFlow {
+  readonly machine: FlowMachine<OAuthState>;
+  exchange(provider: string, accessToken: string): Promise<void>;
+  submitTotp(proof: { code?: string; backup_code?: string }): Promise<void>;
+  reset(): void;
+}
+
+export interface OAuthFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  readonly onAuthenticated?: (result: AuthResponse) => void;
+}
+
+export function createOAuthFlow(deps: OAuthFlowDeps): OAuthFlow {
+  const machine = createFlowMachine<OAuthState>({
+    id: "auth.oauth",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function exchange(provider: string, accessToken: string): Promise<void> {
+    await machine.run(
+      { step: "exchanging", provider },
+      () => deps.api.oauthLogin(provider, accessToken),
+      {
+        resolve: (r): OAuthState => {
+          if (isTotpChallenge(r)) {
+            return {
+              step: "totpRequired",
+              challengeToken: r.challenge_token,
+              expiresIn: r.expires_in,
+            };
+          }
+          deps.onAuthenticated?.(r);
+          return { step: "authenticated", result: r };
+        },
+        reject: (error): OAuthState => ({
+          step: "error",
+          provider,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function submitTotp(proof: {
+    code?: string;
+    backup_code?: string;
+  }): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "totpRequired" && s.step !== "totpError") return;
+    const { challengeToken, expiresIn } = s;
+    await machine.run(
+      { step: "verifyingTotp", challengeToken, expiresIn },
+      () => deps.api.totpChallengeVerify(challengeToken, proof),
+      {
+        resolve: (result): OAuthState => {
+          deps.onAuthenticated?.(result);
+          return { step: "authenticated", result };
+        },
+        reject: (error): OAuthState => ({
+          step: "totpError",
+          challengeToken,
+          expiresIn,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, exchange, submitTotp, reset };
+}