@oxy.so/core 4.1.0 → 4.2.0

package/src/session/SessionClient.ts

@@ -13,6 +13,7 @@ import {
 } from '@oxy.so/contracts';
 import { logger } from '../logger';
 import { computeIdentityTag } from '../utils/cacheKey';
+import { decodeTokenClaims } from '../utils/tokenClaims';
 import { resolveActiveContext, type DeviceContext } from './deviceDirectory';
 import { getSocketIO } from './socketLoader';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
@@ -55,6 +56,8 @@ export interface SessionClientHost {
 }
 
 export interface SessionClientOptions {
+  /** Await durable local logout intent after an explicit removal or an applied nonempty→empty device transition. */
+  onFullExplicitSignOut?: () => Promise<void>;
   transport?: TokenTransport;
   /**
    * Invoked when an APPLIED state has zero accounts — i.e. a device
@@ -142,6 +145,8 @@ export class SessionClient {
   protected socket: MinimalSocket | null = null;
   private tokenUnsub: (() => void) | null = null;
   private started = false;
+  private lifecycleGeneration = 0;
+  private fullSignOutPersistence: { state: DeviceSessionState; pending: Promise<void> } | null = null;
   /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
   private channel: SessionBroadcastChannel | null = null;
   /** App-facing subscriptions to named server-pushed socket events. */
@@ -154,6 +159,34 @@ export class SessionClient {
     protected readonly options: SessionClientOptions = {},
   ) {}
 
+  private persistFullSignOut(): Promise<void> {
+    const state = this.state;
+    if (!state || !this.options.onFullExplicitSignOut) return Promise.resolve();
+    if (this.fullSignOutPersistence?.state === state) return this.fullSignOutPersistence.pending;
+    const pending = this.options.onFullExplicitSignOut();
+    this.fullSignOutPersistence = { state, pending };
+    void pending.catch(() => {
+      if (this.fullSignOutPersistence?.pending === pending) this.fullSignOutPersistence = null;
+    });
+    return pending;
+  }
+
+  private async requestDevice<T>(method: 'GET' | 'POST', url: string, data?: unknown, requestOptions?: { cache?: boolean }): Promise<T> {
+    const generation = this.lifecycleGeneration;
+    const response = await this.host.makeRequest<T>(method, url, data, requestOptions);
+    if (generation !== this.lifecycleGeneration) throw new Error('Device session request was superseded');
+    return response;
+  }
+
+  /** Stop and discard only this client's local device projection; no server revocation. */
+  resetLocalState(): void {
+    this.lifecycleGeneration += 1;
+    this.stop();
+    this.state = null;
+    this.directory = null;
+    this.notify();
+  }
+
   getState(): DeviceSessionState | null {
     return this.state;
   }
@@ -280,6 +313,7 @@ export class SessionClient {
    * cross-device push, a cold mint), not just the initial "no bearer yet" case.
    */
   protected applyState(raw: unknown, origin: SessionStateOrigin = 'push', activeToken?: string): boolean {
+    const generation = this.lifecycleGeneration;
     const next = safeParseContract(deviceSessionStateSchema, raw);
     if (!next) {
       logger.warn('[SessionClient] discarded invalid session state');
@@ -341,6 +375,7 @@ export class SessionClient {
       (activeAccountId === null || computeIdentityTag(this.host.getAccessToken()) !== activeAccountId);
 
     const publish = (): void => {
+      if (generation !== this.lifecycleGeneration || this.state !== next) return;
       this.notify();
       if (next.accounts.length === 0 && this.options.onUnauthenticated) {
         try {
@@ -359,6 +394,7 @@ export class SessionClient {
     // (and this stays synchronous) for every client that never read a
     // directory, i.e. the whole account lane.
     const finishApply = (): void => {
+      if (generation !== this.lifecycleGeneration || this.state !== next) return;
       const settling = this.settleDirectory(next);
       if (settling === null) {
         publish();
@@ -367,8 +403,39 @@ export class SessionClient {
       void settling.then(publish);
     };
 
+    // A sibling's validated full removal is logout here too. Persist the local
+    // account-mode recovery suppression before publishing signed-out or running
+    // the empty-state refresh (which could otherwise challenge Commons again).
+    // Keep the push credential intact; a marker is not a destructive wipe.
+    // Unknown initial empty state, stale revisions and identity pins do not
+    // turn into logout intent. A newer state/lifecycle suppresses this publish.
+    const priorBearer = this.host.getAccessToken();
+    const bearerAccount = priorBearer ? decodeTokenClaims(priorBearer)?.userId : null;
+    // Warm cold boot may fetch authoritative empty state before it ever had a
+    // local projection. Its authenticated holder is history too. Decoding only
+    // identifies local history; authority remains the validated REST response.
+    const warmHolderEnded = previousState === null && origin === 'request' &&
+      typeof bearerAccount === 'string' && bearerAccount.length > 0 &&
+      this.host.getDeviceCredential()?.deviceId === next.deviceId;
+    if (
+      ((previousState?.deviceId === next.deviceId && previousState.accounts.length > 0) || warmHolderEnded) &&
+      next.accounts.length === 0 && pinnedAccountId === null && this.options.onFullExplicitSignOut
+    ) {
+      try {
+        void this.persistFullSignOut().then(finishApply).catch((error) => {
+          logger.error('[SessionClient] failed to persist received full sign-out', error);
+          finishApply();
+        });
+      } catch (error) {
+        logger.error('[SessionClient] failed to persist received full sign-out', error);
+        finishApply();
+      }
+      return true;
+    }
+
     if (needsMintBeforeNotify) {
       void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
+        if (generation !== this.lifecycleGeneration) return;
         logger.warn('[SessionClient] ensureActiveToken failed — reverting session state', { component: 'SessionClient' }, error);
         // Do NOT notify under a mismatched bearer. Revert to the last applied
         // state so subscribers keep observing the account whose token is planted.
@@ -392,7 +459,7 @@ export class SessionClient {
    * the token still needs to be planted. The account-match guard rejects a stale response for an
    * account that is no longer active.
    */
-  private applySync(raw: unknown): void {
+  private async applySync(raw: unknown): Promise<void> {
     const sync = safeParseContract(deviceSessionSyncSchema, raw);
     if (!sync) {
       const parsed = deviceSessionSyncSchema.safeParse(raw);
@@ -411,6 +478,7 @@ export class SessionClient {
       return;
     }
     this.commitSync(sync);
+    if (this.fullSignOutPersistence?.state === this.state) await this.fullSignOutPersistence.pending;
   }
 
   /**
@@ -495,7 +563,7 @@ export class SessionClient {
 
   /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
   private async fetchDirectory(): Promise<boolean> {
-    const res = await this.host.makeRequest<unknown>('GET', '/session/device/directory', undefined, { cache: false });
+    const res = await this.requestDevice<unknown>('GET', '/session/device/directory', undefined, { cache: false });
     return this.applyDirectory(res);
   }
 
@@ -611,8 +679,8 @@ export class SessionClient {
   }
 
   async bootstrap(): Promise<void> {
-    const res = await this.host.makeRequest<unknown>('GET', '/session/device/state', undefined, { cache: false });
-    this.applySync(res);
+    const res = await this.requestDevice<unknown>('GET', '/session/device/state', undefined, { cache: false });
+    await this.applySync(res);
   }
 
   /**
@@ -658,7 +726,7 @@ export class SessionClient {
    * compatibility path for callers still keyed on account ids.
    */
   async activateContext(contextId: string): Promise<void> {
-    const res = await this.host.makeRequest<unknown>('POST', '/session/device/activate', { contextId }, { cache: false });
+    const res = await this.requestDevice<unknown>('POST', '/session/device/activate', { contextId }, { cache: false });
     const activation = safeParseContract(deviceActivateResponseSchema, res);
     if (!activation) {
       logger.warn('[SessionClient] discarded invalid activation response');
@@ -685,8 +753,8 @@ export class SessionClient {
   }
 
   async switchAccount(accountId: string): Promise<void> {
-    const res = await this.host.makeRequest<unknown>('POST', '/session/device/switch', { accountId }, { cache: false });
-    this.applySync(res);
+    const res = await this.requestDevice<unknown>('POST', '/session/device/switch', { accountId }, { cache: false });
+    await this.applySync(res);
     this.postCommitPing();
   }
 
@@ -702,9 +770,10 @@ export class SessionClient {
    * {@link signOutPrincipal} for the two that can tell those apart.
    */
   async signOut(target: { accountId: string } | { all: true }): Promise<void> {
-    const res = await this.host.makeRequest<unknown>('POST', '/session/device/signout', target, { cache: false });
-    this.applySync(res);
+    const res = await this.requestDevice<unknown>('POST', '/session/device/signout', target, { cache: false });
+    await this.applySync(res);
     this.postCommitPing();
+    if (this.state?.accounts.length === 0) await this.persistFullSignOut();
   }
 
   /**
@@ -746,7 +815,7 @@ export class SessionClient {
    * applied this revision.
    */
   private async removeFromDevice(target: { contextId: string } | { principalId: string }): Promise<void> {
-    const res = await this.host.makeRequest<unknown>('POST', '/session/device/signout', target, { cache: false });
+    const res = await this.requestDevice<unknown>('POST', '/session/device/signout', target, { cache: false });
     const removal = safeParseContract(deviceDirectorySyncSchema, res);
     if (!removal) {
       logger.warn('[SessionClient] discarded invalid device removal response');
@@ -754,6 +823,7 @@ export class SessionClient {
     }
     const directoryApplied = this.applyDirectory(removal.directory);
     const stateApplied = this.commitSync({ state: removal.state, activeToken: removal.activeToken });
+    if (this.fullSignOutPersistence?.state === this.state) await this.fullSignOutPersistence.pending;
     // `commitSync` publishes whenever the flat state moved. When only the
     // directory did — a socket push already applied this revision — the
     // directory half would otherwise never reach a subscriber.
@@ -761,11 +831,12 @@ export class SessionClient {
       this.notify();
     }
     this.postCommitPing();
+    if (this.state?.accounts.length === 0) await this.persistFullSignOut();
   }
 
   async addCurrentAccount(): Promise<void> {
-    const res = await this.host.makeRequest<unknown>('POST', '/session/device/add', undefined, { cache: false });
-    this.applySync(res);
+    const res = await this.requestDevice<unknown>('POST', '/session/device/add', undefined, { cache: false });
+    await this.applySync(res);
     this.postCommitPing();
   }
 
@@ -866,6 +937,7 @@ export class SessionClient {
     const deviceCredential = this.host.getDeviceCredential();
     if (!token && !deviceCredential) return;
 
+    const generation = this.lifecycleGeneration;
     const socket = io(this.host.getBaseURL(), {
       transports: ['websocket'],
       autoConnect: true,
@@ -890,6 +962,7 @@ export class SessionClient {
     socket.on('session_state', (payload: unknown) => {
       // A socket broadcast is a `push`-origin — potentially transient, so an
       // empty state here must not erase the durable device credential.
+      if (generation !== this.lifecycleGeneration) return;
       const applied = this.applyState(payload, 'push');
       if (!applied) return;
       // An identity-bound client tracks the pushed state but NEVER chases the

package/src/session/authStateStore.ts

@@ -84,7 +84,28 @@ export interface AuthStateStore {
    * session built on a secret that will not survive a reload.
    */
   save(state: PersistedAuthState): Promise<boolean>;
+  /** Compare inside the storage queue before committing a proven shared holder. */
+  saveIfCurrent?(state: PersistedAuthState, guard: AuthStateWriteGuard): Promise<boolean>;
   clear(): Promise<void>;
+  /** Durable local intent only: never authority or a mutation of an identity key. */
+  isAutomaticIdentitySignInSuppressed?(): Promise<boolean>;
+  setAutomaticIdentitySignInSuppressed?(suppressed: boolean, guard?: {
+    /** Checked inside the native store queue, before mutating logout intent. */
+    expectedState: PersistedAuthState;
+    isCurrent: () => boolean;
+  }): Promise<boolean>;
+}
+
+export interface AuthStateWriteGuard {
+  expectedState: PersistedAuthState | null;
+  isCurrent: () => boolean;
+}
+
+export function matchesAuthState(actual: PersistedAuthState | null, expected: PersistedAuthState | null): boolean {
+  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;
 }
 
 /**
@@ -115,6 +136,7 @@ export interface NativeKeyValueStorage {
  * 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
@@ -294,6 +316,11 @@ export function createMemoryAuthStateStore(): AuthStateStore {
       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;
     },
@@ -428,8 +455,100 @@ export function createNativeAuthStateStore(storage: NativeKeyValueStorage): Auth
   // 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: PersistedAuthState | null | undefined;
+  let suppressedMirror: boolean | undefined;
+  let pending: Promise<void> = Promise.resolve();
+  const serialize = <T>(operation: () => Promise<T>): Promise<T> => {
+    const result = pending.then(operation);
+    pending = result.then(() => undefined, () => undefined);
+    return result;
+  };
+  const readCurrent = async (): Promise<PersistedAuthState | null> => {
+    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: PersistedAuthState): Promise<boolean> => {
+    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;
       }
@@ -442,51 +561,16 @@ export function createNativeAuthStateStore(storage: NativeKeyValueStorage): Auth
       } 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);
-        }
-      } catch {
-        // Locked / oversize keychain — non-fatal warm-boot loss only.
-      }
-      // Report ONLY the durable-credential landing; the warm-token outcome above
-      // is intentionally excluded (it is a best-effort optimization).
-      return durablePersisted;
-    },
-    clear: async () => {
+        const current = await readCurrent();
+        if (!guard.isCurrent() || !matchesAuthState(current, guard.expectedState)) return false;
+      } catch { return false; }
+      return persistState(state);
+    }),
+    clear: () => serialize(async () => {
       sessionMirror = null;
       try {
         await storage.removeItem(AUTH_STATE_STORAGE_KEY);
@@ -498,6 +582,6 @@ export function createNativeAuthStateStore(storage: NativeKeyValueStorage): Auth
       } catch {
         // Non-fatal.
       }
-    },
+    }),
   };
 }

package/src/session/index.ts

@@ -132,6 +132,7 @@ export {
 export type {
     PersistedAuthState,
     AuthStateStore,
+    AuthStateWriteGuard,
     NativeKeyValueStorage,
 } from './authStateStore';