@bravely-studios/account-web 0.3.9 → 0.4.0

package/dist/BravelyAccountManager.js

@@ -20,9 +20,18 @@ const KEY_BAS = "bas";
 const KEY_REFRESH = "refresh_token";
 const KEY_BA_ID = "ba_id";
 const KEY_EMAIL = "email";
+const KEY_EXPIRES_AT = "expires_at";
 const KEY_DPOP_JKT = "dpop_jkt_thumbprint";
 const KEY_PKCE_VERIFIER = "pkce_verifier";
 const KEY_PKCE_STATE = "pkce_state";
+/**
+ * Proactive refresh window (D4): when the BAS has less than this much life
+ * left (or is already past `expires_at`), the manager rotates the session in
+ * the background via `grant_type=refresh_token` instead of waiting for a 401.
+ * BAS access tokens live 14 days; 48h is comfortably inside that while still
+ * rotating well before expiry for any returning visitor.
+ */
+export const PRE_EXPIRY_REFRESH_WINDOW_MS = 48 * 60 * 60 * 1000;
 export class BravelyAccountManager {
     cfg;
     storage;
@@ -40,6 +49,23 @@ export class BravelyAccountManager {
     libVersionPolicy = null;
     dpopKeypairPromise = null;
     dpopJktThumbprint = null;
+    /**
+     * PHASE-2 install→account reconciliation id (optional). When set, it is
+     * forwarded as `install_id` on BOTH the OAuth authorize URL and the
+     * `/oauth/token` exchange so the auth server can reconcile the install onto
+     * the resolved `ba_id`. `null` ⇒ nothing is sent and both legs stay
+     * byte-identical to the pre-`install_id` flow. Settable post-construction
+     * via `setInstallId()` because the host often learns the id asynchronously
+     * (e.g. after reading it from native bridge / first-launch storage).
+     */
+    installId = null;
+    /**
+     * Single-flight guard for the refresh grant: concurrent 401s / proactive
+     * refreshes join the in-flight rotation instead of racing the one-time-use
+     * refresh token (a second concurrent presentation of the same token would
+     * trip the server's family reuse detection and revoke the session).
+     */
+    refreshInFlight = null;
     constructor(config) {
         if (!config.authority)
             throw new Error("authority is required");
@@ -59,9 +85,13 @@ export class BravelyAccountManager {
             redirectUri,
             scope: config.scope ?? DEFAULT_SCOPE,
             libName: config.libName ?? "bravely-account-web",
-            libVersion: config.libVersion ?? "0.3.9",
+            libVersion: config.libVersion ?? "0.4.0",
         };
         this.storage = config.storage ?? defaultStorage();
+        // Optional PHASE-2 install→account reconciliation id. When the host omits
+        // it (the common case), `installId` stays null and no `install_id` rides
+        // on the authorize URL or token exchange — byte-identical legacy behavior.
+        this.installId = normalizeInstallId(config.installId);
         // No-op when the host injects nothing — preserves prior silent behavior.
         this.log = config.log ?? (() => undefined);
         // Thread the same seam into the entitlement cache so its
@@ -101,10 +131,38 @@ export class BravelyAccountManager {
     getLibVersionPolicy() {
         return this.libVersionPolicy ? { ...this.libVersionPolicy } : null;
     }
+    /**
+     * Set (or clear) the PHASE-2 install→account reconciliation id. Idempotent.
+     * Pass the per-install identifier the native client minted at
+     * `app_first_opened`; the manager forwards it as `install_id` on the next
+     * OAuth authorize redirect AND on the token exchange, so the auth server's
+     * existing reconcile path can stamp the resolved `ba_id` onto that install.
+     *
+     * Pass `undefined`/`null`/empty to clear it — after which the flow is again
+     * byte-identical to the pre-`install_id` behavior (no param sent). Purely
+     * additive: existing consumers that never call this send no `install_id`.
+     */
+    setInstallId(installId) {
+        this.installId = normalizeInstallId(installId);
+    }
+    /** Current install→account reconciliation id, or `null` if none is set. */
+    getInstallId() {
+        return this.installId;
+    }
     /**
      * Hydrate from persistent storage and (if a BAS is present) verify it
      * against the identity API. Call once on page load before rendering UI
      * that depends on `getState()`.
+     *
+     * D4 session-forever behavior:
+     *   - A stored BAS yields `signed_in` immediately (cache-backed); the
+     *     entitlement check runs in the background. Transport failures NEVER
+     *     wipe tokens or flip the state to signed_out.
+     *   - A BAS near/past `expires_at` triggers a background refresh-grant
+     *     rotation (`PRE_EXPIRY_REFRESH_WINDOW_MS`).
+     *   - No BAS but a stored refresh token → the session is resurrected via
+     *     `grant_type=refresh_token` before giving up (sessions survive even
+     *     if the access token row was lost).
      */
     async restore() {
         await this.cache.hydrate();
@@ -112,6 +170,25 @@ export class BravelyAccountManager {
         const baId = await this.storage.get(KEY_BA_ID);
         const email = await this.storage.get(KEY_EMAIL);
         if (!bas || !baId || !email) {
+            // No usable BAS triple — but a durable refresh token can still
+            // resurrect the session without any user interaction.
+            const refresh = await this.storage.get(KEY_REFRESH);
+            if (refresh) {
+                this.activation.transition("app_launched", { bas_present: true });
+                const outcome = await this.refreshSession();
+                if (outcome === "refreshed") {
+                    // persistRefreshedToken set the signed_in state; run the
+                    // authoritative entitlement check in the background.
+                    void this.refreshEntitlements().catch(() => undefined);
+                    return this.getState();
+                }
+                // definitive_failure already cleared storage; transient failures
+                // KEEP the refresh token for the next launch (never wipe on
+                // transport failure) — but without a BAS there is no session to
+                // serve, so surface signed_out + pending_user_action.
+                this.activation.transition("bas_invalid");
+                return this.setState({ kind: "signed_out" });
+            }
             this.activation.transition("app_launched_no_session", { bas_present: false });
             return this.setState({ kind: "signed_out" });
         }
@@ -128,6 +205,12 @@ export class BravelyAccountManager {
             this.activation.force("fresh_launch_restoration");
         }
         this.setState({ kind: "signed_in", ba_id: baId, email, bas, entitlements: cachedEntitlements });
+        // Pre-expiry rotation: refresh in the background when the BAS is inside
+        // the proactive window (or already expired). Single-flight, so the
+        // entitlement refresh below joining a 401-triggered rotation is safe.
+        if (await this.shouldProactivelyRefresh()) {
+            void this.refreshSession().catch(() => undefined);
+        }
         // Refresh in the background; failures fall back to cache.
         void this.refreshEntitlements().catch(() => {
             // Already handled by transition logic; nothing else to do.
@@ -169,7 +252,8 @@ export class BravelyAccountManager {
                 return this.setState({ kind: "failed", error: errorMessage(err) });
             }
         }
-        // Otherwise, kick off the redirect.
+        // Otherwise, kick off the redirect. `installId` rides along only when the
+        // host has set one (PHASE-2 reconcile); absent ⇒ legacy authorize URL.
         const { verifier, state, authorizeUrl } = await preparePkce({
             authority: this.cfg.authority,
             clientId: this.cfg.appSlug,
@@ -177,6 +261,7 @@ export class BravelyAccountManager {
             scope: this.cfg.scope,
             loginHint: opts.loginHint,
             provider: opts.provider,
+            installId: this.installId ?? undefined,
         });
         await this.storage.set(KEY_PKCE_VERIFIER, verifier);
         await this.storage.set(KEY_PKCE_STATE, state);
@@ -189,6 +274,7 @@ export class BravelyAccountManager {
     async signOut() {
         try {
             const bas = await this.storage.get(KEY_BAS);
+            const refresh = await this.storage.get(KEY_REFRESH);
             if (bas) {
                 // Fire-and-forget revoke; if the OAuth server doesn't have a revoke
                 // endpoint yet (Gate 1), this is a no-op. Wrapped in try/catch so
@@ -196,7 +282,11 @@ export class BravelyAccountManager {
                 await this.fetchWithDeprecation(`${this.cfg.authority}/oauth/revoke`, {
                     method: "POST",
                     headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                    body: new URLSearchParams({ token: bas, client_id: this.cfg.appSlug }).toString(),
+                    body: new URLSearchParams({
+                        token: bas,
+                        token_type_hint: "access_token",
+                        client_id: this.cfg.appSlug,
+                    }).toString(),
                 }).catch((err) => {
                     // Best-effort revoke; local sign-out proceeds regardless. Breadcrumb
                     // the cause (never the token) so a server-side revoke regression is
@@ -204,19 +294,50 @@ export class BravelyAccountManager {
                     this.log("signout_revoke_failed", { step: "oauth_revoke", error: errorMessage(err) });
                 });
             }
+            // With sliding-365d refresh families (D4), explicit sign-out should
+            // also revoke the durable refresh family — RFC 7009 form, best-effort
+            // (the router's revocation endpoint is still pending; sending now means
+            // already-shipped libs revoke correctly the day it lands).
+            if (refresh) {
+                await this.fetchWithDeprecation(`${this.cfg.authority}/oauth/revoke`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: new URLSearchParams({
+                        token: refresh,
+                        token_type_hint: "refresh_token",
+                        client_id: this.cfg.appSlug,
+                    }).toString(),
+                }).catch((err) => {
+                    this.log("signout_revoke_failed", {
+                        step: "oauth_revoke_refresh",
+                        error: errorMessage(err),
+                    });
+                });
+            }
         }
         finally {
-            await this.storage.remove(KEY_BAS);
-            await this.storage.remove(KEY_REFRESH);
-            await this.storage.remove(KEY_BA_ID);
-            await this.storage.remove(KEY_EMAIL);
-            await this.storage.remove(KEY_DPOP_JKT);
-            await this.cache.invalidate();
-            this.dpopKeypairPromise = null;
-            this.dpopJktThumbprint = null;
-            this.setState({ kind: "signed_out" });
+            await this.clearLocalSession();
         }
     }
+    /**
+     * Drop every locally-persisted session artifact and flip to `signed_out`.
+     * The DESTRUCTIVE half of sign-out — only ever called from explicit user
+     * sign-out or a DEFINITIVE auth failure (`invalid_grant` on the refresh
+     * grant, or a 401 that survived a successful refresh-and-retry). Transport
+     * failures must never reach this.
+     */
+    async clearLocalSession() {
+        await this.storage.remove(KEY_BAS);
+        await this.storage.remove(KEY_REFRESH);
+        await this.storage.remove(KEY_BA_ID);
+        await this.storage.remove(KEY_EMAIL);
+        await this.storage.remove(KEY_EXPIRES_AT);
+        await this.storage.remove(KEY_DPOP_JKT);
+        await this.cache.invalidate();
+        this.dpopKeypairPromise = null;
+        this.dpopJktThumbprint = null;
+        this.setState({ kind: "signed_out" });
+    }
     /**
      * Read entitlements, serving the cached row if fresh and refreshing
      * opportunistically. Always returns an array (possibly empty).
@@ -319,8 +440,9 @@ export class BravelyAccountManager {
      * introduced in the Mac/iOS v2 onboarding port.
      *
      * Throws if the user is not signed in (`not_signed_in`) or if the server
-     * returns a non-2xx status. 401 is surfaced as a sign-out (matching the
-     * pattern in `refreshEntitlements`).
+     * returns a non-2xx status. A definitive 401 (refresh-and-retry exhausted)
+     * is surfaced as `not_signed_in`; a 401 riding a transient refresh failure
+     * keeps the session and throws a plain request failure.
      */
     async getAccountEntitlements() {
         const bas = await this.requireBas();
@@ -328,8 +450,12 @@ export class BravelyAccountManager {
             method: "GET",
         });
         if (res.status === 401) {
-            await this.signOut();
-            throw new Error("not_signed_in");
+            // `fetchWithBas` already refreshed-and-retried; a surviving 401 either
+            // cleared the session (definitive ⇒ not_signed_in) or rode a transient
+            // refresh failure (session kept ⇒ plain request failure).
+            if (await this.sessionWasCleared())
+                throw new Error("not_signed_in");
+            throw new Error("getAccountEntitlements failed: 401");
         }
         if (!res.ok) {
             throw new Error(`getAccountEntitlements failed: ${res.status}`);
@@ -379,7 +505,11 @@ export class BravelyAccountManager {
             try {
                 const url = new URL("/api/entitlements", this.cfg.identityOrigin);
                 url.searchParams.set("app", this.cfg.appSlug);
-                const res = await this.fetchWithBas(url.toString(), bas, {
+                // Re-read the BAS each attempt: a mid-poll refresh rotation (401 →
+                // refresh-then-retry inside fetchWithBas) replaces the stored token,
+                // and polling on with the stale capture would 401 every round.
+                const currentBas = (await this.storage.get(KEY_BAS)) ?? bas;
+                const res = await this.fetchWithBas(url.toString(), currentBas, {
                     method: "GET",
                 });
                 if (res.ok) {
@@ -455,6 +585,12 @@ export class BravelyAccountManager {
             code_verifier: verifier,
             client_id: this.cfg.appSlug,
         });
+        // PHASE-2 reconcile: carry the install id on the exchange too, so the
+        // server reconciles even if it keys off the token-leg value rather than
+        // (or in addition to) the value persisted from the authorize leg. Only
+        // appended when set — absent ⇒ the body is byte-identical to legacy.
+        if (this.installId)
+            body.set("install_id", this.installId);
         const res = await this.fetchWithDeprecation(`${this.cfg.authority}/oauth/token`, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
@@ -474,7 +610,12 @@ export class BravelyAccountManager {
         await this.persistToken(data);
         return this.getState();
     }
-    async persistToken(data) {
+    /**
+     * Persist the token + identity rows shared by the sign-in and refresh
+     * legs (BAS, rotated refresh token, ba_id, email, expires_at, lib version
+     * policy). Returns the inline entitlement snapshot.
+     */
+    async persistSessionCore(data) {
         const bas = "access_token" in data ? data.access_token : data.bas;
         const refresh = data.refresh_token ?? null;
         await this.storage.set(KEY_BAS, bas);
@@ -482,11 +623,19 @@ export class BravelyAccountManager {
             await this.storage.set(KEY_REFRESH, refresh);
         await this.storage.set(KEY_BA_ID, data.bravely_account_id);
         await this.storage.set(KEY_EMAIL, data.email);
+        // Track the BAS expiry client-side so the proactive refresh loop can
+        // rotate before a 401 ever happens (D4).
+        if (data.expires_at) {
+            await this.storage.set(KEY_EXPIRES_AT, data.expires_at);
+        }
         if ("bravely_lib_version" in data && data.bravely_lib_version) {
             this.libVersionPolicy = data.bravely_lib_version;
         }
+        return { bas, entitlements: (data.active_entitlements ?? []) };
+    }
+    async persistToken(data) {
+        const { bas, entitlements } = await this.persistSessionCore(data);
         // Active entitlements ride along on Gate 1 BAS exchange (B6).
-        const entitlements = (data.active_entitlements ?? []);
         await this.cache.update({ entitlements });
         this.setState({
             kind: "signed_in",
@@ -503,6 +652,172 @@ export class BravelyAccountManager {
             this.activation.transition("entitlement_check_success_none");
         }
     }
+    /**
+     * Persist a `grant_type=refresh_token` rotation result. Differs from the
+     * sign-in leg deliberately:
+     *   - The inline entitlement snapshot is best-effort on the server (an RC
+     *     hiccup yields `[]` so rotation never fails) — so an EMPTY snapshot
+     *     must not downgrade the 72h offline cache mid-session. Non-empty
+     *     snapshots update cache + state; empty ones leave the authoritative
+     *     `/api/entitlements` check (which runs on every restore) in charge.
+     *   - No `entitlement_check_*` activation events are fired here for the
+     *     same reason; only `bas_found` advances the restore lane.
+     */
+    async persistRefreshedToken(data) {
+        const { bas, entitlements } = await this.persistSessionCore(data);
+        // Contract enforcement (router ≥1.6.0 always rotates): if a 200 refresh
+        // response somehow lacks the rotated token, the OLD token is spent
+        // server-side — presenting it again later would read as reuse and revoke
+        // the family. Drop it: the fresh BAS still serves its full window, and
+        // the next 401 walks the no_refresh_token lane instead of a false-reuse
+        // revoke.
+        if (!data.refresh_token) {
+            await this.storage.remove(KEY_REFRESH);
+            this.log("session_refresh_missing_rotated_token", { step: "oauth_refresh" });
+        }
+        if (entitlements.length > 0) {
+            await this.cache.update({ entitlements, dpopJktThumbprint: this.dpopJktThumbprint });
+        }
+        const effective = entitlements.length > 0
+            ? entitlements
+            : this.state.kind === "signed_in"
+                ? this.state.entitlements
+                : (this.cache.raw()?.entitlements ?? []);
+        this.setState({
+            kind: "signed_in",
+            ba_id: data.bravely_account_id,
+            email: data.email,
+            bas,
+            entitlements: effective,
+        });
+        this.activation.transition("bas_found");
+    }
+    /**
+     * True when the stored BAS is inside the proactive-refresh window (or past
+     * expiry). Unknown expiry (legacy rows) ⇒ false — the 401-retry path
+     * covers those sessions.
+     */
+    async shouldProactivelyRefresh() {
+        const expiresAt = await this.storage.get(KEY_EXPIRES_AT);
+        if (!expiresAt)
+            return false;
+        const parsed = Date.parse(expiresAt);
+        if (Number.isNaN(parsed))
+            return false;
+        return parsed - Date.now() < PRE_EXPIRY_REFRESH_WINDOW_MS;
+    }
+    /**
+     * Rotate the session via `POST {authority}/oauth/token` with
+     * `grant_type=refresh_token` (router ≥1.6.0). Single-flight: concurrent
+     * callers join the in-flight rotation (the refresh token is one-time-use;
+     * racing it would trip server-side reuse detection).
+     *
+     * Cross-TAB races are handled by two layers: (a) where available, a Web
+     * Lock (`bravely:session_refresh:<slug>`) serializes rotations across tabs
+     * sharing the same IndexedDB token; (b) the token is re-read inside the
+     * critical section, and if another tab already rotated (stored BAS changed
+     * while we waited) the rotation is skipped. Browsers without Web Locks
+     * fall back to the server's 30s idempotent-retry grace for near-
+     * simultaneous presentations of the same token.
+     *
+     * Destructive ONLY on a definitive rejection (`invalid_grant` / 401):
+     * transport failures, 5xx, and 429 keep every token in place.
+     */
+    refreshSession() {
+        if (!this.refreshInFlight) {
+            this.refreshInFlight = this.refreshSessionCrossTab().finally(() => {
+                this.refreshInFlight = null;
+            });
+        }
+        return this.refreshInFlight;
+    }
+    async refreshSessionCrossTab() {
+        const basBefore = await this.storage.get(KEY_BAS);
+        const run = async () => {
+            // Another tab may have rotated while we waited on the lock — adopt its
+            // result instead of spending a second rotation.
+            if (basBefore) {
+                const basNow = await this.storage.get(KEY_BAS);
+                if (basNow && basNow !== basBefore)
+                    return "refreshed";
+            }
+            return this.doRefreshSession();
+        };
+        const locks = globalThis.navigator?.locks;
+        if (locks?.request) {
+            try {
+                return await locks.request(`bravely:session_refresh:${this.cfg.appSlug}`, run);
+            }
+            catch (error) {
+                // Lock machinery failure (not a refresh verdict) — fall through to
+                // the unlocked path rather than failing the rotation.
+                this.log("session_refresh_lock_error", {
+                    step: "oauth_refresh",
+                    error: errorMessage(error),
+                });
+            }
+        }
+        return run();
+    }
+    async doRefreshSession() {
+        const refresh = await this.storage.get(KEY_REFRESH);
+        if (!refresh)
+            return "no_refresh_token";
+        try {
+            const res = await this.fetchWithDeprecation(`${this.cfg.authority}/oauth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: refresh,
+                    client_id: this.cfg.appSlug,
+                }).toString(),
+            });
+            if (res.ok) {
+                const data = (await res.json());
+                await this.persistRefreshedToken(data);
+                this.log("session_refreshed", { step: "oauth_refresh" });
+                return "refreshed";
+            }
+            let err = {};
+            try {
+                err = (await res.json());
+            }
+            catch {
+                /* ignore non-JSON error bodies */
+            }
+            // `invalid_grant` covers invalid / revoked / reuse-detected tokens —
+            // the server's uniform rejection. 401 = invalid_client-class failures.
+            // Both are definitive: the session cannot be recovered.
+            if (err.error === "invalid_grant" || res.status === 401) {
+                this.log("session_refresh_rejected", {
+                    step: "oauth_refresh",
+                    status: res.status,
+                    error: err.error ?? null,
+                });
+                await this.clearLocalSession();
+                return "definitive_failure";
+            }
+            // 429 / 5xx / anything else: server-side trouble, NOT a verdict on the
+            // token. Keep the session and retry later.
+            this.log("session_refresh_http_error", {
+                step: "oauth_refresh",
+                status: res.status,
+                error: err.error ?? null,
+            });
+            return "transient_failure";
+        }
+        catch (error) {
+            // Network failure (offline) or the 426 kill-switch. Neither is a
+            // verdict on the refresh token — tokens are NEVER wiped on transport
+            // failure (D4).
+            this.log("session_refresh_network_error", {
+                step: "oauth_refresh",
+                error: errorMessage(error),
+            });
+            return "transient_failure";
+        }
+    }
     async refreshEntitlements() {
         const bas = await this.storage.get(KEY_BAS);
         if (!bas)
@@ -514,13 +829,26 @@ export class BravelyAccountManager {
                 method: "GET",
             });
             if (res.status === 401) {
-                // BAS invalid; treat as signed-out.
-                this.log("entitlement_refresh_unauthorized", {
+                // `fetchWithBas` already ran refresh-then-retry-once and cleared the
+                // session iff the failure was definitive. Only mirror that verdict —
+                // never sign out on a 401 that rode a transient refresh failure.
+                if (await this.sessionWasCleared()) {
+                    this.log("entitlement_refresh_unauthorized", {
+                        step: "refresh_entitlements",
+                        status: 401,
+                    });
+                    return [];
+                }
+                const cached = this.cache.getCached();
+                this.log("entitlement_refresh_unauthorized_transient", {
                     step: "refresh_entitlements",
                     status: 401,
+                    entitlement_cache_present: !!cached,
                 });
-                await this.signOut();
-                return [];
+                this.activation.transition("entitlement_check_failure", {
+                    entitlement_cache_present: !!cached,
+                });
+                return cached?.entitlements ?? [];
             }
             if (!res.ok) {
                 const cached = this.cache.getCached();
@@ -569,15 +897,74 @@ export class BravelyAccountManager {
      * the current router accepts Bearer on shared BAS endpoints, but attach a
      * real RFC 9449 proof in the `DPoP` header so Gate 2 traffic is already
      * exercising proof generation.
+     *
+     * D4 401 handling — refresh-then-retry-once: a 401 triggers ONE refresh
+     * grant; on success the request is retried with the new BAS. Destructive
+     * sign-out happens ONLY when the failure is definitive:
+     *   - the refresh grant itself was rejected (`invalid_grant`/401), or
+     *   - there is no refresh token to present, or
+     *   - the retried request STILL came back 401 after a successful refresh.
+     * A transient refresh failure (offline/5xx/429) returns the original 401
+     * response WITHOUT touching the stored session — callers must treat a 401
+     * with the session still present as a transient failure (serve cache).
      */
     async fetchWithBas(input, bas, init = {}) {
-        const method = init.method ?? "GET";
-        const headers = new Headers(init.headers);
-        headers.set("Authorization", `Bearer ${bas}`);
-        const proof = await this.dpopProof(method, input, bas);
-        if (proof)
-            headers.set("DPoP", proof);
-        return this.fetchWithDeprecation(input, { ...init, method, headers });
+        const doFetch = async (token) => {
+            const method = init.method ?? "GET";
+            const headers = new Headers(init.headers);
+            headers.set("Authorization", `Bearer ${token}`);
+            const proof = await this.dpopProof(method, input, token);
+            if (proof)
+                headers.set("DPoP", proof);
+            return this.fetchWithDeprecation(input, { ...init, method, headers });
+        };
+        const res = await doFetch(bas);
+        if (res.status !== 401)
+            return res;
+        // Another caller may have already rotated the session while this request
+        // was in flight (the caller captured a now-stale BAS). Retry with the
+        // current stored token before spending a rotation.
+        const current = await this.storage.get(KEY_BAS);
+        if (current && current !== bas) {
+            const retriedWithCurrent = await doFetch(current);
+            if (retriedWithCurrent.status !== 401)
+                return retriedWithCurrent;
+            // Still 401 — fall through to a real refresh with the live token.
+        }
+        const outcome = await this.refreshSession();
+        if (outcome === "refreshed") {
+            const rotated = await this.storage.get(KEY_BAS);
+            if (!rotated)
+                return res; // defensive; persistRefreshedToken always writes it
+            const retried = await doFetch(rotated);
+            if (retried.status === 401) {
+                // Fresh BAS minted seconds ago and still rejected — definitive.
+                this.log("bas_unauthorized_after_refresh", { step: "fetch_with_bas", status: 401 });
+                await this.clearLocalSession();
+            }
+            return retried;
+        }
+        if (outcome === "no_refresh_token" || outcome === "definitive_failure") {
+            // 401 with no recovery path (definitive_failure already cleared
+            // storage inside the refresh; the no-token path clears here).
+            if (outcome === "no_refresh_token") {
+                this.log("bas_unauthorized_no_refresh_token", { step: "fetch_with_bas", status: 401 });
+                await this.clearLocalSession();
+            }
+            return res;
+        }
+        // transient_failure: keep the session; surface the original 401.
+        return res;
+    }
+    /**
+     * True when a 401 response should be treated as a signed-out verdict:
+     * `fetchWithBas` has already run the refresh-then-retry dance and cleared
+     * local storage iff the failure was definitive. If the BAS row is still
+     * present, the 401 rode a TRANSIENT refresh failure — the session is kept
+     * and callers must degrade gracefully (serve cache) instead of signing out.
+     */
+    async sessionWasCleared() {
+        return (await this.storage.get(KEY_BAS)) === null;
     }
     async dpopProof(method, url, accessToken) {
         const keypair = await this.getDpopKeypair();
@@ -673,6 +1060,18 @@ export class BravelyAccountManager {
 function stripTrailingSlash(s) {
     return s.endsWith("/") ? s.slice(0, -1) : s;
 }
+/**
+ * Normalize an optional install id: trim whitespace and collapse empty /
+ * missing values to `null` so the manager's "is one set?" check is a simple
+ * truthiness test. A non-empty value is passed through verbatim (the auth
+ * server applies its own length cap on the `app_auth_codes` write).
+ */
+function normalizeInstallId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 function supportsDpopCrypto() {
     return (typeof globalThis !== "undefined" &&
         typeof globalThis.crypto !== "undefined" &&