@atlasauth/js 0.1.0

package/dist/attempt.d.ts

@@ -0,0 +1,71 @@
+/**
+ * §5: "the client reads `status` and renders whatever the server demands next;
+ * it never picks the step itself."
+ *
+ * This is the client half of that contract, and it is written as an exhaustive
+ * mapping rather than a chain of ifs on purpose. An `if (status === ...)` ladder
+ * silently falls through when the server introduces a status the client has not
+ * seen — and "falls through" in a sign-in flow means a blank screen with no
+ * error, which is the single worst failure mode a login box has.
+ *
+ * Here an unknown status maps to an explicit `unknown` step that a UI can render
+ * as "this needs an update", which is honest and actionable.
+ */
+export type AttemptStatus = 'needs_identifier' | 'needs_first_factor' | 'needs_second_factor'
+/** §11.1 MFA policy `required`, for a user who has no second factor yet. */
+ | 'needs_mfa_enrollment' | 'needs_email_verification' | 'needs_oauth_callback' | 'needs_new_password'
+/** §5 the server is asking the identifier step to clear a captcha challenge. */
+ | 'needs_captcha' | 'complete' | 'abandoned';
+export type Step = {
+    kind: 'collect_identifier';
+} | {
+    kind: 'collect_first_factor';
+    strategies: string[];
+} | {
+    kind: 'collect_second_factor';
+} | {
+    kind: 'enroll_second_factor';
+} | {
+    kind: 'collect_email_code';
+} | {
+    kind: 'collect_captcha';
+} | {
+    kind: 'await_oauth';
+} | {
+    kind: 'collect_new_password';
+} | {
+    kind: 'done';
+    sessionId: string | null;
+} | {
+    kind: 'restart';
+    reason: 'abandoned';
+} | {
+    kind: 'unknown';
+    status: string;
+};
+export interface AttemptView {
+    status: string;
+    supported_first_factors?: string[];
+    created_session_id?: string | null;
+}
+export declare function nextStep(attempt: AttemptView): Step;
+/** Whether the flow can still progress, for deciding whether to keep polling. */
+export declare function isTerminal(attempt: AttemptView): boolean;
+/**
+ * §9.1 error envelope, reduced to what a form needs.
+ *
+ * The API writes messages for humans, so they are surfaced verbatim. The `param`
+ * is what lets a form attach the message to the right field instead of dumping
+ * everything in a banner at the top, which is how "password too short" ends up
+ * appearing next to the email input.
+ */
+export interface FieldError {
+    code: string;
+    message: string;
+    param?: string;
+}
+export declare function fieldErrors(body: unknown): FieldError[];
+/** Errors for one field, so a form can render them inline. */
+export declare function errorsFor(errors: readonly FieldError[], param: string): FieldError[];
+/** Errors with no field, which belong in a form-level banner. */
+export declare function formErrors(errors: readonly FieldError[]): FieldError[];

