@atlasauth/js 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,188 @@
+# @atlasauth/js changelog
+
+## 0.7.0
+- **Popup OAuth completes when the opener page sends `Cross-Origin-Opener-Policy: same-origin`.** That
+  header puts the provider popup in another browsing-context group: `popup.closed` reads `true` at once and
+  the popup has no `window.opener`, so the result could never be posted back and the flow settled as a
+  cancel while the popup stayed open. Now the popup lands back on your page with the result in the URL
+  fragment (`#atlas_popup_result=…`, never the query string), the SDK there hands it to the opener over
+  `BroadcastChannel('atlas:oauth:<nonce>')` (a `localStorage` `storage` event where BroadcastChannel is
+  missing) and closes the popup.
+- **Changed `startOauthPopup` cancel semantics.** `popup.closed` turning true within 1.5 s of opening means
+  the opener link was severed, not that the user closed it: the flow keeps waiting, probing `GET /v1/client`
+  with back-off, for up to 5 minutes, and settles as `popup_closed` only on that timeout, an explicit error
+  result, `signal` aborting, or a newer popup flow starting. A close after 1.5 s is a cancel after one final
+  session probe (as before).
+- **Changed `startOauthPopup` request.** It now sends `popup_nonce` and `opener_origin`
+  (`window.location.origin`) with `mode: 'popup'`, and opens the popup with the window name `atlas:oauth`.
+- **Added** to `startOauthPopup`: `input.signal?: AbortSignal`, `handlers.onSevered?: () => void`,
+  `PopupStartResult.severed?: boolean`; new `OAuthPopupInput` type; `POPUP_SEVERED_WINDOW_MS` (1500) and
+  `POPUP_SEVERED_TIMEOUT_MS` (300000); `mapOAuthPopupPayload(data)` (the payload half of
+  `parseOAuthPopupMessage`).
+- **Added popup channel helpers:** `completeOAuthPopupLanding({ win?, ackTimeoutMs? })` →
+  `PopupLanding | null` (`{ payload, delivered }`; reads and scrubs the fragment, relays the result and
+  closes once the opener acknowledges — call it on startup), `closeOAuthPopupAfterSignIn({ win?, ackTimeoutMs? })`
+  (a page that finished a sign-in inside the Atlas popup closes itself when an opener is waiting),
+  `listenForPopupResult(nonce, { onResult, onSignedIn? })`, `readPopupLanding(hash)`, `popupChannelName(nonce)`,
+  `createPopupNonce()`, `PopupRelayMessage`, and the constants `OAUTH_POPUP_WINDOW_NAME`
+  (`'atlas:oauth'`), `POPUP_RESULT_FRAGMENT` (`'atlas_popup_result'`), `POPUP_SIGNAL_CHANNEL`.
+- **Sign-out tombstones are shared by every tab.** `SessionTombstones` moved from `sessionStorage` to
+  `localStorage`, so after a failed revoke a newly opened tab no longer re-adopts the session. Entries are
+  `{ id, at }`, at most 20, kept 30 days, pruned on every read, and keyed per Frontend API origin
+  (`atlas:signed-out-sessions:<origin>`). `sessionStorage` is used only when `localStorage` throws; tombstones
+  an earlier version kept in `sessionStorage` are carried over.
+- **Changed** `new SessionTombstones(options?)`: accepts `{ frontendApi?, storageKey?, now? }`
+  (`SessionTombstonesOptions`); a bare storage-key string is still accepted. **Added** `remove(...ids)` (forget
+  a tombstone once a later revoke is confirmed) and `subscribe(listener)` (another tab's changes, via the
+  `storage` event). `has()`/`list()` re-read storage, so other tabs' changes are seen.
+
+## 0.6.0
+- **Per-flow captcha widget rendering**, shared by the prebuilt sign-in / sign-up UIs:
+  `renderCaptchaWidget(flow, container)` → `{ token: Promise<string>, remove() }`,
+  `getCaptchaToken(flow, container)`, `loadCaptchaProvider(provider, siteKey, win)`,
+  `isRenderableCaptcha(provider)`, `flowNeedsCaptcha(flow)`, `isCaptchaError(error)` and
+  `CAPTCHA_ERROR_CODES`. Renders Turnstile, hCaptcha, reCAPTCHA v2, v3 and Enterprise, honouring the
+  `invisible` / `managed` / `visible` widget mode. A failed script load is retried on the next render.
+- **Added types** `FlowCaptcha` (`{ enabled, provider?, siteKey?, widget? }` — one entry of
+  `/v1/appearance` `captchaFlows`), `CaptchaFlowKey`, `CaptchaWidgetMode`, `CaptchaWidgetHandle`.
+- **Framework-agnostic captcha lifecycle** for the prebuilt forms of every framework SDK:
+  `createCaptchaController(options?)` → `CaptchaController` (`needed`, `configure(options)`,
+  `attach(el)`, `getToken()`, `reset()`, `destroy()`), with the new `CaptchaControllerOptions` type
+  (`{ flow, active, eager?, onSolved? }`); `localizeCaptchaErrors(errors, t)`.
+- **Sign-in / sign-up submit helpers:** `signInCaptchaOptions(flow, state, onChallengeSolved)`,
+  `advanceWithCaptcha(client, state, values, { captcha?, identifier?, t })` → `{ state, identifier }`
+  (adds the captcha token on the identifier / `needs_captcha` step, reports a rejected token as
+  `CAPTCHA_FAILED` and draws a fresh widget), and `createSignUp(client, values, { consent, captcha?, t })`
+  (posts `/v1/client/sign_ups` with the sign-up captcha's token).
+- **Instance settings:** `fetchInstanceSettings(client)` (`GET /v1/appearance`, null on failure),
+  `instanceSettingsFrom(body)`, `toSignUpInput(values, consent, captchaToken?)`, and the types
+  `InstanceSettings` (`{ captchaFlows, signUpFields, legal }`) and `PublicSignUpField` (moved here from
+  `@atlasauth/react`, which re-exports them unchanged).
+
+- **New: `resolveFrontendApi(value, { component?, allowSameOrigin? })`** — validates a provider's
+  `frontendApi` and returns the request base URL. Throws an **`AtlasConfigError`** (new, exported;
+  `code: AtlasConfigErrorCode` = `'FRONTEND_API_REQUIRED' | 'FRONTEND_API_INVALID'`) when the value is
+  missing, non-string, blank, not an absolute `https:` URL (`http:` only for localhost / local development hosts), or
+  carries credentials, a query or a fragment. `"same-origin"` (new constant `SAME_ORIGIN_FRONTEND_API`)
+  resolves to `""` and a root-relative path such as `"/atlas"` is kept, for reverse proxies; both are refused
+  with `allowSameOrigin: false` (native apps). An explicit `""` is the **deprecated** same-origin spelling: it
+  still resolves to `""` (one-time console warning pointing at `"same-origin"`), and is refused with
+  `allowSameOrigin: false`. Every framework SDK now uses it instead of `frontendApi ?? ''`.
+- **New: `revokeSession(request, sessionId, { retries = 1 })`** → `RevokeSessionOutcome`
+  (`{ revoked, status, response?, activeSessionId? }`). Retries once on a network failure, 5xx or 429; a 404
+  counts as revoked; `activeSessionId` is the parked session the server promoted.
+- **New: `SessionTombstones`** — remembers (memory + `sessionStorage`, bounded to 20) the session ids a tab
+  signed out of, so a re-boot from a still-valid refresh cookie never re-adopts them.
+- **New types:** `SignOutResult` (`{ revoked: boolean; activeSessionId?: string }`), `SignOutError`
+  (`code: 'SIGN_OUT_REVOKE_FAILED'`, `sessionId`, `status`), `ResolveFrontendApiOptions`, `RevokeSessionOutcome`.
+- **`SignOutOptions.strict?: boolean`** added (reject with `SignOutError` when the revoke fails; honoured by
+  `@atlasauth/react`).
+- **Popup OAuth:** when the popup closes without posting a result, `startOauthPopup()` checks
+  `GET /v1/client` once; if a session now exists it resolves `{ error: 'popup_closed', sessionDetected: true }`
+  (new `PopupStartResult.sessionDetected?: boolean`) so the caller re-boots instead of treating it as a cancel.
+- **End-user API key self-service.** New `listApiKeys(client, { organizationId? })`,
+  `createApiKey(client, input)`, `updateApiKey(client, id, { name })` and
+  `revokeApiKey(client, id)` drive `/v1/client/me/api_keys` through a `FapiClient`.
+  Added types: `UserApiKey` (`id`, `subject_type`, `subject_id`, `name`, `prefix`, `claims`,
+  `scopes`, optional `limits`, `last_used_at`, `expires_at`, `revoked_at`, `created_at`),
+  `CreatedUserApiKey` (adds the one-time `secret`, `note`), `UserApiKeyList` (`data`,
+  `allowedScopes`, `allowedClaims`, `maxActiveKeys`, `activeCount`) and `CreateUserApiKeyInput`
+  (`name`, `expiresAt`, `expiresInSeconds`, `scopes`, `claims`, `organizationId`). A refused call
+  throws the new `ApiKeyRequestError` (`code`, `status`, `param`, `needsReverification`).
+
+## 0.5.0
+- **OIDC Front-Channel Logout helpers.** `runFrontChannelLogout(urls, { timeoutMs })` loads each
+  front-channel logout URL in a hidden, sandboxed iframe and resolves once they have all loaded or
+  after the timeout (default 5 s); it never throws, only loads `https:` URLs (and `http://localhost`
+  for development), and is a no-op without a DOM (SSR). `runFrontChannelLogoutFromResponse(res)`
+  reads `frontchannel_logout_urls` from a Frontend API sign-out response. The framework SDKs'
+  `signOut()` uses them; the new `SignOutOptions` type (`{ frontchannel?: boolean }`) is the option
+  they accept.
+
+
+## 0.4.0
+- `AttemptView` now carries `id` (`string | null`; `null` only on the pre-attempt captcha
+  challenge), plus optional `object`, `identifier` and `expires_at`, matching what the server
+  returns, so consumers can read `attempt.id` without a cast.
+
+## 0.3.0
+- **Captcha for any action.** New `captcha(client)` returns `config(action?)` (fetch the
+  centrally managed public provider + site key), `verify(token, action?)` (server-side check)
+  and `protect(element, action?)` (load the provider's widget script, render it, resolve the
+  solved token) — so an app can protect any action without hardcoding provider keys.
+- New `CaptchaWidgetConfig` and `CaptchaVerification` types, plus `loadCaptchaScript()` /
+  `resetCaptchaScripts()`.
+
+## 0.2.0
+- **Native-session helpers** for apps without a cookie jar (React Native, Electron, extension
+  service workers): `exchangeForSession()` trades a first-party OAuth access token for an Atlas
+  session, and `refreshNativeSession()` rotates it without cookies. Both return `null` instead
+  of throwing on failure.
+- `NativeSessionManager` holds the current session, hands out a fresh session JWT and fires
+  `onChange` on every rotation so the new refresh token can be persisted.
+  `serializeNativeSession()` / `parseNativeSession()` help store it. New `NativeSession` type.
+
+## 0.1.9
+- Fixed: the invisible Google overlay now uses a near-zero opacity instead of exactly `0`.
+  Google's button treats an element at `opacity: 0` as not visible and silently ignores the
+  click; the overlay stays invisible to users but now receives the click.
+
+## 0.1.8
+- Fixed: the native Google overlay now stretches Google's button iframe, which Google injects
+  asynchronously, to cover the whole wrapper (re-applied via a `MutationObserver`), so clicks
+  near the edges no longer miss.
+
+## 0.1.7
+- Added: `renderGoogleOverlayButton` accepts `visible` — `false` (default) keeps Google's button
+  as an invisible click target over your own styled button; `true` shows Google's own button.
+- Added: `diagnoseProvider()` reports a provider's resolved mode, client id, overlay geometry and
+  whether a credential was minted this session, for debugging a dead Google button. New `Rect`,
+  `OverlayGeometry` and `ProviderDiagnosis` types; `resetGoogleCredentialFlag()`.
+- Changed: the invisible Google overlay is stretched to fill its wrapper, and in development it
+  warns in the console when it is misaligned or undersized.
+
+## 0.1.6
+- Added: `reportProviderUnavailable(client, provider, reason)` sends a best-effort beacon when a
+  native provider (Google) can't be used, so the failure shows up in the dashboard. New
+  `ProviderUnavailableReason` type (`'script_blocked' | 'not_rendered'`).
+- Changed: device telemetry honours Do-Not-Track — when it is on, no persistent device id is
+  stored. New `doNotTrackEnabled()`.
+
+## 0.1.5
+- Added: popup-mode social / OIDC sign-in. `startOauthPopup(client, { provider, redirectUrl })`
+  opens the provider in a popup, accepts the result only from the Frontend API origin, and falls
+  back to a full-page redirect when the popup is blocked. New `parseOAuthPopupMessage()`,
+  `PopupOutcome`, `PopupStartResult` and `OAuthPopupHandlers`.
+- Added: `FapiClient.frontendApiOrigin`.
+
+## 0.1.4
+- Added: `startOauthRedirect(client, { provider, redirectUrl })` starts a redirect OAuth sign-in
+  and returns the provider's authorization URL.
+
+## 0.1.3
+- Added: `renderGoogleOverlayButton` accepts `oneTap` to also show Google One Tap (off by
+  default).
+
+## 0.1.2
+- Added: native Google sign-in with replay protection. `mintNativeNonce(client, provider)` gets a
+  single-use nonce from Atlas and `nativeSignIn(client, { provider, idToken, nonce })` signs in
+  with a provider id token, returning the same `FlowState` as the other sign-in flows.
+
+## 0.1.1
+- First published release.
+- Sign-in / sign-up flow driver over the Frontend API (`FapiClient`, `initialFlow`, `advance`,
+  `startSignUp`, `prepareFactor`, `pollAttempt`) with attempt helpers (`nextStep`, `fieldErrors`,
+  `formErrors`).
+- Session token cache with refresh scheduling (`TokenCache`) and cross-tab refresh election
+  (`winsElection`, `bestChannel`).
+- Google Identity Services helpers (`loadGoogleIdentityServices`, `renderGoogleButton`,
+  `renderGoogleOverlayButton`), passkeys (`createPasskey`, `getPasskeyAssertion`,
+  `passkeysSupported`), Telegram and Sign-In with Ethereum request builders.
+- Redirect handling (`readRedirectResult`, `stripRedirectParams`), password reset
+  (`startPasswordReset`, `advancePasswordReset`), step-up re-authentication
+  (`reauthenticate`), connecting an extra provider (`connectExternalAccount`) and provider
+  tokens (`getProviderToken`).
+- Silent cross-site session check (`checkSession`, `handleSilentCallback`) and device
+  telemetry (`sendTelemetry`).
+- Authorization helpers re-exported from `@atlasauth/authz` (`hasFromClaims`,
+  `protectFromClaims`, `evaluate`, `ForbiddenError`, …).

package/dist/api-keys.d.ts

@@ -0,0 +1,84 @@
+import type { FapiClient } from './fapi';
+/**
+ * End-user API key self-service — a signed-in user manages their OWN `ak_` keys
+ * (or, when the application allows it, their active organization's) over
+ * `/v1/client/me/api_keys`. Cookie-authenticated through the {@link FapiClient};
+ * the feature is off until the application enables it.
+ *
+ * Creating a key needs a RECENT re-authentication: a stale session gets an
+ * {@link ApiKeyRequestError} whose `code` is `STEP_UP_REQUIRED`. Re-authenticate
+ * (`reauthenticate()`), then call `createApiKey` again.
+ */
+/** An end-user API key as its owner sees it. The secret is never part of it. */
+export interface UserApiKey {
+    object: 'api_key';
+    id: string;
+    subject_type: 'user' | 'organization';
+    subject_id: string;
+    name: string | null;
+    /** The public `ak_…` head — recognises a key, cannot be used as one. */
+    prefix: string;
+    claims: Record<string, unknown>;
+    scopes: string[] | null;
+    /** Usage limits on the key, when the application sets them. */
+    limits?: Record<string, unknown> | null;
+    last_used_at: number | null;
+    expires_at: number | null;
+    revoked_at: number | null;
+    created_at: number;
+}
+/** The create response: the key plus its one-time `secret`. */
+export interface CreatedUserApiKey extends UserApiKey {
+    /** The plaintext `ak_…` key. Shown exactly once — store it now. */
+    secret: string;
+    note?: string;
+}
+export interface UserApiKeyList {
+    data: UserApiKey[];
+    /** The scopes a new key may carry. */
+    allowedScopes: string[];
+    /** The claim names a new key may set. */
+    allowedClaims: string[];
+    /** The most active keys this user (or organization) may hold. */
+    maxActiveKeys: number;
+    /** Active (unrevoked, unexpired) keys held now. */
+    activeCount: number;
+}
+export interface CreateUserApiKeyInput {
+    name?: string;
+    /** Absolute expiry, epoch milliseconds. Not with `expiresInSeconds`. */
+    expiresAt?: number;
+    /** Relative lifetime in seconds. Not with `expiresAt`. */
+    expiresInSeconds?: number;
+    /** Only scopes the application allows (`allowedScopes`). */
+    scopes?: string[];
+    /** Only claim names the application allows (`allowedClaims`). */
+    claims?: Record<string, unknown>;
+    /** Create the key for this (active) organization instead of the user. */
+    organizationId?: string;
+}
+/** A refused request. `code` is the server's stable error code. */
+export declare class ApiKeyRequestError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly param?: string;
+    constructor(status: number, code: string, message: string, param?: string);
+    /** True when the action needs a fresh re-authentication first. */
+    get needsReverification(): boolean;
+}
+/** List the user's keys (or the active organization's, with `organizationId`). */
+export declare function listApiKeys(client: FapiClient, options?: {
+    organizationId?: string;
+}): Promise<UserApiKeyList>;
+/** Create a key. The returned `secret` is shown exactly once. */
+export declare function createApiKey(client: FapiClient, input?: CreateUserApiKeyInput): Promise<CreatedUserApiKey>;
+/** Rename a key (`null` clears the name). */
+export declare function updateApiKey(client: FapiClient, id: string, input: {
+    name: string | null;
+}): Promise<UserApiKey>;
+/** Revoke a key. Immediate and permanent. */
+export declare function revokeApiKey(client: FapiClient, id: string): Promise<{
+    object: 'api_key';
+    id: string;
+    revoked: true;
+}>;

