@oxyhq/services 14.1.0 → 15.0.0

package/src/ui/session/__tests__/tokenTransport.test.ts

@@ -1,19 +1,22 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
-import { logger } from '@oxyhq/core';
+import { logger, createMemoryAuthStateStore, refreshPersistedSession } from '@oxyhq/core';
 import { createTokenTransport } from '../tokenTransport';
-import { isWebBrowser } from '../../hooks/useWebSSO';
 
-jest.mock('../../hooks/useWebSSO', () => ({
-  isWebBrowser: jest.fn(),
-}));
+// The device-first transport mints a fallback token by rotating the persisted
+// refresh family via `refreshPersistedSession` (the ONE unified refresh path) —
+// there is no `silentSignIn`/`signInWithSharedIdentity` arm anymore. Mock that
+// one core function so the transport's own coalescing / logging contract can be
+// exercised in isolation; keep the real `logger` + memory store.
+jest.mock('@oxyhq/core', () => {
+  const actual = jest.requireActual('@oxyhq/core');
+  return { __esModule: true, ...actual, refreshPersistedSession: jest.fn() };
+});
 
-const mockedIsWebBrowser = isWebBrowser as jest.MockedFunction<typeof isWebBrowser>;
+const mockedRefresh = refreshPersistedSession as jest.MockedFunction<typeof refreshPersistedSession>;
 
 function fakeOxy(accessToken: string | null) {
   return {
     getAccessToken: jest.fn().mockReturnValue(accessToken),
-    silentSignIn: jest.fn().mockResolvedValue(null),
-    signInWithSharedIdentity: jest.fn().mockResolvedValue(null),
   };
 }
 
@@ -28,51 +31,39 @@ const state: DeviceSessionState = {
 describe('createTokenTransport', () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    mockedRefresh.mockResolvedValue('minted-token');
   });
 
   test('no-ops when a token is already present', async () => {
     const oxy = fakeOxy('tok');
-    const transport = createTokenTransport(oxy as never);
-
-    await transport.ensureActiveToken(state);
-
-    expect(oxy.silentSignIn).not.toHaveBeenCalled();
-    expect(oxy.signInWithSharedIdentity).not.toHaveBeenCalled();
-  });
-
-  test('mints via silentSignIn on web when no token is present', async () => {
-    mockedIsWebBrowser.mockReturnValue(true);
-    const oxy = fakeOxy(null);
-    const transport = createTokenTransport(oxy as never);
+    const transport = createTokenTransport(oxy as never, createMemoryAuthStateStore());
 
     await transport.ensureActiveToken(state);
 
-    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
-    expect(oxy.signInWithSharedIdentity).not.toHaveBeenCalled();
+    expect(mockedRefresh).not.toHaveBeenCalled();
   });
 