package/dist/attempt.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * §5: "the client reads `status` and renders whatever the server demands next;
+ * it never picks the step itself."
+ *
+ * This is the client half of that contract, and it is written as an exhaustive
+ * mapping rather than a chain of ifs on purpose. An `if (status === ...)` ladder
+ * silently falls through when the server introduces a status the client has not
+ * seen — and "falls through" in a sign-in flow means a blank screen with no
+ * error, which is the single worst failure mode a login box has.
+ *
+ * Here an unknown status maps to an explicit `unknown` step that a UI can render
+ * as "this needs an update", which is honest and actionable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextStep = nextStep;
+exports.isTerminal = isTerminal;
+exports.fieldErrors = fieldErrors;
+exports.errorsFor = errorsFor;
+exports.formErrors = formErrors;
+function nextStep(attempt) {
+    switch (attempt.status) {
+        case 'needs_identifier':
+            return { kind: 'collect_identifier' };
+        case 'needs_first_factor':
+            return {
+                kind: 'collect_first_factor',
+                // The server's list, never a client-side guess. §13.2 makes this list
+                // identical for unknown identifiers, so a client that filtered it by
+                // "what this user probably has" would reintroduce the enumeration leak
+                // the uniform response exists to close.
+                strategies: attempt.supported_first_factors ?? [],
+            };
+        case 'needs_second_factor':
+            return { kind: 'collect_second_factor' };
+        /**
+         * Distinct from `collect_second_factor`, and the difference matters: this
+         * user has NO factor to be asked for. Rendering a "enter your code" box
+         * here would ask for something that does not exist, and the person would
+         * have no way past it.
+         */
+        case 'needs_mfa_enrollment':
+            return { kind: 'enroll_second_factor' };
+        case 'needs_email_verification':
+            return { kind: 'collect_email_code' };
+        case 'needs_captcha':
+            return { kind: 'collect_captcha' };
+        case 'needs_oauth_callback':
+            return { kind: 'await_oauth' };
+        case 'needs_new_password':
+            return { kind: 'collect_new_password' };
+        case 'complete':
+            return { kind: 'done', sessionId: attempt.created_session_id ?? null };
+        case 'abandoned':
+            return { kind: 'restart', reason: 'abandoned' };
+        default:
+            /**
+             * A status this SDK version does not know. Rendering nothing would be a
+             * blank login box with no error; saying so lets the app show something a
+             * user can act on.
+             */
+            return { kind: 'unknown', status: attempt.status };
+    }
+}
+/** Whether the flow can still progress, for deciding whether to keep polling. */
+function isTerminal(attempt) {
+    return attempt.status === 'complete' || attempt.status === 'abandoned';
+}
+function fieldErrors(body) {
+    if (!body || typeof body !== 'object')
+        return [];
+    const errors = body.errors;
+    if (!Array.isArray(errors))
+        return [];
+    return errors
+        .filter((error) => {
+        return Boolean(error) && typeof error.message === 'string';
+    })
+        .map((error) => ({ code: error.code, message: error.message, param: error.param }));
+}
+/** Errors for one field, so a form can render them inline. */
+function errorsFor(errors, param) {
+    return errors.filter((error) => error.param === param);
+}
+/** Errors with no field, which belong in a form-level banner. */
+function formErrors(errors) {
+    return errors.filter((error) => !error.param);
+}
+//# sourceMappingURL=attempt.js.map

