@somewhere-cloud/sdk 0.0.0-stage → 0.13.1

package/dist/cjs/auth/client.js

@@ -0,0 +1,1142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthError = void 0;
+exports.createSomewhereAuth = createSomewhereAuth;
+const continuation_js_1 = require("./continuation.js");
+const ACCESS_ROTATE_HEADER = 'X-New-Access-Token';
+const REFRESH_ROTATE_HEADER = 'X-New-Refresh-Token';
+const RIDE_ALONG_HEADER = 'X-Refresh-Token';
+// Sent on every sign-in call: `cookie` when this client prefers cookies (a
+// cookie-capable backend sets the httpOnly pair and replies
+// `cookie_session: true`; one that ignores the hint is refused with
+// COOKIE_SESSION_NOT_CONFIRMED), `header` in header mode — the explicit
+// opt-in the packaged handler requires before it returns tokens.
+const MODE_HINT_HEADER = 'X-Sw-Auth-Mode';
+function memoryStorage() {
+    const m = new Map();
+    return {
+        getItem: (k) => (m.has(k) ? m.get(k) : null),
+        setItem: (k, v) => void m.set(k, v),
+        removeItem: (k) => void m.delete(k),
+    };
+}
+function defaultStorage() {
+    try {
+        if (typeof localStorage !== 'undefined')
+            return localStorage;
+    }
+    catch {
+        /* access can throw in sandboxed iframes */
+    }
+    return memoryStorage();
+}
+/** The social callback's public attempt id: passed explicitly, or read from the
+ *  callback page's own URL. It only selects which of this browser's attempt
+ *  cookies the server presents; the platform proves it before the code counts. */
+function oauthAttempt(input) {
+    if (typeof input.attempt === 'string')
+        return { attempt: input.attempt };
+    if (typeof window === 'undefined')
+        return {};
+    const fromUrl = new URL(window.location.href).searchParams.get('attempt');
+    return fromUrl ? { attempt: fromUrl } : {};
+}
+/** undefined → 30000; anything else must be 1..2147483647 ms (setTimeout's range). */
+function mutationTimeout(value) {
+    if (value === undefined)
+        return 30000;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 2147483647) {
+        throw new RangeError('mutationTimeoutMs must be a number of milliseconds from 1 to 2147483647.');
+    }
+    return value;
+}
+function createSomewhereAuth(options = {}) {
+    const baseUrl = (options.baseUrl ?? '').replace(/\/$/, '');
+    const authPath = (options.authPath ?? '/api/auth').replace(/\/$/, '');
+    const storage = options.storage ?? defaultStorage();
+    const key = options.storageKey ?? 'sw_auth';
+    const userKey = `${key}_user`; // cached user JSON for optimistic restore (tsk_1288e1c6)
+    // ONLY-PATH CONTRACT (tsk_acd56ee8): browsers use cookie sessions and keep
+    // credentials out of page JavaScript. Header mode exists only for non-browser
+    // clients and rule-9 compatibility with pre-0.2.0/older-handler sessions.
+    const preferCookie = options.mode ? options.mode === 'cookie' : typeof document !== 'undefined';
+    // No credentials: retain logout intent across navigation, including navigation
+    // before the queued request starts. Only a confirmed new sign-in replaces it.
+    const signOutKey = `${userKey}:sign-out:${baseUrl}${authPath}`;
+    let signOutIntent = null;
+    let signOutStorageAvailable = true;
+    function readSignOutIntent() {
+        if (preferCookie && signOutStorageAvailable) {
+            try {
+                signOutIntent = storage.getItem(signOutKey);
+            }
+            catch { /* retain memory state */ }
+        }
+        return signOutIntent;
+    }
+    function writeSignOutIntent(next) {
+        signOutIntent = next;
+        if (preferCookie) {
+            try {
+                if (next === null)
+                    storage.removeItem(signOutKey);
+                else
+                    storage.setItem(signOutKey, next);
+            }
+            catch {
+                signOutStorageAvailable = false;
+            }
+        }
+    }
+    const restoredSignOut = readSignOutIntent();
+    let session = restoredSignOut ? null : loadSession();
+    // Optimistic restore: seed the user from cache so a fresh page load paints
+    // the signed-in UI immediately and a transient /me failure (offline, 5xx)
+    // never flashes logged-out. In header mode only trust the cache when a
+    // session exists — no tokens means no user, don't show a ghost. In cookie
+    // mode the tokens are httpOnly (unreadable here), so the cached user IS our
+    // best knowledge of the session; /me validates it in the background.
+    //
+    // Note: when `session` is non-null under preferCookie, this is an EXISTING
+    // header-mode session from a pre-0.2.0 install. We adopt it as-is (header
+    // transport) so the upgrade logs nobody out; it migrates to cookies on the
+    // next sign-in.
+    let pendingMfa = null;
+    let user = !restoredSignOut && (session || preferCookie) ? loadUser() : null;
+    // A cached user is unverified until the backend answers.
+    let status = !restoredSignOut && (session || preferCookie) ? 'checking' : 'signed-out';
+    let error = restoredSignOut?.startsWith('pending:')
+        ? new AuthError('Sign-out has not been confirmed by the server.', 0, 'SIGN_OUT_UNCONFIRMED') : null;
+    // Advances when an identity change is REQUESTED (sign-in family, signOut) or
+    // arrives from another tab. Responses to requests started under an earlier
+    // generation never write user, session or status.
+    let generation = 0;
+    // Cookie-changing calls run one at a time, in call order. The chain keeps
+    // going after a rejection; each call is bounded by mutationTimeoutMs.
+    let mutations = Promise.resolve();
+    let pendingMutations = 0;
+    const mutationTimeoutMs = mutationTimeout(options.mutationTimeoutMs);
+    // A sign-out the server has not confirmed. It stays owed (state
+    // signOutUnconfirmed + error) and the next signOut() retries it, with the
+    // header session it was for, until /logout succeeds or a sign-in replaces
+    // the session. Cookie clients retain intent across reload as well.
+    let owedSignOut = error ? { session: null, error } : null;
+    // signOut() calls whose /logout has not settled yet (AuthState.signingOut).
+    let signOutsInFlight = 0;
+    // At most one /me per generation; concurrent getUser() calls share it.
+    let check = null;
+    const listeners = new Set();
+    let refreshFlight = null;
+    // True while the in-flight refresh was started in the background (timer or focus), while the
+    // held access token was still valid. Requests then need not wait for it (see authFetch).
+    let refreshInBackground = false;
+    let refreshTimer;
+    let nextRefreshAt = 0;
+    const refreshStampKey = userKey + ':refresh-at';
+    const refreshPendingKey = userKey + ':refresh-pending';
+    function beginRefresh() {
+        if (storage.getItem(refreshPendingKey))
+            throw new AuthError('Another refresh has an unknown outcome. Sign in again.', 0, 'REFRESH_OUTCOME_UNKNOWN');
+        const marker = String(Date.now()) + ':' + Math.random();
+        storage.setItem(refreshPendingKey, marker);
+        return marker;
+    }
+    /** A pending marker seen while holding the refresh lock belongs to no live refresh: one that was
+     *  cut off (a page change or crash mid-request), so its rotation may or may not have committed. */
+    function refreshOrphaned() { try {
+        return storage.getItem(refreshPendingKey) !== null;
+    }
+    catch {
+        return false;
+    } }
+    function confirmRefresh(marker) { try {
+        if (marker === undefined || storage.getItem(refreshPendingKey) === marker)
+            storage.removeItem(refreshPendingKey);
+    }
+    catch { /* a new sign-in still replaces local credentials */ } }
+    let accessExpiresAt = session ? tokenExpiry(session.accessToken) : 0;
+    let refreshUncertain = false;
+    function tokenExpiry(token) {
+        try {
+            return Number(JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/'))).exp) * 1000 || 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    function loadSession() {
+        try {
+            const raw = storage.getItem(key);
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed.accessToken === 'string' && typeof parsed.refreshToken === 'string') {
+                return { accessToken: parsed.accessToken, refreshToken: parsed.refreshToken };
+            }
+        }
+        catch {
+            /* corrupt → treat as logged out */
+        }
+        return null;
+    }
+    function loadUser() {
+        try {
+            const raw = storage.getItem(userKey);
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            if ((0, continuation_js_1.isAuthUser)(parsed))
+                return parsed;
+            storage.removeItem(userKey);
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    function snapshot() {
+        return { status, user, session, error, signOutUnconfirmed: owedSignOut !== null, signingOut: signOutsInFlight > 0 };
+    }
+    function emit() {
+        const state = snapshot();
+        for (const l of listeners)
+            l(state);
+    }
+    /** ATOMIC: persist the whole session as one value, or clear it. There is no
+     *  code path that writes one token without the other. */
+    function writeSession(next) {
+        session = next;
+        accessExpiresAt = next ? tokenExpiry(next.accessToken) : 0;
+        try {
+            if (next)
+                storage.setItem(key, JSON.stringify(next));
+            else
+                storage.removeItem(key);
+        }
+        catch {
+            /* storage unavailable — keep the in-memory session anyway */
+        }
+    }
+    function writeUser(next) {
+        user = next;
+        try {
+            const raw = next ? JSON.stringify(next) : null;
+            // Identical writes are skipped so other tabs only hear real changes.
+            if (storage.getItem(userKey) !== raw) {
+                if (raw === null)
+                    storage.removeItem(userKey);
+                else
+                    storage.setItem(userKey, raw);
+            }
+        }
+        catch {
+            /* storage unavailable — keep the in-memory user anyway */
+        }
+    }
+    function setSession(next) {
+        writeSession(next);
+        emit();
+    }
+    /** A definitive state. An owed sign-out keeps reporting its error. */
+    function settle(next, nextUser) {
+        if (next === 'authenticated' && !(0, continuation_js_1.isAuthUser)(nextUser))
+            throw new AuthError('Auth response did not include a valid user.', 502, 'INVALID_AUTH_RESPONSE');
+        writeUser(nextUser);
+        status = next;
+        scheduleRefresh();
+        error = owedSignOut?.error ?? null;
+        emit();
+    }
+    /** A check failed without an answer: keep the last-known user, unverified. */
+    function indeterminate(httpStatus) {
+        status = 'indeterminate';
+        error = new AuthError(httpStatus
+            ? `The session check failed (${httpStatus}); the sign-in state is unknown.`
+            : 'The session check could not reach the server; the sign-in state is unknown.', httpStatus, 'SESSION_CHECK_FAILED');
+        emit();
+    }
+    function superseded() {
+        return new AuthError('A newer sign-in or sign-out replaced this request.', 0, 'AUTH_SUPERSEDED');
+    }
+    function timedOut() {
+        return new AuthError('The auth request timed out; the server may still have completed it.', 0, 'AUTH_TIMEOUT');
+    }
+    /** Run a cookie-changing call after every earlier one has settled. The
+     *  deadline covers the whole call (request, body, follow-up /me): at
+     *  mutationTimeoutMs the call is aborted and rejected so the queue moves on,
+     *  and the task must write nothing once `signal.aborted` is true. */
+    function enqueue(task) {
+        pendingMutations++;
+        const run = mutations
+            .then(() => new Promise((resolve, reject) => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => {
+                controller.abort();
+                reject(timedOut());
+            }, mutationTimeoutMs);
+            const execute = () => new Promise((done, fail) => {
+                const abort = () => fail(timedOut());
+                if (controller.signal.aborted) {
+                    abort();
+                    return;
+                }
+                controller.signal.addEventListener('abort', abort, { once: true });
+                task(controller.signal).then(done, fail).finally(() => controller.signal.removeEventListener('abort', abort));
+            });
+            const work = typeof navigator !== 'undefined' && navigator.locks
+                ? navigator.locks.request(refreshStampKey, { signal: controller.signal }, execute) : execute();
+            work
+                .then(resolve, (e) => reject(controller.signal.aborted ? timedOut() : e))
+                .finally(() => clearTimeout(timer));
+        }))
+            .finally(() => {
+            pendingMutations--;
+        });
+        mutations = run.catch(() => undefined);
+        return run;
+    }
+    // Cross-tab sync: `storage` fires only in OTHER tabs/windows of the same
+    // origin. A rotated header pair for the same identity is adopted (the
+    // multi-tab refresh footgun this package exists to kill). A different
+    // identity is NOT trusted: status goes to 'checking' and /me re-checks.
+    // key === null means storage.clear().
+    if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+        window.addEventListener('storage', (e) => {
+            if (e.key !== null && e.key !== key && e.key !== userKey && e.key !== signOutKey)
+                return;
+            const intent = readSignOutIntent();
+            if (intent) {
+                generation++;
+                writeSession(null);
+                owedSignOut = intent.startsWith('pending:')
+                    ? { session: null, error: new AuthError('Sign-out has not been confirmed by the server.', 0, 'SIGN_OUT_UNCONFIRMED') } : null;
+                settle('signed-out', null);
+                return;
+            }
+            const nextSession = loadSession();
+            const nextUser = nextSession || preferCookie ? loadUser() : null;
+            const identityChanged = (nextUser?.id ?? null) !== (user?.id ?? null) || !nextSession !== !session;
+            if (!identityChanged) {
+                if (nextSession?.accessToken !== session?.accessToken || nextSession?.refreshToken !== session?.refreshToken) {
+                    session = nextSession;
+                    accessExpiresAt = nextSession ? tokenExpiry(nextSession.accessToken) : 0;
+                    scheduleRefresh();
+                    emit();
+                }
+                return;
+            }
+            generation++;
+            session = nextSession;
+            user = nextUser;
+            status = 'checking';
+            error = null;
+            emit();
+            void getUser();
+        });
+    }
+    // Standard short access-token refresh. Timers are an optimization: a resumed
+    // client also refreshes before sending protected work. No password is involved.
+    function scheduleRefresh(delay) {
+        if (refreshTimer !== undefined)
+            clearTimeout(refreshTimer);
+        if (status !== 'authenticated' || refreshUncertain || readSignOutIntent())
+            return;
+        // An unknown expiry is not an expired one: refreshing at once raced the page change that follows
+        // a sign-in (pfb_01e440702f31). The next session check learns the expiry (X-Sw-Access-Expires).
+        if (delay === undefined) {
+            if (!(accessExpiresAt > 0)) {
+                nextRefreshAt = Number.POSITIVE_INFINITY;
+                return;
+            }
+            delay = Math.max(0, accessExpiresAt - Date.now() - 10000 - Math.random() * 3000);
+        }
+        nextRefreshAt = Date.now() + delay;
+        if (typeof window === 'undefined')
+            return;
+        refreshTimer = setTimeout(() => { void refreshSession(true).catch(() => undefined); }, delay);
+    }
+    function refreshSession(background = false) {
+        if (readSignOutIntent())
+            return Promise.resolve();
+        if (refreshFlight)
+            return refreshFlight;
+        if (refreshUncertain)
+            return Promise.reject(new AuthError('Refresh outcome is unknown. Sign in again to establish a new session.', 0, 'REFRESH_OUTCOME_UNKNOWN'));
+        const started = generation;
+        const run = async (signal) => {
+            if (started !== generation || status === 'signed-out' || readSignOutIntent())
+                return;
+            // Another browser tab may have refreshed while this one awaited the lock.
+            let sharedAt = 0;
+            try {
+                sharedAt = Number(storage.getItem(refreshStampKey));
+            }
+            catch { /* storage can be unavailable */ }
+            if (Number.isFinite(sharedAt) && sharedAt > Date.now()) {
+                if (!preferCookie) {
+                    session = loadSession();
+                    accessExpiresAt = session ? tokenExpiry(session.accessToken) : 0;
+                }
+                scheduleRefresh(Math.max(1000, sharedAt - Date.now()));
+                return;
+            }
+            beginRefresh();
+            const headers = { 'X-Sw-Auth-Mode': preferCookie ? 'cookie' : 'header' };
+            if (session) {
+                headers.Authorization = 'Bearer ' + session.accessToken;
+                headers[RIDE_ALONG_HEADER] = session.refreshToken;
+            }
+            // Cookie refresh must not outlive its document and overwrite cookies from
+            // a newer sign-in. Interrupted rotations retain the existing unknown-outcome
+            // marker; they are reconciled without replaying a possibly consumed token.
+            const res = await fetch(url('/refresh'), { method: 'POST', credentials: 'include', headers, signal, keepalive: !preferCookie });
+            if (started !== generation || signal.aborted || readSignOutIntent())
+                return;
+            if (res.status === 401 || res.status === 403) {
+                confirmRefresh();
+                writeSession(null);
+                settle('signed-out', null);
+                return;
+            }
+            if (!res.ok)
+                throw new AuthError('Session refresh unavailable.', res.status);
+            const body = await res.json();
+            if (started !== generation || signal.aborted || readSignOutIntent())
+                return;
+            if (!preferCookie) {
+                const tokens = pickTokens(body);
+                if (!tokens)
+                    throw new AuthError('Refresh did not return credentials.', 502);
+                writeSession({ accessToken: tokens.access, refreshToken: tokens.refresh });
+            }
+            if (body.user)
+                writeUser(body.user);
+            accessExpiresAt = body.expires_at ?? (session ? tokenExpiry(session.accessToken) : 0);
+            if (!Number.isFinite(accessExpiresAt) || accessExpiresAt <= Date.now())
+                throw new AuthError('Refresh returned an expired access token.', 502);
+            const delay = Math.max(1000, accessExpiresAt - Date.now() - 10000 - Math.random() * 3000);
+            confirmRefresh();
+            try {
+                storage.setItem(refreshStampKey, String(Date.now() + delay));
+            }
+            catch { /* memory still works */ }
+            scheduleRefresh(delay);
+        };
+        // Web Locks serialize refresh across same-origin tabs; the existing mutation
+        // queue serializes it against sign-in/out in this client.
+        refreshInBackground = background;
+        refreshFlight = enqueue(run).catch((e) => {
+            if (started === generation) {
+                refreshUncertain = true;
+                indeterminate(0);
+                if (refreshTimer !== undefined)
+                    clearTimeout(refreshTimer);
+            }
+            throw e;
+        }).finally(() => { refreshFlight = null; refreshInBackground = false; });
+        return refreshFlight;
+    }
+    if (typeof window !== 'undefined') {
+        window.addEventListener('focus', () => { if (status === 'authenticated' && Date.now() >= nextRefreshAt)
+            void refreshSession(true).catch(() => undefined); });
+    }
+    // A background refresh starts while the held access token is still valid (10-13 s before
+    // expiry). A read sent meanwhile need not wait for it: it goes out on the still-valid token
+    // with X-No-Auto-Refresh (and no ride-along refresh token), so the server can never rotate the
+    // refresh credential the background refresh is already rotating, and the response carries no
+    // pair that could overwrite the new one. If the token is rejected anyway (clock skew), the read
+    // waits for the refresh to settle and is sent ONCE more the normal way; it is never treated as
+    // a sign-out while the refresh is pending. Only GET/HEAD qualify: a mutation still waits, so a
+    // mutation is never sent twice. A demand refresh (token expired or about to be) still blocks.
+    const CONCURRENT_READ_MIN_MS = 5000;
+    const authFetch = (input, init = {}) => send(input, init, true);
+    const sendDuringRefresh = (input, init) => {
+        const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
+        headers.set('X-No-Auto-Refresh', '1');
+        headers.delete(RIDE_ALONG_HEADER);
+        const target = input instanceof Request ? input.clone() : input;
+        // Cookie transport: the browser attaches the cookies; the opt-out keeps the server from
+        // rotating them in-band, so no Set-Cookie can race the background refresh.
+        if (preferCookie && !session)
+            return fetch(target, { credentials: 'include', ...init, headers });
+        if (session)
+            headers.set('Authorization', `Bearer ${session.accessToken}`);
+        return fetch(target, { ...init, headers });
+    };
+    const send = async (input, init = {}, mayOverlapRefresh) => {
+        if (readSignOutIntent()) {
+            const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
+            headers.delete('Authorization');
+            headers.delete(RIDE_ALONG_HEADER);
+            return fetch(input, { ...init, headers, credentials: 'omit' });
+        }
+        if (refreshUncertain) {
+            if (status !== 'authenticated')
+                throw new AuthError('Refresh outcome is unknown. Sign in again.', 0, 'REFRESH_OUTCOME_UNKNOWN');
+            // Reconciled: the held access token still answers, but the refresh credential behind it may
+            // have rotated, so it is used as is and never rotated. When it runs out, re-check the session.
+            const res = await sendDuringRefresh(input, init);
+            if (res.status === 401)
+                void getUser();
+            return res;
+        }
+        const method = (init.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+        const flight = refreshFlight;
+        const overlap = mayOverlapRefresh && flight !== null && refreshInBackground
+            && (method === 'GET' || method === 'HEAD')
+            && Number.isFinite(accessExpiresAt) && accessExpiresAt - Date.now() >= CONCURRENT_READ_MIN_MS;
+        if (flight && !overlap)
+            await flight;
+        else if (!flight && pendingMutations === 0 && status === 'authenticated' && Date.now() >= nextRefreshAt)
+            await refreshSession();
+        if (readSignOutIntent())
+            return send(input, init, false);
+        const started = generation;
+        if (overlap && flight) {
+            const res = await sendDuringRefresh(input, init);
+            if (res.status !== 401)
+                return res;
+            await flight.catch(() => undefined);
+            if (started !== generation)
+                return res;
+            return send(input, init, false);
+        }
+        // Cookie path: no held tokens — the browser attaches the httpOnly pair
+        // and the server refreshes it in-band (re-issued via Set-Cookie). Taken
+        // only when no header session exists, so an adopted pre-0.2.0 session
+        // keeps its header transport untouched.
+        if (preferCookie && !session) {
+            // NETWORK BLIP — if fetch throws, the request never reached the server;
+            // the throw propagates and the cached user stays. A fetch failure is
+            // NOT a 401.
+            const res = await fetch(input, { credentials: 'include', ...init });
+            // The server had the refresh cookie and still rejected: the session is
+            // genuinely dead — unless a newer sign-in/out happened meanwhile.
+            if (res.status === 401 && started === generation && status !== 'signed-out')
+                settle('signed-out', null);
+            return res;
+        }
+        const attempt = async (sess) => {
+            const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
+            if (sess) {
+                headers.set('Authorization', `Bearer ${sess.accessToken}`);
+                headers.set(RIDE_ALONG_HEADER, sess.refreshToken);
+            }
+            // Clone Request inputs so a body can survive the one stale-session
+            // retry below (a consumed body throws on re-send).
+            const target = input instanceof Request ? input.clone() : input;
+            // NETWORK BLIP — if fetch throws, the request never reached the
+            // server. The throw propagates untouched; the session stays.
+            return fetch(target, { ...init, headers });
+        };
+        // Rotation: only when BOTH new tokens are present, and only for the
+        // identity this request started under. Atomic swap.
+        const applyRotation = (res) => {
+            const newAccess = res.headers.get(ACCESS_ROTATE_HEADER);
+            const newRefresh = res.headers.get(REFRESH_ROTATE_HEADER);
+            if (newAccess && newRefresh && started === generation) {
+                setSession({ accessToken: newAccess, refreshToken: newRefresh });
+            }
+        };
+        const used = session;
+        let res = await attempt(used);
+        applyRotation(res);
+        // 401 with a since-rotated pair: another tab may have refreshed while
+        // this request was in flight. Re-read storage; if a DIFFERENT pair for
+        // the SAME identity is there, retry ONCE with it. Never retry under a
+        // newer identity.
+        if (res.status === 401 && used && started === generation) {
+            const stored = loadSession();
+            if (stored && (stored.accessToken !== used.accessToken || stored.refreshToken !== used.refreshToken)) {
+                setSession(stored);
+                res = await attempt(stored);
+                applyRotation(res);
+            }
+        }
+        // A 401 on the freshest pair means refresh already failed server-side
+        // (it had the ride-along refresh token and still couldn't mint a
+        // session). The session is genuinely dead — clear it, if it is still the
+        // identity this request started under. Any other status leaves it intact.
+        if (res.status === 401 && session && started === generation) {
+            writeSession(null);
+            settle('signed-out', null);
+        }
+        return res;
+    };
+    function url(path) {
+        return `${baseUrl}${authPath}${path}`;
+    }
+    function pickTokens(body) {
+        const d = body.data ?? body;
+        const access = d.token ?? d.access_token;
+        const refresh = d.refresh_token;
+        if (!access || !refresh)
+            return null;
+        return { access, refresh, user: d.user ?? null };
+    }
+    /** Reads `{ user }` / `{ data: { user } }`. undefined = unreadable answer. */
+    function readUser(body) {
+        if (!body || typeof body !== 'object')
+            return undefined;
+        const b = body;
+        const value = 'user' in b ? b.user : b.data && typeof b.data === 'object' && 'user' in b.data ? b.data.user : undefined;
+        if (value === null)
+            return null;
+        if ((0, continuation_js_1.isAuthUser)(value))
+            return value;
+        return undefined;
+    }
+    function postForSession(path, payload, completingMfa = false) {
+        if (!completingMfa)
+            pendingMfa = null;
+        // Intent: from this call on, earlier checks and updates no longer apply.
+        const mine = ++generation;
+        try {
+            storage.removeItem(refreshStampKey);
+        }
+        catch { /* optional cross-tab coordination */ }
+        const run = enqueue(async (signal) => {
+            // Before any write: a timed-out or superseded call changes nothing.
+            const stillCurrent = () => {
+                if (signal.aborted)
+                    throw timedOut();
+                if (generation !== mine)
+                    throw superseded();
+            };
+            try {
+                storage.removeItem(refreshStampKey);
+            }
+            catch { /* optional cross-tab coordination */ }
+            const headers = { 'Content-Type': 'application/json' };
+            // Header mode must ASK for tokens: a handler answers a request without
+            // the hint with a cookie session only (pfb_e1254f754222).
+            headers[MODE_HINT_HEADER] = preferCookie ? 'cookie' : 'header';
+            const res = await fetch(url(path), {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload ?? {}),
+                signal,
+                ...(preferCookie ? { credentials: 'include' } : {}),
+            });
+            const body = (await res.json().catch(() => ({})));
+            stillCurrent();
+            const challenge = (0, continuation_js_1.mfaChallenge)(body);
+            if (challenge) {
+                pendingMfa = challenge.mfa_token;
+                if (status === 'checking')
+                    settle('signed-out', null);
+                throw new AuthError('Enter an authenticator or backup code to finish signing in.', res.status, 'MFA_REQUIRED');
+            }
+            if (!res.ok)
+                throw new AuthError(body.message || body.error || `Request failed (${res.status})`, res.status);
+            // Cookie handshake confirmed: the backend set the httpOnly pair and the
+            // browser owns the session — no tokens in the body, nothing to store.
+            // This is also the transparent header→cookie migration point: any legacy
+            // localStorage pair from a pre-0.2.0 install is purged here.
+            const d = body.data ?? body;
+            confirmRefresh();
+            refreshUncertain = false;
+            accessExpiresAt = Number(d.expires_at) || 0;
+            if (preferCookie && (d.cookie_session === true || body.cookie_session === true)) {
+                if (session) {
+                    writeSession(null);
+                    accessExpiresAt = Number(d.expires_at) || 0;
+                }
+                if (d.user) {
+                    if (!(0, continuation_js_1.isAuthUser)(d.user))
+                        throw new AuthError('Auth response did not include a valid user.', 502, 'INVALID_AUTH_RESPONSE');
+                    owedSignOut = null; // this confirmed identity replaces the owed session
+                    writeSignOutIntent(null);
+                    settle('authenticated', d.user);
+                }
+                else
+                    await checkNow(mine, signal, true);
+                stillCurrent();
+                if (!(0, continuation_js_1.isAuthUser)(user))
+                    throw new AuthError('Auth response did not include a valid user.', 502, 'INVALID_AUTH_RESPONSE');
+                pendingMfa = null;
+                return user;
+            }
+            // Cookie mode was requested and the server did not confirm it: the
+            // handler omitted cookie mode (a pasted or pre-0.2.0 handler). Storing the
+            // tokens it returned would leave the session where page scripts can read
+            // it, so fail loudly and store nothing (pfb_961179f4970e).
+            if (preferCookie) {
+                throw new AuthError(`Sign-in reached ${url(path)} but the server did not confirm a cookie session, so nothing was stored. ` +
+                    `The handler there does not support cookie mode: mount the SDK's handler ` +
+                    `(export { somewhereAuth as default } from '@somewhere-cloud/sdk/server'), or make yours set the ` +
+                    `session cookies and reply { user, cookie_session: true } when the request has X-Sw-Auth-Mode: cookie.`, res.status, 'COOKIE_SESSION_NOT_CONFIRMED');
+            }
+            // Header mode (explicit, or the non-browser default): the caller asked
+            // for tokens in storage.
+            const tokens = pickTokens(body);
+            if (!tokens)
+                throw new AuthError('Auth response did not include a session.', res.status);
+            if (tokens.user && !(0, continuation_js_1.isAuthUser)(tokens.user))
+                throw new AuthError('Auth response did not include a valid user.', 502, 'INVALID_AUTH_RESPONSE');
+            writeSession({ accessToken: tokens.access, refreshToken: tokens.refresh });
+            accessExpiresAt = Number(d.expires_at) || accessExpiresAt;
+            owedSignOut = null;
+            if (tokens.user)
+                settle('authenticated', tokens.user);
+            else
+                await checkNow(mine, signal);
+            stillCurrent();
+            if (!(0, continuation_js_1.isAuthUser)(user))
+                throw new AuthError('Auth response did not include a valid user.', 502, 'INVALID_AUTH_RESPONSE');
+            pendingMfa = null;
+            return user;
+        });
+        // Any failure of the current call (server refusal, network, timeout) that
+        // invalidated the first check: ask /me so the state leaves 'checking'.
+        // A failure after a newer sign-in/out changes nothing.
+        return run.catch((e) => {
+            if (generation === mine && status === 'checking' && !(e instanceof AuthError && e.code === 'MFA_REQUIRED'))
+                void getUser();
+            throw e;
+        });
+    }
+    /** One /me round-trip. Writes state only if `started` is still current and
+     *  the caller's `signal` (a queued call's deadline) has not fired. */
+    async function checkNow(started, signal, completingSignIn = false) {
+        const stale = () => started !== generation || signal?.aborted === true || (!completingSignIn && !!readSignOutIntent());
+        if (stale())
+            return user;
+        if (refreshUncertain)
+            return reconcileUnknownRefresh(started, signal);
+        const cookie = !session && preferCookie;
+        if (!cookie && !session) {
+            if (!stale())
+                settle('signed-out', null);
+            return null;
+        }
+        let res;
+        let orphaned = false;
+        try {
+            // Cookie mode: the browser owns the session, so always probe /me with
+            // credentials — even with no cached user (the cookie can outlive a
+            // cleared cache). Header mode rides authFetch (refresh + rotation).
+            const cookieCheck = async (checkSignal) => {
+                // /me may rotate an expired cookie. It uses the same cross-tab lock and
+                // durable pending marker as explicit refresh, including page restore.
+                let sharedAt = 0;
+                try {
+                    sharedAt = Number(storage.getItem(refreshStampKey));
+                }
+                catch { /* optional */ }
+                const mayRotate = accessExpiresAt <= Date.now() && sharedAt <= Date.now();
+                if (mayRotate && refreshOrphaned()) {
+                    orphaned = true;
+                    return probeWithoutRotation(checkSignal);
+                }
+                const marker = mayRotate ? beginRefresh() : undefined;
+                try {
+                    const reply = await fetch(url('/me'), { method: 'GET', credentials: 'include', signal: checkSignal });
+                    if (checkSignal.aborted)
+                        return reply;
+                    if (mayRotate && (reply.ok || reply.status === 401 || reply.status === 403))
+                        confirmRefresh(marker);
+                    if (started !== generation)
+                        return reply;
+                    if (mayRotate && !reply.ok && reply.status !== 401 && reply.status !== 403)
+                        refreshUncertain = true;
+                    const expiry = Number(reply.headers.get('X-Sw-Access-Expires'));
+                    if (Number.isFinite(expiry) && expiry > Date.now())
+                        accessExpiresAt = expiry;
+                    return reply;
+                }
+                catch (e) {
+                    if (mayRotate && !checkSignal.aborted && started === generation)
+                        refreshUncertain = true;
+                    throw e;
+                }
+            };
+            res = cookie
+                ? await (signal ? cookieCheck(signal) : enqueue(cookieCheck))
+                : await authFetch(url('/me'), { method: 'GET', signal });
+        }
+        catch {
+            // A refresh with an unknown outcome surfaced here: reconcile it now rather than on a later call.
+            if (!stale() && refreshUncertain)
+                return reconcileUnknownRefresh(started, signal);
+            // Network blip: never a logout. Keep the last-known user, unverified.
+            if (!stale())
+                indeterminate(0);
+            return user;
+        }
+        if (stale())
+            return user;
+        if (orphaned)
+            return settleReconciled(res, started, signal);
+        // 401 or an explicit { user: null } is DEFINITIVE signed-out, which also
+        // settles an owed sign-out: the server holds no session for this browser.
+        if (res.status === 401) {
+            owedSignOut = null;
+            settle('signed-out', null);
+            return null;
+        }
+        if (!res.ok) {
+            indeterminate(res.status);
+            return user;
+        }
+        const body = await res.json().catch(() => undefined);
+        if (stale())
+            return user;
+        const u = readUser(body);
+        if (u === undefined) {
+            indeterminate(res.status);
+            return user;
+        }
+        if (completingSignIn && !u)
+            throw new AuthError('Auth response did not include a valid user.', 502, 'INVALID_AUTH_RESPONSE');
+        // Only an explicit successful sign-in can replace durable logout intent.
+        owedSignOut = null;
+        if (completingSignIn && u)
+            writeSignOutIntent(null);
+        settle(u ? 'authenticated' : 'signed-out', u);
+        return u;
+    }
+    /** /me that can never rotate: no ride-along refresh token, and X-No-Auto-Refresh, so the server
+     *  answers from the held access credential alone. */
+    function probeWithoutRotation(probeSignal) {
+        const headers = { 'X-No-Auto-Refresh': '1' };
+        if (session)
+            headers.Authorization = 'Bearer ' + session.accessToken;
+        return fetch(url('/me'), { method: 'GET', credentials: 'include', headers, signal: probeSignal });
+    }
+    /** An earlier refresh's outcome is unknown: it may have rotated the refresh credential, and
+     *  replaying a rotated one past the server's grace revokes every session of the user. So the state
+     *  is reconciled without rotating: a still-valid access credential keeps the user signed in (used,
+     *  never rotated, until it runs out); one that no longer answers cannot be confirmed safely, so the
+     *  dead local marker and session are cleared and a sign-in is asked for. A failed check stays
+     *  indeterminate and the next getUser() checks again, never a permanent no-op. */
+    async function reconcileUnknownRefresh(started, signal) {
+        const stale = () => started !== generation || signal?.aborted === true || !!readSignOutIntent();
+        if (stale())
+            return user;
+        refreshUncertain = true;
+        let res;
+        try {
+            res = await (signal ? probeWithoutRotation(signal) : enqueue(probeWithoutRotation));
+        }
+        catch {
+            if (!stale())
+                indeterminate(0);
+            return user;
+        }
+        if (stale())
+            return user;
+        return settleReconciled(res, started, signal);
+    }
+    async function settleReconciled(res, started, signal) {
+        const stale = () => started !== generation || signal?.aborted === true || !!readSignOutIntent();
+        if (stale())
+            return user;
+        refreshUncertain = true;
+        if (res.status !== 401 && !res.ok) {
+            indeterminate(res.status);
+            return user;
+        }
+        const u = res.status === 401 ? null : readUser(await res.json().catch(() => undefined));
+        if (stale())
+            return user;
+        if (u === undefined) {
+            indeterminate(res.status);
+            return user;
+        }
+        if (u) {
+            const expiry = Number(res.headers.get('X-Sw-Access-Expires'));
+            if (Number.isFinite(expiry) && expiry > Date.now())
+                accessExpiresAt = expiry;
+            if (refreshTimer !== undefined)
+                clearTimeout(refreshTimer);
+            writeUser(u);
+            status = 'authenticated';
+            error = null;
+            emit();
+            return u;
+        }
+        confirmRefresh();
+        refreshUncertain = false;
+        writeSession(null);
+        owedSignOut = null;
+        writeUser(null);
+        status = 'signed-out';
+        error = new AuthError('Your sign-in could not be confirmed. Sign in again.', 401, 'SIGN_IN_REQUIRED');
+        emit();
+        return null;
+    }
+    /** Validate the session against /me. Runs after queued sign-ins/outs and is
+     *  shared by concurrent callers within one generation. */
+    function getUser() {
+        if (check && check.generation === generation)
+            return check.promise;
+        const started = generation;
+        const promise = mutations
+            .then(() => {
+            if (started !== generation)
+                return user;
+            const intent = readSignOutIntent();
+            if (intent) {
+                if (intent.startsWith('pending:'))
+                    return client.signOut().then(() => null);
+                settle('signed-out', null);
+                return null;
+            }
+            return checkNow(started);
+        })
+            .finally(() => {
+            if (check?.promise === promise)
+                check = null;
+        });
+        check = { generation: started, promise };
+        return promise;
+    }
+    const client = {
+        fetch: authFetch,
+        signUp: (i) => postForSession('/signup', { email: i.email, password: i.password, display_name: i.displayName }),
+        signIn: (i) => postForSession('/login', { email: i.email, password: i.password }),
+        sendMagicLink: async (i) => {
+            const res = await fetch(url('/magic-link'), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ email: i.email, redirect_uri: i.redirectUri }),
+            });
+            if (!res.ok) {
+                const b = (await res.json().catch(() => ({})));
+                throw new AuthError(b.message || b.error || `Could not send magic link (${res.status})`, res.status);
+            }
+        },
+        verifyMagicLink: (i) => postForSession('/magic-link/verify', { token: i.token }),
+        emailVerified: async () => {
+            const res = await authFetch(url('/verify-email'), { method: 'GET' });
+            const b = (await res.json().catch(() => ({})));
+            if (!res.ok)
+                throw new AuthError(b.message || b.error || `Could not check the email address (${res.status})`, res.status);
+            return b.email_verified === true;
+        },
+        requestEmailVerification: async () => {
+            const res = await authFetch(url('/request-email-verification'), {
+                method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}',
+            });
+            if (!res.ok) {
+                const b = (await res.json().catch(() => ({})));
+                throw new AuthError(b.message || b.error || `Could not send the verification code (${res.status})`, res.status);
+            }
+        },
+        verifyEmail: async (i) => {
+            const res = await authFetch(url('/verify-email'), {
+                method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ code: i.code }),
+            });
+            if (!res.ok) {
+                const b = (await res.json().catch(() => ({})));
+                throw new AuthError(b.message || b.error || `Could not verify the code (${res.status})`, res.status);
+            }
+        },
+        googleSignInUrl: async (i) => {
+            const res = await fetch(url(`/google-url${i?.redirectUri ? `?redirect_uri=${encodeURIComponent(i.redirectUri)}` : ''}`));
+            const b = (await res.json().catch(() => ({})));
+            const u = b.url ?? b.data?.url;
+            if (!u)
+                throw new AuthError('Could not get the Google sign-in URL.', res.status);
+            return u;
+        },
+        completeGoogleSignIn: (i) => postForSession('/google', { code: i.code, ...oauthAttempt(i) }),
+        githubSignInUrl: async (i) => {
+            const res = await fetch(url(`/github-url${i?.redirectUri ? `?redirect_uri=${encodeURIComponent(i.redirectUri)}` : ''}`));
+            const b = (await res.json().catch(() => ({})));
+            const u = b.url ?? b.data?.url;
+            if (!u)
+                throw new AuthError('Could not get the GitHub sign-in URL.', res.status);
+            return u;
+        },
+        completeGithubSignIn: (i) => postForSession('/github', { code: i.code, ...oauthAttempt(i) }),
+        discordSignInUrl: async (i) => {
+            const res = await fetch(url(`/discord-url${i?.redirectUri ? `?redirect_uri=${encodeURIComponent(i.redirectUri)}` : ''}`));
+            const b = (await res.json().catch(() => ({})));
+            const u = b.url ?? b.data?.url;
+            if (!u)
+                throw new AuthError('Could not get the Discord sign-in URL.', res.status);
+            return u;
+        },
+        completeDiscordSignIn: (i) => postForSession('/discord', { code: i.code, ...oauthAttempt(i) }),
+        completeMfa: (input) => {
+            if (!pendingMfa)
+                return Promise.reject(new AuthError('There is no pending MFA sign-in. Start signing in again.', 400, 'MFA_CHALLENGE_REQUIRED'));
+            return postForSession('/mfa/challenge', { mfa_token: pendingMfa, code: input.code }, true);
+        },
+        signOut: () => {
+            pendingMfa = null;
+            const existingIntent = readSignOutIntent();
+            // An owed sign-out is retried with the header session it was for.
+            const had = session ?? owedSignOut?.session ?? null;
+            // Something to end server-side: an owed sign-out, a header session, a
+            // known or pending cookie identity, or a sign-in queued ahead of this call.
+            const serverWork = existingIntent?.startsWith('pending:') || owedSignOut !== null || !!had
+                || (preferCookie && (!!user || status !== 'signed-out' || pendingMutations > 0));
+            // Invalidate earlier checks/rotations and drop credentials immediately.
+            // Retain the last-known user until settlement: a user-null UI can trigger
+            // navigation before this queued request has even started.
+            const mine = ++generation;
+            writeSession(null);
+            // Pending until /logout is answered: consumers show "signing out", not
+            // "signed out", while the server may still accept the session.
+            if (!serverWork) {
+                settle('signed-out', null);
+                return Promise.resolve();
+            }
+            const intent = existingIntent?.startsWith('pending:') ? existingIntent : `pending:${Date.now()}:${Math.random()}`;
+            if (preferCookie)
+                writeSignOutIntent(intent);
+            signOutsInFlight++;
+            status = 'checking';
+            scheduleRefresh();
+            emit();
+            const unconfirmed = (failure) => {
+                // Owed only for this call's generation: a newer sign-in replaced the
+                // session, and a newer signOut() retries it itself.
+                if (generation !== mine)
+                    return;
+                owedSignOut = { session: had, error: failure };
+                error = failure;
+                emit();
+            };
+            // Server-side revoke (and, in cookie mode, the Set-Cookie expirations
+            // that actually end the browser session), after every earlier queued
+            // call. Resolves either way; a failure stays owed (signOutUnconfirmed,
+            // error 'SIGN_OUT_UNCONFIRMED') and the next signOut() retries it.
+            return enqueue(async (signal) => {
+                // A new sign-in in another tab may have replaced this queued logout.
+                if (preferCookie && readSignOutIntent() !== intent)
+                    return;
+                let res;
+                try {
+                    res = await fetch(url('/logout'), {
+                        method: 'POST',
+                        // Cookie logout is resumed from durable intent after navigation.
+                        // Do not let the old document's late Set-Cookie erase a newer login.
+                        // Header revocation has no browser cookie response to race.
+                        keepalive: !preferCookie,
+                        // A header session is revoked by its refresh token, sent as the same
+                        // ride-along header authFetch uses; the access bearer alone revokes
+                        // nothing. `had` is captured at call time, so a retry resends the
+                        // credential of the session it is for, never a newer one.
+                        headers: had
+                            ? { 'Content-Type': 'application/json', Authorization: `Bearer ${had.accessToken}`, [RIDE_ALONG_HEADER]: had.refreshToken }
+                            : { 'Content-Type': 'application/json' },
+                        signal,
+                        ...(preferCookie ? { credentials: 'include' } : {}),
+                    });
+                }
+                catch {
+                    if (!signal.aborted)
+                        unconfirmed(new AuthError('Sign-out could not reach the server; the session may still be active.', 0, 'SIGN_OUT_UNCONFIRMED'));
+                    return;
+                }
+                if (signal.aborted)
+                    return;
+                if (!res.ok) {
+                    unconfirmed(new AuthError(`The server did not confirm sign-out (${res.status}).`, res.status, 'SIGN_OUT_UNCONFIRMED'));
+                    return;
+                }
+                // /logout's finite JSON response should finish being read. Header
+                // success already confirms logout; body latency/failure must not hold
+                // the mutation queue or change that confirmation.
+                if (res.body !== null && res.headers.get('Content-Type')?.split(';')[0].trim().toLowerCase() === 'application/json') {
+                    void res.text().catch(() => { });
+                }
+                if (preferCookie && readSignOutIntent() === intent)
+                    writeSignOutIntent(intent.replace('pending:', 'confirmed:'));
+                owedSignOut = null;
+                if (error?.code === 'SIGN_OUT_UNCONFIRMED')
+                    error = null;
+                emit();
+            }).catch(() => {
+                // Only the deadline rejects here.
+                unconfirmed(new AuthError('Sign-out timed out; the session may still be active.', 0, 'SIGN_OUT_UNCONFIRMED'));
+            }).finally(() => {
+                signOutsInFlight--;
+                if (generation === mine)
+                    settle('signed-out', null);
+                else
+                    emit();
+            });
+        },
+        getUser,
+        getSession: () => session,
+        getCachedUser: () => user,
+        getState: snapshot,
+        onChange: (listener) => {
+            listeners.add(listener);
+            listener(snapshot());
+            return () => void listeners.delete(listener);
+        },
+        billing: {
+            has: (_feature) => { throw new AuthError('Paid access is no longer part of sign-in identity. Check it in a server endpoint with await sw.billing.has(feature).', 0, 'BILLING_EXPLICIT_CHECK_REQUIRED'); },
+            entitlements: () => { throw new AuthError('Paid access is no longer part of sign-in identity. Read it in a server endpoint with await sw.billing.entitlements().', 0, 'BILLING_EXPLICIT_CHECK_REQUIRED'); },
+            plans: async () => {
+                const res = await authFetch(url('/plans'), { method: 'GET' });
+                if (!res.ok) {
+                    const b = (await res.json().catch(() => ({})));
+                    throw new AuthError(b.message || b.error || `Could not load plans (${res.status})`, res.status);
+                }
+                const body = (await res.json().catch(() => ({})));
+                return body.plans ?? body.data?.plans ?? [];
+            },
+            subscribe: async (plan, opts) => {
+                const here = typeof window !== 'undefined' ? window.location.href : undefined;
+                const res = await authFetch(url('/billing/checkout'), {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        plan,
+                        success_url: opts?.successUrl ?? here,
+                        cancel_url: opts?.cancelUrl ?? here,
+                    }),
+                });
+                if (!res.ok) {
+                    const b = (await res.json().catch(() => ({})));
+                    throw new AuthError(b.message || b.error || `Could not start checkout (${res.status})`, res.status);
+                }
+                const body = (await res.json().catch(() => ({})));
+                const u = body.url ?? body.data?.url;
+                if (!u)
+                    throw new AuthError('Checkout did not return a URL.', res.status);
+                if (opts?.redirect !== false && typeof window !== 'undefined')
+                    window.location.assign(u);
+                return { url: u };
+            },
+            openBillingPortal: async (opts) => {
+                const here = typeof window !== 'undefined' ? window.location.href : undefined;
+                const res = await authFetch(url('/billing/portal'), {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ return_url: opts?.returnUrl ?? here }),
+                });
+                if (!res.ok) {
+                    const b = (await res.json().catch(() => ({})));
+                    throw new AuthError(b.message || b.error || `Could not open the billing portal (${res.status})`, res.status);
+                }
+                const body = (await res.json().catch(() => ({})));
+                const u = body.url ?? body.data?.url;
+                if (!u)
+                    throw new AuthError('Billing portal did not return a URL.', res.status);
+                if (opts?.redirect !== false && typeof window !== 'undefined')
+                    window.location.assign(u);
+                return { url: u };
+            },
+        },
+    };
+    return client;
+}
+class AuthError extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.name = 'AuthError';
+        this.status = status;
+        if (code !== undefined)
+            this.code = code;
+    }
+}
+exports.AuthError = AuthError;
+//# sourceMappingURL=client.js.map