-  test('mints via signInWithSharedIdentity off web when no token is present', async () => {
-    mockedIsWebBrowser.mockReturnValue(false);
+  test('mints via refreshPersistedSession when no token is present', async () => {
     const oxy = fakeOxy(null);
-    const transport = createTokenTransport(oxy as never);
+    const store = createMemoryAuthStateStore();
+    const transport = createTokenTransport(oxy as never, store);
 
     await transport.ensureActiveToken(state);
 
-    expect(oxy.signInWithSharedIdentity).toHaveBeenCalledTimes(1);
-    expect(oxy.silentSignIn).not.toHaveBeenCalled();
+    expect(mockedRefresh).toHaveBeenCalledTimes(1);
+    expect(mockedRefresh).toHaveBeenCalledWith({ oxy, store });
   });
 
-  test('resolves (never rejects) and logs a warning when the mint throws', async () => {
-    mockedIsWebBrowser.mockReturnValue(true);
+  test('resolves (never rejects) and logs a warning when the refresh throws', async () => {
     const oxy = fakeOxy(null);
-    oxy.silentSignIn.mockRejectedValue(new Error('mint boom'));
-    const transport = createTokenTransport(oxy as never);
+    mockedRefresh.mockRejectedValue(new Error('mint boom'));
+    const transport = createTokenTransport(oxy as never, createMemoryAuthStateStore());
     const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
 
     await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
 
     expect(warnSpy).toHaveBeenCalledWith(
-      'ensureActiveToken: mint failed',
+      'ensureActiveToken: refresh failed',
       { component: 'TokenTransport' },
       expect.any(Error),
     );
@@ -80,52 +71,49 @@ describe('createTokenTransport', () => {
     warnSpy.mockRestore();
   });
 
-  test('resolves cleanly when the mint returns null', async () => {
-    mockedIsWebBrowser.mockReturnValue(true);
+  test('resolves cleanly when the refresh produces no session', async () => {
     const oxy = fakeOxy(null);
-    const transport = createTokenTransport(oxy as never);
+    mockedRefresh.mockResolvedValue(null);
+    const transport = createTokenTransport(oxy as never, createMemoryAuthStateStore());
 
     await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
-    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+    expect(mockedRefresh).toHaveBeenCalledTimes(1);
   });
 
   test('coalesces concurrent calls into a single mint', async () => {
-    mockedIsWebBrowser.mockReturnValue(true);
     const oxy = fakeOxy(null);
-    let resolveMint: ((value: null) => void) | null = null;
-    oxy.silentSignIn.mockImplementation(
+    let resolveMint: ((value: string | null) => void) | null = null;
+    mockedRefresh.mockImplementation(
       () =>
-        new Promise((resolve) => {
+        new Promise<string | null>((resolve) => {
           resolveMint = resolve;
         }),
     );
-    const transport = createTokenTransport(oxy as never);
+    const transport = createTokenTransport(oxy as never, createMemoryAuthStateStore());
 
     const first = transport.ensureActiveToken(state);
     const second = transport.ensureActiveToken(state);
 
-    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+    expect(mockedRefresh).toHaveBeenCalledTimes(1);
 
     resolveMint?.(null);
     await Promise.all([first, second]);
 
-    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+    expect(mockedRefresh).toHaveBeenCalledTimes(1);
 
-    // A later call after the in-flight mint settled starts a fresh mint
-    // (the mock reassigns `resolveMint` on the second silentSignIn call).
+    // A later call after the in-flight mint settled starts a fresh mint.
     const third = transport.ensureActiveToken(state);
-    expect(oxy.silentSignIn).toHaveBeenCalledTimes(2);
+    expect(mockedRefresh).toHaveBeenCalledTimes(2);
     resolveMint?.(null);
     await third;
   });
 
   test('treats a throwing getAccessToken as no-token and still mints', async () => {
-    mockedIsWebBrowser.mockReturnValue(true);
     const oxy = fakeOxy(null);
     oxy.getAccessToken.mockImplementation(() => {
       throw new Error('storage unavailable');
     });
-    const transport = createTokenTransport(oxy as never);
+    const transport = createTokenTransport(oxy as never, createMemoryAuthStateStore());
     const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
 
     await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
@@ -135,7 +123,7 @@ describe('createTokenTransport', () => {
       { component: 'TokenTransport' },
       expect.any(Error),
     );
-    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+    expect(mockedRefresh).toHaveBeenCalledTimes(1);
 
     warnSpy.mockRestore();
   });

package/src/ui/session/authStore.ts

@@ -0,0 +1,164 @@
+/**
+ * Platform `AuthStateStore` for `@oxyhq/services`.
+ *
+ * The device-first session model persists the rotating refresh-token family
+ * head per origin (web) / per device (native). `@oxyhq/core` owns the store
+ * shape + logic (`createWebAuthStateStore` / `createNativeAuthStateStore`); this
+ * module only supplies the platform storage seam and wires the native device
+ * token to the SHARED keychain so every native Oxy app joins one DeviceSession:
+ *
+ *  - web  → `createWebAuthStateStore()` (localStorage, in-memory fallback).
+ *  - native → `createNativeAuthStateStore(secureKV)` for the SESSION blob
+ *    (refresh token) over `expo-secure-store` (AsyncStorage fallback), with the
+ *    long-lived DEVICE token delegated to `KeyManager`'s shared keychain
+ *    (`group.so.oxy.shared`) instead of per-app storage — so an in-app login on
+ *    any native Oxy app attributes to the SAME server-side DeviceSession.
+ *
+ * `expo-secure-store` is loaded via a runtime-computed dynamic import (the same
+ * optional-native-module pattern `OxyProvider` uses for netinfo / keyboard
+ * controller), so the web bundle never pulls it and a device without it falls
+ * back to AsyncStorage rather than crashing.
+ */
+import {
+  KeyManager,
+  createWebAuthStateStore,
+  createNativeAuthStateStore,
+  type AuthStateStore,
+  type NativeKeyValueStorage,
+  logger,
+} from '@oxyhq/core';
+import { createPlatformStorage, isReactNative } from '../utils/storageHelpers';
+
+// Variable indirection so Metro's static analyzer never traces expo-secure-store
+// into the web bundle; the module is native-only and optional.
+const SECURE_STORE_MODULE = 'expo-secure-store';
+
+interface SecureStoreLike {
+  getItemAsync(key: string): Promise<string | null>;
+  setItemAsync(key: string, value: string): Promise<void>;
+  deleteItemAsync(key: string): Promise<void>;
+}
+
+let secureStorePromise: Promise<SecureStoreLike | null> | null = null;
+
+/**
+ * Resolve the `expo-secure-store` module once (memoised), or `null` when it is
+ * unavailable — callers then fall back to AsyncStorage. Never throws.
+ */
+function loadSecureStore(): Promise<SecureStoreLike | null> {
+  if (!secureStorePromise) {
+    const moduleName = SECURE_STORE_MODULE;
+    secureStorePromise = import(moduleName)
+      .then((mod: Partial<SecureStoreLike>) => {
+        if (
+          typeof mod.getItemAsync === 'function' &&
+          typeof mod.setItemAsync === 'function' &&
+          typeof mod.deleteItemAsync === 'function'
+        ) {
+          return {
+            getItemAsync: mod.getItemAsync.bind(mod),
+            setItemAsync: mod.setItemAsync.bind(mod),
+            deleteItemAsync: mod.deleteItemAsync.bind(mod),
+          } satisfies SecureStoreLike;
+        }
+        return null;
+      })
+      .catch(() => null);
+  }
+  return secureStorePromise;
+}
+
+/**
+ * A native `NativeKeyValueStorage` that prefers `expo-secure-store` (encrypted
+ * at rest) and falls back to AsyncStorage when SecureStore is not installed.
+ * The SecureStore module is resolved lazily on first access so construction
+ * stays synchronous.
+ */
+function createNativeSecureKeyValueStorage(): NativeKeyValueStorage {
+  let asyncStorage: Awaited<ReturnType<typeof createPlatformStorage>> | null = null;
+  const getAsyncStorage = async () => {
+    if (!asyncStorage) {
+      asyncStorage = await createPlatformStorage();
+    }
+    return asyncStorage;
+  };
+  return {
+    getItem: async (key) => {
+      const secure = await loadSecureStore();
+      if (secure) {
+        return secure.getItemAsync(key);
+      }
+      return (await getAsyncStorage()).getItem(key);
+    },
+    setItem: async (key, value) => {
+      const secure = await loadSecureStore();
+      if (secure) {
+        await secure.setItemAsync(key, value);
+        return;
+      }
+      await (await getAsyncStorage()).setItem(key, value);
+    },
+    removeItem: async (key) => {
+      const secure = await loadSecureStore();
+      if (secure) {
+        await secure.deleteItemAsync(key);
+        return;
+      }
+      await (await getAsyncStorage()).removeItem(key);
+    },
+  };
+}
+
+/**
+ * Build the platform {@link AuthStateStore} for this runtime.
+ *
+ * Native additionally routes the device token through the shared keychain so
+ * every native Oxy app shares one server-side DeviceSession; the session blob
+ * (refresh token) stays per-app in SecureStore. Best-effort keychain access —
+ * a locked/failed shared-keychain read degrades to "no device token" rather
+ * than throwing out of cold boot / refresh.
+ */
+export function createPlatformAuthStateStore(): AuthStateStore {
+  if (!isReactNative()) {
+    return createWebAuthStateStore();
+  }
+
+  const base = createNativeAuthStateStore(createNativeSecureKeyValueStorage());
+  return {
+    ...base,
+    loadDeviceToken: async () => {
+      try {
+        return await KeyManager.getSharedDeviceToken();
+      } catch (error) {
+        logger.debug(
+          'Shared device-token read failed (treating as none)',
+          { component: 'authStore', method: 'loadDeviceToken' },
+          error,
+        );
+        return null;
+      }
+    },
+    saveDeviceToken: async (token) => {
+      try {
+        await KeyManager.setSharedDeviceToken(token);
+      } catch (error) {
+        logger.debug(
+          'Shared device-token write failed (non-fatal)',
+          { component: 'authStore', method: 'saveDeviceToken' },
+          error,
+        );
+      }
+    },
+    clearDeviceToken: async () => {
+      try {
+        await KeyManager.clearSharedDeviceToken();
+      } catch (error) {
+        logger.debug(
+          'Shared device-token clear failed (non-fatal)',
+          { component: 'authStore', method: 'clearDeviceToken' },
+          error,
+        );
+      }
+    },
+  };
+}

package/src/ui/session/createSessionClient.ts

@@ -1,29 +1,42 @@
-import type { OxyServices } from '@oxyhq/core';
-import { SessionClient } from '@oxyhq/core';
 import { io } from 'socket.io-client';
-import { createSessionClientHost } from './sessionClientHost';
+import {
+  SessionClient,
+  createSessionClientHost,
+  type AuthStateStore,
+  type OxyServices,
+} from '@oxyhq/core';
 import { createTokenTransport } from './tokenTransport';
 
 /**
- * Wires a `SessionClient` for `@oxyhq/services`: builds the `SessionClientHost`
- * adapter (Task 1) and the platform `TokenTransport` (Task 3) over the given
- * `OxyServices` instance, and returns both the client and the host — the host
- * is returned (not just the client) so `OxyContext` (Fase 3-B) can call
- * `host.setCurrentAccountId(...)` as the active account changes.
+ * Wire a `SessionClient` for `@oxyhq/services`.
  *
- * `socket.io-client`'s `io` is STATICALLY imported and injected as the
- * `SessionClient` `socketFactory` (socket.io-client is a real dependency of
- * `@oxyhq/services`). This is what keeps realtime session sync working in the
- * Metro/Expo-web bundle: core's lazy dynamic `import('socket.io-client')` of a
- * bare specifier does not resolve reliably against the published core dist, so
- * the app-bundled static import is the reliable source of the factory.
+ * The platform-agnostic parts (host adapter, client, projection helpers) live
+ * ONCE in `@oxyhq/core`; this thin factory only injects the pieces specific to
+ * the RN/Expo SDK:
+ *
+ *  - `socket.io-client`'s `io`, STATICALLY imported (socket.io-client is a real
+ *    dependency of `@oxyhq/services`) so realtime session sync never relies on
+ *    core's lazy dynamic import of a bare specifier — bundler-fragile in
+ *    Metro/Expo-web against the published core dist.
+ *  - the device-first {@link createTokenTransport}, which mints a fallback token
+ *    by rotating the persisted refresh family (`store`).
+ *
+ * `onUnauthenticated` fires when an applied device state has zero accounts (a
+ * device signout-all): the provider clears the persisted store + local state so
+ * a reload does not try to restore a dead session. The host is returned
+ * alongside the client so the caller can call `host.setCurrentAccountId(...)`
+ * as the active account changes.
  */
-export function createSessionClient(oxyServices: OxyServices): {
+export function createSessionClient(
+  oxyServices: OxyServices,
+  store: AuthStateStore,
+  onUnauthenticated?: () => void,
+): {
   client: SessionClient;
   host: ReturnType<typeof createSessionClientHost>;
 } {
   const host = createSessionClientHost(oxyServices);
-  const transport = createTokenTransport(oxyServices);
-  const client = new SessionClient(host, { transport, socketFactory: io });
+  const transport = createTokenTransport(oxyServices, store);
+  const client = new SessionClient(host, { transport, socketFactory: io, onUnauthenticated });
   return { client, host };
 }

package/src/ui/session/index.ts

@@ -1,19 +1,20 @@
 /**
- * Session-sync integration layer (Fase 3-A) — intra-package use only.
+ * Session-sync integration layer — intra-package use only.
  *
- * These modules let `@oxyhq/services` drive the platform-agnostic
- * `SessionClient` (in `@oxyhq/core`): a thin host adapter over `OxyServices`,
- * pure `DeviceSessionState → services` projection helpers, a platform token
- * transport, and the factory that wires them together. Nothing here is
- * re-exported from the package root — `OxyContext` consumes it directly in
- * Fase 3-B.
+ * `@oxyhq/core` owns the platform-agnostic `SessionClient`, its host adapter,
+ * and the pure `DeviceSessionState → services` projection helpers; those are
+ * re-exported straight from core here so `OxyContext` has one import site.
+ * `@oxyhq/services` supplies only the two platform pieces: the thin
+ * `createSessionClient` factory (injects socket.io-client `io` + the
+ * device-first token transport) and the `AuthStateStore` factory.
  */
 export { createSessionClient } from './createSessionClient';
-export { createSessionClientHost } from './sessionClientHost';
 export { createTokenTransport } from './tokenTransport';
+export { createPlatformAuthStateStore } from './authStore';
 export {
+  createSessionClientHost,
   accountIdsOf,
   activeSessionIdOf,
   activeUserOf,
   deviceStateToClientSessions,
-} from './projectSessionState';
+} from '@oxyhq/core';

package/src/ui/session/tokenTransport.ts

@@ -1,42 +1,35 @@
+import {
+  refreshPersistedSession,
+  logger,
+  type AuthStateStore,
+  type OxyServices,
+  type TokenTransport,
+} from '@oxyhq/core';
 import type { DeviceSessionState } from '@oxyhq/contracts';
-import type { OxyServices, TokenTransport } from '@oxyhq/core';
-import { logger } from '@oxyhq/core';
-import { isWebBrowser } from '../hooks/useWebSSO';
 
 /**
- * Platform `TokenTransport` for `SessionClient`: mints an access token when
- * none is currently held, reusing the SAME primitives `OxyContext`'s cold
- * boot already relies on (never re-implemented here):
+ * Platform `TokenTransport` for `SessionClient` (device-first model).
  *
- * - web: `oxyServices.silentSignIn()` (per-apex `/auth/silent` iframe).
- * - native: `oxyServices.signInWithSharedIdentity()` (app-group keychain).
+ * `ensureActiveToken` is the fallback the client uses when a `session_state`
+ * push arrived WITHOUT an embedded `activeToken` and the app currently holds no
+ * bearer. It mints one through the ONE unified refresh path
+ * (`refreshPersistedSession`): rotate the persisted refresh-token family
+ * (`POST /auth/refresh-token`) and, on native, fall back to the shared-keychain
+ * re-mint. There is no FedCM/silent-iframe arm anymore — the per-origin
+ * persisted refresh token is the durable web credential.
  *
- * Both primitives plant the token internally on success (the "Sign-In Token
- * Planting" rule) — `ensureActiveToken` never calls `setTokens` itself.
- *
- * `ensureActiveToken` treats a PRESENT token as sufficient in this phase; it
- * does not decode/match the token's subject against `state.activeAccountId`
- * (that refinement is Fase 3-B). Account switching itself is server-driven
- * via the `activeToken` carried in the sync envelope — this transport is
- * only the fallback used when the envelope carried no token.
- *
- * A failed mint is logged and swallowed: it must never throw out of
- * `ensureActiveToken`, since that would crash the caller (the SessionClient
- * socket handler in Fase 3-B).
+ * Concurrent pushes coalesce onto one in-flight mint. A failure is logged and
+ * swallowed: this method must never throw out (it runs inside the socket state
+ * handler).
  */
-export function createTokenTransport(oxyServices: OxyServices): TokenTransport {
-  // Coalesces concurrent mints: `SessionClient.applyState` can fire
-  // `ensureActiveToken` on rapid successive state pushes; a second call while a
-  // mint is already in flight must reuse it, not spawn a second silent iframe /
-  // shared-key challenge round-trip.
+export function createTokenTransport(
+  oxyServices: OxyServices,
+  store: AuthStateStore,
+): TokenTransport {
   let inFlightMint: Promise<void> | null = null;
 
   return {
     async ensureActiveToken(state: DeviceSessionState): Promise<void> {
-      // Read the current token defensively: it is an in-memory getter that
-      // should never throw, but the documented contract is that this method
-      // never throws out — so a surprising throw is logged and treated as "no
-      // token" (fall through to mint) rather than rejecting the promise.
       try {
         if (oxyServices.getAccessToken()) {
           return;
@@ -51,18 +44,15 @@ export function createTokenTransport(oxyServices: OxyServices): TokenTransport {
 
       inFlightMint = (async () => {
         try {
-          const session = isWebBrowser()
-            ? await oxyServices.silentSignIn()
-            : await oxyServices.signInWithSharedIdentity();
-
-          if (!session) {
-            logger.debug('ensureActiveToken: platform mint returned no session', {
+          const token = await refreshPersistedSession({ oxy: oxyServices, store });
+          if (!token) {
+            logger.debug('ensureActiveToken: refresh produced no session', {
               component: 'TokenTransport',
               deviceId: state.deviceId,
             });
           }
         } catch (error) {
-          logger.warn('ensureActiveToken: mint failed', { component: 'TokenTransport' }, error);
+          logger.warn('ensureActiveToken: refresh failed', { component: 'TokenTransport' }, error);
         }
       })();
 

package/src/ui/utils/isWebBrowser.ts

@@ -0,0 +1,8 @@
+/**
+ * Web-browser detection for `@oxyhq/services`.
+ *
+ * The predicate now lives ONCE in `@oxyhq/core` (`isWebBrowser`) so services and
+ * auth-sdk share the exact same DOM probe. This module re-exposes it under the
+ * existing internal import path so consumers stay unchanged.
+ */
+export { isWebBrowser } from '@oxyhq/core';