@oxyhq/core 9.2.1 → 9.2.3

package/dist/esm/session/authStateStore.js

@@ -16,12 +16,34 @@
  *
  * ESM-safe (no `require()`).
  */
+import { logger } from '../utils/loggerUtils.js';
 /**
- * Versioned storage key. The `.v1` suffix lets a future shape change ship a
- * `.v2` key without reading a stale/incompatible `.v1` blob. Distinct from the
- * `oxy_shared_*` keychain keys in `KeyManager`, so it never collides.
+ * Versioned DURABLE storage key. Holds ONLY the small, re-mint-critical fields
+ * (`sessionId`, `userId`, `deviceId`, `deviceSecret`) — never the large JWT
+ * `accessToken`. Keeping this blob small (<2KB) matters on Android
+ * `expo-secure-store`, whose backing store can silently fail to persist an
+ * oversize value; bundling the token here previously took the mint credential
+ * down with it on every write, losing the session on cold restart.
+ *
+ * The `.v1` suffix lets a future shape change ship a `.v2` key without reading a
+ * stale/incompatible `.v1` blob. Distinct from the `oxy_shared_*` keychain keys
+ * in `KeyManager`, so it never collides.
+ *
+ * BACK-COMPAT: pre-split builds wrote the WHOLE state (including `accessToken` /
+ * `expiresAt`) into this single key. `load()` still reads those token fields
+ * from here when the warm key ({@link AUTH_STATE_TOKEN_STORAGE_KEY}) is absent,
+ * so upgrading users are not signed out; the next `save()` splits them apart.
  */
 export const AUTH_STATE_STORAGE_KEY = 'oxy.auth.v1';
