@stapel/auth-react 1.0.0

package/dist/flows/createFlowMachine.d.ts

@@ -0,0 +1,55 @@
+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 declare function createFlowMachine<S extends FlowStateBase>(options: FlowMachineOptions<S>): FlowMachine<S>;
+//# sourceMappingURL=createFlowMachine.d.ts.map

package/dist/flows/createFlowMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFlowMachine.d.ts","sourceRoot":"","sources":["../../src/flows/createFlowMachine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,aAAa;IAClD,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,IAAI,CAAC,CAAC;IACd,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,wEAAwE;IACxE,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EACH,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,QAAQ,EAAE;QACR,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;QACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;KACxC,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,aAAa;IACzD,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACvC;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,aAAa,EACvD,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,WAAW,CAAC,CAAC,CAAC,CA6DhB"}

package/dist/flows/createFlowMachine.js

@@ -0,0 +1,56 @@
+import { trackFlowStep } from "@stapel/core";
+export function createFlowMachine(options) {
+    const { id, analytics } = options;
+    let state = options.initial;
+    const listeners = new Set();
+    function emit(step, phase) {
+        if (analytics)
+            trackFlowStep(analytics, id, step, phase);
+    }
+    function notify() {
+        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) {
+        state = next;
+        generation += 1;
+        emit(next.step, "started");
+        notify();
+    }
+    async function run(pending, task, handlers) {
+        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,
+    };
+}
+//# sourceMappingURL=createFlowMachine.js.map

package/dist/flows/createFlowMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFlowMachine.js","sourceRoot":"","sources":["../../src/flows/createFlowMachine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA8D7C,MAAM,UAAU,iBAAiB,CAC/B,OAA8B;IAE9B,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAClC,IAAI,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;IAC5B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAExC,SAAS,IAAI,CAAC,IAAY,EAAE,KAAyC;QACnE,IAAI,SAAS;YAAE,aAAa,CAAC,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC;IAED,SAAS,MAAM;QACb,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,EAAE,CAAC;IAC/C,CAAC;IAED,6EAA6E;IAC7E,6EAA6E;IAC7E,qEAAqE;IACrE,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,SAAS,EAAE,CAAC,IAAO;QACjB,KAAK,GAAG,IAAI,CAAC;QACb,UAAU,IAAI,CAAC,CAAC;QAChB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC3B,MAAM,EAAE,CAAC;IACX,CAAC;IAED,KAAK,UAAU,GAAG,CAChB,OAAU,EACV,IAAsB,EACtB,QAGC;QAED,EAAE,CAAC,OAAO,CAAC,CAAC;QACZ,yEAAyE;QACzE,wEAAwE;QACxE,0EAA0E;QAC1E,8DAA8D;QAC9D,MAAM,KAAK,GAAG,UAAU,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAChC,IAAI,UAAU,KAAK,KAAK;gBAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC7B,IAAI,UAAU,KAAK,KAAK;gBAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE;QACF,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK;QACrB,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE;YACtB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC,CAAC;QACJ,CAAC;QACD,EAAE;QACF,GAAG;KACJ,CAAC;AACJ,CAAC"}

package/dist/flows/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function toFlowError(error: unknown): FlowError;
+/** Convenience predicate: did this error carry a specific backend code? */
+export declare function isErrorCode(error: FlowError, code: string): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/flows/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/flows/errors.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CASrD;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnE"}

package/dist/flows/errors.js

@@ -0,0 +1,17 @@
+import { StapelApiError } from "@stapel/core";
+/** Fold any thrown value into a {@link FlowError} for a flow error state. */
+export function toFlowError(error) {
+    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, code) {
+    return error.code === code;
+}
+//# sourceMappingURL=errors.js.map

package/dist/flows/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/flows/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAa9C,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO;QACL,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,SAAS;KAClB,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,KAAgB,EAAE,IAAY;IACxD,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC7B,CAAC"}

package/dist/flows/magicLinkFlow.d.ts

@@ -0,0 +1,41 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { FlowMachine } from "./createFlowMachine.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 declare function createMagicLinkFlow(deps: MagicLinkFlowDeps): MagicLinkFlow;
+//# sourceMappingURL=magicLinkFlow.d.ts.map

package/dist/flows/magicLinkFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magicLinkFlow.d.ts","sourceRoot":"","sources":["../../src/flows/magicLinkFlow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAElF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC9C,sFAAsF;IACtF,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACvC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CA+B1E"}

package/dist/flows/magicLinkFlow.js

