@oxyhq/services 13.3.0 → 14.0.0

package/src/ui/utils/activeAuthuser.ts

@@ -1,17 +1,23 @@
 /**
- * Web-only persistence of the active multi-account slot index.
+ * Web-only helpers around the retired `oxy_rt_${authuser}` multi-slot
+ * refresh-cookie scheme, PLUS the (unrelated, still load-bearing) deliberate
+ * sign-out / SSO-bounce gates.
  *
- * Google-style multi-account sign-in stores ONE refresh cookie per device
- * slot (`oxy_rt_${authuser}`, where `authuser` is an integer 0..N). The
- * server's `/auth/refresh-all` returns one entry per valid cookie; the
- * client must remember WHICH slot is currently active across reloads so
- * that the cold-boot snapshot resolves to the user's last selection
- * rather than always defaulting to slot 0.
- *
- * The persisted value is JUST the slot INDEX (a small integer) — never an
- * access token, refresh token, session id, or any user-identifying secret.
- * It is read by both `OxyContext` (cold-boot active selection) and the
- * session-management / auth-operations hooks (switch / logout).
+ * NOTE (session-sync cutover, Task 5): the device account SET is now
+ * server-authoritative via `SessionClient` (`@oxyhq/core`) — nothing in
+ * `@oxyhq/services` writes the persisted active-`authuser`-slot key anymore
+ * (`writeActiveAuthuser`/`clearActiveAuthuser` were deleted; their only
+ * callers were the deleted `establishDeviceRefreshSlot` sign-in registration
+ * and the deleted `switchToAccount`/`switchSession` slot bookkeeping).
+ * {@link readActiveAuthuser} is KEPT purely as an OPTIONAL restore hint:
+ * `OxyContext`'s `restoreStoredSession` cold-boot step reads it only to
+ * backfill `clientSession.authuser` for the active session when a legacy value
+ * happens to be present. It NO LONGER gates whether restore is attempted — the
+ * old guard that also required this marker made every web reload with a lapsed
+ * local bearer bail before any network validation (P0), and was replaced by a
+ * "bail only when there is nothing to restore" guard plus a valid-session
+ * election. Since nothing writes the key anymore, the backfill is dormant on
+ * fresh installs; it stays for legacy installs and costs nothing.
  *
  * Native (React Native) has no equivalent of these device-local cookies
  * and uses bearer-protected session ids directly, so these helpers no-op
@@ -30,22 +36,8 @@ import {
 
 const ACTIVE_AUTHUSER_KEY = 'oxy_active_authuser';
 
-/**
- * Safely resolve `window.localStorage`, returning `null` when it is
- * unavailable. The PROPERTY ACCESS itself (`window.localStorage`) can throw a
- * `SecurityError` synchronously in opaque-origin / sandboxed iframes or when
- * storage is disabled — even `typeof window.localStorage` evaluates the getter
- * and throws. Every read/write in this module routes through here so the getter
- * throw is caught once, at the source, and callers stay clean. Returns `null`
- * off-web and on any access failure (fail safe).
- */
-function getLocalStorage(): Storage | null {
-  if (typeof window === 'undefined') return null;
-  try {
-    return window.localStorage ?? null;
-  } catch {
-    return null;
-  }
+function hasLocalStorage(): boolean {
+  return typeof window !== 'undefined' && typeof window.localStorage !== 'undefined';
 }
 
 function getSessionStorage(): Storage | null {
@@ -65,12 +57,11 @@ function getSessionStorage(): Storage | null {
  * fall back to deterministic selection (lowest authuser).
  */
 export function readActiveAuthuser(): number | null {
-  const storage = getLocalStorage();
-  if (!storage) {
+  if (!hasLocalStorage()) {
     return null;
   }
   try {
-    const raw = storage.getItem(ACTIVE_AUTHUSER_KEY);
+    const raw = window.localStorage.getItem(ACTIVE_AUTHUSER_KEY);
     if (raw === null) return null;
     const parsed = Number.parseInt(raw, 10);
     if (!Number.isFinite(parsed) || parsed < 0) return null;
@@ -80,50 +71,18 @@ export function readActiveAuthuser(): number | null {
   }
 }
 
-/**
- * Persist the active `authuser` slot index. No-ops on native and on any
- * storage failure (e.g. Safari private mode). Callers MUST NOT depend on
- * this succeeding — it is best-effort UX persistence, not authoritative.
- */
-export function writeActiveAuthuser(authuser: number): void {
-  if (!Number.isFinite(authuser) || authuser < 0) return;
-  const storage = getLocalStorage();
-  if (!storage) return;
-  try {
-    storage.setItem(ACTIVE_AUTHUSER_KEY, String(authuser));
-  } catch {
-    // Best-effort persistence; swallow QuotaExceededError / SecurityError.
-  }
-}
-
-/**
- * Clear the persisted active `authuser` slot index. Called on full sign-out
- * (logoutAll) so that the next cold boot doesn't try to resurrect a
- * cleared slot.
- */
-export function clearActiveAuthuser(): void {
-  const storage = getLocalStorage();
-  if (!storage) return;
-  try {
-    storage.removeItem(ACTIVE_AUTHUSER_KEY);
-  } catch {
-    // Best-effort.
-  }
-}
-
 /**
  * Mark this origin as DELIBERATELY signed out (durable `localStorage`, via the
  * core {@link ssoSignedOutKey}). Called ONLY on EXPLICIT full sign-out so that
  * the next cold boot does NOT silently re-mint a session from a still-live IdP
- * session (`fedcm-silent` / per-apex `/auth/silent` iframe). Cleared by any
+ * session (the per-apex `/auth/silent` iframe cold-boot step). Cleared by any
  * deliberate sign-in (see {@link clearSignedOut}). No-ops on native / storage
  * failure (best-effort).
  */
 export function markSignedOut(): void {
-  const storage = getLocalStorage();
-  if (!storage) return;
+  if (!hasLocalStorage()) return;
   try {
-    storage.setItem(ssoSignedOutKey(window.location.origin), '1');
+    window.localStorage.setItem(ssoSignedOutKey(window.location.origin), '1');
   } catch {
     // Best-effort; swallow QuotaExceededError / SecurityError (private mode).
   }
@@ -131,15 +90,14 @@ export function markSignedOut(): void {
 
 /**
  * Clear the durable deliberately-signed-out flag. Called on ANY deliberate
- * sign-in (password, FedCM, account switch, device claim) so a real sign-in
+ * sign-in (password, account switch, device claim) so a real sign-in
  * fully re-enables automatic silent restore — there is no "stuck signed out"
  * state. No-ops on native / storage failure.
  */
 export function clearSignedOut(): void {
-  const storage = getLocalStorage();
-  if (!storage) return;
+  if (!hasLocalStorage()) return;
   try {
-    storage.removeItem(ssoSignedOutKey(window.location.origin));
+    window.localStorage.removeItem(ssoSignedOutKey(window.location.origin));
   } catch {
     // Best-effort.
   }
@@ -150,12 +108,14 @@ export function clearSignedOut(): void {
  * the user deliberately signed out. Reads the durable flag through the core
  * {@link silentRestoreSuppressed} predicate. Returns `false` off-web and on any
  * storage failure (fail safe toward normal restore). Used to gate the
- * `fedcm-silent` and `silent-iframe` cold-boot steps.
+ * `silent-iframe` cold-boot step.
  */
 export function isSilentRestoreSuppressed(): boolean {
-  const storage = getLocalStorage();
-  if (!storage) return false;
-  return silentRestoreSuppressed(storage, window.location.origin);
+  // Unlike its try/catch-wrapped siblings this reads `window.location.origin`
+  // directly, so guard it: an RN polyfill can expose `localStorage` without a
+  // `location`, which would throw here. Fail safe toward normal restore.
+  if (!hasLocalStorage() || typeof window.location === 'undefined') return false;
+  return silentRestoreSuppressed(window.localStorage, window.location.origin);
 }
 
 /**
@@ -180,5 +140,3 @@ export function clearSsoBounceState(): void {
     // Best-effort; swallow SecurityError (e.g. Safari private mode).
   }
 }
-
-export { ACTIVE_AUTHUSER_KEY };

package/src/ui/utils/sessionHelpers.ts

@@ -26,19 +26,6 @@ export interface FetchSessionsWithFallbackOptions {
   logger?: (message: string, error?: unknown) => void;
 }
 
-export interface ValidateSessionBatchOptions {
-  useHeaderValidation?: boolean;
-  maxConcurrency?: number;
-}
-
-export interface SessionValidationResult {
-  sessionId: string;
-  valid: boolean;
-  user?: unknown;
-  raw?: unknown;
-  error?: unknown;
-}
-
 /**
  * Normalize backend session payloads into `ClientSession` objects.
  *
@@ -99,56 +86,3 @@ export const fetchSessionsWithFallback = async (
   }
 };
 
-/**
- * Validate multiple sessions concurrently with configurable concurrency.
- *
- * @param oxyServices - Oxy service instance
- * @param sessionIds - Session identifiers to validate
- * @param options - Validation options
- */
-export const validateSessionBatch = async (
-  oxyServices: OxyServicesAny,
-  sessionIds: string[],
-  { useHeaderValidation = true, maxConcurrency = 5 }: ValidateSessionBatchOptions = {},
-): Promise<SessionValidationResult[]> => {
-  if (!sessionIds.length) {
-    return [];
-  }
-
-  const uniqueSessionIds = Array.from(new Set(sessionIds));
-  const safeConcurrency = Math.max(1, Math.min(maxConcurrency, uniqueSessionIds.length));
-  const results: SessionValidationResult[] = [];
-  let index = 0;
-
-  const worker = async () => {
-    while (index < uniqueSessionIds.length) {
-      const currentIndex = index;
-      index += 1;
-      const sessionId = uniqueSessionIds[currentIndex];
-
-      try {
-        const validation = await oxyServices.validateSession(sessionId, { useHeaderValidation });
-        const valid = Boolean(validation?.valid);
-
-        results.push({
-          sessionId,
-          valid,
-          user: validation?.user,
-          raw: validation,
-        });
-      } catch (error) {
-        results.push({
-          sessionId,
-          valid: false,
-          error,
-        });
-      }
-    }
-  };
-
-  await Promise.all(Array.from({ length: safeConcurrency }, worker));
-
-  return results;
-};
-
-

package/src/utils/__tests__/deviceFlowSignIn.test.ts

@@ -1,23 +1,34 @@
 /**
  * @jest-environment node
  *
- * Regression coverage for the NATIVE device-flow sign-in bug:
+ * Regression coverage for the device-flow sign-in bugs:
  *
- *   On native, tapping "Sign In with Oxy" opens `OxyAuthScreen`, which creates
- *   a device-flow AuthSession and opens auth.oxy.so/authorize. The user signs
- *   in successfully, the API authorizes the session and notifies the client via
- *   the auth-session socket — but the screen then called `switchSession`
- *   DIRECTLY without first claiming the bearer with the secret `sessionToken`.
- *   The session was authorized server-side but the app never became
- *   authenticated ("nothing happens").
+ *   BUG 1 (native): tapping "Sign In with Oxy" opens `OxyAuthScreen`, which
+ *   creates a device-flow AuthSession and opens auth.oxy.so/authorize. The
+ *   user signs in successfully, the API authorizes the session and notifies
+ *   the client via the auth-session socket — but the screen then called
+ *   `switchSession` DIRECTLY without first claiming the bearer with the
+ *   secret `sessionToken`. The session was authorized server-side but the app
+ *   never became authenticated ("nothing happens").
  *
- *   The web `SignInModal` already claimed first; the native screen did not.
- *   `completeDeviceFlowSignIn` consolidates the claim->switch sequence so both
- *   paths are identical. These tests pin the ORDER (claim before switch) and the
- *   fail-fast behaviour.
+ *   BUG 2 (session-sync cutover regression): once claiming was fixed,
+ *   `completeDeviceFlowSignIn` still committed the claimed session through
+ *   `switchSession`. After the session-sync cutover, `switchSession` became an
+ *   account-SWITCH between accounts already registered on the device and
+ *   throws `No device account found for session "..."` for a freshly-claimed
+ *   session that was never registered — surfacing as "Authorization
+ *   successful but failed to complete sign in." The fix commits the claimed
+ *   session through `commitSession` (`useOxy().handleWebSession`) instead —
+ *   the same path a fresh password sign-in uses to register the account
+ *   into the device's session set.
+ *
+ *   These tests pin the order (claim before commit), the fail-fast behaviour
+ *   on a claim that returns no usable session, and propagation of a
+ *   `commitSession` failure.
  */
 
-import type { User } from '@oxyhq/core';
+import type { SessionLoginResponse, User } from '@oxyhq/core';
+import { ssoStateKey, ssoGuardKey, ssoDestKey } from '@oxyhq/core';
 import {
   completeDeviceFlowSignIn,
   type DeviceFlowClient,
@@ -25,67 +36,159 @@ import {
 
 const SESSION_ID = 'session-id-123';
 const SESSION_TOKEN = 'a'.repeat(32);
-const USER = { id: 'user-1', username: 'nate', privacySettings: {} } as User;
+const ACCESS_TOKEN = 'access-token-abc';
+const USER = {
+  id: 'user-1',
+  username: 'nate',
+  name: { displayName: 'Nate' },
+  privacySettings: {},
+} as User;
+// The session carries only the minimal shape (`id`/`username`/`name`/`avatar`)
+// — this is what `commitSession` receives, not the full claimed `User`.
+const MINIMAL_USER = { id: USER.id, username: USER.username, name: USER.name, avatar: undefined };
 
 describe('completeDeviceFlowSignIn', () => {
-  it('claims the sessionToken BEFORE switching the session', async () => {
+  it('claims the sessionToken BEFORE committing the session', async () => {
     const order: string[] = [];
 
     const oxyServices: DeviceFlowClient = {
+      requestSsoEstablishUrl: jest.fn(async () => ({ establishUrl: 'https://auth.oxy.so/sso/establish' })),
       claimSessionByToken: jest.fn(async (token: string) => {
         expect(token).toBe(SESSION_TOKEN);
         order.push('claim');
+        return {
+          accessToken: ACCESS_TOKEN,
+          sessionId: SESSION_ID,
+          deviceId: 'device-1',
+          expiresAt: '2026-01-01T00:00:00.000Z',
+          user: USER,
+        };
       }),
     };
-    const switchSession = jest.fn(async (sessionId: string): Promise<User> => {
-      expect(sessionId).toBe(SESSION_ID);
-      order.push('switch');
-      return USER;
+    const commitSession = jest.fn(async (session: SessionLoginResponse): Promise<void> => {
+      expect(session).toEqual({
+        sessionId: SESSION_ID,
+        deviceId: 'device-1',
+        expiresAt: '2026-01-01T00:00:00.000Z',
+        user: MINIMAL_USER,
+        accessToken: ACCESS_TOKEN,
+      });
+      order.push('commit');
     });
 
     const user = await completeDeviceFlowSignIn({
       oxyServices,
       sessionId: SESSION_ID,
       sessionToken: SESSION_TOKEN,
-      switchSession,
+      commitSession,
     });
 
-    expect(order).toEqual(['claim', 'switch']);
+    expect(order).toEqual(['claim', 'commit']);
     expect(oxyServices.claimSessionByToken).toHaveBeenCalledWith(SESSION_TOKEN);
-    expect(switchSession).toHaveBeenCalledWith(SESSION_ID);
+    expect(commitSession).toHaveBeenCalledTimes(1);
     expect(user).toBe(USER);
   });
 
-  it('does NOT switch the session when the claim fails (the native regression)', async () => {
+  it('falls back to the delivered sessionId/deviceId/expiresAt when the claim omits them', async () => {
+    const oxyServices: DeviceFlowClient = {
+      requestSsoEstablishUrl: jest.fn(async () => ({ establishUrl: 'https://auth.oxy.so/sso/establish' })),
+      claimSessionByToken: jest.fn(async () => ({
+        accessToken: ACCESS_TOKEN,
+        user: USER,
+      })),
+    };
+    const commitSession = jest.fn(async (): Promise<void> => {});
+
+    await completeDeviceFlowSignIn({
+      oxyServices,
+      sessionId: SESSION_ID,
+      sessionToken: SESSION_TOKEN,
+      commitSession,
+    });
+
+    expect(commitSession).toHaveBeenCalledWith({
+      sessionId: SESSION_ID,
+      deviceId: '',
+      expiresAt: '',
+      user: MINIMAL_USER,
+      accessToken: ACCESS_TOKEN,
+    });
+  });
+
+  it('does NOT commit the session when the claim fails (the original native regression)', async () => {
     const claimError = new Error('claim failed (401)');
     const oxyServices: DeviceFlowClient = {
+      requestSsoEstablishUrl: jest.fn(async () => ({ establishUrl: 'https://auth.oxy.so/sso/establish' })),
       claimSessionByToken: jest.fn(async () => {
         throw claimError;
       }),
     };
-    const switchSession = jest.fn(async (): Promise<User> => USER);
+    const commitSession = jest.fn(async (): Promise<void> => {});
 
     await expect(
       completeDeviceFlowSignIn({
         oxyServices,
         sessionId: SESSION_ID,
         sessionToken: SESSION_TOKEN,
-        switchSession,
+        commitSession,
       }),
     ).rejects.toThrow('claim failed (401)');
 
     // The bearer was never planted, so we must not attempt the bearer-protected
-    // switch — surfacing the failure to the caller instead.
-    expect(switchSession).not.toHaveBeenCalled();
+    // commit — surfacing the failure to the caller instead.
+    expect(commitSession).not.toHaveBeenCalled();
+  });
+
+  it('throws when the claim returns no accessToken (the session-sync regression guard)', async () => {
+    const oxyServices: DeviceFlowClient = {
+      requestSsoEstablishUrl: jest.fn(async () => ({ establishUrl: 'https://auth.oxy.so/sso/establish' })),
+      claimSessionByToken: jest.fn(async () => ({ sessionId: SESSION_ID, user: USER })),
+    };
+    const commitSession = jest.fn(async (): Promise<void> => {});
+
+    await expect(
+      completeDeviceFlowSignIn({
+        oxyServices,
+        sessionId: SESSION_ID,
+        sessionToken: SESSION_TOKEN,
+        commitSession,
+      }),
+    ).rejects.toThrow('Device-flow claim did not return a usable session');
+
+    expect(commitSession).not.toHaveBeenCalled();
+  });
+
+  it('throws when the claim returns no user', async () => {
+    const oxyServices: DeviceFlowClient = {
+      requestSsoEstablishUrl: jest.fn(async () => ({ establishUrl: 'https://auth.oxy.so/sso/establish' })),
+      claimSessionByToken: jest.fn(async () => ({ accessToken: ACCESS_TOKEN, sessionId: SESSION_ID })),
+    };
+    const commitSession = jest.fn(async (): Promise<void> => {});
+
+    await expect(
+      completeDeviceFlowSignIn({
+        oxyServices,
+        sessionId: SESSION_ID,
+        sessionToken: SESSION_TOKEN,
+        commitSession,
+      }),
+    ).rejects.toThrow('Device-flow claim did not return a usable session');
+
+    expect(commitSession).not.toHaveBeenCalled();
   });
 
-  it('propagates a switchSession failure after a successful claim', async () => {
-    const switchError = new Error('session invalid');
+  it('propagates a commitSession failure after a successful claim', async () => {
+    const commitError = new Error('session invalid');
     const oxyServices: DeviceFlowClient = {
-      claimSessionByToken: jest.fn(async () => undefined),
+      requestSsoEstablishUrl: jest.fn(async () => ({ establishUrl: 'https://auth.oxy.so/sso/establish' })),
+      claimSessionByToken: jest.fn(async () => ({
+        accessToken: ACCESS_TOKEN,
+        sessionId: SESSION_ID,
+        user: USER,
+      })),
     };
-    const switchSession = jest.fn(async (): Promise<User> => {
-      throw switchError;
+    const commitSession = jest.fn(async (): Promise<void> => {
+      throw commitError;
     });
 
     await expect(
@@ -93,11 +196,117 @@ describe('completeDeviceFlowSignIn', () => {
         oxyServices,
         sessionId: SESSION_ID,
         sessionToken: SESSION_TOKEN,
-        switchSession,
+        commitSession,
       }),
     ).rejects.toThrow('session invalid');
 
     expect(oxyServices.claimSessionByToken).toHaveBeenCalledTimes(1);
-    expect(switchSession).toHaveBeenCalledTimes(1);
+    expect(commitSession).toHaveBeenCalledTimes(1);
+  });
+
+  describe('web durable-session establish hop', () => {
+    const RP_ORIGIN = 'https://accounts.oxy.so';
+    const RP_HREF = 'https://accounts.oxy.so/settings';
+    const ESTABLISH_URL =
+      'https://auth.oxy.so/sso/establish?et=jwt&return_to=https%3A%2F%2Faccounts.oxy.so%2F__oxy%2Fsso-callback&state=state-1';
+
+    function webDeps(overrides: Record<string, unknown> = {}) {
+      const map = new Map<string, string>();
+      const navigated: string[] = [];
+      const deps = {
+        isWeb: () => true,
+        storage: {
+          getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+          setItem: (k: string, v: string) => { map.set(k, v); },
+        },
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url: string) => { navigated.push(url); },
+        generateState: () => 'state-1',
+        now: () => 1_700_000_000_000,
+        ...overrides,
+      };
+      return { deps, map, navigated };
+    }
+
+    function baseClient(
+      requestSsoEstablishUrl: DeviceFlowClient['requestSsoEstablishUrl'],
+    ): DeviceFlowClient {
+      return {
+        requestSsoEstablishUrl,
+        claimSessionByToken: jest.fn(async () => ({
+          accessToken: ACCESS_TOKEN,
+          sessionId: SESSION_ID,
+          deviceId: 'device-1',
+          expiresAt: '2026-01-01T00:00:00.000Z',
+          user: USER,
+        })),
+      };
+    }
+
+    it('fires the establish hop on web: requests the URL with the RP origin + state and navigates once', async () => {
+      const requestSsoEstablishUrl = jest.fn(async (origin: string, state: string) => {
+        expect(origin).toBe(RP_ORIGIN);
+        expect(state).toBe('state-1');
+        return { establishUrl: ESTABLISH_URL };
+      });
+      const oxyServices = baseClient(requestSsoEstablishUrl);
+      const { deps, map, navigated } = webDeps();
+
+      const user = await completeDeviceFlowSignIn({
+        oxyServices,
+        sessionId: SESSION_ID,
+        sessionToken: SESSION_TOKEN,
+        commitSession: jest.fn(async () => {}),
+        establishDeps: deps,
+      });
+
+      expect(user).toBe(USER);
+      expect(requestSsoEstablishUrl).toHaveBeenCalledTimes(1);
+      expect(navigated).toEqual([ESTABLISH_URL]);
+      // Bounce state persisted so the post-bounce `sso-return` step validates it.
+      expect(map.get(ssoStateKey(RP_ORIGIN))).toBe('state-1');
+      expect(map.get(ssoGuardKey(RP_ORIGIN))).toBe(String(1_700_000_000_000));
+      expect(map.get(ssoDestKey(RP_ORIGIN))).toBe(RP_HREF);
+    });
+
+    it('does NOT fire the hop on native (no request, no navigation)', async () => {
+      const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: ESTABLISH_URL }));
+      const oxyServices = baseClient(requestSsoEstablishUrl);
+      const { deps, navigated } = webDeps({ isWeb: () => false });
+
+      await completeDeviceFlowSignIn({
+        oxyServices,
+        sessionId: SESSION_ID,
+        sessionToken: SESSION_TOKEN,
+        commitSession: jest.fn(async () => {}),
+        establishDeps: deps,
+      });
+
+      expect(requestSsoEstablishUrl).not.toHaveBeenCalled();
+      expect(navigated).toEqual([]);
+    });
+
+    it('completes sign-in even if the establish request fails — exactly one attempt, no navigation', async () => {
+      const requestSsoEstablishUrl = jest.fn(async () => {
+        throw new Error('403 unapproved');
+      });
+      const oxyServices = baseClient(requestSsoEstablishUrl);
+      const { deps, map, navigated } = webDeps();
+
+      const user = await completeDeviceFlowSignIn({
+        oxyServices,
+        sessionId: SESSION_ID,
+        sessionToken: SESSION_TOKEN,
+        commitSession: jest.fn(async () => {}),
+        establishDeps: deps,
+      });
+
+      // Sign-in still completed (the primitive is total — never throws).
+      expect(user).toBe(USER);
+      expect(requestSsoEstablishUrl).toHaveBeenCalledTimes(1);
+      expect(navigated).toEqual([]);
+      // No stale bounce state left behind on failure.
+      expect(map.size).toBe(0);
+    });
   });
 });