@oxyhq/core 9.2.1 → 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/mixins/OxyServices.utility.js

@@ -9,8 +9,8 @@ exports.OxyServicesUtilityMixin = OxyServicesUtilityMixin;
  */
 const jwt_decode_1 = require("jwt-decode");
 const protocol_1 = require("@oxyhq/protocol");
+const apiUtils_1 = require("../utils/apiUtils");
 const loggerUtils_1 = require("../utils/loggerUtils");
-const mixinHelpers_1 = require("./mixinHelpers");
 /**
  * Expected JWT audience for tokens issued by the Oxy auth service.
  */
@@ -111,10 +111,14 @@ function OxyServicesUtilityMixin(Base) {
          */
         async fetchLinkMetadata(url) {
             try {
-                return await this.makeRequest('GET', '/link-metadata', { url }, {
-                    cache: true,
-                    cacheTTL: mixinHelpers_1.CACHE_TIMES.EXTRA_LONG,
-                });
+                const path = (0, apiUtils_1.buildUrl)('/links/preview', { url, wait: 1 });
+                const preview = await this.makeRequest('GET', path, undefined, { cache: false });
+                return {
+                    url: preview.url,
+                    title: preview.title?.trim() || preview.url.replace(/^https?:\/\//, '').replace(/\/$/, ''),
+                    description: preview.description?.trim() || 'Link',
+                    image: preview.image,
+                };
             }
             catch (error) {
                 throw this.handleError(error);

package/dist/cjs/session/SessionClient.js

@@ -24,6 +24,10 @@ class SessionClient {
         this.started = false;
         /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
         this.channel = null;
+        /** App-facing subscriptions to named server-pushed socket events. */
+        this.serverEvents = new Map();
+        /** Event names already bound on the CURRENT socket instance. */
+        this.boundServerEvents = new Set();
     }
     getState() {
         return this.state;
@@ -34,6 +38,41 @@ class SessionClient {
             this.listeners.delete(listener);
         };
     }
+    /**
+     * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
+     * Listeners survive reconnects and socket re-creation; the returned function
+     * unsubscribes. Payloads are delivered as-is — callers validate shape.
+     */
+    onServerEvent(event, listener) {
+        let listeners = this.serverEvents.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.serverEvents.set(event, listeners);
+        }
+        listeners.add(listener);
+        this.bindServerEvent(event);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    bindServerEvent(event) {
+        if (!this.socket || this.boundServerEvents.has(event))
+            return;
+        this.boundServerEvents.add(event);
+        this.socket.on(event, (payload) => {
+            const listeners = this.serverEvents.get(event);
+            if (!listeners)
+                return;
+            for (const listener of [...listeners]) {
+                try {
+                    listener(payload);
+                }
+                catch (error) {
+                    loggerUtils_1.logger.warn('[SessionClient] server-event listener threw', { component: 'SessionClient' }, error);
+                }
+            }
+        });
+    }
     notify() {
         for (const listener of this.listeners) {
             try {
@@ -45,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');
@@ -69,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);
@@ -115,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);
         }
@@ -213,6 +255,7 @@ class SessionClient {
         if (this.socket) {
             this.socket.disconnect();
             this.socket = null;
+            this.boundServerEvents.clear();
         }
     }
     async connectSocket() {
@@ -252,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
@@ -267,6 +312,11 @@ class SessionClient {
             }
         });
         this.socket = socket;
+        // (Re)bind app-facing server-event subscriptions on the fresh socket.
+        this.boundServerEvents.clear();
+        for (const event of this.serverEvents.keys()) {
+            this.bindServerEvent(event);
+        }
     }
     /**
      * Open the same-origin `BroadcastChannel` (web only). A sibling tab that

package/dist/cjs/session/accountDialogController.js

@@ -34,6 +34,12 @@ const authWebUrl_1 = require("../utils/authWebUrl");
 const oauthPkce_1 = require("../utils/oauthPkce");
 const accountProjection_1 = require("./accountProjection");
 const DEFAULT_POLL_INTERVAL_MS = 3000;
+/**
+ * Commons's custom URL scheme. Probed via the injected `canOpenApp` to detect an
+ * installed Commons on the same device; the `oxycommons://approve?...` deep link
+ * itself is the flow's `qrPayload`.
+ */
+const COMMONS_APP_SCHEME = 'oxycommons://';
 const IDLE_SIGN_IN = {
     phase: 'idle',
     authorizeCode: null,
@@ -76,6 +82,7 @@ class AccountDialogController {
         this.authRedirectUri = options.authRedirectUri ?? null;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.openUrl = options.openUrl;
+        this.canOpenApp = options.canOpenApp;
         this.snapshot = this.computeSnapshot();
     }
     // =========================================================================
@@ -400,11 +407,34 @@ class AccountDialogController {
                 error: null,
             });
             this.scheduleNextPoll(handle.sessionToken);
+            // Same-device convenience: if Commons is installed (native only — `canOpenApp`
+            // is undefined/false on web), deep-link straight into its approve screen with
+            // the same `oxycommons://approve?...` payload the QR encodes. The QR + polling
+            // stay live as the fallback, so a user who dismisses the app-open still
+            // completes the sign-in by scanning.
+            void this.maybeOpenCommons(handle.qrPayload);
         }
         catch (error) {
             this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: errorMessage(error) });
         }
     }
+    /**
+     * When a `canOpenApp` probe is injected and reports Commons installed, open the
+     * approve deep link via the injected `openUrl`. Best-effort and non-blocking: a
+     * probe/open failure is logged and swallowed — the QR/polling fallback remains.
+     */
+    async maybeOpenCommons(qrPayload) {
+        if (!this.canOpenApp || !this.openUrl)
+            return;
+        try {
+            if (await this.canOpenApp(COMMONS_APP_SCHEME)) {
+                this.openUrl(qrPayload);
+            }
+        }
+        catch (error) {
+            loggerUtils_1.logger.debug('[AccountDialogController] Commons deep-link probe failed (QR fallback active)', { component: 'AccountDialogController' }, error);
+        }
+    }
     /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
     cancelSignIn() {
         this.clearPollTimer();