@@ -0,0 +1,29 @@
+import { validRedirectUrl } from "../api/urls.js";
+import { createFlowMachine } from "./createFlowMachine.js";
+import { toFlowError } from "./errors.js";
+export function createMagicLinkFlow(deps) {
+    const machine = createFlowMachine({
+        id: "auth.magic_link",
+        initial: { step: "idle" },
+        analytics: deps.analytics ?? null,
+    });
+    async function request(email, redirectUrl) {
+        if (redirectUrl !== undefined && validRedirectUrl(redirectUrl) === null) {
+            machine.to({ step: "invalidRedirect", email });
+            return;
+        }
+        await machine.run({ step: "requesting", email }, () => deps.api.magicRequest(email, redirectUrl), {
+            resolve: () => ({ step: "sent", email }),
+            reject: (error) => ({
+                step: "error",
+                email,
+                error: toFlowError(error),
+            }),
+        });
+    }
+    function reset() {
+        machine.to({ step: "idle" });
+    }
+    return { machine, request, reset };
+}
+//# sourceMappingURL=magicLinkFlow.js.map

package/dist/flows/magicLinkFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"magicLinkFlow.js","sourceRoot":"","sources":["../../src/flows/magicLinkFlow.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA+B1C,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,MAAM,OAAO,GAAG,iBAAiB,CAAiB;QAChD,EAAE,EAAE,iBAAiB;QACrB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;KAClC,CAAC,CAAC;IAEH,KAAK,UAAU,OAAO,CAAC,KAAa,EAAE,WAAoB;QACxD,IAAI,WAAW,KAAK,SAAS,IAAI,gBAAgB,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC;YACxE,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/C,OAAO;QACT,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,CACf,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,EAC7B,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,EAC/C;YACE,OAAO,EAAE,GAAmB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACxD,MAAM,EAAE,CAAC,KAAK,EAAkB,EAAE,CAAC,CAAC;gBAClC,IAAI,EAAE,OAAO;gBACb,KAAK;gBACL,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC;aAC1B,CAAC;SACH,CACF,CAAC;IACJ,CAAC;IAED,SAAS,KAAK;QACZ,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC"}

package/dist/flows/oauthFlow.d.ts

@@ -0,0 +1,58 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse } from "../api/types.js";
+import type { FlowMachine } from "./createFlowMachine.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 declare function createOAuthFlow(deps: OAuthFlowDeps): OAuthFlow;
+//# sourceMappingURL=oauthFlow.d.ts.map

package/dist/flows/oauthFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthFlow.d.ts","sourceRoot":"","sources":["../../src/flows/oauthFlow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1D;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/F;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAChF;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B,CAAC;AAEN,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,UAAU,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAC3D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CA8D9D"}

package/dist/flows/oauthFlow.js

@@ -0,0 +1,53 @@
+import { isTotpChallenge } from "../api/types.js";
+import { createFlowMachine } from "./createFlowMachine.js";
+import { toFlowError } from "./errors.js";
+export function createOAuthFlow(deps) {
+    const machine = createFlowMachine({
+        id: "auth.oauth",
+        initial: { step: "idle" },
+        analytics: deps.analytics ?? null,
+    });
+    async function exchange(provider, accessToken) {
+        await machine.run({ step: "exchanging", provider }, () => deps.api.oauthLogin(provider, accessToken), {
+            resolve: (r) => {
+                if (isTotpChallenge(r)) {
+                    return {
+                        step: "totpRequired",
+                        challengeToken: r.challenge_token,
+                        expiresIn: r.expires_in,
+                    };
+                }
+                deps.onAuthenticated?.(r);
+                return { step: "authenticated", result: r };
+            },
+            reject: (error) => ({
+                step: "error",
+                provider,
+                error: toFlowError(error),
+            }),
+        });
+    }
+    async function submitTotp(proof) {
+        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) => {
+                deps.onAuthenticated?.(result);
+                return { step: "authenticated", result };
+            },
+            reject: (error) => ({
+                step: "totpError",
+                challengeToken,
+                expiresIn,
+                error: toFlowError(error),
+            }),
+        });
+    }
+    function reset() {
+        machine.to({ step: "idle" });
+    }
+    return { machine, exchange, submitTotp, reset };
+}
+//# sourceMappingURL=oauthFlow.js.map