package/dist/attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.js","sourceRoot":"","sources":["../src/attempt.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAmCH,4BAqDC;AAGD,gCAEC;AAgBD,kCAUC;AAGD,8BAEC;AAGD,gCAEC;AA9FD,SAAgB,QAAQ,CAAC,OAAoB;IAC3C,QAAQ,OAAO,CAAC,MAAuB,EAAE,CAAC;QACxC,KAAK,kBAAkB;YACrB,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAExC,KAAK,oBAAoB;YACvB,OAAO;gBACL,IAAI,EAAE,sBAAsB;gBAC5B,sEAAsE;gBACtE,qEAAqE;gBACrE,uEAAuE;gBACvE,wCAAwC;gBACxC,UAAU,EAAE,OAAO,CAAC,uBAAuB,IAAI,EAAE;aAClD,CAAC;QAEJ,KAAK,qBAAqB;YACxB,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;QAE3C;;;;;WAKG;QACH,KAAK,sBAAsB;YACzB,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAE1C,KAAK,0BAA0B;YAC7B,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAExC,KAAK,eAAe;YAClB,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;QAErC,KAAK,sBAAsB;YACzB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QAEjC,KAAK,oBAAoB;YACvB,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAE1C,KAAK,UAAU;YACb,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI,EAAE,CAAC;QAEzE,KAAK,WAAW;YACd,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAElD;YACE;;;;eAIG;YACH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAgB,UAAU,CAAC,OAAoB;IAC7C,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,CAAC;AACzE,CAAC;AAgBD,SAAgB,WAAW,CAAC,IAAa;IACvC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACjD,MAAM,MAAM,GAAI,IAA6B,CAAC,MAAM,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAuB,EAAE;QACrC,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,OAAQ,KAAoB,CAAC,OAAO,KAAK,QAAQ,CAAC;IAC7E,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,8DAA8D;AAC9D,SAAgB,SAAS,CAAC,MAA6B,EAAE,KAAa;IACpE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;AACzD,CAAC;AAED,iEAAiE;AACjE,SAAgB,UAAU,CAAC,MAA6B;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/dist/check-session.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Silent "is this user already signed in with Atlas?" check for cross-property
+ * SSO — the browser-side companion to the server handshake.
+ *
+ * It runs an OIDC `prompt=none` request in a hidden iframe against the Atlas
+ * instance's `/oauth2/authorize`. If a session exists, Atlas redirects the
+ * iframe to the registered `redirectUri` with a `code` (the user is signed in);
+ * if not, it returns `error=login_required`. The tiny page you host at
+ * `redirectUri` calls {@link handleSilentCallback} to postMessage the result
+ * back to this opener — the standard OIDC silent-renew pattern.
+ *
+ * There is no visible navigation. This is a client-side convenience for UI
+ * decisions ("show Sign in" vs "show account"); the server (`authenticateRequest`
+ * / the handshake middleware) remains the security boundary.
+ *
+ * NOTE: not yet exercised in an integration test — verify against a live
+ * instance before relying on it. See docs/atlas-cross-property-sso-plan.md (P3).
+ */
+export interface CheckSessionOptions {
+    /** The Atlas instance origin / OIDC issuer, e.g. `https://id.atlasauth.net`. */
+    issuer: string;
+    /** A public OIDC client registered for silent checks. */
+    clientId: string;
+    /** A redirect URI registered on that client whose page calls {@link handleSilentCallback}. */
+    redirectUri: string;
+    /** Extra scopes beyond `openid`. Default: `['openid']`. */
+    scopes?: readonly string[];
+    /** Give up and report signed-out after this many ms. Default 8000. */
+    timeoutMs?: number;
+    /** A prior id_token to assert a specific user (`id_token_hint`). */
+    idTokenHint?: string;
+}
+export interface CheckSessionResult {
+    signedIn: boolean;
+    /** The OIDC error when signed out (`login_required`, `consent_required`, …). */
+    error?: string;
+}
+/**
+ * Run the silent check. Resolves `{ signedIn: true }` when the authorize
+ * endpoint returns a code, `{ signedIn: false, error }` on `login_required`
+ * (or any error / timeout). Never rejects — a timeout is a signed-out signal.
+ */
+export declare function checkSession(options: CheckSessionOptions): Promise<CheckSessionResult>;
+/**
+ * Call this from the page you host at `redirectUri`. It reads the OIDC result
+ * from the current URL and postMessages ONLY a signed-in/out verdict to the
+ * opener (the {@link checkSession} iframe parent), then the iframe is discarded.
+ * Safe to call unconditionally on that page; it no-ops outside an iframe.
+ *
+ * The single-use authorization `code` is deliberately NOT forwarded: silent auth
+ * only needs to know *whether* the user is signed in, and putting a live OAuth
+ * code on a postMessage channel is a needless secret exposure (a misconfigured
+ * `targetOrigin`, or any other listener, could capture and redeem it). We send a
+ * boolean instead; the code stays in this callback frame and is never redeemed.
+ */
+export declare function handleSilentCallback(targetOrigin?: string): void;

