@oxyhq/core 9.2.2 → 9.2.3

package/dist/cjs/HttpService.js

@@ -135,6 +135,7 @@ class HttpService {
         this.tokenRefreshCooldownUntil = 0;
         this.authRefreshHandler = null;
         this.accessTokenProvider = null;
+        this.deviceSecretMintInFlight = null;
         /**
          * Epoch (ms) before which a cache-size telemetry warning must not be
          * re-emitted. Throttles the {@link CACHE_SOFT_MAX_ENTRIES} warning to at most
@@ -837,6 +838,32 @@ class HttpService {
         }
         return this.tokenRefreshPromise;
     }
+    /**
+     * PROCESS-WIDE single-flight for the rotating device-secret mint
+     * (`POST /session/device/token`).
+     *
+     * The server rotates the presented `deviceSecret` on every successful mint, so
+     * two concurrent mints would double-rotate and the durable store could end up
+     * holding a superseded secret → a later cold-boot mint 401s → the user is
+     * signed out. Every mint lane (the re-mint handler behind `refreshAccessToken`,
+     * the device-first cold boot, the socket token transport, the tab-focus
+     * reconcile) funnels its `refreshDeviceSecretArm` call through here, so
+     * concurrent callers await the SAME in-flight mint and all receive its result —
+     * exactly one server rotation.
+     *
+     * Distinct from {@link tokenRefreshPromise} (which dedups the FULL re-mint
+     * handler incl. the native shared-key arm + the failure cooldown): this inner
+     * guard serializes the rotation itself across BOTH the handler and the
+     * handler-independent cold boot, which never runs through `refreshAccessToken`.
+     */
+    runSingleFlightDeviceSecretMint(mint) {
+        if (!this.deviceSecretMintInFlight) {
+            this.deviceSecretMintInFlight = mint().finally(() => {
+                this.deviceSecretMintInFlight = null;
+            });
+        }
+        return this.deviceSecretMintInFlight;
+    }
     /**
      * Unwrap standardized API response format
      */

package/dist/cjs/boot/sessionColdBoot.js

@@ -10,31 +10,23 @@ exports.runSessionColdBoot = runSessionColdBoot;
  * the app renders with a "Sign in with Oxy" button.
  *
  * Ordered steps (first to yield a session wins):
- *   1. `device-secret-mint` (web + native) — the zero-cookie transport: when the
+ *   1. `warm-token-plant` (web + native) — the fastest path: when the persisted
+ *      store still holds a warm access token that is valid for more than the
+ *      refresh lead window, plant it and yield the session with NO network
+ *      round-trip. The background scheduler rotates it shortly after.
+ *   2. `device-secret-mint` (web + native) — the zero-cookie transport: when the
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   2. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
- *   3. Signed out.
+ *   3. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
+ *   4. Signed out.
  *
  * ESM-safe (no `require()`); no react/react-native/expo imports.
  */
 const coldBoot_1 = require("../utils/coldBoot");
 const platform_1 = require("../utils/platform");
-const errorUtils_1 = require("../utils/errorUtils");
 const loggerUtils_1 = require("../utils/loggerUtils");
-function classifyMintFailure(error) {
-    if ((0, errorUtils_1.extractErrorStatus)(error) === 401) {
-        // Structural read (not `instanceof Error`): the thrown value can be a plain
-        // ApiError-shaped object or come from another realm, where instanceof fails
-        // and a `no_active_session` would be misread as a stale secret and dropped.
-        const message = error?.message;
-        return typeof message === 'string' && message.includes('no_active_session')
-            ? 'no_active_session'
-            : 'invalid_secret';
-    }
-    return 'transient';
-}
+const refresh_1 = require("../session/refresh");
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
  * a side effect, invokes `onSession` (winning session, token already planted) or
@@ -47,60 +39,98 @@ async function runSessionColdBoot(opts) {
     // bundler re-evaluation.
     let signedOutReason = 'no_session';
     const steps = [];
-    // 1. device-secret-mint (web + native) — the zero-cookie fast path. When the
-    //    origin persisted a deviceId + deviceSecret, mint a short access token with
-    //    a single bearer-less POST (no cookie, no navigation).
+    // 1. warm-token-plant (web + native) — the fastest path. When the persisted
+    //    store already holds a still-valid warm access token (its expiry more than
+    //    the refresh lead window away) plus its owning session identity, plant it
+    //    and yield the session IMMEDIATELY, skipping the blocking mint round-trip on
+    //    first paint. The token is used AS-IS: this step NEVER mints, rotates, or
+    //    persists anything. The proactive `startTokenRefreshScheduler` + the
+    //    request-time preflight (both wired in the services provider) rotate it in
+    //    the background; a revoked token self-heals via the 401 -> re-mint -> clear
+    //    path. This exposure is sanctioned by `authStateStore.ts` (~L30-36): the
+    //    warm token is short-lived and adds nothing over the already-persisted
+    //    `deviceSecret`.
     steps.push({
-        id: 'device-secret-mint',
+        id: 'warm-token-plant',
         run: async () => {
             const persisted = await store.load();
-            if (!persisted?.deviceId || !persisted?.deviceSecret) {
+            if (!persisted?.accessToken || !persisted.sessionId || !persisted.userId || !persisted.expiresAt) {
                 return { kind: 'skip' };
             }
-            try {
-                const mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
-                // Rotation-in-use anti-loss: persist the NEXT secret (+ refreshed warm
-                // fields, + the server's authoritative active account) BEFORE planting
-                // the minted access token, so a multi-tab race that rotates again can
-                // never strand this tab with a superseded secret.
-                const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
-                const next = {
-                    ...persisted,
-                    deviceId: mint.state.deviceId,
-                    deviceSecret: mint.nextDeviceSecret,
-                    accessToken: mint.accessToken,
-                    expiresAt: mint.expiresAt,
-                    ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
-                };
-                await store.save(next);
-                oxy.setTokens(mint.accessToken);
-                return {
-                    kind: 'session',
-                    session: { sessionId: next.sessionId, userId: next.userId, accessToken: mint.accessToken },
-                };
+            // Guard a malformed `expiresAt` (Date.parse -> NaN): treat as not-valid and
+            // fall through to the mint lane. A token still inside the refresh lead
+            // window (or already expired) is likewise skipped — let the mint lane get a
+            // fresh one rather than plant a token about to expire.
+            const expiresAtMs = new Date(persisted.expiresAt).getTime();
+            if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now() + refresh_1.TOKEN_REFRESH_LEAD_MS) {
+                return { kind: 'skip' };
             }
-            catch (error) {
-                const failure = classifyMintFailure(error);
-                if (failure === 'invalid_secret') {
+            oxy.setTokens(persisted.accessToken);
+            return {
+                kind: 'session',
+                session: {
+                    sessionId: persisted.sessionId,
+                    userId: persisted.userId,
+                    accessToken: persisted.accessToken,
+                },
+            };
+        },
+    });
+    // 2. device-secret-mint (web + native) — the zero-cookie fast path. When the
+    //    origin persisted a deviceId + deviceSecret, mint a short access token with
+    //    a single bearer-less POST (no cookie, no navigation). The mint itself runs
+    //    through `refreshDeviceSecretArm`, which acquires the client's PROCESS-WIDE
+    //    single-flight, persists the rotated `nextDeviceSecret` BEFORE planting the
+    //    token, and returns a classified outcome — so this step can never
+    //    double-rotate the server against the scheduler/transport/401 lanes, and
+    //    the durable store always converges on the true `current` secret.
+    steps.push({
+        id: 'device-secret-mint',
+        run: async () => {
+            const result = await (0, refresh_1.refreshDeviceSecretArm)({ oxy, store });
+            switch (result.status) {
+                case 'ok':
+                    // The arm persisted the rotated secret and planted the token.
+                    return {
+                        kind: 'session',
+                        session: {
+                            sessionId: result.sessionId,
+                            userId: result.userId,
+                            accessToken: result.token,
+                        },
+                    };
+                case 'invalid-secret': {
                     // Stale/diverged secret — drop it so the mint lane stops firing. On
                     // native the shared-key step below can still recover; on web this ends
                     // signed out. Setting it undefined drops the key on the store's JSON
                     // serialization, and the mint guard treats undefined as absent.
-                    await store.save({ ...persisted, deviceSecret: undefined });
+                    const persisted = await store.load();
+                    if (persisted) {
+                        await store.save({ ...persisted, deviceSecret: undefined });
+                    }
                     return { kind: 'skip' };
                 }
-                if (failure === 'no_active_session') {
-                    // Device known, no live session — authoritative signed-out.
+                case 'no-session':
+                    // Device known, no live session — authoritative signed-out. Keep the
+                    // secret (the device may sign in again).
                     signedOutReason = 'no_session';
                     return { kind: 'skip' };
-                }
-                // Transient (network / 5xx): keep the secret; a later attempt can succeed.
-                loggerUtils_1.logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'sessionColdBoot', method: 'device-secret-mint' }, error);
-                return { kind: 'skip' };
+                case 'persist-failed':
+                    // The mint rotated the secret but it could not be durably persisted —
+                    // refuse to advertise a session that will not survive a reload. Keep
+                    // the secret; a later boot/attempt re-mints once storage recovers.
+                    loggerUtils_1.logger.error('device-secret mint rotated the secret but it could not be durably persisted — not planting', undefined, { component: 'sessionColdBoot', method: 'device-secret-mint' });
+                    return { kind: 'skip' };
+                case 'transient':
+                    // Network / 5xx: keep the secret; a later attempt can succeed.
+                    loggerUtils_1.logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'sessionColdBoot', method: 'device-secret-mint' });
+                    return { kind: 'skip' };
+                case 'no-secret':
+                    return { kind: 'skip' };
             }
         },
     });
-    // 2. shared-key-signin (native) — re-mint from the shared identity.
+    // 3. shared-key-signin (native) — re-mint from the shared identity.
     steps.push({
         id: 'shared-key-signin',
         enabled: () => isNative,

package/dist/cjs/crypto/keyManager.js

@@ -234,12 +234,21 @@ class KeyManager {
             }
         }
         else if ((0, platform_1.isAndroid)()) {
-            // Android: Store in secure store (accessible via sharedUserId)
-            // Note: All Oxy apps must have the same sharedUserId in AndroidManifest.xml
-            await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
-                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-            });
-            await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+            // Android: write through the cross-app bridge (`@oxyhq/expo-oxy-identity`)
+            // when present — it persists into Commons's hardware-backed
+            // EncryptedSharedPreferences behind a signature-protected ContentProvider,
+            // so same-key Oxy apps can read it. When the bridge is not linked, fall
+            // back to the package-private secure store (no cross-app sharing).
+            const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+            if (bridge) {
+                await bridge.putShared(privateKey, publicKey);
+            }
+            else {
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
+                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                });
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+            }
         }
         // Update cache
         KeyManager.cachedSharedPublicKey = publicKey;
