@oxy.so/core 4.1.0 → 4.2.0

package/dist/esm/session/authStateStore.js

@@ -17,6 +17,13 @@
  * ESM-safe (no `require()`).
  */
 import { logger } from '../logger/index.js';
+export function matchesAuthState(actual, expected) {
+    if (!actual || !expected)
+        return actual === expected;
+    return actual.deviceId === expected.deviceId && actual.deviceSecret === expected.deviceSecret &&
+        actual.sessionId === expected.sessionId && actual.userId === expected.userId &&
+        actual.accessToken === expected.accessToken && actual.expiresAt === expected.expiresAt;
+}
 /**
  * Versioned DURABLE storage key. Holds ONLY the small, re-mint-critical fields
  * (`sessionId`, `userId`, `deviceId`, `deviceSecret`) — never the large JWT
@@ -35,6 +42,7 @@ import { logger } from '../logger/index.js';
  * so upgrading users are not signed out; the next `save()` splits them apart.
  */
 export const AUTH_STATE_STORAGE_KEY = 'oxy.auth.v1';
+export const AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY = 'oxy.auth.automatic-identity-signin-suppressed.v1';
 /**
  * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
  * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a
@@ -198,6 +206,12 @@ export function createMemoryAuthStateStore() {
             current = state;
             return true;
         },
+        saveIfCurrent: async (state, guard) => {
+            if (!guard.isCurrent() || !matchesAuthState(current, guard.expectedState))
+                return false;
+            current = state;
+            return true;
+        },
         clear: async () => {
             current = null;
         },
@@ -325,8 +339,110 @@ export function createNativeAuthStateStore(storage) {
     // Same in-memory mirror as the web store — a locked/failed SecureStore write
     // must not silently lose the session for the app's lifetime.
     let sessionMirror;
+    let suppressedMirror;
+    let pending = Promise.resolve();
+    const serialize = (operation) => {
+        const result = pending.then(operation);
+        pending = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const readCurrent = async () => {
+        if (sessionMirror !== undefined)
+            return sessionMirror;
+        const [durable, warm] = await Promise.all([
+            storage.getItem(AUTH_STATE_STORAGE_KEY), storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY),
+        ]);
+        return composeState(durable, warm);
+    };
+    const persistState = 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 {
+            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 {
+            // 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;
+    };
     return {
-        load: async () => {
+        isAutomaticIdentitySignInSuppressed: () => serialize(async () => {
+            if (suppressedMirror !== undefined)
+                return suppressedMirror;
+            try {
+                return (await storage.getItem(AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY)) !== null;
+            }
+            catch {
+                return true; // Unknown storage must not start a new key sign-in.
+            }
+        }),
+        setAutomaticIdentitySignInSuppressed: (suppressed, guard) => serialize(async () => {
+            if (guard) {
+                let current = sessionMirror;
+                if (current === undefined) {
+                    try {
+                        const [durable, warm] = await Promise.all([
+                            storage.getItem(AUTH_STATE_STORAGE_KEY), storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY),
+                        ]);
+                        current = composeState(durable, warm);
+                    }
+                    catch {
+                        suppressedMirror = true;
+                        return false;
+                    }
+                }
+                const expected = guard.expectedState;
+                if (!guard.isCurrent() || !current ||
+                    current.deviceId !== expected.deviceId || current.deviceSecret !== expected.deviceSecret ||
+                    current.sessionId !== expected.sessionId || current.userId !== expected.userId ||
+                    current.accessToken !== expected.accessToken || current.expiresAt !== expected.expiresAt)
+                    return false;
+            }
+            suppressedMirror = suppressed;
+            try {
+                if (suppressed)
+                    await storage.setItem(AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY, '1');
+                else
+                    await storage.removeItem(AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY);
+                const actual = await storage.getItem(AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY);
+                const verified = suppressed ? actual === '1' : actual === null;
+                if (!verified)
+                    suppressedMirror = true;
+                return verified;
+            }
+            catch {
+                suppressedMirror = true;
+                return false;
+            }
+        }),
+        load: () => serialize(async () => {
             if (sessionMirror !== undefined) {
                 return sessionMirror;
             }
@@ -340,46 +456,20 @@ export function createNativeAuthStateStore(storage) {
             catch {
                 return null;
             }
-        },
-        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;
+        }),
+        save: (state) => serialize(() => persistState(state)),
+        saveIfCurrent: (state, guard) => serialize(async () => {
             try {
-                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);
-                }
+                const current = await readCurrent();
+                if (!guard.isCurrent() || !matchesAuthState(current, guard.expectedState))
+                    return false;
             }
             catch {
-                // Locked / oversize keychain — non-fatal warm-boot loss only.
+                return false;
             }
-            // Report ONLY the durable-credential landing; the warm-token outcome above
-            // is intentionally excluded (it is a best-effort optimization).
-            return durablePersisted;
-        },
-        clear: async () => {
+            return persistState(state);
+        }),
+        clear: () => serialize(async () => {
             sessionMirror = null;
             try {
                 await storage.removeItem(AUTH_STATE_STORAGE_KEY);
@@ -393,6 +483,6 @@ export function createNativeAuthStateStore(storage) {
             catch {
                 // Non-fatal.
             }
-        },
+        }),
     };
 }

package/dist/esm/session/refresh.js

@@ -1,3 +1,4 @@
+import { matchesAuthState } from './authStateStore.js';
 import { establishIdentitySession, resolveIdentityPin } from './identitySession.js';
 import { isNative } from '../utils/platform.js';
 import { extractErrorStatus } from '../utils/errorUtils.js';
@@ -57,9 +58,13 @@ export const REMINT_AFTER_EXPIRY_MS = 2000;
  *
  * 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
+ * planting. Apart from the account-mode logout marker below, failure mutations
+ * belong to the caller, which
  * applies the drop/clear policy (which differs web vs native) from the returned
- * status.
+ * status. A native account store with a suppression marker records a current
+ * `no_active_session`, or an invalid secret with prior authenticated session
+ * history, records durable ACCOUNT logout intent; it never deletes that holder.
+ * Error classification uses the existing 401 message markers.
  *
  * `pin` makes the mint IDENTITY-BOUND: the request carries the pinned
  * `accountId` (so the server mints that account's token without touching
@@ -70,7 +75,10 @@ export const REMINT_AFTER_EXPIRY_MS = 2000;
 export async function refreshDeviceSecretArm(deps) {
     const { oxy, store } = deps;
     const pin = deps.pin ?? null;
+    const isCurrent = deps.isCurrent ?? (() => true);
     return oxy.http.runSingleFlightDeviceSecretMint(async () => {
+        if (!isCurrent())
+            return { status: 'session-ended' };
         const epoch = oxy.http.getSessionEpoch();
         const persisted = await store.load();
         if (!persisted?.deviceId || !persisted?.deviceSecret) {
@@ -112,10 +120,29 @@ export async function refreshDeviceSecretArm(deps) {
                 // transient and KEEP the credential so a later attempt self-heals. Wiping the
                 // credential on an ambiguous 401 is what logged users out on every deploy,
                 // ecosystem-wide.
-                if (body.includes('invalid_device_secret'))
-                    return { status: 'invalid-secret' };
-                if (body.includes('no_active_session'))
-                    return { status: 'no-session' };
+                const invalidSecret = body.includes('invalid_device_secret');
+                const noSession = body.includes('no_active_session');
+                if (invalidSecret || noSession) {
+                    // A stopped ACCOUNT sibling cannot receive the other app's logout
+                    // push. Its exact live holder's authoritative empty-device rejection
+                    // must suppress automatic key recovery on this and future boots.
+                    // A late rejection for a replaced session/local epoch is not current.
+                    if (pin === null && store.setAutomaticIdentitySignInSuppressed && (!invalidSecret || (persisted.sessionId && persisted.userId))) {
+                        const current = await store.load();
+                        if (!isCurrent() || oxy.http.getSessionEpoch() !== epoch ||
+                            current?.deviceId !== persisted.deviceId ||
+                            current.deviceSecret !== persisted.deviceSecret ||
+                            current.sessionId !== persisted.sessionId ||
+                            current.userId !== persisted.userId ||
+                            current.accessToken !== persisted.accessToken)
+                            return { status: 'session-ended' };
+                        if (!(await store.setAutomaticIdentitySignInSuppressed(true, {
+                            expectedState: persisted, isCurrent: () => isCurrent() && oxy.http.getSessionEpoch() === epoch,
+                        })))
+                            return { status: 'session-ended' };
+                    }
+                    return { status: invalidSecret ? 'invalid-secret' : 'no-session' };
+                }
                 // A pinned mint whose account left the device set. The secret is intact —
                 // never classify this as a bad secret, or the caller would drop a healthy
                 // credential over a stale identity binding.
@@ -137,24 +164,33 @@ export async function refreshDeviceSecretArm(deps) {
             expiresAt: mint.expiresAt,
             ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
         };
+        if (!isCurrent())
+            return { status: 'session-ended' };
         if (oxy.http.getSessionEpoch() !== epoch) {
-            // Signed out while minting. A store that still holds the presented
-            // secret takes the server's `nextDeviceSecret` (the token-null lane keeps
-            // the store so a reload can restore); a store the sign-out cleared must
-            // NOT be refilled. Either way, plant nothing.
+            // A logout or account/session switch invalidated this mint. Preserve
+            // only credential rotation for an otherwise unchanged retained context;
+            // never transplant the old mint's account, session or bearer. Compare
+            // the entire snapshot inside the store queue: same holder bytes alone
+            // cannot distinguish an account switch, nor a queued save of that switch.
+            const retainedEpoch = oxy.http.getSessionEpoch();
             const current = await store.load();
-            if (current?.deviceId === persisted.deviceId && current.deviceSecret === persisted.deviceSecret) {
-                await store.save(next);
+            if (store.saveIfCurrent && current && matchesAuthState(current, persisted)) {
+                await store.saveIfCurrent({ ...current, deviceSecret: mint.nextDeviceSecret }, {
+                    expectedState: current,
+                    isCurrent: () => isCurrent() && oxy.http.getSessionEpoch() === retainedEpoch,
+                });
             }
             return { status: 'session-ended' };
         }
         // Persist nextDeviceSecret (read-back-verified) BEFORE planting the token.
         // A failed durable persist must NOT plant.
-        const persistedOk = await store.save(next);
+        const persistedOk = store.saveIfCurrent
+            ? await store.saveIfCurrent(next, { expectedState: persisted, isCurrent: () => isCurrent() && oxy.http.getSessionEpoch() === epoch })
+            : await store.save(next);
         if (!persistedOk) {
             return { status: 'persist-failed' };
         }
-        if (oxy.http.getSessionEpoch() !== epoch) {
+        if (!isCurrent() || oxy.http.getSessionEpoch() !== epoch) {
             return { status: 'session-ended' };
         }
         oxy.session.setAccessToken(mint.accessToken);
@@ -167,15 +203,76 @@ export async function refreshDeviceSecretArm(deps) {
         };
     });
 }
+/**
+ * Prove a shared native ACCOUNT holder before replacing local bytes. Callers
+ * may replace a local credential only after its explicit mint rejection. The
+ * optional guarded storage seam makes custom stores fail closed on adoption.
+ * This lane never clears explicit sign-out intent or uses an identity key.
+ */
+export async function refreshSharedDeviceArm(deps) {
+    const { oxy, store, shared } = deps;
+    const isCurrent = deps.isCurrent ?? (() => true);
+    return oxy.http.runSingleFlightDeviceSecretMint(async () => {
+        const epoch = oxy.http.getSessionEpoch();
+        if (!isCurrent())
+            return { status: 'session-ended' };
+        const before = await store.load();
+        if (before?.deviceId && before.deviceSecret && !deps.rejectedLocalHolder)
+            return { status: 'no-secret' };
+        const read = await shared.read();
+        if (read.state !== 'present' || !store.saveIfCurrent)
+            return { status: 'no-secret' };
+        const credential = read.credential;
+        if (credential.deviceId === before?.deviceId && credential.deviceSecret === before.deviceSecret)
+            return { status: 'no-secret' };
+        let mint;
+        try {
+            mint = await oxy.devices.mintToken(credential.deviceId, credential.deviceSecret);
+        }
+        catch (error) {
+            if (extractErrorStatus(error) === 429)
+                oxy.http.noteRefreshRateLimited();
+            if (extractErrorStatus(error) === 401) {
+                const message = error?.message;
+                if (typeof message === 'string' && message.includes('invalid_device_secret')) {
+                    // There is no cross-app CAS clear in the bridge contract. An old
+                    // rejection cannot delete a slot another app has since published.
+                    return { status: 'invalid-secret' };
+                }
+                if (typeof message === 'string' && message.includes('no_active_session'))
+                    return { status: 'no-session' };
+            }
+            return { status: 'transient' };
+        }
+        const bound = mint.state.accounts.find(account => account.accountId === mint.state.activeAccountId);
+        if (!bound || mint.state.deviceId !== credential.deviceId || !mint.accessToken || !mint.nextDeviceSecret)
+            return { status: 'transient' };
+        if (!isCurrent() || oxy.http.getSessionEpoch() !== epoch || !matchesAuthState(await store.load(), before))
+            return { status: 'session-ended' };
+        const next = {
+            deviceId: mint.state.deviceId, deviceSecret: mint.nextDeviceSecret,
+            sessionId: bound.sessionId, userId: bound.accountId,
+            accessToken: mint.accessToken, expiresAt: mint.expiresAt,
+        };
+        if (!(await store.saveIfCurrent(next, { expectedState: before, isCurrent: () => isCurrent() && oxy.http.getSessionEpoch() === epoch })))
+            return { status: 'persist-failed' };
+        if (!isCurrent() || oxy.http.getSessionEpoch() !== epoch)
+            return { status: 'session-ended' };
+        oxy.session.setAccessToken(mint.accessToken);
+        return { status: 'ok', token: mint.accessToken, sessionId: bound.sessionId, userId: bound.accountId, state: mint.state };
+    });
+}
 /**
  * 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`, 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
+ * from the persisted `deviceId` + `deviceSecret`. An authenticated native
+ * holder's invalid-secret or `no_active_session` verdict suppresses key recovery
+ * while permitting a separately proved new shared holder. The latter verdict
+ * retains that holder and ends ACCOUNT recovery without a new key challenge.
+ * Classification still uses the existing 401 message markers, not a new parser.
+ * A transient error — or a durable-persist failure — leaves the store and
  * returns `null` WITHOUT falling to arm 2 (those are not bad-secret signals).
  *
  * Arm 2 (native Commons identity): when the secret is absent or was just
@@ -192,9 +289,11 @@ export async function refreshDeviceSecretArm(deps) {
  */
 export async function refreshPersistedSession(deps) {
     const { oxy, store } = deps;
+    if (deps.isCurrent && !deps.isCurrent())
+        return null;
     const identity = deps.identity ?? null;
     // The shared identity is never an identity-bound client's recovery path.
-    const allowCommonsIdentityFallback = identity ? false : (deps.allowCommonsIdentityFallback ?? isNative());
+    const allowCommonsIdentityFallback = identity ? false : (deps.allowCommonsIdentityFallback ?? isNative()) && !(await store.isAutomaticIdentitySignInSuppressed?.());
     const epoch = oxy.http.getSessionEpoch();
     // Resolved per call: a re-established identity session can move the pin, and a
     // replaced/removed local key clears it (in which case arm 1 must NOT mint —
@@ -203,7 +302,7 @@ export async function refreshPersistedSession(deps) {
     if (identity && !pin) {
         return recoverIdentitySession(oxy, store, identity);
     }
-    const arm1 = await refreshDeviceSecretArm({ oxy, store, pin });
+    const arm1 = await refreshDeviceSecretArm({ oxy, store, pin, isCurrent: deps.isCurrent });
     switch (arm1.status) {
         case 'ok':
             return arm1.token;
@@ -221,6 +320,28 @@ export async function refreshPersistedSession(deps) {
             return null;
         case 'invalid-secret':
         case 'no-session': {
+            if (!identity && deps.sharedDeviceCredential) {
+                const joined = await refreshSharedDeviceArm({ oxy, store, shared: deps.sharedDeviceCredential, rejectedLocalHolder: true, isCurrent: deps.isCurrent });
+                if (joined.status === 'ok')
+                    return joined.token;
+                if (joined.status === 'session-ended' || joined.status === 'persist-failed')
+                    return null;
+            }
+            if (!identity && arm1.status === 'invalid-secret' && await store.isAutomaticIdentitySignInSuppressed?.())
+                return null;
+            if (arm1.status === 'no-session' && !identity) {
+                if (store.setAutomaticIdentitySignInSuppressed)
+                    return null;
+                // The holder is still valid, but its account session ended. Retain only
+                // the holder for a later deliberate/shared sign-in; never use the key
+                // to turn this signed-out verdict into a new account session.
+                const persisted = await store.load();
+                if (persisted?.deviceId && persisted.deviceSecret) {
+                    await store.save({ sessionId: '', userId: '', deviceId: persisted.deviceId, deviceSecret: persisted.deviceSecret });
+                }
+                return null;
+            }
+            // Identity mode retains its separate pinned-key recovery contract.
             // 401: secret diverged or no live session. When a key-based arm 2 can still
             // recover (the native Commons identity, or an identity-bound client's own
             // primary key) drop ONLY the secret and keep the deviceId; otherwise (web) the
@@ -231,13 +352,6 @@ export async function refreshPersistedSession(deps) {
                     await store.save({ ...persisted, deviceSecret: undefined });
                 }
             }
-            else if (arm1.status === 'no-session' && persisted?.deviceId && persisted.deviceSecret) {
-                // Web, a credential the server still recognises: this origin stays a
-                // holder of the browser's device (ADR 0029 D2) — the next sign-in in any
-                // app lands on it, and this app follows without opening the bridge
-                // again. Only the session fields go.
-                await store.save({ sessionId: '', userId: '', deviceId: persisted.deviceId, deviceSecret: persisted.deviceSecret });
-            }
             else {
                 await store.clear();
             }
@@ -249,6 +363,13 @@ export async function refreshPersistedSession(deps) {
             logger.debug('Pinned device-secret mint rejected: the pinned account is no longer on this device — re-establishing from the identity key', { component: 'refresh', method: 'refreshPersistedSession' });
             break;
         case 'no-secret':
+            if (!identity && deps.sharedDeviceCredential) {
+                const joined = await refreshSharedDeviceArm({ oxy, store, shared: deps.sharedDeviceCredential, isCurrent: deps.isCurrent });
+                if (joined.status === 'ok')
+                    return joined.token;
+                if (joined.status === 'session-ended' || joined.status === 'persist-failed' || joined.status === 'transient')
+                    return null;
+            }
             break;
     }
     if (identity) {
@@ -256,14 +377,14 @@ export async function refreshPersistedSession(deps) {
     }
     // Never after a sign-out: the shared identity is a KEY, not a session, and
     // proving it here would sign the user straight back in.
-    if (allowCommonsIdentityFallback && !oxy.http.hasSessionEnded()) {
+    if (allowCommonsIdentityFallback && (deps.isCurrent?.() ?? true) && !oxy.http.hasSessionEnded() && !(await store.isAutomaticIdentitySignInSuppressed?.())) {
         try {
             // Planted here, not by the sign-in: a sign-out that lands while the
             // challenge round-trips must win, or the identity proof signs the user
             // straight back in.
             const session = await oxy.auth.signInWithCommonsIdentity({ plantTokens: false });
             if (session?.accessToken) {
-                if (oxy.http.getSessionEpoch() !== epoch) {
+                if (!(deps.isCurrent?.() ?? true) || oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.()) {
                     return null;
                 }
                 // Repopulate the fast device-secret lane from the identity re-mint.
@@ -277,7 +398,7 @@ export async function refreshPersistedSession(deps) {
                         expiresAt: session.expiresAt,
                     });
                 }
-                if (oxy.http.getSessionEpoch() !== epoch) {
+                if (!(deps.isCurrent?.() ?? true) || oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.()) {
                     return null;
                 }
                 oxy.session.setAccessToken(session.accessToken);

package/dist/esm/session/sharedDeviceCredential.js

@@ -193,7 +193,9 @@ export async function publishProvenDeviceCredential(deps) {
  *    seam, no lane left out, and no new call site to forget.
  *  - Adopting on read would hide a change of WHO THIS APP IS SIGNED IN AS inside
  *    a storage primitive, and would run on every `load()`. Adoption is an
- *    explicit, once-per-boot cold-boot step instead (`shared-device-adopt`).
+ *    explicit cold-boot/resume recovery instead; an existing local holder must
+ *    first be rejected by the server, and a new shared holder must mint before
+ *    conditional persistence.
  *
  * `clear()` deliberately does NOT clear the shared slot. This app signing out is
  * not authority over the device-wide join point: other apps may still be signed
@@ -208,8 +210,22 @@ export function createSharedMirroringAuthStateStore(deps) {
     // next launch rather than mid-process.
     let mirrored = null;
     return {
+        ...local,
         load: () => local.load(),
         clear: () => local.clear(),
+        ...(local.saveIfCurrent ? { saveIfCurrent: async (state, guard) => {
+                const committed = await local.saveIfCurrent?.(state, guard);
+                if (!committed)
+                    return false;
+                const credential = readLocalDeviceCredential(state);
+                if (credential && guard.isCurrent()) {
+                    try {
+                        await publishProvenDeviceCredential({ shared, credential });
+                    }
+                    catch { /* Local durability already verified. */ }
+                }
+                return true;
+            } } : {}),
         save: async (state) => {
             // The durable local write is the contract this store owes its caller —
             // run it first and report ITS result, unchanged. The mirror is additive.

package/dist/esm/utils/officialOrigins.js

@@ -1,3 +1,5 @@
+import { isLoopbackOrigin } from '@oxy.so/contracts';
+export { isLoopbackOrigin } from '@oxy.so/contracts';
 /**
  * Official first-party web origin allowlist — shared by OAuth redirect
  * validation and the server-side trusted-origin checks.
@@ -21,19 +23,6 @@ const OFFICIAL_APEXES = new Set([
  * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
  * or `[::1]` on any port, http or https).
  */
-export function isLoopbackOrigin(origin) {
-    try {
-        const parsed = new URL(origin);
-        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-            return false;
-        }
-        const host = parsed.hostname.toLowerCase();
-        return host === 'localhost' || host === '127.0.0.1' || host === '[::1]';
-    }
-    catch {
-        return false;
-    }
-}
 /** Whether an origin belongs to the official Oxy web ecosystem. */
 export function isOfficialWebOrigin(origin) {
     if (isLoopbackOrigin(origin)) {

package/dist/types/HttpService.d.ts

@@ -22,19 +22,25 @@ export type AccessTokenProvider = () => string | null;
  * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
+/** A trusted platform transport, for example Expo's streaming fetch. */
+export type ResponseTransport = (input: string, init: RequestInit) => Promise<Response>;
 /**
- * A low-level authenticated request whose response body remains unread.
- *
- * This is intended for streaming protocols such as SSE. The body must already
- * be serialised so it can be replayed once after an access-token refresh.
+ * A low-level same-origin request whose response body remains unread.
+ * Only absent/string request bodies can be replayed after a 401. Multipart,
+ * binary and stream bodies are sent once, even if their platform can replay them.
+ * The caller owns response parsing and the AbortSignal for its full lifetime.
  */
-export interface AuthenticatedResponseRequest {
+export interface ResponseRequest {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     url: string;
-    body?: string;
-    headers?: Record<string, string>;
+    body?: BodyInit;
+    headers?: HeadersInit;
     signal?: AbortSignal;
+    /** Must honour the supplied URL, headers, signal and redirect policy. */
+    fetch?: ResponseTransport;
 }
+/** Same response contract, but rejects locally when the SDK has no bearer. */
+export type AuthenticatedResponseRequest = ResponseRequest;
 export interface RequestOptions {
     cache?: boolean;
     cacheTTL?: number;
@@ -431,7 +437,14 @@ export declare class HttpService {
      * abort signal defines the lifetime of a healthy stream.
      */
     requestAuthenticatedResponse(config: AuthenticatedResponseRequest): Promise<Response>;
-    private requestAuthenticatedResponseAttempt;
+    /**
+     * Raw response for public or authenticated app endpoints. The SDK supplies
+     * its current bearer when available; caller headers never supply authority.
+     * No caching, envelope transformation or transport-error retry is performed.
+     */
+    requestResponse(config: ResponseRequest): Promise<Response>;
+    private requestRawResponse;
+    private requestResponseAttempt;
     get<T = unknown>(url: string, config?: Omit<RequestConfig, 'method' | 'url'>): Promise<T>;
     post<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<T>;
     put<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<T>;
@@ -442,13 +455,14 @@ export declare class HttpService {
      * End the local session: clear the bearer and abandon every re-mint already
      * in flight, so none of them can plant a token after the sign-out.
      *
-     * {@link clearTokens} alone only drops the bearer, which is right for a
-     * mirror (a linked client following its parent) but not for a sign-out: a
-     * refresh started a moment earlier would finish and plant a new one.
+     * Unlike {@link clearTokens}, this also marks the session as ended and
+     * invalidates pending re-mints even when no bearer is currently present.
      */
     endSession(): void;
     /**
-     * The current session epoch — see {@link endSession}. A re-mint lane that
+     * The current context epoch: account/session switches and bearer removal
+     * invalidate pending work; rotation within the same context preserves it.
+     * A re-mint lane that
      * plants tokens itself (the device-secret arm) compares it across its awaits.
      */
     getSessionEpoch(): number;