@stapel/auth-react 1.0.0

package/src/flows/passwordResetFlow.ts

@@ -0,0 +1,123 @@
+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";
+
+/**
+ * Unauthenticated password reset (auth-sa.md §5). User proves ownership of an
+ * email/phone via OTP and receives a fresh session with the new password. The
+ * verify step carries the new password, so this is a two-input human-wait
+ * (`codeSent`): code + new password together.
+ */
+export type PasswordResetState =
+  | { readonly step: "idle" }
+  | { readonly step: "requesting"; readonly channel: OtpChannel; readonly value: string }
+  | {
+      readonly step: "codeSent";
+      readonly channel: OtpChannel;
+      readonly value: string;
+      readonly target: string;
+    }
+  | { readonly step: "verifying"; readonly channel: OtpChannel; readonly value: string; readonly target: string }
+  | { readonly step: "authenticated"; readonly result: AuthResponse }
+  | {
+      readonly step: "requestError";
+      readonly channel: OtpChannel;
+      readonly value: string;
+      readonly error: FlowError;
+    }
+  | {
+      readonly step: "codeError";
+      readonly channel: OtpChannel;
+      readonly value: string;
+      readonly target: string;
+      readonly error: FlowError;
+    };
+
+export interface PasswordResetFlow {
+  readonly machine: FlowMachine<PasswordResetState>;
+  request(channel: OtpChannel, value: string): Promise<void>;
+  resend(): Promise<void>;
+  submit(code: string, newPassword: string): Promise<void>;
+  reset(): void;
+}
+
+export interface PasswordResetFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  readonly onAuthenticated?: (result: AuthResponse) => void;
+}
+
+export function createPasswordResetFlow(
+  deps: PasswordResetFlowDeps
+): PasswordResetFlow {
+  const machine = createFlowMachine<PasswordResetState>({
+    id: "auth.password_reset",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function request(channel: OtpChannel, value: string): Promise<void> {
+    await machine.run(
+      { step: "requesting", channel, value },
+      () => deps.api.passwordResetRequest(channel, value),
+      {
+        resolve: (r): PasswordResetState => ({
+          step: "codeSent",
+          channel,
+          value,
+          target: r.target,
+        }),
+        reject: (error): PasswordResetState => ({
+          step: "requestError",
+          channel,
+          value,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function resend(): Promise<void> {
+    const s = machine.getState();
+    if (
+      s.step === "codeSent" ||
+      s.step === "codeError" ||
+      s.step === "requestError"
+    ) {
+      await request(s.channel, s.value);
+    }
+  }
+
+  async function submit(code: string, newPassword: string): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "codeSent" && s.step !== "codeError") return;
+    const { channel, value, target } = s;
+    await machine.run(
+      { step: "verifying", channel, value, target },
+      () => deps.api.passwordResetVerify(channel, value, code, newPassword),
+      {
+        resolve: (result): PasswordResetState => {
+          deps.onAuthenticated?.(result);
+          return { step: "authenticated", result };
+        },
+        reject: (error): PasswordResetState => ({
+          step: "codeError",
+          channel,
+          value,
+          target,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, request, resend, submit, reset };
+}

package/src/flows/qrLoginFlow.ts

@@ -0,0 +1,158 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthTokens, QrType } 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";
+
+/**
+ * QR authentication with background polling (auth-sa.md §8). Serves both the
+ * `login_request` sign-in tab (polling device receives `access_token` /
+ * `refresh_token` on fulfilment) and the `session_share` profile modal (the
+ * *scanning* device gets the session; the generator just watches for
+ * `fulfilled`).
+ *
+ * Device binding matters: generate and poll from the same browser context so
+ * the httponly `stapel_qr_<key>` cookie is present (the client must send
+ * credentials). On `expired` the flow auto-regenerates and resets the poll
+ * loop, per spec.
+ */
+export type QrLoginState =
+  | { readonly step: "idle" }
+  | { readonly step: "generating"; readonly type: QrType }
+  | {
+      readonly step: "awaitingScan";
+      readonly type: QrType;
+      readonly key: string;
+      readonly scanUrl: string;
+      readonly expiresIn: number;
+    }
+  | { readonly step: "fulfilled"; readonly tokens: AuthTokens | null }
+  | { readonly step: "rejected"; readonly key: string }
+  | { readonly step: "error"; readonly error: FlowError };
+
+export interface QrLoginFlow {
+  readonly machine: FlowMachine<QrLoginState>;
+  /** Generate a QR and begin the poll loop. */
+  start(
+    type: QrType,
+    redirectUrl: string,
+    allowUnauthenticatedScanner?: boolean
+  ): Promise<void>;
+  /** Stop polling and reset to idle (call on modal close / unmount). */
+  dispose(): void;
+}
+
+export interface QrLoginFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  /** For `login_request` fulfilment — receives the delivered tokens. */
+  readonly onAuthenticated?: (tokens: AuthTokens) => void;
+  /** Poll cadence; default 5000 ms (auth-sa.md §8). */
+  readonly pollIntervalMs?: number;
+}
+
+export function createQrLoginFlow(deps: QrLoginFlowDeps): QrLoginFlow {
+  const machine = createFlowMachine<QrLoginState>({
+    id: "auth.qr_login",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+  const interval = deps.pollIntervalMs ?? 5000;
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let params: {
+    type: QrType;
+    redirectUrl: string;
+    allowUnauth: boolean | undefined;
+  } | null = null;
+
+  function clearTimer(): void {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+
+  function schedulePoll(key: string): void {
+    clearTimer();
+    timer = setTimeout(() => {
+      void poll(key);
+    }, interval);
+  }
+
+  async function poll(key: string): Promise<void> {
+    // Bail if the machine moved on (disposed / regenerated).
+    const s = machine.getState();
+    if (s.step !== "awaitingScan" || s.key !== key) return;
+    try {
+      const status = await deps.api.qrStatus(key);
+      if (machine.getState().step !== "awaitingScan") return;
+      switch (status.status) {
+        case "pending":
+          schedulePoll(key);
+          break;
+        case "fulfilled": {
+          clearTimer();
+          const tokens: AuthTokens | null =
+            status.access_token !== undefined && status.refresh_token !== undefined
+              ? { access: status.access_token, refresh: status.refresh_token }
+              : null;
+          if (tokens) deps.onAuthenticated?.(tokens);
+          machine.to({ step: "fulfilled", tokens });
+          break;
+        }
+        case "expired":
+          clearTimer();
+          if (params) {
+            void start(params.type, params.redirectUrl, params.allowUnauth);
+          }
+          break;
+        case "rejected":
+          clearTimer();
+          machine.to({ step: "rejected", key });
+          break;
+      }
+    } catch (error) {
+      clearTimer();
+      machine.to({ step: "error", error: toFlowError(error) });
+    }
+  }
+
+  async function start(
+    type: QrType,
+    redirectUrl: string,
+    allowUnauthenticatedScanner?: boolean
+  ): Promise<void> {
+    clearTimer();
+    params = { type, redirectUrl, allowUnauth: allowUnauthenticatedScanner };
+    await machine.run(
+      { step: "generating", type },
+      () => deps.api.qrGenerate(type, redirectUrl, allowUnauthenticatedScanner),
+      {
+        resolve: (r): QrLoginState => ({
+          step: "awaitingScan",
+          type,
+          key: r.key,
+          scanUrl: r.scan_url,
+          expiresIn: r.expires_in,
+        }),
+        reject: (error): QrLoginState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+    const after = machine.getState();
+    if (after.step === "awaitingScan") schedulePoll(after.key);
+  }
+
+  function dispose(): void {
+    clearTimer();
+    params = null;
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, start, dispose };
+}

package/src/flows/ssoFlow.ts

@@ -0,0 +1,84 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { SsoLookupResponse } from "../api/types.js";
+import { authUrls } 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";
+
+/**
+ * Enterprise SSO discovery (auth-sa.md §18). The flow covers the *frontend*
+ * part: look up a domain after the user types their email, then decide what to
+ * render. Actual login is a full-page browser navigation to
+ * `authUrls(base).ssoLogin(orgSlug)` — the backend handles SAML/OIDC opaquely
+ * and drops the user back on `FRONTEND_URL/` with cookies set. `beginLogin`
+ * performs that navigation when a redirector is available.
+ */
+export type SsoState =
+  | { readonly step: "idle" }
+  | { readonly step: "looking"; readonly domain: string }
+  | {
+      readonly step: "resolved";
+      readonly domain: string;
+      readonly result: SsoLookupResponse;
+    }
+  | { readonly step: "error"; readonly domain: string; readonly error: FlowError };
+
+export interface SsoFlow {
+  readonly machine: FlowMachine<SsoState>;
+  /** Look up SSO for an email domain (`sso_required` / optional / none). */
+  lookup(domain: string): Promise<void>;
+  /** Navigate the browser to the SSO login endpoint for an org slug. */
+  beginLogin(orgSlug: string): void;
+  reset(): void;
+}
+
+export interface SsoFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  /**
+   * Full-page redirect seam (default `window.location.assign`). Injectable for
+   * tests / custom routers.
+   */
+  readonly redirect?: (url: string) => void;
+}
+
+export function createSsoFlow(deps: SsoFlowDeps): SsoFlow {
+  const machine = createFlowMachine<SsoState>({
+    id: "auth.sso",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function lookup(domain: string): Promise<void> {
+    await machine.run(
+      { step: "looking", domain },
+      () => deps.api.ssoLookup(domain),
+      {
+        resolve: (result): SsoState => ({ step: "resolved", domain, result }),
+        reject: (error): SsoState => ({
+          step: "error",
+          domain,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function beginLogin(orgSlug: string): void {
+    const url = authUrls(deps.api.client.baseUrl).ssoLogin(orgSlug);
+    const go =
+      deps.redirect ??
+      ((target: string) => {
+        if (typeof window !== "undefined") window.location.assign(target);
+      });
+    go(url);
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, lookup, beginLogin, reset };
+}

package/src/flows/totpSetupFlow.ts

@@ -0,0 +1,96 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import { createFlowMachine } from "./createFlowMachine.js";
+import type { FlowMachine } from "./createFlowMachine.js";
+import { toFlowError } from "./errors.js";
+import type { FlowError } from "./errors.js";
+
+/**
+ * TOTP enrollment on the security-settings screen (auth-sa.md §11 "TOTP
+ * setup"). `start()` mints a pending secret + `otpauth://` URI (render as a
+ * QR); `confirm(code)` proves the authenticator and returns the one-time
+ * backup codes (shown ONCE — host must surface a copy/warn affordance).
+ */
+export type TotpSetupState =
+  | { readonly step: "idle" }
+  | { readonly step: "starting" }
+  | {
+      readonly step: "enrolling";
+      readonly secret: string;
+      readonly qrUri: string;
+      readonly expiresIn: number;
+    }
+  | { readonly step: "confirming"; readonly secret: string; readonly qrUri: string; readonly expiresIn: number }
+  | { readonly step: "done"; readonly backupCodes: readonly string[] }
+  | { readonly step: "startError"; readonly error: FlowError }
+  | {
+      readonly step: "confirmError";
+      readonly secret: string;
+      readonly qrUri: string;
+      readonly expiresIn: number;
+      readonly error: FlowError;
+    };
+
+export interface TotpSetupFlow {
+  readonly machine: FlowMachine<TotpSetupState>;
+  start(): Promise<void>;
+  confirm(code: string): Promise<void>;
+  reset(): void;
+}
+
+export interface TotpSetupFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+}
+
+export function createTotpSetupFlow(deps: TotpSetupFlowDeps): TotpSetupFlow {
+  const machine = createFlowMachine<TotpSetupState>({
+    id: "auth.totp_setup",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function start(): Promise<void> {
+    await machine.run({ step: "starting" }, () => deps.api.totpSetup(), {
+      resolve: (r): TotpSetupState => ({
+        step: "enrolling",
+        secret: r.secret,
+        qrUri: r.qr_uri,
+        expiresIn: r.expires_in,
+      }),
+      reject: (error): TotpSetupState => ({
+        step: "startError",
+        error: toFlowError(error),
+      }),
+    });
+  }
+
+  async function confirm(code: string): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "enrolling" && s.step !== "confirmError") return;
+    const { secret, qrUri, expiresIn } = s;
+    await machine.run(
+      { step: "confirming", secret, qrUri, expiresIn },
+      () => deps.api.totpSetupConfirm(code),
+      {
+        resolve: (r): TotpSetupState => ({
+          step: "done",
+          backupCodes: r.backup_codes,
+        }),
+        reject: (error): TotpSetupState => ({
+          step: "confirmError",
+          secret,
+          qrUri,
+          expiresIn,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, start, confirm, reset };
+}

package/src/flows/useFlow.ts

@@ -0,0 +1,16 @@
+import { useSyncExternalStore } from "react";
+import type { FlowMachine, FlowStateBase } from "./createFlowMachine.js";
+
+/**
+ * React binding for a {@link FlowMachine}: subscribes to transitions and
+ * returns the current state. Because the machine stores immutable state
+ * snapshots, `getState` is a stable reference read — no tearing under
+ * concurrent React.
+ */
+export function useFlow<S extends FlowStateBase>(machine: FlowMachine<S>): S {
+  return useSyncExternalStore(
+    machine.subscribe,
+    machine.getState,
+    machine.getState
+  );
+}