+/**
+ * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
+ * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a
+ * failure (quota / oversize keychain value) is swallowed because the session is
+ * fully re-mintable from the durable `deviceSecret`. Kept separate from
+ * {@link AUTH_STATE_STORAGE_KEY} so a failed token write can NEVER abort or
+ * corrupt the durable credential write.
+ */
+export const AUTH_STATE_TOKEN_STORAGE_KEY = 'oxy.auth.token.v1';
 /**
  * Parse + shape-validate a stored blob. Returns `null` for anything that is
  * not a well-formed {@link PersistedAuthState} (absent, malformed JSON, wrong
@@ -72,6 +94,95 @@ function deserialize(raw) {
     }
     return state;
 }
+/**
+ * Parse the best-effort warm-token blob. Returns `null` for anything not a
+ * well-formed object so a corrupt warm entry simply forgoes the warm-boot
+ * optimization (the durable credential re-mints a fresh token).
+ */
+function parseWarmToken(raw) {
+    if (!raw) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return null;
+    }
+    const candidate = parsed;
+    const warm = {};
+    if (typeof candidate.accessToken === 'string' && candidate.accessToken.length > 0) {
+        warm.accessToken = candidate.accessToken;
+    }
+    if (typeof candidate.expiresAt === 'string' && candidate.expiresAt.length > 0) {
+        warm.expiresAt = candidate.expiresAt;
+    }
+    return warm;
+}
+/** Serialize ONLY the small, re-mint-critical fields for the durable key. */
+function serializeDurable(state) {
+    const durable = {
+        sessionId: state.sessionId,
+        userId: state.userId,
+    };
+    if (state.deviceId) {
+        durable.deviceId = state.deviceId;
+    }
+    if (state.deviceSecret) {
+        durable.deviceSecret = state.deviceSecret;
+    }
+    return JSON.stringify(durable);
+}
+/**
+ * Serialize the warm-token blob, or `null` when there is no token to persist
+ * (so the caller clears the warm key rather than writing an empty object).
+ */
+function serializeWarmToken(state) {
+    const warm = {};
+    if (state.accessToken) {
+        warm.accessToken = state.accessToken;
+    }
+    if (state.expiresAt) {
+        warm.expiresAt = state.expiresAt;
+    }
+    if (!warm.accessToken && !warm.expiresAt) {
+        return null;
+    }
+    return JSON.stringify(warm);
+}
+/**
+ * Compose the unchanged {@link PersistedAuthState} return shape from the two
+ * on-disk keys. `accessToken` / `expiresAt` come from the warm key when it is
+ * present; when the warm key is ABSENT the token fields fall back to whatever
+ * the durable blob carried — the pre-split combined `oxy.auth.v1` blob (BACK-COMPAT).
+ */
+function composeState(durableRaw, warmRaw) {
+    const state = deserialize(durableRaw);
+    if (!state) {
+        return null;
+    }
+    if (warmRaw !== null) {
+        // New split layout: the warm key is authoritative for the token fields.
+        // Drop anything the durable blob may have carried, then overlay the warm
+        // values (a warm key with no token → the session simply has no warm token).
+        delete state.accessToken;
+        delete state.expiresAt;
+        const warm = parseWarmToken(warmRaw);
+        if (warm?.accessToken) {
+            state.accessToken = warm.accessToken;
+        }
+        if (warm?.expiresAt) {
+            state.expiresAt = warm.expiresAt;
+        }
+    }
+    // else: BACK-COMPAT — the warm key is absent, so `deserialize` already applied
+    // any `accessToken` / `expiresAt` from the old combined blob.
+    return state;
+}
 /**
  * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
  * tests/SSR and as the degraded fallback of the web store when `localStorage`
@@ -83,7 +194,9 @@ export 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;
@@ -109,8 +222,9 @@ function safeGetLocalStorage() {
     }
 }
 /**
- * A `localStorage`-backed {@link AuthStateStore} under the versioned
- * {@link AUTH_STATE_STORAGE_KEY}.
+ * A `localStorage`-backed {@link AuthStateStore} split across the durable
+ * {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the best-effort
+ * {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token).
  *
  * Resilience:
  *  - If `localStorage` is unreachable (sandboxed-iframe `SecurityError`, SSR),
@@ -137,7 +251,7 @@ export function createWebAuthStateStore() {
                 return sessionMirror;
             }
             try {
-                return deserialize(storage.getItem(AUTH_STATE_STORAGE_KEY));
+                return composeState(storage.getItem(AUTH_STATE_STORAGE_KEY), storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY));
             }
             catch {
                 return null;
@@ -145,13 +259,39 @@ export function createWebAuthStateStore() {
         },
         save: async (state) => {
             sessionMirror = state; // mirror FIRST — authoritative even if persist fails
+            // Durable credential FIRST, then VERIFY it landed. The in-memory mirror
+            // keeps the session live for this page, but a failed DURABLE write means
+            // the mint credential will NOT survive a reload — surface it, never swallow.
+            let durablePersisted = false;
+            try {
+                const durableJson = serializeDurable(state);
+                storage.setItem(AUTH_STATE_STORAGE_KEY, durableJson);
+                durablePersisted = storage.getItem(AUTH_STATE_STORAGE_KEY) === durableJson;
+                if (!durablePersisted) {
+                    logger.error('[authStateStore] durable credential read-back mismatch after save — the device credential did not persist; the session survives this process via the in-memory mirror but will be lost on reload', undefined, { component: 'authStateStore' });
+                }
+            }
+            catch (error) {
+                logger.error('[authStateStore] durable credential persist threw — the device credential did not persist; the session survives this process via the in-memory mirror but will be lost on reload', error, { component: 'authStateStore' });
+            }
+            // Warm token AFTER, best-effort. Its failure is genuinely non-fatal (the
+            // durable credential re-mints a fresh token) and must never abort or
+            // corrupt the durable write above.
             try {
-                storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+                const warmJson = serializeWarmToken(state);
+                if (warmJson) {
+                    storage.setItem(AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+                }
+                else {
+                    storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+                }
             }
             catch {
-                // Quota / private-mode / disabled storage — non-fatal. The session
-                // stays live via the in-memory mirror; only reload durability is lost.
+                // 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;
@@ -161,6 +301,12 @@ export function createWebAuthStateStore() {
             catch {
                 // Non-fatal — see save().
             }
+            try {
+                storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal — see save().
+            }
         },
     };
 }
@@ -168,9 +314,12 @@ export function createWebAuthStateStore() {
  * A native {@link AuthStateStore} over an injected async key/value store.
  *
  * `@oxyhq/core` never imports `expo-secure-store`; `@oxyhq/services` constructs
- * the SecureStore-backed adapter and passes it here. Every operation is wrapped
- * so a storage exception degrades gracefully (read → `null`, write → swallowed)
- * exactly like the web store.
+ * the SecureStore-backed adapter and passes it here. Persistence is split across
+ * the durable {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the
+ * best-effort {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token) — the
+ * durable write is read-back-verified and its failure surfaced (not swallowed),
+ * while the warm-token write and all reads degrade gracefully exactly like the
+ * web store.
  */
 export function createNativeAuthStateStore(storage) {
     // Same in-memory mirror as the web store — a locked/failed SecureStore write
@@ -182,7 +331,11 @@ export function createNativeAuthStateStore(storage) {
                 return sessionMirror;
             }
             try {
-                return deserialize(await storage.getItem(AUTH_STATE_STORAGE_KEY));
+                const [durableRaw, warmRaw] = await Promise.all([
+                    storage.getItem(AUTH_STATE_STORAGE_KEY),
+                    storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY),
+                ]);
+                return composeState(durableRaw, warmRaw);
             }
             catch {
                 return null;
@@ -190,12 +343,41 @@ export function createNativeAuthStateStore(storage) {
         },
         save: async (state) => {
             sessionMirror = state;
+            // Durable credential FIRST, then VERIFY. On Android SecureStore an
+            // oversize/failed write can resolve WITHOUT throwing, so a read-back is the
+            // only reliable proof. The mirror keeps the session live for this app run,
+            // but a failed DURABLE write means the mint credential will NOT survive a
+            // cold restart — surface it, never swallow.
+            let durablePersisted = false;
             try {
-                await storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+                const durableJson = serializeDurable(state);
+                await storage.setItem(AUTH_STATE_STORAGE_KEY, durableJson);
+                durablePersisted = (await storage.getItem(AUTH_STATE_STORAGE_KEY)) === durableJson;
+                if (!durablePersisted) {
+                    logger.error('[authStateStore] durable credential read-back mismatch after save — the device credential did not persist (likely oversize SecureStore value); the session survives this app run via the in-memory mirror but will be lost on cold restart', undefined, { component: 'authStateStore' });
+                }
+            }
+            catch (error) {
+                logger.error('[authStateStore] durable credential persist threw — the device credential did not persist; the session survives this app run via the in-memory mirror but will be lost on cold restart', error, { component: 'authStateStore' });
+            }
+            // Warm token AFTER, best-effort. Its failure is genuinely non-fatal (the
+            // durable credential re-mints a fresh token) and must never abort or
+            // corrupt the durable write above.
+            try {
+                const warmJson = serializeWarmToken(state);
+                if (warmJson) {
+                    await storage.setItem(AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+                }
+                else {
+                    await storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+                }
             }
             catch {
-                // Non-fatal — session stays live via the in-memory mirror.
+                // 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;
@@ -205,6 +387,12 @@ export function createNativeAuthStateStore(storage) {
             catch {
                 // Non-fatal.
             }
+            try {
+                await storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal.
+            }
         },
     };
 }

package/dist/esm/session/refresh.js

@@ -30,64 +30,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.
+ */
+export 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 (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.
  */
 export async function refreshPersistedSession(deps) {
     const { oxy, store } = deps;
     const allowSharedKeyFallback = deps.allowSharedKeyFallback ?? 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 (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':
+            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.
+            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 {
-                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;
             }
         }