package/dist/flows/oauthFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthFlow.js","sourceRoot":"","sources":["../../src/flows/oauthFlow.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA6C1C,MAAM,UAAU,eAAe,CAAC,IAAmB;IACjD,MAAM,OAAO,GAAG,iBAAiB,CAAa;QAC5C,EAAE,EAAE,YAAY;QAChB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;KAClC,CAAC,CAAC;IAEH,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,WAAmB;QAC3D,MAAM,OAAO,CAAC,GAAG,CACf,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,EAChC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,WAAW,CAAC,EAChD;YACE,OAAO,EAAE,CAAC,CAAC,EAAc,EAAE;gBACzB,IAAI,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;oBACvB,OAAO;wBACL,IAAI,EAAE,cAAc;wBACpB,cAAc,EAAE,CAAC,CAAC,eAAe;wBACjC,SAAS,EAAE,CAAC,CAAC,UAAU;qBACxB,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC1B,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;YAC9C,CAAC;YACD,MAAM,EAAE,CAAC,KAAK,EAAc,EAAE,CAAC,CAAC;gBAC9B,IAAI,EAAE,OAAO;gBACb,QAAQ;gBACR,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC;aAC1B,CAAC;SACH,CACF,CAAC;IACJ,CAAC;IAED,KAAK,UAAU,UAAU,CAAC,KAGzB;QACC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO;QAChE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,OAAO,CAAC,GAAG,CACf,EAAE,IAAI,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,EACpD,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,cAAc,EAAE,KAAK,CAAC,EACzD;YACE,OAAO,EAAE,CAAC,MAAM,EAAc,EAAE;gBAC9B,IAAI,CAAC,eAAe,EAAE,CAAC,MAAM,CAAC,CAAC;gBAC/B,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;YAC3C,CAAC;YACD,MAAM,EAAE,CAAC,KAAK,EAAc,EAAE,CAAC,CAAC;gBAC9B,IAAI,EAAE,WAAW;gBACjB,cAAc;gBACd,SAAS;gBACT,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC;aAC1B,CAAC;SACH,CACF,CAAC;IACJ,CAAC;IAED,SAAS,KAAK;QACZ,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAClD,CAAC"}

package/dist/flows/otpFlow.d.ts

@@ -0,0 +1,74 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse, OtpChannel } from "../api/types.js";
+import type { FlowMachine } from "./createFlowMachine.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;
+}
+export declare function createOtpFlow(deps: OtpFlowDeps): OtpFlow;
+//# sourceMappingURL=otpFlow.d.ts.map

package/dist/flows/otpFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otpFlow.d.ts","sourceRoot":"","sources":["../../src/flows/otpFlow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrF;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7G;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACjE;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B,CAAC;AAEN,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxC,mFAAmF;IACnF,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,gFAAgF;IAChF,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,+BAA+B;IAC/B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAC3D;AAID,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAiFxD"}

package/dist/flows/otpFlow.js

@@ -0,0 +1,68 @@
+import { createFlowMachine } from "./createFlowMachine.js";
+import { toFlowError } from "./errors.js";
+const LOCKED_STATUS = 423;
+export function createOtpFlow(deps) {
+    const machine = createFlowMachine({
+        id: "auth.otp",
+        initial: { step: "idle" },
+        analytics: deps.analytics ?? null,
+    });
+    async function requestCode(channel, value, captchaToken) {
+        await machine.run({ step: "requesting", channel, value }, () => deps.api.otpRequest(channel, value, captchaToken), {
+            resolve: (r) => ({
+                step: "codeSent",
+                channel,
+                value,
+                target: r.target,
+            }),
+            reject: (error) => {
+                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() {
+        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) {
+        const id = currentIdentifier();
+        if (id === null)
+            return;
+        await requestCode(id.channel, id.value, captchaToken);
+    }
+    async function submitCode(code) {
+        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) => {
+                deps.onAuthenticated?.(result);
+                return { step: "authenticated", result };
+            },
+            reject: (error) => {
+                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() {
+        machine.to({ step: "idle" });
+    }
+    return { machine, requestCode, resend, submitCode, reset };
+}
+//# sourceMappingURL=otpFlow.js.map

package/dist/flows/otpFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otpFlow.js","sourceRoot":"","sources":["../../src/flows/otpFlow.ts"],"names":[],"mappings":"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"}

package/dist/flows/passkeyFlow.d.ts

@@ -0,0 +1,75 @@
+import type { Analytics } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse, Passkey } from "../api/types.js";
+import type { FlowMachine } from "./createFlowMachine.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).
+ */
+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 declare function createPasskeyRegistrationFlow(deps: PasskeyRegistrationFlowDeps): PasskeyRegistrationFlow;
+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 declare function createPasskeyLoginFlow(deps: PasskeyLoginFlowDeps): PasskeyLoginFlow;
+//# sourceMappingURL=passkeyFlow.d.ts.map

package/dist/flows/passkeyFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkeyFlow.d.ts","sourceRoot":"","sources":["../../src/flows/passkeyFlow.ts"],"names":[],"mappings":"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"}