@oxy.so/services 1.0.0

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

@@ -0,0 +1,289 @@
+/**
+ * The platform half of the shared DeviceSession credential.
+ *
+ * `@oxy.so/core` owns and tests the RULES; what is pinned here is the mapping from
+ * each platform's failure shapes onto them — and that mapping is where the
+ * dangerous mistake lives. `expo-secure-store` returns `null` for a missing item
+ * and THROWS when the keychain refuses; the Android broker answers with an
+ * explicit status. Collapsing either failure into "absent" is what would let a
+ * locked device look like one that never had a session.
+ */
+import type { SharedDeviceCredentialStore } from '@oxy.so/core';
+
+const CRED = { deviceId: 'dev-shared', deviceSecret: 'ds-shared' };
+const STORAGE_KEY = 'oxy_shared_device_session_v1';
+
+/** A minimal in-memory `expo-secure-store` that records the options it was given. */
+function makeSecureStoreMock() {
+  const items = new Map<string, string>();
+  const calls: { key: string; options?: Record<string, unknown> }[] = [];
+  let readError: Error | null = null;
+  let writeError: Error | null = null;
+  /** When set, `setItemAsync` resolves but nothing lands — the phantom-write case. */
+  let swallowWrites = false;
+  return {
+    items,
+    calls,
+    setReadError: (error: Error | null) => {
+      readError = error;
+    },
+    setWriteError: (error: Error | null) => {
+      writeError = error;
+    },
+    setSwallowWrites: (value: boolean) => {
+      swallowWrites = value;
+    },
+    module: {
+      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 3,
+      getItemAsync: async (key: string, options?: Record<string, unknown>) => {
+        calls.push({ key, options });
+        if (readError) {
+          throw readError;
+        }
+        return items.get(key) ?? null;
+      },
+      setItemAsync: async (key: string, value: string, options?: Record<string, unknown>) => {
+        calls.push({ key, options });
+        if (writeError) {
+          throw writeError;
+        }
+        if (!swallowWrites) {
+          items.set(key, value);
+        }
+      },
+      deleteItemAsync: async (key: string, options?: Record<string, unknown>) => {
+        calls.push({ key, options });
+        items.delete(key);
+      },
+    },
+  };
+}
+
+type BrokerModule = {
+  read(): Promise<unknown>;
+  write(deviceId: string, deviceSecret: string): Promise<boolean>;
+  clear(): Promise<void>;
+};
+
+/**
+ * Load the module fresh, with `Platform.OS` set and both native seams mocked.
+ *
+ * Two things here are load-bearing and were each got wrong first:
+ *
+ *  - `jest.resetModules()` + `require`, NOT `jest.isolateModules`. The module
+ *    memoises its keychain and broker handles at module scope, so it must be
+ *    re-required per case — and with `isolateModules` a mock factory registered
+ *    in one block leaked into the next block's module, so a test's own mock was
+ *    silently ignored and its assertions read the PREVIOUS test's store.
+ *  - `Platform.OS` is set on the instance in the CURRENT registry. A reset hands
+ *    out a fresh `react-native` mock whose `OS` is back to its `'web'` default,
+ *    so mutating an instance captured earlier leaves the code under test on the
+ *    web branch and every platform assertion passes vacuously.
+ */
+function loadStore(
+  os: 'ios' | 'android' | 'web',
+  seams: { secureStore?: ReturnType<typeof makeSecureStoreMock>; broker?: BrokerModule | null } = {},
+): SharedDeviceCredentialStore | null {
+  jest.resetModules();
+  jest.doMock('expo-modules-core', () => ({
+    requireOptionalNativeModule: () => seams.broker ?? null,
+    requireNativeModule: () => {
+      throw new Error('not available');
+    },
+  }));
+  // NOT `{ virtual: true }`: a virtual mock is keyed to the directory of the
+  // file that declared it, so one declared here would be invisible to the module
+  // under test two directories up — it would silently keep resolving
+  // `unsupported`. `expo-secure-store` is installed in the workspace, so the
+  // ordinary mock registers against its real resolved path. With no mock given,
+  // model the module being ABSENT.
+  const secureStoreModule = seams.secureStore?.module;
+  jest.doMock('expo-secure-store', () => {
+    if (!secureStoreModule) {
+      throw new Error("Cannot find module 'expo-secure-store'");
+    }
+    return secureStoreModule;
+  });
+  const rn = require('react-native') as { Platform: { OS: string } };
+  rn.Platform.OS = os;
+  const mod = require('../sharedDeviceCredentialStore') as typeof import('../sharedDeviceCredentialStore');
+  return mod.createPlatformSharedDeviceCredentialStore();
+}
+
+afterEach(() => {
+  jest.dontMock('expo-modules-core');
+  jest.dontMock('expo-secure-store');
+  jest.resetModules();
+});
+
+describe('createPlatformSharedDeviceCredentialStore', () => {
+  test('web has no shared slot at all', () => {
+    // Each web origin is its own device by design; there is nothing to join.
+    expect(loadStore('web')).toBeNull();
+    // Positive control: `null` must mean "web", not "the harness never reached
+    // the platform branch" — the failure mode this whole harness had once.
+    expect(loadStore('android', { broker: null })).not.toBeNull();
+    expect(loadStore('ios')).not.toBeNull();
+  });
+
+  test('iOS uses the keychain, not the Android broker', async () => {
+    // The branch is on the platform because `expo-secure-store` LOADS on Android
+    // too — it would just ignore the access group and read a package-private
+    // item, which is indistinguishable from an empty shared slot.
+    const secureStore = makeSecureStoreMock();
+    const broker: BrokerModule = {
+      read: jest.fn(async () => ({ status: 'present', ...CRED })),
+      write: jest.fn(async () => true),
+      clear: jest.fn(async () => undefined),
+    };
+    const store = loadStore('ios', { secureStore, broker });
+    await store?.read();
+    expect(broker.read).not.toHaveBeenCalled();
+    expect(secureStore.calls.length).toBeGreaterThan(0);
+  });
+
+  test('Android uses the broker, not the keychain', async () => {
+    const secureStore = makeSecureStoreMock();
+    const broker: BrokerModule = {
+      read: jest.fn(async () => ({ status: 'absent' })),
+      write: jest.fn(async () => true),
+      clear: jest.fn(async () => undefined),
+    };
+    const store = loadStore('android', { secureStore, broker });
+    await expect(store?.read()).resolves.toEqual({ state: 'absent' });
+    expect(broker.read).toHaveBeenCalled();
+    expect(secureStore.calls).toHaveLength(0);
+  });
+});
+
+describe('iOS keychain-group slot', () => {
+  test('a missing item is absent; a THROWN read is unavailable', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+
+    await expect(store?.read()).resolves.toEqual({ state: 'absent' });
+
+    secureStore.setReadError(new Error('User interaction is not allowed'));
+    const locked = await store?.read();
+    // The pair that must never be confused. `absent` authorises seeding the slot.
+    expect(locked?.state).toBe('unavailable');
+  });
+
+  test('an unparseable item is unavailable, never absent', async () => {
+    const secureStore = makeSecureStoreMock();
+    secureStore.items.set(STORAGE_KEY, 'not-json-at-all');
+    const store = loadStore('ios', { secureStore });
+    // Something IS stored. Reporting absent would authorise overwriting whatever
+    // a newer build put there.
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('reads and writes carry the dedicated service AND the access group', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+    await store?.publish(CRED);
+
+    // Without `keychainAccessGroup` the item is package-private and no sibling
+    // app can ever join. Without the dedicated `keychainService` it shares the
+    // legacy shared-IDENTITY namespace inside the group — the exact conflation
+    // this phase exists to end.
+    for (const call of secureStore.calls) {
+      expect(call.options).toMatchObject({
+        keychainService: 'oxy_device_session',
+        keychainAccessGroup: 'group.so.oxy.shared',
+      });
+    }
+    expect(secureStore.calls.length).toBeGreaterThan(0);
+  });
+
+  test('the item is written device-only so it never rides an OS backup to a new handset', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+    await store?.publish(CRED);
+    const write = secureStore.calls.find((c) => c.options?.keychainAccessible !== undefined);
+    expect(write?.options?.keychainAccessible).toBe(secureStore.module.WHEN_UNLOCKED_THIS_DEVICE_ONLY);
+  });
+
+  test('a publish round-trips and reads back as present', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+    await expect(store?.publish(CRED)).resolves.toBe(true);
+    await expect(store?.read()).resolves.toEqual({ state: 'present', credential: CRED });
+  });
+
+  test('a write that silently does not land reports false', async () => {
+    // A keychain write can resolve without the item landing under the access
+    // group (a missing entitlement is the usual cause). A phantom credential
+    // would send a fresh install into a mint that can never succeed.
+    const secureStore = makeSecureStoreMock();
+    secureStore.setSwallowWrites(true);
+    const store = loadStore('ios', { secureStore });
+    await expect(store?.publish(CRED)).resolves.toBe(false);
+  });
+
+  test('a throwing write reports false rather than propagating', async () => {
+    const secureStore = makeSecureStoreMock();
+    secureStore.setWriteError(new Error('keychain error -34018'));
+    const store = loadStore('ios', { secureStore });
+    await expect(store?.publish(CRED)).resolves.toBe(false);
+  });
+
+  test('the slot is unsupported when expo-secure-store is not installed', async () => {
+    const store = loadStore('ios');
+    // No `expo-secure-store` mock registered → the dynamic import rejects.
+    expect((await store?.read())?.state).toBe('unsupported');
+  });
+});
+
+describe('Android broker slot', () => {
+  test('narrows a present payload', async () => {
+    const store = loadStore('android', {
+      broker: { read: async () => ({ status: 'present', ...CRED }), write: async () => true, clear: async () => undefined },
+    });
+    await expect(store?.read()).resolves.toEqual({ state: 'present', credential: CRED });
+  });
+
+  test('an explicit unavailable status stays unavailable', async () => {
+    const store = loadStore('android', {
+      broker: {
+        read: async () => ({ status: 'unavailable', reason: 'GeneralSecurityException' }),
+        write: async () => true,
+        clear: async () => undefined,
+      },
+    });
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('a THROWN broker call is unavailable, never absent', async () => {
+    const store = loadStore('android', {
+      broker: {
+        read: async () => {
+          throw new Error('binder transaction failed');
+        },
+        write: async () => true,
+        clear: async () => undefined,
+      },
+    });
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('an unrecognised payload from an older sibling is unavailable, never absent', async () => {
+    const store = loadStore('android', {
+      broker: { read: async () => ({ ok: true }), write: async () => true, clear: async () => undefined },
+    });
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('the slot is unsupported when the native module is not linked', async () => {
+    const store = loadStore('android', { broker: null });
+    expect((await store?.read())?.state).toBe('unsupported');
+    await expect(store?.publish(CRED)).resolves.toBe(false);
+  });
+
+  test('publish forwards the broker’s own read-back verdict', async () => {
+    const unverified = loadStore('android', {
+      broker: { read: async () => ({ status: 'absent' }), write: async () => false, clear: async () => undefined },
+    });
+    await expect(unverified?.publish(CRED)).resolves.toBe(false);
+  });
+});

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

@@ -0,0 +1,163 @@
+import type { DeviceSessionState } from '@oxy.so/contracts';
+import { logger } from '@oxy.so/core';
+import { createTokenTransport } from '../tokenTransport';
+
+// The device-first transport no longer owns a private mint single-flight: it
+// routes through the ONE shared `oxyServices.httpService.refreshAccessToken(...)`
+// the scheduler/preflight/401 use, so concurrent lanes can never double-rotate
+// the device secret. It short-circuits ONLY when the planted bearer already
+// identifies the state's active account — a bearer for a DIFFERENT account (an
+// account switch) must still mint the new account's token. These tests exercise
+// that account-match contract and the transport's error/swallow behavior.
+
+function fakeOxy(currentUserId: string | null, refreshAccessToken = jest.fn(async () => 'minted-token')) {
+  return {
+    getCurrentUserId: jest.fn().mockReturnValue(currentUserId),
+    httpService: { refreshAccessToken },
+  };
+}
+
+const state: DeviceSessionState = {
+  deviceId: 'device-1',
+  accounts: [{ accountId: 'a1', sessionId: 'sess-a1', authuser: 0 }],
+  activeAccountId: 'a1',
+  revision: 1,
+  updatedAt: Date.UTC(2026, 6, 1, 0, 0, 0, 0),
+};
+
+describe('createTokenTransport', () => {
+  test('no-ops when the planted bearer already belongs to the active account', async () => {
+    const refreshAccessToken = jest.fn(async () => 'minted-token');
+    const oxy = fakeOxy('a1', refreshAccessToken);
+    const transport = createTokenTransport(oxy as never);
+
+    await transport.ensureActiveToken(state);
+
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+  });
+
+  test('mints when the planted bearer belongs to a DIFFERENT account (account switch)', async () => {
+    // The core account-switch 404 fix: a bearer for the PREVIOUS account must
+    // NOT short-circuit — it must mint the new active account's token.
+    const refreshAccessToken = jest.fn(async () => 'minted-token');
+    const oxy = fakeOxy('previous-account', refreshAccessToken);
+    const transport = createTokenTransport(oxy as never);
+
+    await transport.ensureActiveToken(state);
+
+    expect(refreshAccessToken).toHaveBeenCalledTimes(1);
+    expect(refreshAccessToken).toHaveBeenCalledWith('preflight');
+  });
+
+  test('mints via the shared httpService.refreshAccessToken single-flight when no bearer is present', async () => {
+    const refreshAccessToken = jest.fn(async () => 'minted-token');
+    const oxy = fakeOxy(null, refreshAccessToken);
+    const transport = createTokenTransport(oxy as never);
+
+    await transport.ensureActiveToken(state);
+
+    expect(refreshAccessToken).toHaveBeenCalledTimes(1);
+    expect(refreshAccessToken).toHaveBeenCalledWith('preflight');
+  });
+
+  test('resolves (never rejects) and logs a warning when the refresh throws', async () => {
+    const refreshAccessToken = jest.fn(async () => {
+      throw new Error('mint boom');
+    });
+    const oxy = fakeOxy(null, refreshAccessToken);
+    const transport = createTokenTransport(oxy as never);
+    const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+
+    await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      'ensureActiveToken: refresh failed',
+      { component: 'TokenTransport' },
+      expect.any(Error),
+    );
+
+    warnSpy.mockRestore();
+  });
+
+  test('resolves cleanly when the refresh produces no session', async () => {
+    const refreshAccessToken = jest.fn(async () => null);
+    const oxy = fakeOxy(null, refreshAccessToken);
+    const transport = createTokenTransport(oxy as never);
+
+    await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
+    expect(refreshAccessToken).toHaveBeenCalledTimes(1);
+  });
+
+  test('delegates concurrent calls to the shared single-flight (no private guard of its own)', async () => {
+    // The transport keeps NO local coalescing — it forwards each call to the
+    // shared `httpService.refreshAccessToken`, which owns the single-flight that
+    // collapses concurrent mints into one server rotation (covered in core).
+    const refreshAccessToken = jest.fn(async () => 'minted-token');
+    const oxy = fakeOxy(null, refreshAccessToken);
+    const transport = createTokenTransport(oxy as never);
+
+    const first = transport.ensureActiveToken(state);
+    const second = transport.ensureActiveToken(state);
+    // Both concurrent callers reached the shared entry point synchronously — the
+    // transport does not swallow the second behind a private guard; dedup is the
+    // shared single-flight's job.
+    expect(refreshAccessToken).toHaveBeenCalledTimes(2);
+
+    await expect(Promise.all([first, second])).resolves.toEqual([undefined, undefined]);
+  });
+
+  test('never mints while identity-bound, even when the device switched to another account', async () => {
+    // `sessionMode: 'identity'`: the bearer belongs to the PINNED account and is
+    // minted for it by the cold boot / re-mint lane. Converging it on
+    // `state.activeAccountId` — here a DIFFERENT account another app switched the
+    // device to — is exactly the drift the mode prevents, so the transport must
+    // short-circuit even though the bearer/active-account check disagrees.
+    const refreshAccessToken = jest.fn(async () => 'minted-token');
+    const oxy = fakeOxy('pinned-account', refreshAccessToken);
+    const transport = createTokenTransport(oxy as never, () => 'pinned-account');
+
+    await transport.ensureActiveToken({
+      ...state,
+      accounts: [
+        { accountId: 'pinned-account', sessionId: 'sess-pinned', authuser: 0 },
+        { accountId: 'a1', sessionId: 'sess-a1', authuser: 1 },
+      ],
+      activeAccountId: 'a1',
+    });
+
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+    expect(oxy.getCurrentUserId).not.toHaveBeenCalled();
+  });
+
+  test('a resolver reporting no pin (every account-mode provider) behaves exactly as an absent one', async () => {
+    const refreshAccessToken = jest.fn(async () => 'minted-token');
+    const oxy = fakeOxy('previous-account', refreshAccessToken);
+    const transport = createTokenTransport(oxy as never, () => null);
+
+    await transport.ensureActiveToken(state);
+
+    expect(refreshAccessToken).toHaveBeenCalledTimes(1);
+    expect(refreshAccessToken).toHaveBeenCalledWith('preflight');
+  });
+
+  test('treats a throwing bearer-account check as a mismatch and still mints', async () => {
+    const refreshAccessToken = jest.fn(async () => 'minted-token');
+    const oxy = fakeOxy(null, refreshAccessToken);
+    oxy.getCurrentUserId.mockImplementation(() => {
+      throw new Error('storage unavailable');
+    });
+    const transport = createTokenTransport(oxy as never);
+    const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+
+    await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      'ensureActiveToken: bearer-account check threw',
+      { component: 'TokenTransport' },
+      expect.any(Error),
+    );
+    expect(refreshAccessToken).toHaveBeenCalledTimes(1);
+
+    warnSpy.mockRestore();
+  });
+});

package/src/ui/session/authStore.ts

@@ -0,0 +1,106 @@
+/**
+ * Platform `AuthStateStore` for `@oxy.so/services`.
+ *
+ * The device model persists the durable device credential (`deviceId` +
+ * `deviceSecret`) per origin (web) / per device (native), and the SDK re-mints
+ * the access token from that credential on cold boot. `@oxy.so/core` owns the
+ * store shape + logic (`createWebAuthStateStore` / `createNativeAuthStateStore` /
+ * `createMemoryAuthStateStore`); this module only selects the seam:
+ *
+ *  - `storage: 'ephemeral'` → `createMemoryAuthStateStore()`, on EVERY platform.
+ *  - web  → `createWebAuthStateStore()` (localStorage, in-memory fallback).
+ *  - native → `createNativeAuthStateStore(secureKV)` for the SESSION blob over
+ *    the shared `createNativeSecureKeyValueStorage()` adapter
+ *    (`expo-secure-store`, AsyncStorage fallback), WRAPPED so every credential
+ *    it persists is also mirrored into the device-wide shared slot.
+ *
+ * The native wrapper is how several official apps end up on ONE `DeviceSession`
+ * (and therefore one active context): whichever app proves a credential publishes
+ * it, and a later-installed sibling adopts it during cold boot instead of asking
+ * for the Commons identity key. The mirror is additive — it can neither change
+ * nor fail the app's own durable write.
+ */
+import {
+  createWebAuthStateStore,
+  createNativeAuthStateStore,
+  createMemoryAuthStateStore,
+  createSharedMirroringAuthStateStore,
+  type AuthStateStore,
+  type SessionMode,
+} from '@oxy.so/core';
+import { isReactNative } from '../utils/storageHelpers';
+import { createNativeSecureKeyValueStorage } from './nativeSecureStorage';
+import { createPlatformSharedDeviceCredentialStore } from './sharedDeviceCredentialStore';
+
+export interface PlatformAuthStateStoreOptions {
+  /**
+   * Who owns the session this provider resolves. Only `'account'` mirrors into
+   * the device-wide shared slot.
+   *
+   * `'identity'` (the vault) is deliberately excluded, which keeps its storage
+   * behaviour byte-for-byte what it is today. The vault's credential is a
+   * perfectly valid device credential, so publishing it would arguably be
+   * correct — but it would also let every ordinary app on the device join the
+   * vault's device session as a side effect of the vault persisting a token, and
+   * "a background write changes which session five other apps boot into" is not
+   * a decision a storage seam gets to make.
+   */
+  sessionMode?: SessionMode;
+  /**
+   * Whether this origin/app may persist a durable device credential AT ALL.
+   *
+   * `'ephemeral'` stores nothing durable and mirrors nothing: the session lives
+   * in memory for the lifetime of the page and is gone on reload. Its one caller
+   * is `auth.oxy.so` with the browser hub enabled (issue #937 Phase 5, ADR 0003),
+   * where the durable credential for the browser profile is the server-side
+   * DeviceSession behind the `__Host-oxy-device` handle.
+   *
+   * See `OxyProviderProps.deviceCredentialStorage` for why the answer to "let the
+   * hub be authoritative" is to stop persisting the other credential rather than
+   * to consult it second.
+   */
+  storage?: 'persistent' | 'ephemeral';
+}
+
+/**
+ * Build the platform {@link AuthStateStore} for this runtime.
+ *
+ * Native persists the SESSION blob (`deviceId` + `deviceSecret` + cached access
+ * token) per-app in SecureStore; the SDK re-mints the access token from the
+ * device credential on the next cold boot.
+ *
+ * ## The ephemeral check is FIRST, and the order is load-bearing
+ *
+ * It short-circuits above the `isReactNative()` branch so an ephemeral caller can
+ * never reach the native path — and therefore can never reach the shared-slot
+ * mirroring wrapper. Checked after that branch instead, an origin that has
+ * declined to persist a credential would publish one into the device-wide slot
+ * every sibling app adopts on cold boot: it would keep nothing itself while
+ * deciding which session five other apps boot into.
+ *
+ * That is unreachable today because the only ephemeral caller is a web origin, so
+ * `isReactNative()` is false there anyway. Unreachable today is exactly the kind
+ * of guarantee that stops holding when someone adds the second caller, so it is
+ * structural here rather than incidental, and
+ * `__tests__/session/authStoreEphemeral.test.ts` holds the ordering directly.
+ */
+export function createPlatformAuthStateStore(
+  options: PlatformAuthStateStoreOptions = {},
+): AuthStateStore {
+  // FIRST, above every platform branch — see the docblock for why the ordering
+  // is the guarantee and not a coincidence.
+  if (options.storage === 'ephemeral') {
+    return createMemoryAuthStateStore();
+  }
+
+  if (!isReactNative()) {
+    return createWebAuthStateStore();
+  }
+
+  const local = createNativeAuthStateStore(createNativeSecureKeyValueStorage());
+  if (options.sessionMode === 'identity') {
+    return local;
+  }
+  const shared = createPlatformSharedDeviceCredentialStore();
+  return shared ? createSharedMirroringAuthStateStore({ local, shared }) : local;
+}