@oxyhq/core 5.5.0 → 7.0.0

package/src/mixins/__tests__/accounts.test.ts

@@ -176,27 +176,22 @@ describe('OxyServices.accounts', () => {
   });
 
   describe('switchToAccount', () => {
-    // The switch route NO LONGER returns `authuser` or sets the device cookie —
-    // it can't (it's at /accounts/*, outside the Path=/auth cookie scope). The SDK
-    // establishes the cookie + resolves the slot via a follow-up POST /auth/session.
+    // Device-first: the switch route registers the switched session in the
+    // server-side DeviceSession set directly and returns the fresh access token
+    // + the resolved `authuser`. There is NO follow-up POST /auth/session.
     const switchResponse: SwitchAccountResult = {
       sessionId: 'sess_switch',
       deviceId: 'dev_switch',
       expiresAt: '2026-06-30T01:00:00.000Z',
       accessToken: 'access_switch',
+      authuser: 1,
       user: { id: 'acc1', username: 'oxy-org', name: { displayName: 'Oxy Org' } },
     };
-    // POST /auth/session establishes the cookie in a correctly-allocated NEW slot
-    // and returns that slot + a fresh access token off the same session.
-    const sessionResponse = { accessToken: 'access_session', authuser: 1 };
 
-    // Route makeRequest by path: the switch call vs the /auth/session establishment.
     const routeByPath = (response = switchResponse) =>
-      makeRequestSpy.mockImplementation((_method: string, path: string) =>
-        Promise.resolve(path === '/auth/session' ? sessionResponse : response),
-      );
+      makeRequestSpy.mockResolvedValue(response);
 
-    it('posts to /:id/switch then establishes the cookie via POST /auth/session, planting both tokens and sweeping the cache', async () => {
+    it('posts to /:id/switch, plants the token, carries the response authuser, and sweeps the cache', async () => {
       const setTokensSpy = jest.spyOn(oxy, 'setTokens');
       const clearCacheSpy = jest.spyOn(oxy, 'clearCache');
       routeByPath();
@@ -210,29 +205,20 @@ describe('OxyServices.accounts', () => {
         undefined,
         expect.objectContaining({ cache: false }),
       );
-      // Then the canonical refresh-cookie establishment under /auth (where the
-      // device's oxy_rt_* slots ARE visible, so a NEW slot is allocated).
-      expect(makeRequestSpy).toHaveBeenCalledWith(
-        'POST',
-        '/auth/session',
-        undefined,
-        expect.objectContaining({ cache: false }),
-      );
+      // No secondary /auth/session establishment — the switch registers the
+      // session server-side on its own.
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
 
-      // The switch token is planted first; /auth/session's fresh token re-planted.
-      expect(setTokensSpy).toHaveBeenNthCalledWith(1, 'access_switch');
-      expect(setTokensSpy).toHaveBeenNthCalledWith(2, 'access_session');
-      expect(oxy.getAccessToken()).toBe('access_session');
+      // The switch token is planted; the cache is swept AFTER planting.
+      expect(setTokensSpy).toHaveBeenCalledWith('access_switch');
+      expect(oxy.getAccessToken()).toBe('access_switch');
       expect(oxy.hasValidToken()).toBe(true);
-
-      // Cache swept once, AFTER both tokens are planted.
       expect(clearCacheSpy).toHaveBeenCalledTimes(1);
-      expect(setTokensSpy.mock.invocationCallOrder[1]).toBeLessThan(
+      expect(setTokensSpy.mock.invocationCallOrder[0]).toBeLessThan(
         clearCacheSpy.mock.invocationCallOrder[0],
       );
 
-      // The returned session carries the target account (id-normalised) and the
-      // slot resolved by /auth/session — NEVER the clobbering slot 0.
+      // The returned session carries the target account (id-normalised) + slot.
       expect(result.sessionId).toBe('sess_switch');
       expect(result.user).toEqual({ id: 'acc1', username: 'oxy-org', name: { displayName: 'Oxy Org' } });
       expect(result.authuser).toBe(1);
@@ -247,27 +233,14 @@ describe('OxyServices.accounts', () => {
       expect(makeRequestSpy.mock.calls[0][1]).toBe('/accounts/a%20b%2Fc/switch');
     });
 
-    it('keeps the switch active in-session when /auth/session fails (best-effort cookie)', async () => {
-      const setTokensSpy = jest.spyOn(oxy, 'setTokens');
-      const clearCacheSpy = jest.spyOn(oxy, 'clearCache');
-      makeRequestSpy.mockImplementation((_method: string, path: string) =>
-        path === '/auth/session'
-          ? Promise.reject(Object.assign(new Error('origin'), { response: { status: 403 } }))
-          : Promise.resolve(switchResponse),
-      );
+    it('omits authuser from the result when the switch response has none', async () => {
+      const { authuser, ...noAuthuser } = switchResponse;
+      routeByPath(noAuthuser as SwitchAccountResult);
 
       const result = await oxy.switchToAccount('acc1');
 
-      // The in-session switch survives: the switch token stays planted and the
-      // cache is still swept. The switched account just won't survive a reload
-      // until the cookie is next established (no authuser resolved).
-      expect(setTokensSpy).toHaveBeenCalledWith('access_switch');
       expect(oxy.getAccessToken()).toBe('access_switch');
-      expect(clearCacheSpy).toHaveBeenCalledTimes(1);
       expect(result.authuser).toBeUndefined();
-
-      setTokensSpy.mockRestore();
-      clearCacheSpy.mockRestore();
     });
 
     it('does NOT plant or sweep when the operator is not authorized (403 surfaces via handleError)', async () => {

package/src/mixins/__tests__/passwordSignIn.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Device-first password sign-in (`passwordSignIn` + `completeTwoFactorSignIn`).
+ * Stubs `makeRequest` and asserts the login-result contract handling: the 2FA
+ * arm passes through un-planted, the session arm plants its access token, the
+ * deviceToken is threaded into the request, and a 2FA arm from verify-login is
+ * a protocol error.
+ */
+import type { LoginResult } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+
+const SESSION_ARM: LoginResult = {
+  sessionId: 'sess-1',
+  deviceId: 'dev-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  accessToken: 'access-1',
+  refreshToken: 'refresh-1',
+  user: { id: 'user-1', username: 'u' },
+};
+
+const TWO_FACTOR_ARM: LoginResult = { twoFactorRequired: true, loginToken: 'login-token-1' };
+
+describe('passwordSignIn', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+  let setTokens: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+    setTokens = jest.spyOn(oxy, 'setTokens').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('returns the 2FA arm without planting a token', async () => {
+    makeRequest.mockResolvedValueOnce(TWO_FACTOR_ARM);
+    const result = await oxy.passwordSignIn('alice', 'pw');
+    expect(result).toEqual(TWO_FACTOR_ARM);
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+
+  it('plants the access token on the session arm and threads the deviceToken', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    const result = await oxy.passwordSignIn('alice', 'pw', { deviceToken: 'dt-1', deviceName: 'Phone' });
+    expect(result).toEqual(SESSION_ARM);
+    expect(setTokens).toHaveBeenCalledWith('access-1');
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/login',
+      { identifier: 'alice', password: 'pw', deviceName: 'Phone', deviceFingerprint: undefined, deviceToken: 'dt-1' },
+      { cache: false },
+    );
+  });
+
+  it('throws on an unexpected response shape', async () => {
+    makeRequest.mockResolvedValueOnce({ nope: true });
+    await expect(oxy.passwordSignIn('alice', 'pw')).rejects.toThrow();
+  });
+});
+
+describe('completeTwoFactorSignIn', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+  let setTokens: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+    setTokens = jest.spyOn(oxy, 'setTokens').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('verifies the login token, plants the session, and POSTs to /security/2fa/verify-login', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    const result = await oxy.completeTwoFactorSignIn({ loginToken: 'lt', token: '123456', deviceToken: 'dt-1' });
+    expect(result).toEqual(SESSION_ARM);
+    expect(setTokens).toHaveBeenCalledWith('access-1');
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/security/2fa/verify-login',
+      { loginToken: 'lt', token: '123456', backupCode: undefined, deviceToken: 'dt-1', deviceName: undefined },
+      { cache: false },
+    );
+  });
+
+  it('throws when verify-login unexpectedly returns another 2FA challenge', async () => {
+    makeRequest.mockResolvedValueOnce(TWO_FACTOR_ARM);
+    await expect(oxy.completeTwoFactorSignIn({ loginToken: 'lt', token: '123456' })).rejects.toThrow();
+  });
+});

package/src/mixins/index.ts

@@ -7,10 +7,6 @@
 
 import { OxyServicesBase } from '../OxyServices.base';
 import { OxyServicesAuthMixin } from './OxyServices.auth';
-import { OxyServicesFedCMMixin } from './OxyServices.fedcm';
-import { OxyServicesSilentAuthMixin } from './OxyServices.silent';
-import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect';
-import { OxyServicesSsoMixin } from './OxyServices.sso';
 import { OxyServicesUserMixin } from './OxyServices.user';
 import { OxyServicesIdentityMixin } from './OxyServices.identity';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
@@ -32,6 +28,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
+import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -44,10 +41,6 @@ import { OxyServicesLinksMixin } from './OxyServices.links';
  */
 type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>>
@@ -68,6 +61,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -90,10 +84,9 @@ type MixinFunction = (Base: new (...args: unknown[]) => OxyServicesBase) => new
  *
  * Order matters for dependencies:
  * 1. Base auth mixin first (required by all others)
- * 2. Cross-domain auth mixins (FedCM, silent iframe, Redirect)
- * 3. User mixin (requires auth)
- * 4. Feature mixins (can depend on user)
- * 5. Utility mixin last (augments all)
+ * 2. User mixin (requires auth)
+ * 3. Feature mixins (can depend on user)
+ * 4. Utility mixin last (augments all)
  *
  * To add a new mixin: insert it at the appropriate position in this array.
  */
@@ -101,17 +94,6 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // Base authentication
     OxyServicesAuthMixin,
 
-    // Cross-domain authentication (web-only)
-    // - FedCM: Modern browser-native identity federation (Google-style)
-    // - Silent: iframe-based restore for first-party IdP hosts
-    // - Redirect: Traditional redirect-based authentication
-    OxyServicesFedCMMixin,
-    OxyServicesSilentAuthMixin,
-    OxyServicesRedirectAuthMixin,
-
-    // Central cross-domain SSO (opaque-code exchange).
-    OxyServicesSsoMixin,
-
     // User management (requires auth)
     OxyServicesUserMixin,
     // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
@@ -147,6 +129,11 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // so apps stop scraping link metadata locally.
     OxyServicesLinksMixin,
 
+    // Device-first session bootstrap: the client half of the new
+    // /auth/device/* + /auth/refresh-token surface (exchange, web-session,
+    // refresh, native device-token, bootstrap-url builder).
+    OxyServicesDeviceBootMixin,
+
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];

package/src/models/interfaces.ts

@@ -3,20 +3,6 @@ import type { UserNameResponse } from '@oxyhq/contracts';
 export interface OxyConfig {
   baseURL: string;
   cloudURL?: string;
-  /**
-   * Base URL the SDK's first-party session/refresh calls target.
-   *
-   * Per the 2026 session architecture (docs/SESSION-ARCHITECTURE.md), every app
-   * keeps its OWN first-party session on its OWN domain. For non-`oxy.so` apps
-   * this is the app's own same-site backend (e.g. `https://api.mention.earth`),
-   * whose session bridge forwards the user's refresh credential to
-   * `api.oxy.so`. For `*.oxy.so` apps this is omitted and falls back to
-   * `baseURL` (`https://api.oxy.so`), so their behavior is unchanged.
-   *
-   * Resolve via {@link OxyServices.getSessionBaseUrl}; when unset it returns
-   * `baseURL`. This is purely additive — no refresh/auth logic reads it yet.
-   */
-  sessionBaseUrl?: string;
   authWebUrl?: string;
   authRedirectUri?: string;
   /**
@@ -120,7 +106,6 @@ export interface User {
   phone?: string;
   address?: string;
   birthday?: string;
-  location?: string;
   website?: string;
   createdAt?: string;
   updatedAt?: string;
@@ -689,67 +674,3 @@ export interface UpdateDeviceNameResponse {
   deviceName: string;
 }
 
-// ---------------------------------------------------------------------------
-// Multi-account "refresh-all" (Google-style)
-// ---------------------------------------------------------------------------
-// Wire shape of `POST /auth/refresh-all`. The server rotates every device-local
-// `oxy_rt_${authuser}` cookie in parallel and returns one entry per VALID
-// account, sorted by `authuser` ascending. Slot-level errors are silently
-// omitted; the response is `{ accounts: [] }` in the worst case (no signed-in
-// accounts, all cookies expired, or origin not allowlisted).
-
-/**
- * Minimal user shape included in a `RefreshAllAccount` entry. The server
- * projects a small whitelist (`username name avatar email color`) so the
- * client can render the account chooser without an extra `/users/me` round
- * trip per account.
- *
- * `avatar` and `color` are `string | null` because they are stored as nullable
- * fields in the user document.
- */
-export interface RefreshAllAccountUser {
-  id: string;
-  username: string;
-  /**
-   * Structured human name as emitted by `formatUserResponse` (the canonical
-   * {@link UserNameResponse} `{ first?, last?, full? }` subdocument), NOT a bare
-   * string. The server projects `name` verbatim from the user document. The
-   * single source of truth is `@oxyhq/contracts`.
-   */
-  name: UserNameResponse;
-  avatar?: string | null;
-  email?: string;
-  color?: string | null;
-}
-
-/**
- * One rotated account entry returned by `POST /auth/refresh-all`. `authuser` is
- * the device-local slot index (0..N-1) the cookie was bound to.
- */
-export interface RefreshAllAccount {
-  authuser: number;
-  accessToken: string;
-  expiresAt: string;
-  sessionId: string;
-  user: RefreshAllAccountUser | null;
-}
-
-/**
- * Wire shape of `POST /auth/refresh-all`. Always 200 with a (possibly empty)
- * accounts array — 401 means "no accounts signed in on this device" and is
- * normalised to `{ accounts: [] }` at the SDK layer.
- */
-export interface RefreshAllResponse {
-  accounts: RefreshAllAccount[];
-}
-
-/**
- * Wire shape of `POST /auth/refresh` (single-slot refresh, optionally targeting
- * a specific `?authuser=N` slot). The server always includes the numeric slot in
- * the response.
- */
-export interface RefreshCookieResponse {
-  accessToken: string;
-  expiresAt: string;
-  authuser: number;
-}

package/src/models/session.ts

@@ -8,11 +8,10 @@ export interface ClientSession {
   userId?: string;
   isCurrent?: boolean;
   /**
-   * Web-only: the device-local refresh-cookie slot index (0..N) that backs
-   * this session. Populated from `POST /auth/refresh-all` and from login /
-   * signup / fedcm-exchange responses. Required for per-session web token
-   * refresh via `refreshTokenViaCookie({ authuser })` without a bearer token.
-   * Absent on native (RN uses the bearer-protected session id directly).
+   * The account's ordinal slot (0..N) within the device's account set
+   * (`SessionAccount.authuser` in `@oxyhq/contracts`), projected from the
+   * device-first `DeviceSessionState` — used purely for stable Google-style
+   * account-chooser ordering, not for any token-refresh mechanism.
    */
   authuser?: number;
 }

package/src/server/index.ts

@@ -68,7 +68,7 @@ export { verifySecret } from './verifySecret';
 // SOURCE OF TRUTH shared with the IdP worker and the client FAPI auto-detect.
 // Pure host handling (no browser deps), so it is safe on the server subpath and
 // lets `@oxyhq/api` derive `auth.<apex>` without duplicating PSL logic.
-export { registrableApex } from '../utils/fapiAutoDetect';
+export { registrableApex } from '../utils/registrableApex';
 
 // The single RP callback path the IdP redirects back to. A pure wire-contract
 // constant (no browser deps at module top level), re-used server-side so the

package/src/session/SessionClient.ts

@@ -9,7 +9,7 @@ import { getSocketIO } from './socketLoader';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 
 export interface TokenTransport {
-  /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via FedCM/silent/sso/keychain). Best-effort. */
+  /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via the persisted refresh family / shared keychain). Best-effort. */
   ensureActiveToken(state: DeviceSessionState): Promise<void>;
 }
 
@@ -24,6 +24,16 @@ export interface SessionClientHost {
 
 export interface SessionClientOptions {
   transport?: TokenTransport;
+  /**
+   * Invoked when an APPLIED state has zero accounts — i.e. a device
+   * signout-all removed the last account from this device set. Providers use
+   * this to clear the persisted {@link AuthStateStore} so a reload does not
+   * try to restore a session that no longer exists on the device.
+   *
+   * Only fires when a state is actually applied (revision advanced), never on
+   * a stale/rejected push. Exceptions thrown by the callback are isolated.
+   */
+  onUnauthenticated?: () => void;
   /**
    * Statically-injected `socket.io-client` factory (its `io` export).
    * `@oxyhq/services` and `@oxyhq/auth` list `socket.io-client` as a real
@@ -80,7 +90,17 @@ export class SessionClient {
       logger.warn('[SessionClient] discarded invalid session state');
       return false;
     }
-    if (this.state && next.revision <= this.state.revision) {
+    // The revision is monotone ONLY within a single deviceId. When the incoming
+    // state belongs to a DIFFERENT device than the currently-applied one, reset
+    // the baseline and accept it regardless of revision: a freshly-converged
+    // device (low revision) must not lose last-writer-wins to a stale, higher-
+    // revision state from a retired device. Only when the deviceIds MATCH is the
+    // `revision <= current` guard a valid staleness check.
+    if (
+      this.state &&
+      next.deviceId === this.state.deviceId &&
+      next.revision <= this.state.revision
+    ) {
       return false;
     }
     this.state = next;
@@ -90,6 +110,15 @@ export class SessionClient {
         logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
       });
     }
+    // A device signout-all leaves zero accounts — tell the provider to clear
+    // the persisted store so a reload does not try to restore a dead session.
+    if (next.accounts.length === 0 && this.options.onUnauthenticated) {
+      try {
+        this.options.onUnauthenticated();
+      } catch (error) {
+        logger.error('[SessionClient] onUnauthenticated threw', error);
+      }
+    }
     return true;
   }
 
@@ -144,6 +173,28 @@ export class SessionClient {
     this.applySync(res);
   }
 
+  /**
+   * Register the just-signed-in account into the device set AND make it the
+   * ACTIVE account — the explicit user-intent activation a sign-in UI performs.
+   *
+   * `addCurrentAccount` alone honors the server's `activate:'if-empty'` policy
+   * (a new account does NOT steal focus from an already-active one), which is
+   * correct for a background/silent add but wrong right after a deliberate
+   * sign-in. This adds, then switches to the target so the UI lands on the
+   * account the user just authenticated.
+   *
+   * @param accountId - The signed-in account id (e.g. `session.user.id`). When
+   *   omitted, falls back to the host's current-account ref. If neither
+   *   resolves, the add still applies and no switch is performed.
+   */
+  async registerAndActivate(accountId?: string): Promise<void> {
+    await this.addCurrentAccount();
+    const target = accountId ?? this.host.getCurrentAccountId();
+    if (target && this.state?.activeAccountId !== target) {
+      await this.switchAccount(target);
+    }
+  }
+
   async start(): Promise<void> {
     if (this.started) return;
     this.started = true;

package/src/session/__tests__/SessionClient.additive.test.ts

@@ -0,0 +1,92 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+const stateWith = (rev: number, active: string | null, accountIds: string[]): DeviceSessionState => ({
+  deviceId: 'd1',
+  accounts: accountIds.map((id, i) => ({ accountId: id, sessionId: `s-${id}`, authuser: i })),
+  activeAccountId: active,
+  revision: rev,
+  updatedAt: 1720000000000,
+});
+
+const sync = (state: DeviceSessionState) => ({ state, activeToken: { accessToken: `jwt-${state.revision}`, expiresAt: 'x' } });
+
+function makeHost(makeRequest: jest.Mock, currentAccountId: string | null = null): SessionClientHost {
+  return {
+    makeRequest,
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 't',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => currentAccountId,
+  };
+}
+
+class TestClient extends SessionClient {
+  public apply(raw: unknown): boolean {
+    return this.applyState(raw);
+  }
+}
+
+describe('SessionClient.registerAndActivate', () => {
+  it('adds then switches to the explicit target when it is not already active', async () => {
+    const makeRequest = jest
+      .fn()
+      // add → device set has a1 active, a2 present but not active
+      .mockResolvedValueOnce(sync(stateWith(1, 'a1', ['a1', 'a2'])))
+      // switch → a2 becomes active
+      .mockResolvedValueOnce(sync(stateWith(2, 'a2', ['a1', 'a2'])));
+    const c = new SessionClient(makeHost(makeRequest));
+
+    await c.registerAndActivate('a2');
+
+    expect(makeRequest).toHaveBeenNthCalledWith(1, 'POST', '/session/device/add', undefined, { cache: false });
+    expect(makeRequest).toHaveBeenNthCalledWith(2, 'POST', '/session/device/switch', { accountId: 'a2' }, { cache: false });
+    expect(c.getState()?.activeAccountId).toBe('a2');
+  });
+
+  it('falls back to the host current-account ref when no target is passed', async () => {
+    const makeRequest = jest
+      .fn()
+      .mockResolvedValueOnce(sync(stateWith(1, 'a1', ['a1', 'a2'])))
+      .mockResolvedValueOnce(sync(stateWith(2, 'a2', ['a1', 'a2'])));
+    const c = new SessionClient(makeHost(makeRequest, 'a2'));
+
+    await c.registerAndActivate();
+
+    expect(makeRequest).toHaveBeenNthCalledWith(2, 'POST', '/session/device/switch', { accountId: 'a2' }, { cache: false });
+  });
+
+  it('does NOT switch when the added account is already active', async () => {
+    const makeRequest = jest.fn().mockResolvedValueOnce(sync(stateWith(1, 'a1', ['a1'])));
+    const c = new SessionClient(makeHost(makeRequest));
+
+    await c.registerAndActivate('a1');
+
+    expect(makeRequest).toHaveBeenCalledTimes(1);
+    expect(makeRequest).toHaveBeenCalledWith('POST', '/session/device/add', undefined, { cache: false });
+  });
+});
+
+describe('SessionClient onUnauthenticated', () => {
+  it('fires when an applied state has zero accounts (device signout-all)', () => {
+    const onUnauthenticated = jest.fn();
+    const c = new TestClient(makeHost(jest.fn()), { onUnauthenticated });
+
+    c.apply(stateWith(1, 'a1', ['a1']));
+    expect(onUnauthenticated).not.toHaveBeenCalled();
+
+    c.apply(stateWith(2, null, []));
+    expect(onUnauthenticated).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not fire for a stale (non-applied) empty state', () => {
+    const onUnauthenticated = jest.fn();
+    const c = new TestClient(makeHost(jest.fn()), { onUnauthenticated });
+
+    c.apply(stateWith(5, 'a1', ['a1']));
+    // revision 4 <= 5 → rejected, so onUnauthenticated must NOT fire.
+    c.apply(stateWith(4, null, []));
+    expect(onUnauthenticated).not.toHaveBeenCalled();
+  });
+});

package/src/session/__tests__/SessionClient.rest.test.ts

@@ -77,4 +77,29 @@ describe('SessionClient REST', () => {
     expect(c.getState()?.revision).toBe(7);
     expect(host.setTokens).not.toHaveBeenCalled();
   });
+
+  it('accepts a NEW device\'s lower-revision state and plants its token (cross-device revision reset)', async () => {
+    const deviceA: DeviceSessionState = {
+      deviceId: 'A', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: 10, updatedAt: 1720000000000,
+    };
+    const deviceB: DeviceSessionState = {
+      deviceId: 'B', accounts: [{ accountId: 'a2', sessionId: 's2', authuser: 0 }], activeAccountId: 'a2', revision: 1, updatedAt: 1720000001000,
+    };
+    const makeRequest = jest.fn()
+      .mockResolvedValueOnce({ state: deviceA, activeToken: { accessToken: 'jwt-A', expiresAt: 'x' } })
+      .mockResolvedValueOnce({ state: deviceB, activeToken: { accessToken: 'jwt-B', expiresAt: 'x' } });
+    const host = makeHost(makeRequest);
+    const c = new SessionClient(host);
+
+    await c.bootstrap();
+    expect(c.getState()?.deviceId).toBe('A');
+    expect(host.setTokens).toHaveBeenLastCalledWith('jwt-A');
+
+    // Device B is freshly converged (revision 1) — it must win over device A's
+    // stale-but-higher revision, and its token must be planted.
+    await c.bootstrap();
+    expect(c.getState()?.deviceId).toBe('B');
+    expect(c.getState()?.revision).toBe(1);
+    expect(host.setTokens).toHaveBeenLastCalledWith('jwt-B');
+  });
 });

package/src/session/__tests__/SessionClient.state.test.ts

@@ -32,12 +32,25 @@ describe('SessionClient state', () => {
     expect(seen.at(-1)?.revision).toBe(1);
   });
 
-  it('ignores a stale or equal revision (last-writer-wins)', () => {
+  it('ignores a stale or equal revision (last-writer-wins) WITHIN the same device', () => {
     const c = new TestClient(makeHost());
-    c.apply(STATE(5));
-    expect(c.apply(STATE(5))).toBe(false);
-    expect(c.apply(STATE(4))).toBe(false);
-    expect(c.getState()?.revision).toBe(5);
+    c.apply({ ...STATE(5), deviceId: 'A' });
+    expect(c.apply({ ...STATE(5), deviceId: 'A' })).toBe(false);
+    expect(c.apply({ ...STATE(4), deviceId: 'A' })).toBe(false);
+    expect(c.apply({ ...STATE(6), deviceId: 'A' })).toBe(true);
+    expect(c.getState()?.revision).toBe(6);
+  });
+
+  it('accepts a LOWER-revision state from a DIFFERENT device (revision baseline resets cross-device)', () => {
+    const c = new TestClient(makeHost());
+    // Device A at a high revision.
+    expect(c.apply({ ...STATE(10), deviceId: 'A' })).toBe(true);
+    expect(c.getState()?.deviceId).toBe('A');
+    // Device B, freshly converged (revision 1), must win over device A's
+    // stale-but-higher revision — the cross-device comparison is not monotone.
+    expect(c.apply({ ...STATE(1), deviceId: 'B' })).toBe(true);
+    expect(c.getState()?.deviceId).toBe('B');
+    expect(c.getState()?.revision).toBe(1);
   });
 
   it('rejects an invalid (unvalidated) state without applying', () => {