@@ -270,7 +279,15 @@ class KeyManager {
                 publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
             }
             else if ((0, platform_1.isAndroid)()) {
-                publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
+                // Android reads through the cross-app bridge; when it is not linked, fall
+                // back to the package-private store the fallback write path used.
+                const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+                if (bridge) {
+                    publicKey = (await bridge.getShared())?.publicKey ?? null;
+                }
+                else {
+                    publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
+                }
             }
             // Cache result
             KeyManager.cachedSharedPublicKey = publicKey;
@@ -304,7 +321,15 @@ class KeyManager {
                 privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
             }
             else if ((0, platform_1.isAndroid)()) {
-                privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+                // Android reads through the cross-app bridge; when it is not linked, fall
+                // back to the package-private store the fallback write path used.
+                const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+                if (bridge) {
+                    privateKey = (await bridge.getShared())?.privateKey ?? null;
+                }
+                else {
+                    privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+                }
             }
             return privateKey;
         }
@@ -377,10 +402,18 @@ class KeyManager {
             await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
         }
         else if ((0, platform_1.isAndroid)()) {
-            await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, {
-                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-            });
-            await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+            // Android: write through the cross-app bridge when present; otherwise the
+            // package-private store (kept consistent with the read fallback).
+            const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+            if (bridge) {
+                await bridge.putShared(canonicalPrivate, publicKey);
+            }
+            else {
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, {
+                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                });
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+            }
         }
         // Update cache
         KeyManager.cachedSharedPublicKey = publicKey;

