@stapel/auth-react 1.0.0

package/src/flows/otpFlow.ts

@@ -0,0 +1,156 @@
+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";
+
+/**
+ * Email / Phone OTP passwordless login (auth-sa.md §1–2). One machine serves
+ * both channels — the only difference is the endpoint, carried in `channel`.
+ *
+ * Steps:
+ *  - `idle`         → nothing requested yet
+ *  - `requesting`   → POST /<channel>/request/ in flight
+ *  - `codeSent`     → human-wait: enter the code (or resend)
+ *  - `verifying`    → POST /<channel>/verify/ in flight
+ *  - `authenticated`→ terminal success (AuthResponse)
+ *  - `requestError` → request failed; retry
+ *  - `codeError`    → wrong/expired code; human-wait, retry or resend
+ *  - `locked`       → 423 lockout with `retry_after_minutes`
+ */
+export type OtpState =
+  | { 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;
+    }
+  | {
+      readonly step: "locked";
+      readonly channel: OtpChannel;
+      readonly value: string;
+      readonly error: FlowError;
+    };
+
+export interface OtpFlow {
+  readonly machine: FlowMachine<OtpState>;
+  /** Request a code for the identifier. `captchaToken` when the backend needs it. */
+  requestCode(channel: OtpChannel, value: string, captchaToken?: string): Promise<void>;
+  /** Resend the code for the current identifier (respect the 30 s rate limit). */
+  resend(captchaToken?: string): Promise<void>;
+  /** Verify the entered code. */
+  submitCode(code: string): Promise<void>;
+  /** Return to `idle`. */
+  reset(): void;
+}
+
+export interface OtpFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  /** Called with the session-bearing response on success (token persistence). */
+  readonly onAuthenticated?: (result: AuthResponse) => void;
+}
+
+const LOCKED_STATUS = 423;
+
+export function createOtpFlow(deps: OtpFlowDeps): OtpFlow {
+  const machine = createFlowMachine<OtpState>({
+    id: "auth.otp",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function requestCode(
+    channel: OtpChannel,
+    value: string,
+    captchaToken?: string
+  ): Promise<void> {
+    await machine.run(
+      { step: "requesting", channel, value },
+      () => deps.api.otpRequest(channel, value, captchaToken),
+      {
+        resolve: (r): OtpState => ({
+          step: "codeSent",
+          channel,
+          value,
+          target: r.target,
+        }),
+        reject: (error): OtpState => {
+          const flowError = toFlowError(error);
+          if (flowError.status === LOCKED_STATUS) {
+            return { step: "locked", channel, value, error: flowError };
+          }
+          return { step: "requestError", channel, value, error: flowError };
+        },
+      }
+    );
+  }
+
+  function currentIdentifier(): { channel: OtpChannel; value: string } | null {
+    const s = machine.getState();
+    if (
+      s.step === "codeSent" ||
+      s.step === "verifying" ||
+      s.step === "codeError" ||
+      s.step === "requestError" ||
+      s.step === "requesting"
+    ) {
+      return { channel: s.channel, value: s.value };
+    }
+    return null;
+  }
+
+  async function resend(captchaToken?: string): Promise<void> {
+    const id = currentIdentifier();
+    if (id === null) return;
+    await requestCode(id.channel, id.value, captchaToken);
+  }
+
+  async function submitCode(code: 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.otpVerify(channel, value, code),
+      {
+        resolve: (result): OtpState => {
+          deps.onAuthenticated?.(result);
+          return { step: "authenticated", result };
+        },
+        reject: (error): OtpState => {
+          const flowError = toFlowError(error);
+          if (flowError.status === LOCKED_STATUS) {
+            return { step: "locked", channel, value, error: flowError };
+          }
+          return { step: "codeError", channel, value, target, error: flowError };
+        },
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, requestCode, resend, submitCode, reset };
+}

package/src/flows/passkeyFlow.ts

@@ -0,0 +1,191 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse, Passkey } 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";
+
+/**
+ * Passkeys / WebAuthn (auth-sa.md §17). FLOW-COMPLETE, WEBAUTHN BINDING IS A
+ * THIN TODO (see MODULE.md): both machines model the full begin→ceremony→
+ * complete journey and surface the server `options`. The single browser step —
+ * `navigator.credentials.create()/get()` — is either injected via
+ * `webauthn*` deps (auto-driven) or performed by the host, which then calls
+ * `submitCredential`. No heuristic "no credentials" probing (auth-sa.md §19.6).
+ */
+
+// ── Registration (security settings, requires auth) ─────────────────────────
+
+export type PasskeyRegisterState =
+  | { readonly step: "idle" }
+  | { readonly step: "beginning" }
+  | { readonly step: "awaitingCredential"; readonly options: Record<string, unknown> }
+  | { readonly step: "completing" }
+  | { readonly step: "registered"; readonly passkey: Passkey }
+  | { readonly step: "error"; readonly error: FlowError };
+
+export interface PasskeyRegistrationFlow {
+  readonly machine: FlowMachine<PasskeyRegisterState>;
+  begin(deviceName?: string): Promise<void>;
+  submitCredential(credential: unknown): Promise<void>;
+  reset(): void;
+}
+
+export interface PasskeyRegistrationFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  /** THIN WebAuthn binding: `navigator.credentials.create({ publicKey })`. */
+  readonly webauthnCreate?: (
+    options: Record<string, unknown>
+  ) => Promise<unknown>;
+}
+
+export function createPasskeyRegistrationFlow(
+  deps: PasskeyRegistrationFlowDeps
+): PasskeyRegistrationFlow {
+  const machine = createFlowMachine<PasskeyRegisterState>({
+    id: "auth.passkey_register",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  let pendingDeviceName: string | undefined;
+
+  async function submitCredential(credential: unknown): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "awaitingCredential") return;
+    await machine.run(
+      { step: "completing" },
+      () => deps.api.passkeyRegisterComplete(credential, pendingDeviceName),
+      {
+        resolve: (passkey): PasskeyRegisterState => ({ step: "registered", passkey }),
+        reject: (error): PasskeyRegisterState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function begin(deviceName?: string): Promise<void> {
+    pendingDeviceName = deviceName;
+    await machine.run({ step: "beginning" }, () => deps.api.passkeyRegisterBegin(), {
+      resolve: (r): PasskeyRegisterState => ({
+        step: "awaitingCredential",
+        options: r.options,
+      }),
+      reject: (error): PasskeyRegisterState => ({
+        step: "error",
+        error: toFlowError(error),
+      }),
+    });
+    const after = machine.getState();
+    if (after.step === "awaitingCredential" && deps.webauthnCreate) {
+      try {
+        const credential = await deps.webauthnCreate(after.options);
+        await submitCredential(credential);
+      } catch (error) {
+        machine.to({ step: "error", error: toFlowError(error) });
+      }
+    }
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, begin, submitCredential, reset };
+}
+
+// ── Authentication (sign-in page, no auth required) ─────────────────────────
+
+export type PasskeyLoginState =
+  | { readonly step: "idle" }
+  | { readonly step: "beginning" }
+  | {
+      readonly step: "awaitingAssertion";
+      readonly sessionKey: string;
+      readonly options: Record<string, unknown>;
+    }
+  | { readonly step: "completing"; readonly sessionKey: string }
+  | { readonly step: "authenticated"; readonly result: AuthResponse }
+  | { readonly step: "error"; readonly error: FlowError };
+
+export interface PasskeyLoginFlow {
+  readonly machine: FlowMachine<PasskeyLoginState>;
+  begin(email?: string): Promise<void>;
+  submitAssertion(credential: unknown): Promise<void>;
+  reset(): void;
+}
+
+export interface PasskeyLoginFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  readonly onAuthenticated?: (result: AuthResponse) => void;
+  /** THIN WebAuthn binding: `navigator.credentials.get({ publicKey })`. */
+  readonly webauthnGet?: (options: Record<string, unknown>) => Promise<unknown>;
+}
+
+export function createPasskeyLoginFlow(
+  deps: PasskeyLoginFlowDeps
+): PasskeyLoginFlow {
+  const machine = createFlowMachine<PasskeyLoginState>({
+    id: "auth.passkey_login",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function submitAssertion(credential: unknown): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "awaitingAssertion") return;
+    const { sessionKey } = s;
+    await machine.run(
+      { step: "completing", sessionKey },
+      () => deps.api.passkeyAuthenticateComplete(sessionKey, credential),
+      {
+        resolve: (result): PasskeyLoginState => {
+          deps.onAuthenticated?.(result);
+          return { step: "authenticated", result };
+        },
+        reject: (error): PasskeyLoginState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function begin(email?: string): Promise<void> {
+    await machine.run(
+      { step: "beginning" },
+      () => deps.api.passkeyAuthenticateBegin(email),
+      {
+        resolve: (r): PasskeyLoginState => ({
+          step: "awaitingAssertion",
+          sessionKey: r.session_key,
+          options: r.options,
+        }),
+        reject: (error): PasskeyLoginState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+    const after = machine.getState();
+    if (after.step === "awaitingAssertion" && deps.webauthnGet) {
+      try {
+        const credential = await deps.webauthnGet(after.options);
+        await submitAssertion(credential);
+      } catch (error) {
+        machine.to({ step: "error", error: toFlowError(error) });
+      }
+    }
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, begin, submitAssertion, reset };
+}

package/src/flows/passwordChangeFlow.ts

@@ -0,0 +1,114 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { 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";
+
+/**
+ * Authenticated password change (auth-sa.md §4). Two host-selected paths that
+ * converge on `changed`:
+ *  - **old password** — `changeWithPassword(old, new)`.
+ *  - **email / SMS code** — `requestOtp(method)` → `submitOtp(code, new)`.
+ *
+ * Which tabs to show is a host decision driven by `GET /password/methods/`
+ * (see `usePasswordMethods`); the machine serves whichever path is invoked.
+ */
+export type PasswordChangeState =
+  | { readonly step: "idle" }
+  | { readonly step: "changing" }
+  | { readonly step: "requestingOtp"; readonly method: OtpChannel }
+  | { readonly step: "otpSent"; readonly method: OtpChannel; readonly target: string }
+  | { readonly step: "verifyingOtp"; readonly method: OtpChannel; readonly target: string }
+  | { readonly step: "changed" }
+  | { readonly step: "error"; readonly error: FlowError }
+  | {
+      readonly step: "otpError";
+      readonly method: OtpChannel;
+      readonly target: string;
+      readonly error: FlowError;
+    };
+
+export interface PasswordChangeFlow {
+  readonly machine: FlowMachine<PasswordChangeState>;
+  changeWithPassword(oldPassword: string, newPassword: string): Promise<void>;
+  requestOtp(method: OtpChannel): Promise<void>;
+  submitOtp(code: string, newPassword: string): Promise<void>;
+  reset(): void;
+}
+
+export interface PasswordChangeFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+}
+
+export function createPasswordChangeFlow(
+  deps: PasswordChangeFlowDeps
+): PasswordChangeFlow {
+  const machine = createFlowMachine<PasswordChangeState>({
+    id: "auth.password_change",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function changeWithPassword(
+    oldPassword: string,
+    newPassword: string
+  ): Promise<void> {
+    await machine.run(
+      { step: "changing" },
+      () => deps.api.passwordChange(oldPassword, newPassword),
+      {
+        resolve: (): PasswordChangeState => ({ step: "changed" }),
+        reject: (error): PasswordChangeState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function requestOtp(method: OtpChannel): Promise<void> {
+    await machine.run(
+      { step: "requestingOtp", method },
+      () => deps.api.passwordChangeOtpRequest(method),
+      {
+        resolve: (r): PasswordChangeState => ({
+          step: "otpSent",
+          method,
+          target: r.target,
+        }),
+        reject: (error): PasswordChangeState => ({
+          step: "error",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function submitOtp(code: string, newPassword: string): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "otpSent" && s.step !== "otpError") return;
+    const { method, target } = s;
+    await machine.run(
+      { step: "verifyingOtp", method, target },
+      () => deps.api.passwordChangeOtpVerify(method, code, newPassword),
+      {
+        resolve: (): PasswordChangeState => ({ step: "changed" }),
+        reject: (error): PasswordChangeState => ({
+          step: "otpError",
+          method,
+          target,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, changeWithPassword, requestOtp, submitOtp, reset };
+}

package/src/flows/passwordLoginFlow.ts

@@ -0,0 +1,122 @@
+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";
+
+/**
+ * Password login with the TOTP step-up branch (auth-sa.md §3 + §11). A login
+ * response is a `oneOf` union — when the account has TOTP enabled the server
+ * answers `TOTP_REQUIRED` with a `challenge_token` instead of a session, and
+ * the flow parks in `totpRequired` until the user enters their 6-digit code
+ * (or a backup code).
+ *
+ * A 423 during TOTP verify **invalidates the challenge** (auth-sa.md §11): the
+ * machine goes to `totpLocked` and the user must log in again for a fresh
+ * token — modelled as a terminal step (call `reset()` to return to `idle`).
+ */
+export type PasswordLoginState =
+  | { readonly step: "idle" }
+  | { readonly step: "authenticating"; readonly login: 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 login: string; readonly error: FlowError }
+  | {
+      readonly step: "totpError";
+      readonly challengeToken: string;
+      readonly expiresIn: number;
+      readonly error: FlowError;
+    }
+  | { readonly step: "totpLocked"; readonly error: FlowError };
+
+export interface TotpProof {
+  readonly code?: string;
+  readonly backup_code?: string;
+}
+
+export interface PasswordLoginFlow {
+  readonly machine: FlowMachine<PasswordLoginState>;
+  login(loginId: string, password: string): Promise<void>;
+  submitTotp(proof: TotpProof): Promise<void>;
+  reset(): void;
+}
+
+export interface PasswordLoginFlowDeps {
+  readonly api: AuthApi;
+  readonly analytics?: Analytics | null;
+  readonly onAuthenticated?: (result: AuthResponse) => void;
+}
+
+const LOCKED_STATUS = 423;
+
+export function createPasswordLoginFlow(
+  deps: PasswordLoginFlowDeps
+): PasswordLoginFlow {
+  const machine = createFlowMachine<PasswordLoginState>({
+    id: "auth.password_login",
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function login(loginId: string, password: string): Promise<void> {
+    await machine.run(
+      { step: "authenticating", login: loginId },
+      () => deps.api.passwordLogin(loginId, password),
+      {
+        resolve: (r): PasswordLoginState => {
+          if (isTotpChallenge(r)) {
+            return {
+              step: "totpRequired",
+              challengeToken: r.challenge_token,
+              expiresIn: r.expires_in,
+            };
+          }
+          deps.onAuthenticated?.(r);
+          return { step: "authenticated", result: r };
+        },
+        reject: (error): PasswordLoginState => ({
+          step: "error",
+          login: loginId,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function submitTotp(proof: TotpProof): 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): PasswordLoginState => {
+          deps.onAuthenticated?.(result);
+          return { step: "authenticated", result };
+        },
+        reject: (error): PasswordLoginState => {
+          const flowError = toFlowError(error);
+          if (flowError.status === LOCKED_STATUS) {
+            return { step: "totpLocked", error: flowError };
+          }
+          return { step: "totpError", challengeToken, expiresIn, error: flowError };
+        },
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return { machine, login, submitTotp, reset };
+}