@oxyhq/core 1.11.24 → 2.0.0

package/dist/esm/AuthManager.js

@@ -18,6 +18,14 @@ const STORAGE_KEYS = {
     USER: 'oxy_user',
     AUTH_METHOD: 'oxy_auth_method',
     FEDCM_LOGIN_HINT: 'oxy_fedcm_login_hint',
+    /**
+     * Persisted active `authuser` slot index for the cookie path. Stores ONLY
+     * the integer slot index (e.g. `"0"`, `"1"`), never a token or session
+     * id — that lives in the httpOnly `oxy_rt_${n}` cookie. Used so that a
+     * cold-boot `restoreFromCookies()` lands on the user's last-chosen slot
+     * instead of always defaulting to the lowest authuser.
+     */
+    ACTIVE_AUTHUSER: 'oxy_active_authuser',
 };
 /**
  * Default in-memory storage for non-browser environments.
@@ -108,6 +116,64 @@ export class AuthManager {
         this._broadcastChannel = null;
         /** Set to true when another tab broadcasts a successful refresh, so this tab can skip its own. */
         this._otherTabRefreshed = false;
+        /**
+         * Identifier for this AuthManager instance (≈ "this tab"). Random hex
+         * generated at construction; advertised in every outgoing broadcast and
+         * used as the lookup key in `_knownPeerNonces`.
+         */
+        this._tabId = AuthManager._randomHex(16);
+        /**
+         * Per-tab nonce, advertised in every outgoing broadcast. Receivers record
+         * the first (tabId, nonce) pair they see from a given peer; subsequent
+         * messages from the same tabId MUST carry the same nonce or they're
+         * ignored.
+         *
+         * Threat model: a same-origin XSS payload can post to the channel but can
+         * NOT read this instance's private `_broadcastNonce` field (it lives in
+         * closure, not on `window`). Forged broadcasts from XSS therefore can't
+         * impersonate this tab. A new attacker-controlled tabId trips the
+         * "first message from a new peer" branch, which is by definition trusted
+         * — so the gate raises the bar but is not a complete defence (a perfect
+         * mitigation would require message signing with a server-issued key).
+         */
+        this._broadcastNonce = AuthManager._randomHex(16);
+        /**
+         * Bounded LRU of `(tabId → nonce)` pairs seen on inbound broadcasts. First
+         * sighting of a new tabId records its nonce; later messages from that
+         * tabId are rejected if the nonce doesn't match.
+         */
+        this._knownPeerNonces = new Map();
+        /**
+         * In-flight `switchAuthuser` promise. Deduplicates concurrent calls so two
+         * near-simultaneous switches don't both fire refresh requests and rotate
+         * the slot twice. Mirrors the `refreshPromise` pattern used by
+         * `refreshToken`.
+         */
+        this._switchPromise = null;
+        /**
+         * Last `restoreFromCookies()` completion timestamp, keyed by the
+         * AuthManager's active authuser at the time of completion. Used to gate
+         * cross-tab cascade: a flurry of BroadcastChannel events from sibling
+         * tabs can otherwise trigger N back-to-back snapshots and rotate every
+         * slot's access token N times.
+         */
+        this._lastRestoreAt = new Map();
+        /**
+         * In-memory registry of every device-local account the AuthManager knows
+         * about, keyed by `authuser` slot index. Populated by:
+         *   - `restoreFromCookies()` (cold boot)
+         *   - `switchAuthuser()` (per-account rotation)
+         *   - `handleAuthSuccess()` (fresh login when the server response carries
+         *     an `authuser` field)
+         * Access tokens live ONLY here in the cookie path — they are never
+         * persisted to localStorage.
+         */
+        this.accounts = new Map();
+        /**
+         * Currently-active `authuser` slot in the cookie path. `null` means either
+         * the cookie path hasn't been initialised yet, or no slots are signed in.
+         */
+        this.activeAuthuser = null;
         this.oxyServices = oxyServices;
         const crossTabSync = config.crossTabSync ?? (typeof BroadcastChannel !== 'undefined');
         this.config = {
@@ -115,6 +181,7 @@ export class AuthManager {
             autoRefresh: config.autoRefresh ?? true,
             refreshBuffer: config.refreshBuffer ?? 5 * 60 * 1000, // 5 minutes
             crossTabSync,
+            cookieOnly: config.cookieOnly ?? false,
         };
         this.storage = this.config.storage;
         // Persist tokens to storage when HttpService refreshes them automatically
@@ -151,6 +218,8 @@ export class AuthManager {
     async _handleCrossTabMessage(message) {
         if (!message || !message.type)
             return;
+        if (!this._acceptBroadcast(message))
+            return;
         switch (message.type) {
             case 'tokens_refreshed': {
                 // Another tab successfully refreshed. Signal to cancel our pending refresh.
@@ -189,20 +258,130 @@ export class AuthManager {
                 this.notifyListeners();
                 break;
             }
+            case 'accounts_restored':
+            case 'authuser_switched':
+            case 'authuser_signed_out': {
+                // Another tab restored/switched/dropped a slot. The authoritative
+                // state lives in the httpOnly cookies which we can't read from JS,
+                // so the cleanest reaction is to re-run `restoreFromCookies()` on
+                // a microtask and re-sync our in-memory registry. We swallow
+                // failures: a transient network error must not bring down a tab
+                // that already had a valid session.
+                //
+                // The restoreFromCookies() body owns the per-slot debounce so a
+                // burst of N broadcasts only costs one /auth/refresh-all rotation
+                // (instead of N back-to-back rotations of every cookie slot).
+                Promise.resolve().then(() => {
+                    this.restoreFromCookies().catch(() => {
+                        // Best-effort; existing accounts (if any) remain intact.
+                    });
+                });
+                break;
+            }
+            case 'all_signed_out': {
+                // Mirror `signed_out` but also wipe the cookie-path registry.
+                if (this.refreshTimer) {
+                    clearTimeout(this.refreshTimer);
+                    this.refreshTimer = null;
+                }
+                this.refreshPromise = null;
+                this.accounts.clear();
+                this.activeAuthuser = null;
+                this._lastKnownAccessToken = null;
+                this.oxyServices.httpService.setTokens('');
+                this.currentUser = null;
+                this.notifyListeners();
+                break;
+            }
             // 'refresh_starting' is informational; we don't need to act on it currently
         }
     }
     /**
-     * Broadcast a message to other tabs.
+     * Broadcast a message to other tabs. Always stamps this tab's `tabId` and
+     * `nonce` onto the message so receivers can run the cross-tab nonce gate.
      */
     _broadcast(message) {
+        const stamped = {
+            ...message,
+            tabId: this._tabId,
+            nonce: this._broadcastNonce,
+        };
         try {
-            this._broadcastChannel?.postMessage(message);
+            this._broadcastChannel?.postMessage(stamped);
         }
         catch {
             // Channel closed or unavailable
         }
     }
+    /**
+     * Generate `bytes` bytes of cryptographic randomness encoded as lowercase
+     * hex. Prefers Web Crypto's `getRandomValues` when available (browser /
+     * modern Node); falls back to `Math.random` ONLY in environments without
+     * Web Crypto (the resulting nonce is still unguessable to a same-origin
+     * XSS payload — the goal is unforgeability across tabs, not cryptographic
+     * secrecy across the network).
+     */
+    static _randomHex(bytes) {
+        const buffer = new Uint8Array(bytes);
+        const gcrypto = typeof globalThis !== 'undefined'
+            ? globalThis.crypto
+            : undefined;
+        if (gcrypto && typeof gcrypto.getRandomValues === 'function') {
+            gcrypto.getRandomValues(buffer);
+        }
+        else {
+            for (let i = 0; i < buffer.length; i++) {
+                buffer[i] = Math.floor(Math.random() * 256);
+            }
+        }
+        let hex = '';
+        for (const byte of buffer) {
+            hex += byte.toString(16).padStart(2, '0');
+        }
+        return hex;
+    }
+    /**
+     * Validate an inbound broadcast against the cross-tab nonce gate.
+     *
+     * Returns `true` when the message should be honoured, `false` when it
+     * MUST be ignored:
+     *   - Message is missing `tabId` or `nonce` → ignore (forged or
+     *     mismatched-version sibling tab).
+     *   - First sighting of `tabId` → record the nonce and honour the message
+     *     (trust-on-first-use, the best we can do without a shared secret).
+     *   - Subsequent message from the same `tabId` with the SAME nonce →
+     *     honour.
+     *   - Subsequent message from the same `tabId` with a DIFFERENT nonce →
+     *     ignore (the canonical "forged broadcast" case — a same-origin XSS
+     *     payload can't read the real tab's `_broadcastNonce`).
+     *
+     * Echoes of this tab's own broadcasts (same `tabId`) are also dropped so
+     * we don't react to our own messages.
+     */
+    _acceptBroadcast(message) {
+        if (!message || typeof message.tabId !== 'string' || typeof message.nonce !== 'string') {
+            return false;
+        }
+        if (message.tabId === this._tabId) {
+            // Same-tab echo. Some BroadcastChannel implementations deliver our own
+            // posts back to us; never act on those.
+            return false;
+        }
+        const seen = this._knownPeerNonces.get(message.tabId);
+        if (seen === undefined) {
+            // Trust-on-first-use. Bound the map to avoid unbounded growth from a
+            // tab-id sprayer.
+            if (this._knownPeerNonces.size >= AuthManager._MAX_KNOWN_PEERS) {
+                const oldest = this._knownPeerNonces.keys().next().value;
+                if (oldest !== undefined) {
+                    this._knownPeerNonces.delete(oldest);
+                }
+            }
+            this._knownPeerNonces.set(message.tabId, message.nonce);
+            return true;
+        }
+        return seen === message.nonce;
+    }
     /**
      * Get default storage based on environment.
      */
@@ -532,11 +711,34 @@ export class AuthManager {
         return method;
     }
     /**
-     * Initialize auth state from storage.
+     * Initialize auth state on app startup.
+     *
+     * Order of operations:
+     *   1. Try the cookie path via `restoreFromCookies()`. This is the
+     *      preferred path because the httpOnly refresh cookies are
+     *      cross-tab, persist across hard reloads, and don't expose any
+     *      refresh-token material to JS.
+     *   2. If the cookie path yielded zero accounts AND `cookieOnly` is
+     *      `false`, fall back to the legacy localStorage path
+     *      (`oxy_access_token` / `oxy_session`) for backwards compatibility
+     *      with apps that haven't migrated to the cookie endpoint yet.
+     *   3. If `cookieOnly` is `true`, skip the legacy fallback entirely.
+     *      This guarantees no tokens or refresh tokens are ever read from
+     *      or written to JS-accessible storage.
      *
-     * Call this on app startup to restore previous session.
+     * Returns the active user on success, or `null` when neither path
+     * restored a session.
      */
     async initialize() {
+        // 1. Cookie path (preferred).
+        const cookieResult = await this.restoreFromCookies();
+        if (cookieResult.accounts.length > 0) {
+            return this.currentUser;
+        }
+        // 2. Legacy localStorage path (opt-out via `cookieOnly`).
+        if (this.config.cookieOnly) {
+            return null;
+        }
         try {
             // Try to restore user from storage
             const userJson = await this.storage.getItem(STORAGE_KEYS.USER);
@@ -578,6 +780,472 @@ export class AuthManager {
             return null;
         }
     }
+    // -------------------------------------------------------------------------
+    // Multi-account cookie path (Google-style multi-sign-in).
+    // -------------------------------------------------------------------------
+    // The cookie path is web-only and orthogonal to the legacy bearer path
+    // above: it never touches the `oxy_access_token` / `oxy_refresh_token` /
+    // `oxy_session` localStorage keys, because the refresh token lives in the
+    // httpOnly `oxy_rt_${authuser}` cookies and access tokens live in
+    // `this.accounts` (in-memory only). The only localStorage key the cookie
+    // path writes is `STORAGE_KEYS.ACTIVE_AUTHUSER` — a small integer that is
+    // explicitly NOT a secret.
+    //
+    // Apps that want to opt out of the legacy localStorage path entirely
+    // (recommended for new web apps) pass `cookieOnly: true` to the
+    // AuthManager config; in that mode `initialize()` ONLY uses the cookie
+    // path.
+    // -------------------------------------------------------------------------
+    /**
+     * Read the persisted active `authuser` slot index. Returns `null` when
+     * none is persisted, the value is corrupt, or the storage adapter has no
+     * record. Storage failures are non-fatal: the cookie path falls back to
+     * "lowest authuser" deterministic selection.
+     */
+    async readActiveAuthuser() {
+        try {
+            const raw = await this.storage.getItem(STORAGE_KEYS.ACTIVE_AUTHUSER);
+            if (raw === null || raw === undefined)
+                return null;
+            const parsed = Number.parseInt(raw, 10);
+            if (!Number.isFinite(parsed) || parsed < 0)
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Persist the active `authuser` slot index. No-ops on storage failure
+     * (e.g. Safari private mode, native SecureStore unavailable) — this is
+     * best-effort UX persistence, not authoritative state.
+     */
+    async writeActiveAuthuser(authuser) {
+        if (!Number.isFinite(authuser) || authuser < 0)
+            return;
+        try {
+            await this.storage.setItem(STORAGE_KEYS.ACTIVE_AUTHUSER, String(authuser));
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    /**
+     * Clear the persisted active `authuser` so the next cold boot starts from
+     * a clean slate (used on full sign-out).
+     */
+    async clearActiveAuthuser() {
+        try {
+            await this.storage.removeItem(STORAGE_KEYS.ACTIVE_AUTHUSER);
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    /**
+     * Build a `MinimalUserData` from a `RefreshAllAccount`. Returns `null` when
+     * the wire entry has no user shape (legacy `/auth/refresh` fallback) — the
+     * AuthManager's caller is expected to hydrate via `/users/me` in that
+     * case.
+     */
+    static toMinimalUser(account) {
+        if (!account.user)
+            return null;
+        return {
+            id: account.user.id,
+            username: account.user.username,
+            avatar: account.user.avatar ?? undefined,
+        };
+    }
+    /**
+     * Hydrate the user shape for a slot whose AuthManagerAccount currently has
+     * `user: null` (legacy refresh fallback, or a switch onto a previously
+     * unknown slot). Calls `/users/me` with the slot's freshly-planted access
+     * token already on the HTTP client; merges the result back into the
+     * registry entry. Network failures are non-fatal — the slot remains with
+     * `user: null` and the UI is expected to render the public-key fallback
+     * handle until a later restore picks the real user shape up.
+     */
+    async _hydrateUnknownUser(authuser) {
+        const oxy = this.oxyServices;
+        if (typeof oxy.getCurrentUser !== 'function')
+            return;
+        let me;
+        try {
+            me = await oxy.getCurrentUser();
+        }
+        catch {
+            // Best-effort: keep `user: null` and let the UI fall back to the
+            // public-key handle.
+            return;
+        }
+        const existing = this.accounts.get(authuser);
+        if (!existing)
+            return;
+        const hydrated = {
+            id: me.id,
+            username: me.username,
+            name: typeof me.name === 'string' ? me.name : undefined,
+            avatar: me.avatar ?? null,
+            email: me.email,
+            color: me.color ?? null,
+        };
+        this.accounts.set(authuser, { ...existing, user: hydrated });
+        // Mirror onto `currentUser` if this is the active slot.
+        if (this.activeAuthuser === authuser) {
+            this.currentUser = {
+                id: hydrated.id,
+                username: hydrated.username,
+                avatar: hydrated.avatar ?? undefined,
+            };
+            this.notifyListeners();
+        }
+    }
+    /**
+     * Snapshot of the registered cookie-path accounts, sorted by `authuser`
+     * ascending (canonical order). Mutating the returned array does not
+     * affect AuthManager state.
+     */
+    getAccounts() {
+        return Array.from(this.accounts.values()).sort((a, b) => a.authuser - b.authuser);
+    }
+    /**
+     * The slot index that is currently active in the cookie path, or `null`
+     * if the cookie path hasn't been initialised or no slots are signed in.
+     */
+    getActiveAuthuser() {
+        return this.activeAuthuser;
+    }
+    /**
+     * Convenience: the AuthManagerAccount currently flagged active.
+     */
+    getActiveAccount() {
+        if (this.activeAuthuser === null)
+            return null;
+        return this.accounts.get(this.activeAuthuser) ?? null;
+    }
+    /**
+     * Restore every device-local account from the httpOnly refresh cookies.
+     *
+     * Calls `oxyServices.refreshAllSessions()` (`POST /auth/refresh-all` with
+     * `credentials: 'include'`). The server rotates every presented
+     * `oxy_rt_${authuser}` cookie in parallel and returns one entry per
+     * VALID slot. The SDK transparently falls back to the legacy single-slot
+     * `/auth/refresh` against older servers (handled inside
+     * `refreshAllSessions`).
+     *
+     * Plants the active account's access token on the shared HTTP client;
+     * sibling slots' tokens stay in the in-memory registry so a later
+     * `switchAuthuser()` can hot-swap them without a network round-trip.
+     *
+     * The persisted `oxy_active_authuser` slot wins when it matches a
+     * returned account; otherwise the lowest returned `authuser` is chosen
+     * deterministically.
+     *
+     * Returns `{ accounts: [], activeAuthuser: null }` on any failure or
+     * empty snapshot — callers treat that as "no signed-in accounts" and
+     * proceed unauthenticated. State is NOT cleared on failure; existing
+     * accounts (if any) remain intact.
+     */
+    async restoreFromCookies() {
+        // Cross-tab cascade debounce. If we restored within the last
+        // _RESTORE_DEBOUNCE_MS for the currently-active slot, skip the network
+        // round-trip and return the cached registry verbatim. A burst of N
+        // BroadcastChannel events from sibling tabs therefore costs at most one
+        // /auth/refresh-all rotation. Cold-boot calls (activeAuthuser still
+        // null) always run because the cache hasn't been seeded yet.
+        if (this.activeAuthuser !== null) {
+            const last = this._lastRestoreAt.get(this.activeAuthuser);
+            if (last !== undefined && Date.now() - last < AuthManager._RESTORE_DEBOUNCE_MS) {
+                return {
+                    accounts: this.getAccounts(),
+                    activeAuthuser: this.activeAuthuser,
+                };
+            }
+        }
+        let snapshot;
+        try {
+            snapshot = await this.oxyServices.refreshAllSessions();
+        }
+        catch {
+            return { accounts: [], activeAuthuser: null };
+        }
+        if (snapshot.accounts.length === 0) {
+            return { accounts: [], activeAuthuser: null };
+        }
+        // Replace the registry wholesale: the server's snapshot is authoritative.
+        this.accounts.clear();
+        for (const account of snapshot.accounts) {
+            this.accounts.set(account.authuser, {
+                authuser: account.authuser,
+                sessionId: account.sessionId,
+                user: account.user,
+                accessToken: account.accessToken,
+                expiresAt: account.expiresAt,
+            });
+        }
+        // Pick the active slot: persisted `oxy_active_authuser` wins if it
+        // matches a returned account; otherwise the lowest returned authuser
+        // (the snapshot is already sorted ascending, so accounts[0] is the
+        // lowest).
+        const persisted = await this.readActiveAuthuser();
+        const active = (persisted !== null && this.accounts.has(persisted))
+            ? persisted
+            : snapshot.accounts[0].authuser;
+        this.activeAuthuser = active;
+        const activeAccount = this.accounts.get(active);
+        const slotsNeedingHydration = [];
+        if (activeAccount) {
+            this._lastKnownAccessToken = activeAccount.accessToken;
+            this.oxyServices.httpService.setTokens(activeAccount.accessToken);
+            this.currentUser = AuthManager.toMinimalUser({
+                authuser: activeAccount.authuser,
+                accessToken: activeAccount.accessToken,
+                expiresAt: activeAccount.expiresAt,
+                sessionId: activeAccount.sessionId,
+                user: activeAccount.user,
+            });
+            await this.writeActiveAuthuser(active);
+            // Schedule auto-refresh on the active slot so the in-memory access
+            // token doesn't silently expire under the user.
+            if (this.config.autoRefresh) {
+                this.setupCookieRefresh(activeAccount.expiresAt, active);
+            }
+            // The legacy /auth/refresh fallback yields user=null for the active
+            // slot. Schedule a /users/me hydration so the chooser isn't stuck on
+            // the public-key handle. Hydration is fire-and-forget — the snapshot
+            // is already considered "restored" once the access token is planted.
+            if (activeAccount.user === null) {
+                slotsNeedingHydration.push(activeAccount.authuser);
+            }
+        }
+        this._lastRestoreAt.set(active, Date.now());
+        this._broadcast({ type: 'accounts_restored', timestamp: Date.now() });
+        this.notifyListeners();
+        for (const slot of slotsNeedingHydration) {
+            void this._hydrateUnknownUser(slot);
+        }
+        return {
+            accounts: this.getAccounts(),
+            activeAuthuser: this.activeAuthuser,
+        };
+    }
+    /**
+     * Switch the active account to a different device-local slot.
+     *
+     * Calls `oxyServices.refreshTokenViaCookie({ authuser })` to mint a fresh
+     * access token from the slot's httpOnly cookie, updates the in-memory
+     * registry entry, plants the token on the HTTP client, persists the new
+     * active slot, and broadcasts cross-tab.
+     *
+     * Throws when the slot's refresh cookie is missing / expired / reused
+     * (the SDK returns `null` from `refreshTokenViaCookie` in that case, and
+     * we surface it as an `Error` so callers can clean up the slot from
+     * their UI).
+     */
+    async switchAuthuser(authuser) {
+        // Concurrency gate. Two near-simultaneous switchAuthuser calls would
+        // otherwise both POST /auth/refresh?authuser=N, rotating the slot's
+        // refresh-token family twice and racing on the registry update. The
+        // gate is keyed only by "any switch in flight" — switching to a
+        // DIFFERENT slot while a switch is in flight returns the in-flight
+        // promise (callers can re-issue once it settles if they really meant a
+        // different slot).
+        if (this._switchPromise) {
+            return this._switchPromise;
+        }
+        this._switchPromise = this._doSwitchAuthuser(authuser);
+        try {
+            return await this._switchPromise;
+        }
+        finally {
+            this._switchPromise = null;
+        }
+    }
+    async _doSwitchAuthuser(authuser) {
+        const refreshed = await this.oxyServices.refreshTokenViaCookie({ authuser });
+        if (refreshed === null) {
+            // Drop the dead slot from our registry so the chooser doesn't keep
+            // offering it; callers can drive a `restoreFromCookies()` to
+            // re-sync.
+            this.accounts.delete(authuser);
+            if (this.activeAuthuser === authuser) {
+                this.activeAuthuser = null;
+            }
+            throw new Error(`Refresh cookie for authuser=${authuser} is missing or expired`);
+        }
+        // Update (or insert) the slot in the registry. We preserve any user
+        // metadata we already knew from a prior `restoreFromCookies` — the
+        // single-slot refresh endpoint does NOT re-project the user shape. When
+        // we have no prior metadata, we leave `user: null` and schedule a
+        // /users/me hydration below.
+        const existing = this.accounts.get(authuser);
+        const decoded = AuthManager.decodeSessionIdFromAccessToken(refreshed.accessToken);
+        const sessionId = decoded ?? existing?.sessionId ?? '';
+        const updated = {
+            authuser,
+            sessionId,
+            user: existing?.user ?? null,
+            accessToken: refreshed.accessToken,
+            expiresAt: refreshed.expiresAt,
+        };
+        this.accounts.set(authuser, updated);
+        this.activeAuthuser = authuser;
+        this._lastKnownAccessToken = refreshed.accessToken;
+        this.oxyServices.httpService.setTokens(refreshed.accessToken);
+        this.currentUser = updated.user
+            ? {
+                id: updated.user.id,
+                username: updated.user.username,
+                avatar: updated.user.avatar ?? undefined,
+            }
+            : null;
+        await this.writeActiveAuthuser(authuser);
+        if (this.config.autoRefresh) {
+            this.setupCookieRefresh(refreshed.expiresAt, authuser);
+        }
+        this._broadcast({ type: 'authuser_switched', authuser, timestamp: Date.now() });
+        this.notifyListeners();
+        if (updated.user === null) {
+            // Fire-and-forget hydration: the switch is considered complete once
+            // the token is planted, the UI uses getAccountFallbackHandle (public-
+            // key fallback) until /users/me resolves.
+            void this._hydrateUnknownUser(authuser);
+        }
+        return {
+            accessToken: refreshed.accessToken,
+            expiresAt: refreshed.expiresAt,
+            authuser,
+        };
+    }
+    /**
+     * Sign out a single device-local slot.
+     *
+     * Calls `oxyServices.logoutSessionByAuthuser(authuser)`: server-side
+     * revokes the slot's refresh-token family and clears the
+     * `oxy_rt_${authuser}` cookie via `Set-Cookie`. The slot is removed from
+     * the in-memory registry. If the slot was active, the next lowest
+     * remaining authuser becomes active (or `null` when none remain).
+     */
+    async signOutAuthuser(authuser) {
+        try {
+            await this.oxyServices.logoutSessionByAuthuser(authuser);
+        }
+        catch {
+            // Best-effort: the server-side logout is idempotent on unknown
+            // tokens, and we'd rather drop the slot locally than leave dead
+            // state on a network blip.
+        }
+        this.accounts.delete(authuser);
+        if (this.activeAuthuser === authuser) {
+            const remaining = this.getAccounts();
+            if (remaining.length > 0) {
+                // Pick the lowest remaining authuser as the new active. We don't
+                // proactively refresh its token here — callers can drive
+                // `switchAuthuser` if they need a fresh bearer. This keeps the
+                // method's network footprint to exactly one request.
+                const next = remaining[0];
+                this.activeAuthuser = next.authuser;
+                this._lastKnownAccessToken = next.accessToken;
+                this.oxyServices.httpService.setTokens(next.accessToken);
+                this.currentUser = next.user
+                    ? {
+                        id: next.user.id,
+                        username: next.user.username,
+                        avatar: next.user.avatar ?? undefined,
+                    }
+                    : null;
+                await this.writeActiveAuthuser(next.authuser);
+                if (next.user === null) {
+                    void this._hydrateUnknownUser(next.authuser);
+                }
+            }
+            else {
+                this.activeAuthuser = null;
+                this._lastKnownAccessToken = null;
+                this.oxyServices.httpService.setTokens('');
+                this.currentUser = null;
+                await this.clearActiveAuthuser();
+            }
+        }
+        this._broadcast({ type: 'authuser_signed_out', authuser, timestamp: Date.now() });
+        this.notifyListeners();
+    }
+    /**
+     * Sign out EVERY device-local account on this device.
+     *
+     * Calls `oxyServices.logoutAllSessionsViaCookie()`: server-side revokes
+     * every presented family and `Set-Cookie`s an immediate expiry for every
+     * recognised `oxy_rt_${n}` slot AND the legacy `oxy_rt` cookie. The
+     * in-memory registry is wiped, the active slot is cleared, and the
+     * persisted `oxy_active_authuser` is removed so the next cold boot
+     * starts fresh.
+     */
+    async signOutAllViaCookies() {
+        try {
+            await this.oxyServices.logoutAllSessionsViaCookie();
+        }
+        catch {
+            // Best-effort; server-side endpoint is idempotent.
+        }
+        this.accounts.clear();
+        this.activeAuthuser = null;
+        this._lastKnownAccessToken = null;
+        this.oxyServices.httpService.setTokens('');
+        this.currentUser = null;
+        this._lastRestoreAt.clear();
+        await this.clearActiveAuthuser();
+        // Also clear the refresh timer that the cookie path may have scheduled.
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this._broadcast({ type: 'all_signed_out', timestamp: Date.now() });
+        this.notifyListeners();
+    }
+    /**
+     * Schedule an auto-refresh for the cookie path on the active slot. Reuses
+     * the same single `refreshTimer` as the legacy path (the AuthManager has
+     * exactly ONE active slot at a time, so one timer suffices).
+     */
+    setupCookieRefresh(expiresAt, authuser) {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+        }
+        const expiresAtMs = new Date(expiresAt).getTime();
+        if (!Number.isFinite(expiresAtMs))
+            return;
+        const refreshAt = expiresAtMs - this.config.refreshBuffer;
+        const delay = Math.max(0, refreshAt - Date.now());
+        this.refreshTimer = setTimeout(() => {
+            // Only refresh if this slot is still the active one when the timer
+            // fires (the user might have switched in the meantime).
+            if (this.activeAuthuser !== authuser)
+                return;
+            this.switchAuthuser(authuser).catch(() => {
+                // A failed cookie refresh on the active slot means the user must
+                // re-auth; surface via `notifyListeners` indirectly when the slot
+                // is dropped from the registry by `switchAuthuser`.
+            });
+        }, delay);
+    }
+    /**
+     * Decode the session id from an unverified JWT access token. Decode-only
+     * (no signature verification) — the server already verified the
+     * signature when minting the token. Returns `null` on malformed input.
+     */
+    static decodeSessionIdFromAccessToken(token) {
+        try {
+            const decoded = jwtDecode(token);
+            return typeof decoded.sessionId === 'string' && decoded.sessionId.length > 0
+                ? decoded.sessionId
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Destroy the auth manager and clean up resources.
      */
@@ -587,6 +1255,10 @@ export class AuthManager {
             this.refreshTimer = null;
         }
         this.listeners.clear();
+        this._knownPeerNonces.clear();
+        this._lastRestoreAt.clear();
+        this._switchPromise = null;
+        this.refreshPromise = null;
         // Close BroadcastChannel
         if (this._broadcastChannel) {
             try {
@@ -599,6 +1271,8 @@ export class AuthManager {
         }
     }
 }
+AuthManager._MAX_KNOWN_PEERS = 32;
+AuthManager._RESTORE_DEBOUNCE_MS = 2000;
 /**
  * Create an AuthManager instance.
  *