package/dist/cjs/index.js

@@ -21,7 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.isRTLLocale = exports.normalizeLanguageCode = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.RecoveryPhraseService = exports.SignatureService = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.ORGANIZATION_CATEGORIES = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.ServiceCredentialMismatchError = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
 exports.isValidUsername = exports.isValidEmail = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = exports.createDebugLogger = exports.debugError = exports.debugWarn = exports.debugLog = exports.isDev = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = void 0;
 exports.buildIdpHubOrigin = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.normalizeOAuthRedirectUri = exports.OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = exports.OXY_SILENT_OAUTH_ATTEMPTED_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = exports.CENTRAL_IDP_APEX = exports.registrableApex = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.isValidDisplayName = exports.isValidPassword = void 0;
-exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshPersistedSession = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.redeemHubTicketOnHub = exports.syncHubAfterSignIn = exports.parseHubSyncReturnUrl = exports.normalizeOfficialReturnOrigin = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isIdpHubOrigin = exports.buildHubSyncUrl = void 0;
+exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.redeemHubTicketOnHub = exports.syncHubAfterSignIn = exports.parseHubSyncReturnUrl = exports.normalizeOfficialReturnOrigin = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isIdpHubOrigin = exports.buildHubSyncUrl = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -347,6 +347,7 @@ Object.defineProperty(exports, "createMemoryAuthStateStore", { enumerable: true,
 Object.defineProperty(exports, "AUTH_STATE_STORAGE_KEY", { enumerable: true, get: function () { return authStateStore_1.AUTH_STATE_STORAGE_KEY; } });
 var refresh_1 = require("./session/refresh");
 Object.defineProperty(exports, "refreshPersistedSession", { enumerable: true, get: function () { return refresh_1.refreshPersistedSession; } });
+Object.defineProperty(exports, "refreshDeviceSecretArm", { enumerable: true, get: function () { return refresh_1.refreshDeviceSecretArm; } });
 Object.defineProperty(exports, "createAuthRefreshHandler", { enumerable: true, get: function () { return refresh_1.createAuthRefreshHandler; } });
 Object.defineProperty(exports, "installAuthRefreshHandler", { enumerable: true, get: function () { return refresh_1.installAuthRefreshHandler; } });
 Object.defineProperty(exports, "startTokenRefreshScheduler", { enumerable: true, get: function () { return refresh_1.startTokenRefreshScheduler; } });

package/dist/cjs/session/SessionClient.js

@@ -84,7 +84,7 @@ class SessionClient {
         }
     }
     /** Validate + last-writer-wins by revision. Returns true if applied. */
-    applyState(raw) {
+    applyState(raw, origin = 'push') {
         const next = (0, contracts_1.safeParseContract)(contracts_1.deviceSessionStateSchema, raw);
         if (!next) {
             loggerUtils_1.logger.warn('[SessionClient] discarded invalid session state');
@@ -108,7 +108,7 @@ class SessionClient {
             this.notify();
             if (next.accounts.length === 0 && this.options.onUnauthenticated) {
                 try {
-                    this.options.onUnauthenticated();
+                    this.options.onUnauthenticated(origin);
                 }
                 catch (error) {
                     loggerUtils_1.logger.error('[SessionClient] onUnauthenticated threw', error);
@@ -154,7 +154,10 @@ class SessionClient {
             loggerUtils_1.logger.warn('[SessionClient] discarded invalid session sync', { component: 'SessionClient', issues, keys });
             return;
         }
-        this.applyState(sync.state);
+        // A `sync` is always the response to a direct REST call this client made
+        // (bootstrap / switch / signOut / add) → a `request`-origin, authoritative
+        // verdict.
+        this.applyState(sync.state, 'request');
         if (sync.activeToken && this.state && sync.state.activeAccountId === this.state.activeAccountId) {
             this.host.setTokens(sync.activeToken.accessToken);
         }
@@ -292,7 +295,9 @@ class SessionClient {
             },
         });
         socket.on('session_state', (payload) => {
-            const applied = this.applyState(payload);
+            // A socket broadcast is a `push`-origin — potentially transient, so an
+            // empty state here must not erase the durable device credential.
+            const applied = this.applyState(payload, 'push');
             if (!applied)
                 return;
             // A push changed the active account on another device/tab — re-fetch state

package/dist/cjs/session/authStateStore.js

@@ -200,7 +200,9 @@ function createMemoryAuthStateStore() {
     return {
         load: async () => current,
         save: async (state) => {
+            // Memory IS this store's durability backing — the write always lands.
             current = state;
+            return true;
         },
         clear: async () => {
             current = null;
@@ -293,6 +295,9 @@ function createWebAuthStateStore() {
             catch {
                 // Quota / private-mode / disabled storage — non-fatal warm-boot loss only.
             }
+            // Report ONLY the durable-credential landing; the warm-token outcome above
+            // is intentionally excluded (it is a best-effort optimization).
+            return durablePersisted;
         },
         clear: async () => {
             sessionMirror = null;
@@ -376,6 +381,9 @@ function createNativeAuthStateStore(storage) {
             catch {
                 // Locked / oversize keychain — non-fatal warm-boot loss only.
             }
+            // Report ONLY the durable-credential landing; the warm-token outcome above
+            // is intentionally excluded (it is a best-effort optimization).
+            return durablePersisted;
         },
         clear: async () => {
             sessionMirror = null;

package/dist/cjs/session/refresh.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOKEN_REFRESH_LEAD_MS = void 0;
+exports.refreshDeviceSecretArm = refreshDeviceSecretArm;
 exports.refreshPersistedSession = refreshPersistedSession;
 exports.createAuthRefreshHandler = createAuthRefreshHandler;
 exports.installAuthRefreshHandler = installAuthRefreshHandler;
@@ -37,64 +38,136 @@ const MIN_SCHEDULE_DELAY_MS = 1000;
  */
 const MIN_FAILURE_BACKOFF_MS = 5000;
 const MAX_FAILURE_BACKOFF_MS = 5 * 60000;
+/**
+ * Arm 1 — the rotating device-secret mint, run under the owning client's
+ * PROCESS-WIDE single-flight (`httpService.runSingleFlightDeviceSecretMint`).
+ *
+ * The server ROTATES the presented `deviceSecret` on every successful mint and
+ * the just-presented secret is valid only for a short grace window. If two lanes
+ * (cold boot, the proactive scheduler, a request-time preflight, a 401 retry,
+ * the socket token transport, or a tab-focus reconcile) minted concurrently they
+ * would double-rotate the server and the durable store could converge on the
+ * SUPERSEDED secret — after the grace window the next cold boot mint 401s and the
+ * user is signed out. Routing EVERY lane through this one single-flight makes
+ * concurrent callers await the SAME in-flight mint and all receive its result, so
+ * there is exactly one rotation and the store always converges on the true
+ * `current` secret.
+ *
+ * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
+ * the access token; a failed durable persist yields `persist-failed` WITHOUT
+ * planting. This function performs NO store mutation on failure — the caller
+ * applies the drop/clear policy (which differs web vs native) from the returned
+ * status.
+ */
+async function refreshDeviceSecretArm(deps) {
+    const { oxy, store } = deps;
+    return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
+        const persisted = await store.load();
+        if (!persisted?.deviceId || !persisted?.deviceSecret) {
+            return { status: 'no-secret' };
+        }
+        let mint;
+        try {
+            mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
+        }
+        catch (error) {
+            if ((0, errorUtils_1.extractErrorStatus)(error) === 401) {
+                // Structural read (not `instanceof Error`): the thrown value can be a
+                // plain ApiError-shaped object or come from another realm.
+                const message = error?.message;
+                return typeof message === 'string' && message.includes('no_active_session')
+                    ? { status: 'no-session' }
+                    : { status: 'invalid-secret' };
+            }
+            return { status: 'transient' };
+        }
+        const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
+        const next = {
+            ...persisted,
+            deviceId: mint.state.deviceId,
+            deviceSecret: mint.nextDeviceSecret,
+            accessToken: mint.accessToken,
+            expiresAt: mint.expiresAt,
+            ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
+        };
+        // Rotation-in-use anti-loss: persist the NEXT secret and read-back-VERIFY it
+        // landed BEFORE planting the token. A failed durable persist must NOT plant.
+        const persistedOk = await store.save(next);
+        if (!persistedOk) {
+            return { status: 'persist-failed' };
+        }
+        oxy.setTokens(mint.accessToken);
+        return { status: 'ok', token: mint.accessToken, sessionId: next.sessionId, userId: next.userId };
+    });
+}
 /**
  * Re-mint the persisted session and return the fresh access token, or `null`
  * when no arm could produce one.
  *
- * Arm 1 (`POST /session/device/token`): if the store holds a `deviceId` +
- * `deviceSecret`, mint — on success plant + persist the rotated secret. A 401
- * means the secret is diverged (`invalid_device_secret`) or the device has no
- * live session (`no_active_session`): drop the secret so the mint lane stops (or
- * clear the store on web, where there is no fallback). A transient error leaves
- * the store and returns `null`.
+ * Arm 1 (`POST /session/device/token`, via {@link refreshDeviceSecretArm}): mint
+ * from the persisted `deviceId` + `deviceSecret`. On a 401 the secret is diverged
+ * or the device has no live session: drop the secret so the mint lane stops (or
+ * clear the store on web, where there is no fallback), then fall to arm 2 on
+ * native. A transient error — or a durable-persist failure — leaves the store and
+ * returns `null` WITHOUT falling to shared-key (those are not bad-secret signals).
  *
  * Arm 2 (native shared-keychain): when the secret is absent or was just rejected,
- * re-mint via `signInWithSharedIdentity` (which plants tokens). The shared
- * keychain — not the per-origin store — is the durable native credential, so this
- * arm does not write the store.
+ * re-mint via `signInWithSharedIdentity` (which plants tokens). On success the
+ * recovered `{deviceId, deviceSecret, …}` is PERSISTED so the fast device-secret
+ * lane is repopulated (mirrors the cold boot's `shared-key-signin` step) — an
+ * in-session shared-key recovery must not leave the fast-lane credential empty.
  */
 async function refreshPersistedSession(deps) {
     const { oxy, store } = deps;
     const allowSharedKeyFallback = deps.allowSharedKeyFallback ?? (0, platform_1.isNative)();
-    const persisted = await store.load();
-    if (persisted?.deviceId && persisted?.deviceSecret) {
-        try {
-            const mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
-            oxy.setTokens(mint.accessToken);
-            const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
-            const next = {
-                ...persisted,
-                deviceId: mint.state.deviceId,
-                deviceSecret: mint.nextDeviceSecret,
-                accessToken: mint.accessToken,
-                expiresAt: mint.expiresAt,
-                ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
-            };
-            await store.save(next);
-            return mint.accessToken;
-        }
-        catch (error) {
-            if ((0, errorUtils_1.extractErrorStatus)(error) === 401) {
-                // Secret diverged / no active session. On a shared-key device drop only
-                // the secret so arm 2 below can recover; otherwise the session is over.
-                if (allowSharedKeyFallback) {
+    const arm1 = await refreshDeviceSecretArm({ oxy, store });
+    switch (arm1.status) {
+        case 'ok':
+            return arm1.token;
+        case 'transient':
+            loggerUtils_1.logger.debug('Persisted deviceSecret mint failed (transient) — keeping store', { component: 'refresh', method: 'refreshPersistedSession' });
+            return null;
+        case 'persist-failed':
+            // The server rotated the secret but it did not durably persist. Do NOT fall
+            // to shared-key and do NOT plant — a later attempt re-mints (the process
+            // mirror still holds the rotated secret the server accepts) and can persist
+            // once storage recovers. Never advertise a session on an unsaved secret.
+            loggerUtils_1.logger.error('Device-secret mint rotated the secret but it could not be durably persisted — refusing to plant (a later attempt re-mints)', undefined, { component: 'refresh', method: 'refreshPersistedSession' });
+            return null;
+        case 'invalid-secret':
+        case 'no-session': {
+            // 401: secret diverged or no live session. On a shared-key device drop only
+            // the secret (keep the identity so arm 2 can recover); otherwise (web) the
+            // session is over — clear the store.
+            const persisted = await store.load();
+            if (allowSharedKeyFallback) {
+                if (persisted) {
                     await store.save({ ...persisted, deviceSecret: undefined });
                 }
-                else {
-                    await store.clear();
-                }
-                // Fall through to the native shared-key arm.
             }
             else {
-                loggerUtils_1.logger.debug('Persisted deviceSecret mint failed (transient) — keeping store', { component: 'refresh', method: 'refreshPersistedSession' }, error);
-                return null;
+                await store.clear();
             }
+            break;
         }
+        case 'no-secret':
+            break;
     }
     if (allowSharedKeyFallback) {
         try {
             const session = await oxy.signInWithSharedIdentity();
             if (session?.accessToken) {
+                // Repopulate the fast device-secret lane from the shared-key re-mint.
+                if (session.deviceId && session.deviceSecret) {
+                    await store.save({
+                        sessionId: session.sessionId,
+                        userId: session.user.id,
+                        deviceId: session.deviceId,
+                        deviceSecret: session.deviceSecret,
+                        accessToken: session.accessToken,
+                        expiresAt: session.expiresAt,
+                    });
+                }
                 return session.accessToken;
             }
         }