package/dist/check-session.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Silent "is this user already signed in with Atlas?" check for cross-property
+ * SSO — the browser-side companion to the server handshake.
+ *
+ * It runs an OIDC `prompt=none` request in a hidden iframe against the Atlas
+ * instance's `/oauth2/authorize`. If a session exists, Atlas redirects the
+ * iframe to the registered `redirectUri` with a `code` (the user is signed in);
+ * if not, it returns `error=login_required`. The tiny page you host at
+ * `redirectUri` calls {@link handleSilentCallback} to postMessage the result
+ * back to this opener — the standard OIDC silent-renew pattern.
+ *
+ * There is no visible navigation. This is a client-side convenience for UI
+ * decisions ("show Sign in" vs "show account"); the server (`authenticateRequest`
+ * / the handshake middleware) remains the security boundary.
+ *
+ * NOTE: not yet exercised in an integration test — verify against a live
+ * instance before relying on it. See docs/atlas-cross-property-sso-plan.md (P3).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSession = checkSession;
+exports.handleSilentCallback = handleSilentCallback;
+const DEFAULT_TIMEOUT = 8000;
+function randomState() {
+    const b = new Uint8Array(16);
+    crypto.getRandomValues(b);
+    return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Run the silent check. Resolves `{ signedIn: true }` when the authorize
+ * endpoint returns a code, `{ signedIn: false, error }` on `login_required`
+ * (or any error / timeout). Never rejects — a timeout is a signed-out signal.
+ */
+function checkSession(options) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return Promise.resolve({ signedIn: false, error: 'not_in_browser' });
+    }
+    const state = randomState();
+    const authUrl = new URL('/oauth2/authorize', options.issuer);
+    authUrl.searchParams.set('client_id', options.clientId);
+    authUrl.searchParams.set('redirect_uri', options.redirectUri);
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('scope', (options.scopes ?? ['openid']).join(' '));
+    authUrl.searchParams.set('prompt', 'none');
+    authUrl.searchParams.set('state', state);
+    if (options.idTokenHint)
+        authUrl.searchParams.set('id_token_hint', options.idTokenHint);
+    const expectedOrigin = new URL(options.redirectUri).origin;
+    return new Promise((resolve) => {
+        const iframe = document.createElement('iframe');
+        iframe.style.display = 'none';
+        let done = false;
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            clearTimeout(timer);
+            iframe.remove();
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            cleanup();
+            resolve(result);
+        };
+        const onMessage = (event) => {
+            // Only trust a message from our own callback origin carrying our state.
+            if (event.origin !== expectedOrigin)
+                return;
+            const data = event.data;
+            if (!data || data.source !== 'atlas:silent-auth' || data.state !== state)
+                return;
+            // Trust only the boolean the callback computed — the raw OAuth code never
+            // travels over this channel, so there is nothing here to trust or leak.
+            finish({ signedIn: data.signedIn === true && !data.error, error: data.error });
+        };
+        const timer = setTimeout(() => finish({ signedIn: false, error: 'timeout' }), options.timeoutMs ?? DEFAULT_TIMEOUT);
+        window.addEventListener('message', onMessage);
+        iframe.src = authUrl.toString();
+        document.body.appendChild(iframe);
+    });
+}
+/**
+ * Call this from the page you host at `redirectUri`. It reads the OIDC result
+ * from the current URL and postMessages ONLY a signed-in/out verdict to the
+ * opener (the {@link checkSession} iframe parent), then the iframe is discarded.
+ * Safe to call unconditionally on that page; it no-ops outside an iframe.
+ *
+ * The single-use authorization `code` is deliberately NOT forwarded: silent auth
+ * only needs to know *whether* the user is signed in, and putting a live OAuth
+ * code on a postMessage channel is a needless secret exposure (a misconfigured
+ * `targetOrigin`, or any other listener, could capture and redeem it). We send a
+ * boolean instead; the code stays in this callback frame and is never redeemed.
+ */
+function handleSilentCallback(targetOrigin) {
+    if (typeof window === 'undefined' || window.parent === window)
+        return;
+    const params = new URLSearchParams(window.location.search);
+    const error = params.get('error') ?? undefined;
+    window.parent.postMessage({
+        source: 'atlas:silent-auth',
+        state: params.get('state') ?? undefined,
+        signedIn: Boolean(params.get('code')) && !error,
+        error,
+    }, targetOrigin ?? window.location.origin);
+}
+//# sourceMappingURL=check-session.js.map