package/dist/api-keys.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiKeyRequestError = void 0;
+exports.listApiKeys = listApiKeys;
+exports.createApiKey = createApiKey;
+exports.updateApiKey = updateApiKey;
+exports.revokeApiKey = revokeApiKey;
+/** A refused request. `code` is the server's stable error code. */
+class ApiKeyRequestError extends Error {
+    code;
+    status;
+    param;
+    constructor(status, code, message, param) {
+        super(message);
+        this.name = 'ApiKeyRequestError';
+        this.status = status;
+        this.code = code;
+        this.param = param;
+    }
+    /** True when the action needs a fresh re-authentication first. */
+    get needsReverification() {
+        return this.code === 'STEP_UP_REQUIRED';
+    }
+}
+exports.ApiKeyRequestError = ApiKeyRequestError;
+const BASE = '/v1/client/me/api_keys';
+async function call(client, path, init = {}) {
+    const res = await client.request(path, init);
+    if (!res.ok || !res.data) {
+        const first = res.errors[0];
+        throw new ApiKeyRequestError(res.status, first?.code ?? 'UNKNOWN', first?.message ?? 'The request failed.', first?.param);
+    }
+    return res.data;
+}
+/** List the user's keys (or the active organization's, with `organizationId`). */
+async function listApiKeys(client, options = {}) {
+    const query = options.organizationId
+        ? `?organization_id=${encodeURIComponent(options.organizationId)}`
+        : '';
+    const body = await call(client, `${BASE}${query}`, { method: 'GET' });
+    return {
+        data: body.data ?? [],
+        allowedScopes: body.allowed_scopes ?? [],
+        allowedClaims: body.allowed_claims ?? [],
+        maxActiveKeys: body.max_active_keys ?? 0,
+        activeCount: body.active_count ?? 0,
+    };
+}
+/** Create a key. The returned `secret` is shown exactly once. */
+async function createApiKey(client, input = {}) {
+    const body = {};
+    if (input.name !== undefined)
+        body.name = input.name;
+    if (input.expiresAt !== undefined)
+        body.expires_at = input.expiresAt;
+    if (input.expiresInSeconds !== undefined)
+        body.expires_in_seconds = input.expiresInSeconds;
+    if (input.scopes !== undefined)
+        body.scopes = input.scopes;
+    if (input.claims !== undefined)
+        body.claims = input.claims;
+    if (input.organizationId !== undefined)
+        body.organization_id = input.organizationId;
+    return call(client, BASE, { method: 'POST', body: JSON.stringify(body) });
+}
+/** Rename a key (`null` clears the name). */
+async function updateApiKey(client, id, input) {
+    return call(client, `${BASE}/${encodeURIComponent(id)}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ name: input.name }),
+    });
+}
+/** Revoke a key. Immediate and permanent. */
+async function revokeApiKey(client, id) {
+    return call(client, `${BASE}/${encodeURIComponent(id)}/revoke`, { method: 'POST' });
+}
+//# sourceMappingURL=api-keys.js.map

package/dist/api-keys.js.map

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

package/dist/captcha-controller.d.ts

@@ -0,0 +1,95 @@
+import { type FieldError } from './attempt';
+import { type FapiClient, type FlowState } from './fapi';
+import { type FlowCaptcha } from './captcha-widget';
+/**
+ * The captcha half of a prebuilt sign-in / sign-up form, without a framework.
+ *
+ * The Vue, Svelte, Angular, Solid and Elements bindings each hold one of these
+ * per form; React's `useCaptcha` hook is the same lifecycle. It is driven by the
+ * instance's settings (`captchaFlows` from `/v1/appearance`), so switching
+ * captcha on in the dashboard makes the forms render it with no code change.
+ *
+ * Lifecycle: a visible/managed widget is drawn as soon as its slot is attached,
+ * so the user can solve it while filling in the form; an invisible one is
+ * executed only when the form is submitted ({@link CaptchaController.getToken}).
+ * Tokens are single-use, so after a submit spent one the caller
+ * {@link CaptchaController.reset}s, which draws a fresh widget.
+ */
+export interface CaptchaControllerOptions {
+    /** The flow's captcha settings (`captchaFlows.signUp`, …). */
+    flow: FlowCaptcha | null | undefined;
+    /** Render at all — the caller's "this flow requires a token here" decision. */
+    active: boolean;
+    /** Draw the widget as soon as the slot is attached. Default: unless invisible. */
+    eager?: boolean;
+    /** Called with the token when an eagerly drawn widget is solved. */
+    onSolved?: (token: string) => void;
+}
+export interface CaptchaController {
+    /** Whether the current settings render a widget at all. */
+    readonly needed: boolean;
+    /** Replace the settings; redraws an attached widget only when they changed. */
+    configure(options: CaptchaControllerOptions): void;
+    /** Attach the element the widget draws into (null detaches and removes it). */
+    attach(el: HTMLElement | null): void;
+    /**
+     * The solved token, rendering/executing the widget first if needed. Null when
+     * no captcha is needed, or the provider failed (the server then refuses with
+     * CAPTCHA_REQUIRED, which the caller turns into a message).
+     */
+    getToken(): Promise<string | null>;
+    /** Drop the (spent) widget and, for an eager one, draw a fresh one. */
+    reset(): void;
+    /** Remove the widget for good (component teardown). */
+    destroy(): void;
+}
+export declare function createCaptchaController(initial?: CaptchaControllerOptions): CaptchaController;
+/**
+ * Swap the server's captcha refusals (CAPTCHA_REQUIRED / CAPTCHA_FAILED, which
+ * the server ties to the `captcha_token` param) for a localized, form-level
+ * message — there is no `captcha_token` input to hang a field error on. `t`
+ * resolves the `captcha.required` / `captcha.failed` catalog keys.
+ */
+export declare function localizeCaptchaErrors(errors: FieldError[], t: (key: string) => string): {
+    errors: FieldError[];
+    captchaRejected: boolean;
+};
+/**
+ * The sign-in captcha settings for the flow's current step: drawn on the
+ * identifier step when the instance ALWAYS requires one for sign-in (so the
+ * first POST already carries the token), and on the `needs_captcha` challenge
+ * step the server answers with when it withheld the attempt (always-on, or
+ * risk-triggered) — where it is drawn at once (even an invisible one) and
+ * solving it calls `onChallengeSolved`, which should resubmit.
+ */
+export declare function signInCaptchaOptions(flow: FlowCaptcha | null | undefined, state: FlowState, onChallengeSolved: () => void): CaptchaControllerOptions;
+/**
+ * {@link advance} with the sign-in captcha folded in — what a prebuilt sign-in
+ * form calls on submit. On the identifier / `needs_captcha` step it adds the
+ * widget's token (re-issuing the identifier POST the challenge marker withheld);
+ * a token the provider rejected comes back as the same challenge, so it reports
+ * CAPTCHA_FAILED and draws a fresh widget (tokens are single-use). Captcha
+ * refusals are localized through `t`.
+ *
+ * `identifier` is the last identifier the user typed (the challenge marker
+ * carries none to re-send); the returned one is what to keep for next time.
+ */
+export declare function advanceWithCaptcha(client: FapiClient, state: FlowState, values: Record<string, string>, opts: {
+    captcha?: CaptchaController | null;
+    identifier?: string;
+    t: (key: string) => string;
+}): Promise<{
+    state: FlowState;
+    identifier: string;
+}>;
+/**
+ * Create the account from a prebuilt create-account form: takes the sign-up
+ * captcha's token (when one is needed), POSTs `/v1/client/sign_ups` via
+ * {@link startSignUp}, localizes captcha refusals and, when the create was
+ * refused, draws a fresh widget (the token was spent either way).
+ */
+export declare function createSignUp(client: FapiClient, values: Record<string, string>, opts: {
+    consent: boolean;
+    captcha?: CaptchaController | null;
+    t: (key: string) => string;
+}): Promise<FlowState>;

package/dist/captcha-controller.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCaptchaController = createCaptchaController;
+exports.localizeCaptchaErrors = localizeCaptchaErrors;
+exports.signInCaptchaOptions = signInCaptchaOptions;
+exports.advanceWithCaptcha = advanceWithCaptcha;
+exports.createSignUp = createSignUp;
+const attempt_1 = require("./attempt");
+const fapi_1 = require("./fapi");
+const instance_settings_1 = require("./instance-settings");
+const captcha_widget_1 = require("./captcha-widget");
+function createCaptchaController(initial) {
+    let options = initial ?? { flow: undefined, active: false };
+    let container = null;
+    let handle = null;
+    // The handle whose token a submit already took: the next getToken() draws a
+    // fresh widget instead of replaying it.
+    let spent = null;
+    // The settings the current widget was drawn with, so a redraw happens only
+    // when they actually change.
+    let drawnKey = null;
+    const needed = () => options.active && !!options.flow && (0, captcha_widget_1.isRenderableCaptcha)(options.flow.provider);
+    const eager = () => options.eager ?? options.flow?.widget !== 'invisible';
+    const key = () => {
+        const f = options.flow;
+        return `${needed()}|${f?.provider ?? ''}|${f?.siteKey ?? ''}|${f?.widget ?? ''}|${eager()}`;
+    };
+    const remove = () => {
+        handle?.remove();
+        handle = null;
+        drawnKey = null;
+    };
+    const mount = () => {
+        remove();
+        const flow = options.flow;
+        if (!needed() || !flow || !container)
+            return null;
+        const h = (0, captcha_widget_1.renderCaptchaWidget)(flow, container);
+        handle = h;
+        drawnKey = key();
+        // Swallow here so a removed / failed widget is never an unhandled
+        // rejection; getToken() reads the same promise and reports it.
+        h.token.then((token) => {
+            if (handle === h)
+                options.onSolved?.(token);
+        }, () => undefined);
+        return h;
+    };
+    const reset = () => {
+        remove();
+        if (needed() && eager())
+            mount();
+    };
+    return {
+        get needed() {
+            return needed();
+        },
+        configure(next) {
+            options = next;
+            if (!container)
+                return;
+            if (!needed() || !eager())
+                remove();
+            else if (drawnKey !== key())
+                mount();
+        },
+        attach(el) {
+            if (el === container)
+                return;
+            remove();
+            container = el;
+            if (el && needed() && eager())
+                mount();
+        },
+        async getToken() {
+            if (!needed())
+                return null;
+            let h = handle;
+            if (!h || spent === h)
+                h = mount();
+            if (!h)
+                return null;
+            try {
+                const token = await h.token;
+                spent = h;
+                return token;
+            }
+            catch {
+                // The provider errored / timed out: start over with a fresh widget.
+                if (handle === h)
+                    reset();
+                return null;
+            }
+        },
+        reset,
+        destroy() {
+            remove();
+            container = null;
+        },
+    };
+}
+/**
+ * Swap the server's captcha refusals (CAPTCHA_REQUIRED / CAPTCHA_FAILED, which
+ * the server ties to the `captcha_token` param) for a localized, form-level
+ * message — there is no `captcha_token` input to hang a field error on. `t`
+ * resolves the `captcha.required` / `captcha.failed` catalog keys.
+ */
+function localizeCaptchaErrors(errors, t) {
+    let captchaRejected = false;
+    const out = errors.map((error) => {
+        if (!(0, captcha_widget_1.isCaptchaError)(error))
+            return error;
+        captchaRejected = true;
+        return {
+            code: error.code,
+            message: t(error.code === 'CAPTCHA_REQUIRED' ? 'captcha.required' : 'captcha.failed'),
+        };
+    });
+    return { errors: out, captchaRejected };
+}
+/**
+ * The sign-in captcha settings for the flow's current step: drawn on the
+ * identifier step when the instance ALWAYS requires one for sign-in (so the
+ * first POST already carries the token), and on the `needs_captcha` challenge
+ * step the server answers with when it withheld the attempt (always-on, or
+ * risk-triggered) — where it is drawn at once (even an invisible one) and
+ * solving it calls `onChallengeSolved`, which should resubmit.
+ */
+function signInCaptchaOptions(flow, state, onChallengeSolved) {
+    const kind = state.attempt ? (0, attempt_1.nextStep)(state.attempt).kind : 'collect_identifier';
+    const challenged = kind === 'collect_captcha';
+    return {
+        flow,
+        active: challenged || (kind === 'collect_identifier' && (0, captcha_widget_1.flowNeedsCaptcha)(flow)),
+        ...(challenged ? { eager: true, onSolved: () => onChallengeSolved() } : {}),
+    };
+}
+/**
+ * {@link advance} with the sign-in captcha folded in — what a prebuilt sign-in
+ * form calls on submit. On the identifier / `needs_captcha` step it adds the
+ * widget's token (re-issuing the identifier POST the challenge marker withheld);
+ * a token the provider rejected comes back as the same challenge, so it reports
+ * CAPTCHA_FAILED and draws a fresh widget (tokens are single-use). Captcha
+ * refusals are localized through `t`.
+ *
+ * `identifier` is the last identifier the user typed (the challenge marker
+ * carries none to re-send); the returned one is what to keep for next time.
+ */
+async function advanceWithCaptcha(client, state, values, opts) {
+    const { captcha, t } = opts;
+    const kind = state.attempt ? (0, attempt_1.nextStep)(state.attempt).kind : 'collect_identifier';
+    let identifier = opts.identifier ?? '';
+    let input = values;
+    let sentToken = false;
+    if (kind === 'collect_identifier' || kind === 'collect_captcha') {
+        if (values.identifier)
+            identifier = values.identifier;
+        if (captcha?.needed) {
+            const token = await captcha.getToken();
+            if (token) {
+                input = {
+                    ...values,
+                    identifier: identifier || (state.attempt?.identifier ?? ''),
+                    captcha_token: token,
+                };
+                sentToken = true;
+            }
+            else if (kind === 'collect_captcha') {
+                // Nothing to send until the widget yields a token.
+                return {
+                    state: {
+                        ...state,
+                        busy: false,
+                        errors: [{ code: 'CAPTCHA_REQUIRED', message: t('captcha.required') }],
+                    },
+                    identifier,
+                };
+            }
+        }
+    }
+    let next = await (0, fapi_1.advance)(client, state, input);
+    const rechallenged = !!next.attempt && (0, attempt_1.nextStep)(next.attempt).kind === 'collect_captcha';
+    if (sentToken && rechallenged) {
+        next = { ...next, errors: [{ code: 'CAPTCHA_FAILED', message: t('captcha.failed') }] };
+    }
+    next = { ...next, errors: localizeCaptchaErrors(next.errors, t).errors };
+    if (sentToken && (rechallenged || next.errors.length > 0))
+        captcha?.reset();
+    return { state: next, identifier };
+}
+/**
+ * Create the account from a prebuilt create-account form: takes the sign-up
+ * captcha's token (when one is needed), POSTs `/v1/client/sign_ups` via
+ * {@link startSignUp}, localizes captcha refusals and, when the create was
+ * refused, draws a fresh widget (the token was spent either way).
+ */
+async function createSignUp(client, values, opts) {
+    const token = opts.captcha ? await opts.captcha.getToken() : null;
+    let next = await (0, fapi_1.startSignUp)(client, (0, instance_settings_1.toSignUpInput)(values, opts.consent, token));
+    next = { ...next, errors: localizeCaptchaErrors(next.errors, opts.t).errors };
+    if (next.errors.length > 0 && opts.captcha?.needed)
+        opts.captcha.reset();
+    return next;
+}
+//# sourceMappingURL=captcha-controller.js.map