@oxyhq/core 9.2.1 → 9.2.3

package/dist/esm/HttpService.js

@@ -132,6 +132,7 @@ export 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
@@ -834,6 +835,32 @@ export 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/esm/boot/sessionColdBoot.js

@@ -7,31 +7,23 @@
  * 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.
  */
 import { runColdBoot } from '../utils/coldBoot.js';
 import { isNative as detectNative } from '../utils/platform.js';
-import { extractErrorStatus } from '../utils/errorUtils.js';
 import { logger } from '../utils/loggerUtils.js';
-function classifyMintFailure(error) {
-    if (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';
-}
+import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh.js';
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
  * a side effect, invokes `onSession` (winning session, token already planted) or
@@ -44,60 +36,98 @@ export 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() + 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 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.
-                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.
+                    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.
+                    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/esm/crypto/keyManager.js

@@ -7,7 +7,7 @@
 import _cjs_elliptic from 'elliptic';
 const { ec: EC } = _cjs_elliptic;
 import { isWeb, isIOS, isAndroid } from '../utils/platform.js';
-import { isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore } from '@oxyhq/protocol';
+import { isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
 import { logger } from '../utils/loggerUtils.js';
 import { isDev } from '../shared/utils/debugUtils.js';
 /**
@@ -230,12 +230,21 @@ export class KeyManager {
             }
         }
         else if (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 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;
@@ -266,7 +275,15 @@ export class KeyManager {
                 publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
             }
             else if (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 loadSharedIdentityBridge();
+                if (bridge) {
+                    publicKey = (await bridge.getShared())?.publicKey ?? null;
+                }
+                else {
+                    publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
+                }
             }
             // Cache result
             KeyManager.cachedSharedPublicKey = publicKey;
@@ -300,7 +317,15 @@ export class KeyManager {
                 privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
             }
             else if (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 loadSharedIdentityBridge();
+                if (bridge) {
+                    privateKey = (await bridge.getShared())?.privateKey ?? null;
+                }
+                else {
+                    privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+                }
             }
             return privateKey;
         }
@@ -373,10 +398,18 @@ export class KeyManager {
             await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
         }
         else if (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 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/esm/index.js

@@ -166,7 +166,7 @@ export { AccountDialogController, createAccountDialogController, } from './sessi
 // via `POST /session/device/token`.
 // ---------------------------------------------------------------------------
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore.js';
-export { refreshPersistedSession, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh.js';
+export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh.js';
 export { runSessionColdBoot } from './boot/sessionColdBoot.js';
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every

package/dist/esm/mixins/OxyServices.utility.js

@@ -6,8 +6,8 @@
  */
 import { jwtDecode } from 'jwt-decode';
 import { loadNodeCrypto } from '@oxyhq/protocol';
+import { buildUrl } from '../utils/apiUtils.js';
 import { logger } from '../utils/loggerUtils.js';
-import { CACHE_TIMES } from './mixinHelpers.js';
 /**
  * Expected JWT audience for tokens issued by the Oxy auth service.
  */
@@ -108,10 +108,14 @@ export function OxyServicesUtilityMixin(Base) {
          */
         async fetchLinkMetadata(url) {
             try {
-                return await this.makeRequest('GET', '/link-metadata', { url }, {
-                    cache: true,
-                    cacheTTL: CACHE_TIMES.EXTRA_LONG,
-                });
+                const path = 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/esm/session/SessionClient.js

@@ -21,6 +21,10 @@ export 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;
@@ -31,6 +35,41 @@ export 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) {
+                    logger.warn('[SessionClient] server-event listener threw', { component: 'SessionClient' }, error);
+                }
+            }
+        });
+    }
     notify() {
         for (const listener of this.listeners) {
             try {
@@ -42,7 +81,7 @@ export class SessionClient {
         }
     }
     /** Validate + last-writer-wins by revision. Returns true if applied. */
-    applyState(raw) {
+    applyState(raw, origin = 'push') {
         const next = safeParseContract(deviceSessionStateSchema, raw);
         if (!next) {
             logger.warn('[SessionClient] discarded invalid session state');
@@ -66,7 +105,7 @@ export class SessionClient {
             this.notify();
             if (next.accounts.length === 0 && this.options.onUnauthenticated) {
                 try {
-                    this.options.onUnauthenticated();
+                    this.options.onUnauthenticated(origin);
                 }
                 catch (error) {
                     logger.error('[SessionClient] onUnauthenticated threw', error);
@@ -112,7 +151,10 @@ export class SessionClient {
             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);
         }
@@ -210,6 +252,7 @@ export class SessionClient {
         if (this.socket) {
             this.socket.disconnect();
             this.socket = null;
+            this.boundServerEvents.clear();
         }
     }
     async connectSocket() {
@@ -249,7 +292,9 @@ export 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
@@ -264,6 +309,11 @@ export 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/esm/session/accountDialogController.js

@@ -30,6 +30,12 @@ import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
 import { generateOAuthState, generatePkcePair, normalizeOAuthRedirectUri, persistOAuthHandshake, } from '../utils/oauthPkce.js';
 import { projectSwitchableAccounts, switchableAccountIds, } from './accountProjection.js';
 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,
@@ -72,6 +78,7 @@ export 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();
     }
     // =========================================================================
@@ -396,11 +403,34 @@ export 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) {
+            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();