package/dist/check-session.js.map

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

package/dist/connect.d.ts

@@ -0,0 +1,50 @@
+/**
+ * §6.6 Connect a NEW OAuth provider to the signed-in user.
+ *
+ * This is the SDK call behind a customer's OWN "Connect GitHub" button in their
+ * settings page — no Atlas widget, no panel. It starts the provider OAuth link
+ * flow and resolves with the `authorizationUrl` to send the browser to. On the
+ * customer's `redirectUrl` the provider returns with `?__atlas_status=connected`
+ * (or `error`), which {@link readRedirectResult} parses.
+ *
+ * The link is bound to the CURRENT session's user, so — unlike a sign-in — it
+ * never creates a new account or session, never resolves an identity by email,
+ * and is unaffected by the account-linking `block` policy (the user is already
+ * authenticated and explicitly linking). Requires the browser session cookie, so
+ * the request is sent with credentials.
+ */
+export interface ConnectOptions {
+    /** FAPI base, e.g. 'https://accounts.acme.com' or '' for same-origin. */
+    api: string;
+    publishableKey: string;
+    /**
+     * Where the provider returns after the user authorizes — must be one of the
+     * instance's allowed origins. Read the outcome there with `readRedirectResult`.
+     */
+    redirectUrl: string;
+    /** Extra provider scopes on top of the provider's defaults. */
+    additionalScopes?: string[];
+    fetchImpl?: typeof fetch;
+}
+export interface ConnectStart {
+    provider: string;
+    attemptId: string;
+    /** Navigate the browser here to let the user authorize the provider. */
+    authorizationUrl: string;
+    /** The scopes the connect will request (provider defaults ∪ additionalScopes). */
+    scopes: string[];
+}
+/**
+ * Begin linking `provider` to the signed-in user. Resolves with the provider
+ * authorize URL to navigate to; throws with the server's message (and a `.code`,
+ * e.g. `IDENTITY_ALREADY_LINKED`) on failure. Use {@link startConnect} if you
+ * just want it to redirect for you.
+ */
+export declare function connectExternalAccount(provider: string, opts: ConnectOptions): Promise<ConnectStart>;
+/**
+ * Convenience wrapper: start the connection AND navigate the browser to the
+ * provider. A settings-page button handler can be just:
+ *
+ *   onClick={() => startConnect('github', { api, publishableKey, redirectUrl })}
+ */
+export declare function startConnect(provider: string, opts: ConnectOptions): Promise<void>;

