@oxyhq/core 3.4.1 → 3.4.3

package/src/AuthManagerTypes.ts

@@ -30,13 +30,10 @@ export interface AuthManagerAccount {
    * Projected user shape from the wire (username/avatar/color/email).
    *
    * `null` when a refresh-via-cookie planted a fresh access token for a slot
-   * that the AuthManager has no prior in-memory user metadata for — e.g. the
-   * legacy `/auth/refresh` 404 fallback path inside `refreshAllSessions`, or
-   * a `switchAuthuser` against a slot that wasn't present in the previous
-   * `restoreFromCookies` snapshot. Callers (or the AuthManager itself) are
-   * expected to hydrate the user shape via `getCurrentUser()` after the token
-   * is planted; the chooser UI must render the public-key fallback handle
-   * until the hydration completes.
+   * that the AuthManager has no prior in-memory user metadata for. Callers (or
+   * the AuthManager itself) are expected to hydrate the user shape via
+   * `getCurrentUser()` after the token is planted; the chooser UI must render
+   * the public-key fallback handle until the hydration completes.
    */
   user: RefreshAllAccountUser | null;
   /** Currently-valid access token for this slot (in-memory only). */
@@ -80,8 +77,7 @@ export interface RestoreFromCookiesOptions {
 /**
  * Outcome of `AuthManager.switchAuthuser()`.
  *
- * Mirrors the wire `RefreshCookieResponse` but with `authuser` narrowed to
- * `number` (the SDK boundary normalises the legacy `null` slot to `0`).
+ * Mirrors the wire `RefreshCookieResponse`.
  */
 export interface SwitchAuthuserResult {
   accessToken: string;

package/src/CrossDomainAuth.ts

@@ -5,8 +5,7 @@
  * selects the best authentication method based on browser capabilities:
  *
  * 1. FedCM (if supported) - Modern, Google-style browser-native auth
- * 2. Popup (fallback) - OAuth2-style popup window
- * 3. Redirect (final fallback) - Traditional full-page redirect
+ * 2. Redirect (fallback) - Tokenless central SSO full-page redirect
  *
  * Usage:
  * ```typescript
@@ -17,8 +16,8 @@
  * // Automatic method selection
  * const session = await auth.signIn();
  *
- * // Or use specific method
- * const session = await auth.signInWithPopup();
+ * // Or use a specific method
+ * auth.signInWithRedirect();
  * ```
  */
 
@@ -31,10 +30,9 @@ export interface CrossDomainAuthOptions {
    * Preferred authentication method
    * - 'auto': Automatically select best method (default)
    * - 'fedcm': Use FedCM (browser-native)
-   * - 'popup': Use popup window
    * - 'redirect': Use full-page redirect
    */
-  method?: 'auto' | 'fedcm' | 'popup' | 'redirect';
+  method?: 'auto' | 'fedcm' | 'redirect';
 
   /**
    * Custom redirect URI (for redirect method)
@@ -46,26 +44,10 @@ export interface CrossDomainAuthOptions {
    */
   isSignup?: boolean;
 
-  /**
-   * Popup window dimensions (for popup method)
-   */
-  popupDimensions?: {
-    width?: number;
-    height?: number;
-  };
-
   /**
    * Callback when auth method is selected
    */
-  onMethodSelected?: (method: 'fedcm' | 'popup' | 'redirect') => void;
-
-  /**
-   * A popup window the caller already opened SYNCHRONOUSLY in the user-gesture
-   * handler. Forwarded to `OxyServices.signInWithPopup` so the popup is not
-   * blocked by Chrome after any prior `await` (FedCM / silent SSO) has
-   * consumed the transient user activation. See `OxyServices.openBlankPopup`.
-   */
-  popup?: Window | null;
+  onMethodSelected?: (method: 'fedcm' | 'redirect') => void;
 }
 
 export class CrossDomainAuth {
@@ -76,8 +58,7 @@ export class CrossDomainAuth {
    *
    * Tries methods in this order:
    * 1. FedCM (if supported and not in private browsing)
-   * 2. Popup (if not blocked)
-   * 3. Redirect (always works)
+   * 2. Redirect (always works)
    *
    * @param options - Authentication options
    * @returns Session with user data and access token
@@ -85,49 +66,19 @@ export class CrossDomainAuth {
   async signIn(options: CrossDomainAuthOptions = {}): Promise<SessionLoginResponse | null> {
     const method = options.method || 'auto';
 
-    // If specific method requested, use it directly. The caller MAY have
-    // pre-opened a popup on the raw click (the standard pattern in
-    // WebOxyProvider / services useAuth). For the FedCM and redirect paths
-    // that popup is unused — close it so it doesn't linger as an orphaned
-    // blank window. Close in both success and failure paths.
     if (method === 'fedcm') {
-      try {
-        const session = await this.signInWithFedCM(options);
-        this.closeOrphanPopup(options.popup);
-        return session;
-      } catch (error) {
-        this.closeOrphanPopup(options.popup);
-        throw error;
-      }
-    }
-
-    if (method === 'popup') {
-      return this.signInWithPopup(options);
+      return this.signInWithFedCM(options);
     }
 
     if (method === 'redirect') {
-      this.closeOrphanPopup(options.popup);
       this.signInWithRedirect(options);
       return null; // Redirect doesn't return immediately
     }
 
-    // Auto mode: Try methods in order of preference
+    // Auto mode: try methods in order of preference.
     return this.autoSignIn(options);
   }
 
-  /**
-   * Close a caller-supplied popup window that is no longer needed (e.g. the
-   * resolved auth method didn't end up using it). Safe against null / already
-   * closed handles.
-   *
-   * @private
-   */
-  private closeOrphanPopup(popup: Window | null | undefined): void {
-    if (popup && !popup.closed) {
-      popup.close();
-    }
-  }
-
   /**
    * Automatic sign-in with progressive enhancement
    *
@@ -138,27 +89,13 @@ export class CrossDomainAuth {
     if (this.isFedCMSupported()) {
       try {
         options.onMethodSelected?.('fedcm');
-        const session = await this.signInWithFedCM(options);
-        // FedCM succeeded — close the pre-opened popup so it doesn't linger
-        // as an orphaned blank window.
-        this.closeOrphanPopup(options.popup);
-        return session;
+        return await this.signInWithFedCM(options);
       } catch (error) {
-        logger.warn('FedCM failed, trying popup', { component: 'CrossDomainAuth', method: 'autoSignIn' }, error);
+        logger.warn('FedCM failed, falling back to redirect', { component: 'CrossDomainAuth', method: 'autoSignIn' }, error);
       }
     }
 
-    // 2. Try popup (good UX, widely supported)
-    try {
-      options.onMethodSelected?.('popup');
-      return await this.signInWithPopup(options);
-    } catch (error) {
-      logger.warn('Popup failed, falling back to redirect', { component: 'CrossDomainAuth', method: 'autoSignIn' }, error);
-      // Popup path failed — close the pre-opened popup before redirecting.
-      this.closeOrphanPopup(options.popup);
-    }
-
-    // 3. Fallback to redirect (always works)
+    // 2. Fallback to redirect (always works)
     options.onMethodSelected?.('redirect');
     this.signInWithRedirect(options);
     return null;
@@ -167,7 +104,7 @@ export class CrossDomainAuth {
   /**
    * Sign in using FedCM (Federated Credential Management)
    *
-   * Best method - browser-native, no popups, Google-like experience
+   * Best method - browser-native, Google-like experience
    */
   async signInWithFedCM(options: CrossDomainAuthOptions = {}): Promise<SessionLoginResponse> {
     return this.oxyServices.signInWithFedCM({
@@ -175,20 +112,6 @@ export class CrossDomainAuth {
     });
   }
 
-  /**
-   * Sign in using popup window
-   *
-   * Good method - preserves app state, no full page reload
-   */
-  async signInWithPopup(options: CrossDomainAuthOptions = {}): Promise<SessionLoginResponse> {
-    return this.oxyServices.signInWithPopup({
-      mode: options.isSignup ? 'signup' : 'login',
-      width: options.popupDimensions?.width,
-      height: options.popupDimensions?.height,
-      popup: options.popup ?? undefined,
-    });
-  }
-
   /**
    * Sign in using full-page redirect
    *
@@ -214,7 +137,7 @@ export class CrossDomainAuth {
    * Silent sign-in (check for existing session)
    *
    * Tries to automatically sign in without user interaction.
-   * Works with both FedCM and popup/iframe methods.
+   * Works with FedCM and iframe-based silent auth.
    *
    * @returns Session if user is already signed in, null otherwise
    */
@@ -241,23 +164,13 @@ export class CrossDomainAuth {
   }
 
   /**
-   * Restore session from storage
+   * Restore session from storage.
    *
-   * For redirect method - restores previously authenticated session from localStorage
+   * Access tokens are no longer persisted in browser storage; providers restore
+   * through refresh cookies / SSO code exchange instead.
    */
   restoreSession(): boolean {
-    return this.oxyServices.restoreSession?.() || false;
-  }
-
-  /**
-   * Open a blank popup SYNCHRONOUSLY (call from a raw user-gesture handler
-   * BEFORE any `await`). Returns `null` if the popup was blocked. Pass the
-   * handle into `signIn({ popup })` / `signInWithPopup({ popup })` so the
-   * popup is not blocked by Chrome after any prior `await` consumed the
-   * transient user activation. Delegates to `OxyServices.openBlankPopup`.
-   */
-  openBlankPopup(width?: number, height?: number): Window | null {
-    return this.oxyServices.openBlankPopup(width, height);
+    return false;
   }
 
   /**
@@ -274,7 +187,7 @@ export class CrossDomainAuth {
    *
    * @returns Recommended method name and reason
    */
-  getRecommendedMethod(): { method: 'fedcm' | 'popup' | 'redirect'; reason: string } {
+  getRecommendedMethod(): { method: 'fedcm' | 'redirect'; reason: string } {
     if (this.isFedCMSupported()) {
       return {
         method: 'fedcm',
@@ -284,8 +197,8 @@ export class CrossDomainAuth {
 
     if (typeof window !== 'undefined') {
       return {
-        method: 'popup',
-        reason: 'Browser environment - popup preserves app state',
+        method: 'redirect',
+        reason: 'Browser environment - redirect SSO works without token callback URLs',
       };
     }
 
@@ -300,8 +213,7 @@ export class CrossDomainAuth {
    *
    * This handles:
    * 1. Redirect callback (if returning from auth.oxy.so)
-   * 2. Session restoration (from localStorage)
-   * 3. Silent sign-in (check for existing SSO session)
+   * 2. Silent sign-in (check for existing SSO session)
    *
    * @returns Session if user is authenticated, null otherwise
    */
@@ -312,26 +224,7 @@ export class CrossDomainAuth {
       return callbackSession;
     }
 
-    // 2. Try to restore existing session from storage
-    const restored = this.restoreSession();
-    if (restored) {
-      // Verify session is still valid by fetching user
-      try {
-        const user = await this.oxyServices.getCurrentUser();
-        if (user) {
-          return {
-            sessionId: this.oxyServices.getStoredSessionId?.() || '',
-            deviceId: '',
-            expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-            user,
-          };
-        }
-      } catch (error) {
-        logger.debug('stored session invalid', { component: 'CrossDomainAuth', method: 'initialize' }, error);
-      }
-    }
-
-    // 3. Try silent sign-in (check for SSO session at auth.oxy.so)
+    // 2. Try silent sign-in (check for SSO session at auth.oxy.so)
     return await this.silentSignIn();
   }
 }

package/src/HttpService.ts

@@ -35,6 +35,9 @@ interface JwtPayload {
   [key: string]: any;
 }
 
+export type AuthRefreshReason = 'preflight' | 'response-401';
+export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
+
 /**
  * Structural type that captures the multipart-write surface every supported
  * FormData implementation exposes (browser, React Native, Node `form-data`
@@ -110,26 +113,19 @@ interface RequestConfig extends RequestOptions {
  */
 class TokenStore {
   private accessToken: string | null = null;
-  private refreshToken: string | null = null;
   private csrfToken: string | null = null;
   private csrfTokenFetchPromise: Promise<string | null> | null = null;
 
-  setTokens(accessToken: string, refreshToken = ''): void {
+  setTokens(accessToken: string): void {
     this.accessToken = accessToken;
-    this.refreshToken = refreshToken;
   }
 
   getAccessToken(): string | null {
     return this.accessToken;
   }
 
-  getRefreshToken(): string | null {
-    return this.refreshToken;
-  }
-
   clearTokens(): void {
     this.accessToken = null;
-    this.refreshToken = null;
   }
 
   hasAccessToken(): boolean {
@@ -174,14 +170,13 @@ export class HttpService {
   private config: OxyConfig;
   private tokenRefreshPromise: Promise<string | null> | null = null;
   private tokenRefreshCooldownUntil: number = 0;
-  private _onTokenRefreshed: ((accessToken: string) => void) | null = null;
+  private authRefreshHandler: AuthRefreshHandler | null = null;
 
   /**
    * Fan-out listeners notified on EVERY access-token change on this instance:
-   * explicit `setTokens`, `clearTokens`, a successful silent refresh, and the
-   * internal 401-driven clear. Unlike the single-slot `_onTokenRefreshed`
-   * (owned by AuthManager for the refresh path only), this is a Set so multiple
-   * independent observers can mirror token state without clobbering each other.
+   * explicit `setTokens`, `clearTokens`, an AuthManager-owned refresh, and the
+   * internal 401-driven clear. This is a Set so multiple independent observers
+   * can mirror token state without clobbering each other.
    *
    * Each listener receives the resulting access token, or `null` when cleared.
    */
@@ -421,22 +416,13 @@ export class HttpService {
 
         // Handle response
         if (!response.ok) {
-          // On 401, attempt token refresh and retry once before giving up
+          // On 401, delegate refresh to AuthManager and retry once before
+          // giving up. HttpService deliberately does not know any session
+          // routes; the AuthManager is the single session authority.
           if (response.status === 401 && !config._isAuthRetry) {
-            const currentToken = this.tokenStore.getAccessToken();
-            if (currentToken) {
-              try {
-                const decoded = jwtDecode<JwtPayload>(currentToken);
-                if (decoded.sessionId) {
-                  const refreshResult = await this._refreshTokenFromSession(decoded.sessionId);
-                  if (refreshResult) {
-                    // Retry the request with the new token
-                    return this.request<T>({ ...config, _isAuthRetry: true, retry: false });
-                  }
-                }
-              } catch {
-                // Token decode failed, fall through to clear
-              }
+            const refreshed = await this.refreshAccessToken('response-401');
+            if (refreshed) {
+              return this.request<T>({ ...config, _isAuthRetry: true, retry: false });
             }
             // Refresh failed or no token — clear tokens and stale CSRF
             this.tokenStore.clearTokens();
@@ -464,7 +450,7 @@ export class HttpService {
           if (contentType && contentType.includes('application/json')) {
             try {
               const errorData = await response.json() as { message?: string; error?: string } | null;
-              // Check both 'message' and 'error' fields for backwards compatibility
+              // Accept either structured error field from API responses.
               if (errorData?.message) {
                 errorMessage = errorData.message;
               } else if (errorData?.error) {
@@ -878,24 +864,9 @@ export class HttpService {
       const currentTime = Math.floor(Date.now() / 1000);
 
       // If token expires in less than 60 seconds, refresh it
-      if (decoded.exp && decoded.exp - currentTime < 60 && decoded.sessionId) {
-        // Skip if we recently failed a refresh (15s cooldown to prevent storms)
-        if (Date.now() < this.tokenRefreshCooldownUntil) {
-          return `Bearer ${accessToken}`;
-        }
-        // Deduplicate concurrent refresh attempts. The promise is shared
-        // across all concurrent callers and cleared only after it settles,
-        // so every awaiter receives the same result.
-        if (!this.tokenRefreshPromise) {
-          this.tokenRefreshPromise = this._refreshTokenFromSession(decoded.sessionId)
-            .then((result) => {
-              if (!result) this.tokenRefreshCooldownUntil = Date.now() + 15000;
-              return result;
-            })
-            .finally(() => { this.tokenRefreshPromise = null; });
-        }
-        const result = await this.tokenRefreshPromise;
-        if (result) return result;
+      if (decoded.exp && decoded.exp - currentTime < 60) {
+        const refreshed = await this.refreshAccessToken('preflight');
+        if (refreshed) return `Bearer ${refreshed}`;
         // Refresh failed — don't use the expired token (would cause 401 loop)
         return null;
       }
@@ -907,28 +878,40 @@ export class HttpService {
     }
   }
 
-  private async _refreshTokenFromSession(sessionId: string): Promise<string | null> {
-    try {
-      const refreshUrl = `${this.baseURL}/session/token/${sessionId}`;
-      const response = await fetch(refreshUrl, {
-        method: 'GET',
-        headers: { 'Accept': 'application/json' },
-        signal: AbortSignal.timeout(5000),
-        credentials: 'include',
-      });
-
-      if (response.ok) {
-        const { accessToken: newToken } = await response.json();
-        this.tokenStore.setTokens(newToken);
-        this._onTokenRefreshed?.(newToken);
-        this.notifyTokenChange();
-        this.logger.debug('Token refreshed');
-        return `Bearer ${newToken}`;
-      }
-    } catch (refreshError) {
-      this.logger.warn('Token refresh failed, using current token');
+  private async refreshAccessToken(reason: AuthRefreshReason): Promise<string | null> {
+    if (!this.authRefreshHandler) {
+      return null;
     }
-    return null;
+
+    if (Date.now() < this.tokenRefreshCooldownUntil) {
+      return null;
+    }
+
+    if (!this.tokenRefreshPromise) {
+      this.tokenRefreshPromise = this.authRefreshHandler(reason)
+        .then((newToken) => {
+          if (!newToken) {
+            this.tokenRefreshCooldownUntil = Date.now() + 15000;
+            return null;
+          }
+          if (this.tokenStore.getAccessToken() !== newToken) {
+            this.tokenStore.setTokens(newToken);
+            this.notifyTokenChange();
+          }
+          this.logger.debug('Token refreshed via AuthManager');
+          return newToken;
+        })
+        .catch((error) => {
+          this.logger.warn('Token refresh failed:', error);
+          this.tokenRefreshCooldownUntil = Date.now() + 15000;
+          return null;
+        })
+        .finally(() => {
+          this.tokenRefreshPromise = null;
+        });
+    }
+
+    return this.tokenRefreshPromise;
   }
 
   /**
@@ -996,13 +979,13 @@ export class HttpService {
   }
 
   // Token management
-  setTokens(accessToken: string, refreshToken = ''): void {
-    this.tokenStore.setTokens(accessToken, refreshToken);
+  setTokens(accessToken: string): void {
+    this.tokenStore.setTokens(accessToken);
     this.notifyTokenChange();
   }
 
-  set onTokenRefreshed(callback: ((accessToken: string) => void) | null) {
-    this._onTokenRefreshed = callback;
+  setAuthRefreshHandler(handler: AuthRefreshHandler | null): void {
+    this.authRefreshHandler = handler;
   }
 
   clearTokens(): void {
@@ -1136,4 +1119,3 @@ export class HttpService {
     this.tokenStore.clearCsrfToken();
   }
 }
-

package/src/OxyServices.base.ts

@@ -164,8 +164,8 @@ export class OxyServicesBase {
   /**
    * Set authentication tokens
    */
-  public setTokens(accessToken: string, refreshToken = ''): void {
-    this.httpService.setTokens(accessToken, refreshToken);
+  public setTokens(accessToken: string): void {
+    this.httpService.setTokens(accessToken);
   }
 
   /**
@@ -430,4 +430,3 @@ export class OxyServicesBase {
     }
   }
 }
-

package/src/OxyServices.ts

@@ -60,7 +60,7 @@ import { OxyServicesBase, type OxyConfig } from './OxyServices.base';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 import type { SessionLoginResponse } from './models/session';
 import type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
-import type { PopupAuthOptions } from './mixins/OxyServices.popup';
+import type { SilentAuthOptions } from './mixins/OxyServices.silent';
 import type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 
 // Import mixin composition helper
@@ -137,16 +137,14 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   revokeFedCMCredential(): Promise<void>;
   getFedCMConfig(): FedCMConfig;
 
-  // Popup authentication
-  signInWithPopup(options?: PopupAuthOptions): Promise<SessionLoginResponse>;
-  signUpWithPopup(options?: PopupAuthOptions): Promise<SessionLoginResponse>;
-  /**
-   * Open a blank popup SYNCHRONOUSLY (call from a raw user-gesture handler
-   * BEFORE any `await`). Returns `null` if the popup was blocked. Pass the
-   * handle into `signInWithPopup({ popup })` to navigate it to auth.oxy.so
-   * after the async portion of the sign-in flow runs.
-   */
-  openBlankPopup(width?: number, height?: number): Window | null;
+  // Silent iframe SSO
+  resolveAuthUrl(): string;
+  silentSignIn(options?: SilentAuthOptions): Promise<SessionLoginResponse | null>;
+  waitForIframeAuth(
+    iframe: HTMLIFrameElement,
+    timeout: number,
+    expectedOrigin: string,
+  ): Promise<SessionLoginResponse | null>;
 
   // Redirect authentication
   signInWithRedirect(options?: RedirectAuthOptions): void;

package/src/__tests__/authManager.cookiePath.test.ts

@@ -1,9 +1,8 @@
 /**
  * AuthManager multi-account cookie-path regression tests.
  *
- * Locks in the four new methods that route through the httpOnly
- * `oxy_rt_${authuser}` refresh cookies instead of the legacy bearer
- * `/session/token/:id` endpoint:
+ * Locks in the four methods that route through the httpOnly
+ * `oxy_rt_${authuser}` refresh cookies:
  *
  *   - `restoreFromCookies()` — cold-boot restore of every device-local slot
  *     via `POST /auth/refresh-all`. Picks active slot by persisted
@@ -44,12 +43,17 @@ class InMemoryStorage implements StorageAdapter {
   raw(): Map<string, string> { return this.store; }
 }
 
+interface MockHttpService {
+  setTokens: jest.Mock;
+  setAuthRefreshHandler: jest.Mock;
+}
+
 interface MockServices {
   refreshAllSessions: jest.Mock<Promise<RefreshAllResponse>, []>;
   refreshTokenViaCookie: jest.Mock;
   logoutSessionByAuthuser: jest.Mock<Promise<void>, [number]>;
   logoutAllSessionsViaCookie: jest.Mock<Promise<void>, []>;
-  httpService: { setTokens: jest.Mock; onTokenRefreshed: ((t: string) => void) | undefined };
+  httpService: MockHttpService;
 }
 
 function makeMockServices(): MockServices {
@@ -58,7 +62,7 @@ function makeMockServices(): MockServices {
     refreshTokenViaCookie: jest.fn(),
     logoutSessionByAuthuser: jest.fn(async () => undefined),
     logoutAllSessionsViaCookie: jest.fn(async () => undefined),
-    httpService: { setTokens: jest.fn(), onTokenRefreshed: undefined },
+    httpService: { setTokens: jest.fn(), setAuthRefreshHandler: jest.fn() },
   };
 }
 
@@ -68,7 +72,6 @@ function makeManager(services: MockServices, storage: InMemoryStorage): AuthMana
     storage,
     autoRefresh: false,
     crossTabSync: false,
-    cookieOnly: true,
   });
 }
 
@@ -305,7 +308,7 @@ describe('AuthManager.signOutAllViaCookies', () => {
   });
 });
 
-describe('AuthManager.initialize (cookieOnly)', () => {
+describe('AuthManager.initialize', () => {
   it('returns the active user from restoreFromCookies and never touches localStorage tokens', async () => {
     const services = makeMockServices();
     services.refreshAllSessions.mockResolvedValueOnce(TWO_ACCOUNTS);
@@ -321,24 +324,23 @@ describe('AuthManager.initialize (cookieOnly)', () => {
     expect(storage.has('oxy_user')).toBe(false);
   });
 
-  it('returns null when no cookies AND cookieOnly mode (no legacy fallback)', async () => {
+  it('returns null when no cookies are restored', async () => {
     const services = makeMockServices();
     // Default `{ accounts: [] }`.
     const storage = new InMemoryStorage();
-    // Even if legacy token were present in storage, cookieOnly must skip it.
-    storage.setItem('oxy_access_token', 'stale-legacy-token');
-    storage.setItem('oxy_user', JSON.stringify({ id: 'legacy', username: 'legacy' }));
+    storage.setItem('oxy_access_token', 'stale-storage-token');
+    storage.setItem('oxy_user', JSON.stringify({ id: 'stale', username: 'stale' }));
     const manager = makeManager(services, storage);
 
     const user = await manager.initialize();
 
     expect(user).toBeNull();
-    // The legacy access token was NOT planted.
+    // Stale storage token material is ignored.
     expect(services.httpService.setTokens).not.toHaveBeenCalled();
   });
 });
 
-describe('AuthManager.getAccessToken (cookieOnly in-memory fallback)', () => {
+describe('AuthManager.getAccessToken', () => {
   it('returns the in-memory token after a cold-boot cookie restore even though storage holds no token', async () => {
     // Regression: the cookie restore path plants the active token ONLY in memory
     // (`_lastKnownAccessToken` + httpService) and intentionally NEVER writes
@@ -352,7 +354,7 @@ describe('AuthManager.getAccessToken (cookieOnly in-memory fallback)', () => {
 
     await manager.restoreFromCookies();
 
-    // Storage was never touched for the access token (cookieOnly contract holds).
+    // Storage was never touched for the access token.
     expect(storage.has('oxy_access_token')).toBe(false);
 
     // getAccessToken still resolves the active slot's token from memory.
@@ -369,7 +371,7 @@ describe('AuthManager.getAccessToken (cookieOnly in-memory fallback)', () => {
     expect(token).toBeNull();
   });
 
-  it('prefers the storage token over the in-memory token when both are present', async () => {
+  it('ignores a retired storage token when an in-memory cookie-restored token is present', async () => {
     const services = makeMockServices();
     services.refreshAllSessions.mockResolvedValueOnce(TWO_ACCOUNTS);
     const storage = new InMemoryStorage();
@@ -378,11 +380,11 @@ describe('AuthManager.getAccessToken (cookieOnly in-memory fallback)', () => {
     // After restore the in-memory token is TOKEN_SLOT_0.
     await manager.restoreFromCookies();
 
-    // Simulate a path that DID write storage (legacy/bearer flow). Storage wins.
+    // Simulate stale token material from a retired storage path. Memory wins.
     const STORAGE_TOKEN = buildAccessToken({ sessionId: 'sess-storage', userId: 'user-storage', exp: 9999999999 });
     storage.setItem('oxy_access_token', STORAGE_TOKEN);
 
     const token = await manager.getAccessToken();
-    expect(token).toBe(STORAGE_TOKEN);
+    expect(token).toBe(TOKEN_SLOT_0);
   });
 });