package/dist/connect.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * §6.6 Connect a NEW OAuth provider to the signed-in user.
+ *
+ * This is the SDK call behind a customer's OWN "Connect GitHub" button in their
+ * settings page — no Atlas widget, no panel. It starts the provider OAuth link
+ * flow and resolves with the `authorizationUrl` to send the browser to. On the
+ * customer's `redirectUrl` the provider returns with `?__atlas_status=connected`
+ * (or `error`), which {@link readRedirectResult} parses.
+ *
+ * The link is bound to the CURRENT session's user, so — unlike a sign-in — it
+ * never creates a new account or session, never resolves an identity by email,
+ * and is unaffected by the account-linking `block` policy (the user is already
+ * authenticated and explicitly linking). Requires the browser session cookie, so
+ * the request is sent with credentials.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectExternalAccount = connectExternalAccount;
+exports.startConnect = startConnect;
+/**
+ * Begin linking `provider` to the signed-in user. Resolves with the provider
+ * authorize URL to navigate to; throws with the server's message (and a `.code`,
+ * e.g. `IDENTITY_ALREADY_LINKED`) on failure. Use {@link startConnect} if you
+ * just want it to redirect for you.
+ */
+async function connectExternalAccount(provider, opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const res = await doFetch(`${opts.api}/v1/client/me/external_accounts/connect`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-publishable-key': opts.publishableKey },
+        credentials: 'include',
+        body: JSON.stringify({
+            provider,
+            redirect_url: opts.redirectUrl,
+            additional_scopes: opts.additionalScopes,
+        }),
+    });
+    if (!res.ok) {
+        let message = 'Could not start connecting that provider.';
+        let code;
+        try {
+            const parsed = (await res.json());
+            message = parsed.errors?.[0]?.message ?? message;
+            code = parsed.errors?.[0]?.code;
+        }
+        catch {
+            /* keep the default */
+        }
+        const err = new Error(message);
+        err.code = code;
+        throw err;
+    }
+    const data = (await res.json());
+    return {
+        provider: data.provider,
+        attemptId: data.attempt_id,
+        authorizationUrl: data.authorization_url,
+        scopes: data.scopes ?? [],
+    };
+}
+/**
+ * Convenience wrapper: start the connection AND navigate the browser to the
+ * provider. A settings-page button handler can be just:
+ *
+ *   onClick={() => startConnect('github', { api, publishableKey, redirectUrl })}
+ */
+async function startConnect(provider, opts) {
+    const { authorizationUrl } = await connectExternalAccount(provider, opts);
+    if (typeof window !== 'undefined')
+        window.location.assign(authorizationUrl);
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AA+BH,wDA2CC;AAQD,oCAGC;AA5DD;;;;;GAKG;AACI,KAAK,UAAU,sBAAsB,CAC1C,QAAgB,EAChB,IAAoB;IAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IACxC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,yCAAyC,EAAE;QAC9E,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,IAAI,CAAC,cAAc,EAAE;QACzF,WAAW,EAAE,SAAS;QACtB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,QAAQ;YACR,YAAY,EAAE,IAAI,CAAC,WAAW;YAC9B,iBAAiB,EAAE,IAAI,CAAC,gBAAgB;SACzC,CAAC;KACH,CAAC,CAAC;IAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,OAAO,GAAG,2CAA2C,CAAC;QAC1D,IAAI,IAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuD,CAAC;YACxF,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,OAAO,CAAC;YACjD,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,GAAyB,CAAC,IAAI,GAAG,IAAI,CAAC;QACvC,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAK7B,CAAC;IACF,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,IAAI,CAAC,UAAU;QAC1B,gBAAgB,EAAE,IAAI,CAAC,iBAAiB;QACxC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,YAAY,CAAC,QAAgB,EAAE,IAAoB;IACvE,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,sBAAsB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC1E,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAC9E,CAAC"}

package/dist/fapi.d.ts

@@ -0,0 +1,123 @@
+import { type AttemptView, type FieldError } from './attempt';
+/**
+ * The FAPI client and the sign-in flow driver.
+ *
+ * The driver's whole job is to answer one question — "given the step the server
+ * says we are on, which endpoint does this input go to?" — and to answer it in
+ * ONE place. Scattering that decision across a component is how a password ends
+ * up posted to the second-factor endpoint, or a TOTP code to
+ * `attempt_first_factor`: both produce a confusing 400 rather than an obvious
+ * bug, and both are easy to write.
+ *
+ * Nothing here ever advances the flow locally. The status always comes back
+ * from the server (§5), so a client that guesses wrong is corrected on the next
+ * response rather than diverging silently.
+ */
+export interface FapiClientOptions {
+    publishableKey: string;
+    /** The instance's FAPI origin. Empty for same-origin. */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface FapiResponse<T> {
+    ok: boolean;
+    status: number;
+    data: T | null;
+    errors: FieldError[];
+}
+export declare class FapiClient {
+    private readonly options;
+    constructor(options: FapiClientOptions);
+    request<T>(path: string, init?: RequestInit): Promise<FapiResponse<T>>;
+    post<T>(path: string, body?: unknown): Promise<FapiResponse<T>>;
+    get<T>(path: string): Promise<FapiResponse<T>>;
+}
+/**
+ * §6.6 client-side token vault. A signed-in user's OWN live provider access
+ * token, so the app can call e.g. the Google API from the browser — the
+ * `user.getToken({ provider })` equivalent.
+ *
+ * The server keys the lookup off the session, never a user id, so this can only
+ * ever return the caller's own token. The long-lived refresh token is never
+ * exposed — only the short-lived access token it mints.
+ */
+export interface ProviderToken {
+    provider: string;
+    accessToken: string;
+    /** Epoch ms, or null when the provider issues non-expiring tokens. */
+    expiresAt: number | null;
+    scopes: string[];
+}
+/**
+ * Fetch the signed-in user's provider access token. Returns null when there is
+ * no usable token (no linked account, or the provider granted none / revoked
+ * it) — the caller's cue to prompt a re-connect rather than treat it as fatal.
+ * The server refreshes a stale token on read, single-flight, so the token
+ * handed back is always live.
+ */
+export declare function getProviderToken(client: FapiClient, provider: string): Promise<ProviderToken | null>;
+export interface FlowState {
+    attempt: AttemptView | null;
+    errors: FieldError[];
+    busy: boolean;
+    /** Held only for the magic-link path; see §5.3. */
+    pollSecret: string | null;
+    /**
+     * §7.1: the one-time ticket a completion response carries. Present for exactly
+     * one step — the one that reached `complete` — so the caller can exchange it
+     * for cookies and then it is gone.
+     */
+    ticket: string | null;
+}
+export declare const initialFlow: FlowState;
+/**
+ * Which request the current step needs.
+ *
+ * Exported and tested separately from the network call, because this mapping is
+ * the part that can be wrong in a way nobody notices until a user is stuck.
+ */
+export declare function requestForStep(attempt: AttemptView | null, values: Record<string, string>): {
+    path: string;
+    body: Record<string, unknown>;
+} | null;
+/**
+ * §5.3: seed a flow from an attempt the app was handed mid-stream — an OAuth
+ * redirect that came back needing a second factor (`__atlas_status`), with no
+ * ticket because the server withheld the session until the factor is passed.
+ *
+ * The attempt id lets the next submit target the right attempt; the status
+ * routes the UI to the step the server is demanding. A null pending attempt —
+ * the ordinary fresh sign-in — yields the empty initial flow.
+ */
+export declare function flowFromPending(pending: {
+    id: string;
+    status: string;
+} | null): FlowState;
+/** Advance the flow by one step. Never decides the next status itself. */
+export declare function advance(client: FapiClient, state: FlowState, values: Record<string, string>): Promise<FlowState>;
+/**
+ * §5 Begin a password sign-up. POSTs email + password + the tenant's configured
+ * extra fields (name, company, phone, custom…) to `/v1/client/sign_ups` and
+ * returns a flow. Usually `needs_email_verification` — the shared `advance` then
+ * drives the emailed code to completion — or, when the instance doesn't gate on
+ * verification, a `complete` attempt carrying the session ticket.
+ */
+export declare function startSignUp(client: FapiClient, input: {
+    email: string;
+    password: string;
+    fields?: Record<string, string>;
+    consent?: boolean;
+    captchaToken?: string;
+}): Promise<FlowState>;
+/** §5.3: ask the server to send a code or a magic link. */
+export declare function prepareFactor(client: FapiClient, state: FlowState, strategy: 'email_code' | 'email_link'): Promise<FlowState>;
+/**
+ * §5.3 polling. Returns the updated flow, and a ticket once the link has been
+ * opened somewhere.
+ */
+export declare function pollAttempt(client: FapiClient, state: FlowState): Promise<{
+    state: FlowState;
+    ticket: string | null;
+}>;
+/** Whether polling should continue, so a tab does not poll a dead attempt forever. */
+export declare function shouldKeepPolling(state: FlowState): boolean;