@oxyhq/core 5.5.0 → 6.0.0

package/src/mixins/OxyServices.auth.ts

@@ -3,13 +3,9 @@
  *
  * Supports password-based login (email/username) and public key challenge-response.
  */
-import type {
-  User,
-  RefreshAllResponse,
-  RefreshAllAccount,
-  RefreshCookieResponse,
-} from '../models/interfaces';
-import type { UserNameResponse } from '@oxyhq/contracts';
+import type { User } from '../models/interfaces';
+import type { UserNameResponse, LoginResult, LoginSessionResult } from '@oxyhq/contracts';
+import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -32,26 +28,6 @@ export interface ChallengeResponse {
   expiresAt: string;
 }
 
-/**
- * Options for {@link refreshAllSessions}.
- */
-export interface RefreshAllOptions {
-  /**
-   * Abort the `POST /auth/refresh-all` request after this many milliseconds and
-   * resolve as "no signed-in accounts" (`{ accounts: [] }`) rather than hanging.
-   *
-   * Why: on a cross-domain RP (e.g. `mention.earth`) the `Domain=oxy.so` refresh
-   * cookie never reaches `api.<apex>`, so this request can stall behind a slow
-   * or unreachable endpoint with no useful answer coming back. As one step of
-   * the ordered cold-boot sequence, a stalled refresh is dead latency in front
-   * of the steps that actually hold the answer. A bounded abort lets cold boot
-   * fall through quickly. Omit (or pass `0`/negative) to wait indefinitely.
-   * The abort is treated identically to a 401 — the
-   * "not signed in on this device" path — never an error.
-   */
-  timeout?: number;
-}
-
 export interface RegistrationRequest {
   publicKey: string;
   username: string;
@@ -937,232 +913,6 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
-    /**
-     * Refresh every device-local refresh-cookie slot in a single round trip
-     * (Google-style multi-account rebuild).
-     *
-     * Calls `POST {sessionBaseUrl}/auth/refresh-all` with `credentials: 'include'`
-     * and NO bearer. The browser attaches every indexed `oxy_rt_${authuser}`
-     * cookie it has; the server rotates each in parallel and returns one entry
-     * per VALID account.
-     *
-     * Failure handling:
-     * - 401 → no signed-in accounts on this device → returns `{ accounts: [] }`
-     *   (NOT an error; this is the cold-boot "not signed in" path).
-     * - 404 → endpoint not deployed → returns `{ accounts: [] }`.
-     * - Any other non-2xx → throws via `handleError`.
-     *
-     * The refresh cookie itself never enters JS — only the rotated access
-     * tokens do. Each access token still needs to be planted via
-     * `setTokens(...)` (or per-account in-memory storage) at the consumer.
-     */
-    async refreshAllSessions(options: RefreshAllOptions = {}): Promise<RefreshAllResponse> {
-      const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/refresh-all`;
-
-      // Optional bounded abort (see `RefreshAllOptions.timeout`). A positive
-      // timeout arms an `AbortController` that aborts the in-flight request; an
-      // abort is treated as "no signed-in accounts on this device" — the same
-      // outcome as a 401 — so a cross-domain stall falls through cleanly instead
-      // of hanging the cold boot.
-      const timeout = typeof options.timeout === 'number' && options.timeout > 0 ? options.timeout : undefined;
-      const controller = timeout !== undefined ? new AbortController() : undefined;
-      const timeoutId = timeout !== undefined && controller
-        ? setTimeout(() => controller.abort(), timeout)
-        : undefined;
-
-      let response: Response;
-      try {
-        response = await fetch(url, {
-          method: 'POST',
-          credentials: 'include',
-          headers: { Accept: 'application/json' },
-          signal: controller?.signal,
-        });
-      } catch (error) {
-        // A bounded-timeout abort is the "not signed in / cross-domain stall"
-        // path, NOT an error. The browser raises a DOMException named
-        // 'AbortError' (some runtimes use a generic Error); match on the name so
-        // we never throw the timeout into the cold-boot error handler.
-        if (error instanceof Error && error.name === 'AbortError') {
-          return { accounts: [] };
-        }
-        throw this.handleError(error);
-      } finally {
-        if (timeoutId !== undefined) {
-          clearTimeout(timeoutId);
-        }
-      }
-
-      if (response.status === 401) {
-        return { accounts: [] };
-      }
-
-      if (response.status === 404) {
-        return { accounts: [] };
-      }
-
-      if (!response.ok) {
-        throw this.handleError(
-          new Error(`Refresh-all failed with HTTP ${response.status}`)
-        );
-      }
-
-      const payload = (await response.json()) as { accounts?: unknown };
-      const raw = Array.isArray(payload.accounts) ? payload.accounts : [];
-      const accounts: RefreshAllAccount[] = [];
-
-      for (const entry of raw) {
-        if (entry === null || typeof entry !== 'object') {
-          continue;
-        }
-        const e = entry as {
-          authuser?: number;
-          accessToken?: string;
-          expiresAt?: string;
-          sessionId?: string;
-          user?: { id?: string; _id?: string; username?: string; name?: UserNameResponse; avatar?: string | null; email?: string; color?: string | null };
-        };
-        if (!e.accessToken || !e.expiresAt || !e.sessionId || !e.user) {
-          continue;
-        }
-        const userId = e.user.id ?? e.user._id;
-        // `name.displayName` is optional on the contract — do NOT drop no-name
-        // accounts. Only an absent userId or username makes the entry unusable.
-        if (!userId || !e.user.username) {
-          continue;
-        }
-        if (typeof e.authuser !== 'number') {
-          continue;
-        }
-        accounts.push({
-          authuser: e.authuser,
-          accessToken: e.accessToken,
-          expiresAt: e.expiresAt,
-          sessionId: e.sessionId,
-          user: {
-            id: userId,
-            username: e.user.username,
-            // `name.displayName` is optional; carry whatever structured name the
-            // server sent (possibly an empty object) and let consumers fall back.
-            name: e.user.name ?? {},
-            avatar: e.user.avatar ?? null,
-            email: e.user.email,
-            color: e.user.color ?? null,
-          },
-        });
-      }
-
-      return { accounts };
-    }
-
-    /**
-     * Rotate a single refresh-cookie slot and return the fresh access token.
-     *
-     * When `authuser` is provided, the server rotates ONLY that slot
-     * (`oxy_rt_${authuser}`) — sibling accounts on the same device stay
-     * untouched. When omitted, the server picks the lowest indexed slot present.
-     * The refresh cookie itself never enters JS.
-     *
-     * Returns `null` on 401 (no cookie / expired / reused) so the caller can
-     * fall through cleanly to the unauthenticated path.
-     */
-    async refreshTokenViaCookie(
-      opts: { authuser?: number } = {}
-    ): Promise<RefreshCookieResponse | null> {
-      const result = await this._refreshCookieRaw(opts.authuser);
-      return result;
-    }
-
-    /**
-     * Sign out a single device-local account by its authuser slot index.
-     *
-     * Revokes that slot's refresh-token family and deactivates its session;
-     * sibling indexed slots stay signed in. The browser-side `oxy_rt_${n}`
-     * cookie is cleared by the server's `Set-Cookie` response header.
-     */
-    async logoutSessionByAuthuser(authuser: number): Promise<void> {
-      const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/logout?authuser=${encodeURIComponent(String(authuser))}`;
-      try {
-        const response = await fetch(url, {
-          method: 'POST',
-          credentials: 'include',
-          headers: { Accept: 'application/json' },
-        });
-        if (!response.ok && response.status !== 401) {
-          throw new Error(`Logout (authuser=${authuser}) failed with HTTP ${response.status}`);
-        }
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Sign out EVERY device-local account on this device by clearing every
-     * presented refresh-cookie slot at once. Revokes every family + clears
-     * every slot. Always succeeds (idempotent on unknown/garbage tokens).
-     */
-    async logoutAllSessionsViaCookie(): Promise<void> {
-      const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/logout`;
-      try {
-        const response = await fetch(url, {
-          method: 'POST',
-          credentials: 'include',
-          headers: { Accept: 'application/json' },
-        });
-        if (!response.ok && response.status !== 401) {
-          throw new Error(`Logout-all failed with HTTP ${response.status}`);
-        }
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Internal: raw `POST /auth/refresh[?authuser=N]` call returning the
-     * minted access token. Returns `null` on 401 / non-2xx.
-     *
-     * @internal
-     */
-    async _refreshCookieRaw(authuser?: number): Promise<RefreshCookieResponse | null> {
-      const base = this.getSessionBaseUrl().replace(/\/$/, '');
-      const url = typeof authuser === 'number'
-        ? `${base}/auth/refresh?authuser=${encodeURIComponent(String(authuser))}`
-        : `${base}/auth/refresh`;
-
-      let response: Response;
-      try {
-        response = await fetch(url, {
-          method: 'POST',
-          credentials: 'include',
-          headers: { Accept: 'application/json' },
-        });
-      } catch (error) {
-        throw this.handleError(error);
-      }
-
-      if (!response.ok) {
-        return null;
-      }
-
-      const payload = (await response.json()) as {
-        accessToken?: unknown;
-        expiresAt?: unknown;
-        authuser?: unknown;
-      };
-      if (typeof payload.accessToken !== 'string' || !payload.accessToken) {
-        return null;
-      }
-      const expiresAt = typeof payload.expiresAt === 'string' ? payload.expiresAt : '';
-      if (typeof payload.authuser !== 'number') {
-        return null;
-      }
-      return {
-        accessToken: payload.accessToken,
-        expiresAt,
-        authuser: payload.authuser,
-      };
-    }
-
     /**
      * Internal: decode (without verifying) the `sessionId` claim from a
      * server-signed access token. The server already verified the signature;
@@ -1369,5 +1119,80 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     ): Promise<SessionLoginResponse> {
       return this.signIn(email, password, deviceName, deviceFingerprint);
     }
+
+    /**
+     * Device-first password sign-in. Unlike the legacy {@link signIn} (which
+     * assumes a one-step session and is kept intact for existing callers until
+     * the F4 cutover), this returns the FULL `POST /auth/login` contract — the
+     * discriminated {@link LoginResult}: either a 2FA challenge
+     * (`{ twoFactorRequired, loginToken }`) to complete via
+     * {@link completeTwoFactorSignIn}, or a session arm.
+     *
+     * `options.deviceToken` attributes the new session to the caller's existing
+     * device set (so an in-app login from a cross-apex, cookie-less web app
+     * still joins the same DeviceSession). On the session arm, a returned access
+     * token is planted immediately (mirroring {@link verifyChallenge}), so the
+     * caller has an authenticated client without a second round-trip.
+     */
+    async passwordSignIn(
+      identifier: string,
+      password: string,
+      options: { deviceToken?: string; deviceName?: string; deviceFingerprint?: string } = {},
+    ): Promise<LoginResult> {
+      try {
+        const res = await this.makeRequest<unknown>('POST', '/auth/login', {
+          identifier,
+          password,
+          deviceName: options.deviceName,
+          deviceFingerprint: options.deviceFingerprint,
+          deviceToken: options.deviceToken,
+        }, { cache: false });
+        const parsed = safeParseContract(loginResultSchema, res);
+        if (!parsed) {
+          throw new Error('auth/login returned an unexpected response shape');
+        }
+        if (!('twoFactorRequired' in parsed) && parsed.accessToken) {
+          this.setTokens(parsed.accessToken);
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Complete a 2FA-gated sign-in started by {@link passwordSignIn}. Presents
+     * the short-lived `loginToken` with either a TOTP `token` or a `backupCode`
+     * to `POST /security/2fa/verify-login`, which must resolve to the session
+     * arm of {@link LoginResult} (a second 2FA challenge here is a protocol
+     * error). A returned access token is planted immediately.
+     */
+    async completeTwoFactorSignIn(params: {
+      loginToken: string;
+      token?: string;
+      backupCode?: string;
+      deviceToken?: string;
+      deviceName?: string;
+    }): Promise<LoginSessionResult> {
+      try {
+        const res = await this.makeRequest<unknown>('POST', '/security/2fa/verify-login', {
+          loginToken: params.loginToken,
+          token: params.token,
+          backupCode: params.backupCode,
+          deviceToken: params.deviceToken,
+          deviceName: params.deviceName,
+        }, { cache: false });
+        const parsed = safeParseContract(loginResultSchema, res);
+        if (!parsed || 'twoFactorRequired' in parsed) {
+          throw new Error('security/2fa/verify-login returned an unexpected response shape');
+        }
+        if (parsed.accessToken) {
+          this.setTokens(parsed.accessToken);
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
   };
 }

package/src/mixins/OxyServices.authorizedApps.ts

@@ -0,0 +1,75 @@
+/**
+ * Authorized-apps mixin — the "Connected apps" management surface that survived
+ * the FedCM removal.
+ *
+ * These two methods read/revoke the user's LEGACY FedCM authorization grants
+ * (`GET`/`DELETE /fedcm/me/authorized-apps`). They are the last live consumers
+ * of that endpoint (services' `ConnectedAppsScreen` via `useAccountQueries` /
+ * `useAccountMutations`) and stay until the AppGrant migration retires the
+ * FedCM grant store. All FedCM SIGN-IN machinery was deleted with
+ * `OxyServices.fedcm.ts`; this is management-only, so it has no dependency on
+ * the credential/nonce pipeline.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+
+/**
+ * Public summary of an RP application the user has authorized — mirrors the
+ * `AuthorizedAppSummary` shape returned by `GET /fedcm/me/authorized-apps`.
+ */
+export interface AuthorizedApp {
+  /** Normalised RP origin. */
+  origin: string;
+  /** Friendly display name. */
+  name: string;
+  /** Optional human-readable description. */
+  description?: string;
+  /** ISO-8601 timestamp of when the user first authorized this RP. */
+  firstGrantedAt: string;
+  /** ISO-8601 timestamp of the most recent FedCM exchange for this user+RP. */
+  lastUsedAt: string;
+}
+
+export function OxyServicesAuthorizedAppsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    /**
+     * List the authenticated user's authorized RP apps — the intersection of the
+     * user's FedCM grants and the currently-approved RP catalog. Powers the
+     * "Connected apps" management UI. Requires a real user session.
+     */
+    async listAuthorizedApps(): Promise<AuthorizedApp[]> {
+      try {
+        const response = await this.makeRequest<{ apps: AuthorizedApp[] }>(
+          'GET',
+          '/fedcm/me/authorized-apps',
+          undefined,
+          {
+            cache: true,
+            cacheTTL: 30 * 1000, // 30 second cache — short, this drives a manageable UI
+          },
+        );
+        return response?.apps ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Revoke the authenticated user's authorization for a specific RP origin.
+     * The corresponding cache entry is invalidated so a subsequent
+     * `listAuthorizedApps()` sees fresh data.
+     */
+    async revokeAuthorizedApp(origin: string): Promise<void> {
+      try {
+        await this.makeRequest(
+          'DELETE',
+          `/fedcm/me/authorized-apps/${encodeURIComponent(origin)}`,
+          undefined,
+          { cache: false },
+        );
+        this.clearCacheEntry('GET:/fedcm/me/authorized-apps');
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.deviceBoot.ts

@@ -0,0 +1,146 @@
+/**
+ * Device-first bootstrap mixin (auth centralization, wave 1).
+ *
+ * The client half of the new device-first session bootstrap: the four network
+ * calls the cold boot (`coldBootV2`) and the unified refresh handler
+ * (`refresh.ts`) make, plus the URL builder for the cross-apex bootstrap hop.
+ * Every response is validated against the `@oxyhq/contracts` `deviceBoot`
+ * schemas via `safeParseContract`, so producer (oxy-api) and consumer cannot
+ * drift — an unexpected shape throws here rather than silently corrupting the
+ * persisted store.
+ *
+ * These methods are ADDITIVE and carry NO persistence or token-planting side
+ * effects of their own (except the bearer-authenticated calls that naturally
+ * flow through `HttpService`). The cold boot / refresh handler own persistence
+ * and `setTokens`, so the same network primitive can be reused from either
+ * without double-planting.
+ */
+import {
+  authTokenBundleSchema,
+  tokenRefreshResponseSchema,
+  deviceTokenIssueResponseSchema,
+  webSessionResultSchema,
+  safeParseContract,
+  type AuthTokenBundle,
+  type TokenRefreshResponse,
+  type WebSessionResult,
+} from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+
+export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    /**
+     * Exchange a single-use boot `code` (from the `#oxy_boot` return fragment)
+     * for a token bundle. Origin-bound + GETDEL-burned server-side.
+     *
+     * @throws if the response does not match {@link authTokenBundleSchema}.
+     */
+    async exchangeBootCode(code: string): Promise<AuthTokenBundle> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/device/exchange',
+          { code },
+          { cache: false },
+        );
+        const parsed = safeParseContract(authTokenBundleSchema, res);
+        if (!parsed) {
+          throw new Error('device/exchange returned an unexpected response shape');
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Same-site fast path (`*.oxy.so` apps). Reads the first-party `oxy_device`
+     * cookie via a credentialed same-origin fetch and either resolves a full
+     * session bundle or reports the device is known-but-signed-out. Never
+     * redirects.
+     *
+     * @throws if the response matches neither arm of {@link webSessionResultSchema}.
+     */
+    async requestWebSession(): Promise<WebSessionResult> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/device/web-session',
+          undefined,
+          { cache: false },
+        );
+        const parsed = safeParseContract(webSessionResultSchema, res);
+        if (!parsed) {
+          throw new Error('device/web-session returned an unexpected response shape');
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Rotate the persisted refresh-token family (web + native, one call). The
+     * caller (refresh handler / cold boot) plants + persists the rotated pair.
+     *
+     * @throws if the response does not match {@link tokenRefreshResponseSchema}.
+     */
+    async refreshWithToken(refreshToken: string): Promise<TokenRefreshResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/refresh-token',
+          { refreshToken },
+          // `skipAuth`: refresh-token is body-authenticated and is called from
+          // inside the refresh handler — sending the near-expired bearer through
+          // the preflight would deadlock. See RequestOptions.skipAuth.
+          { cache: false, skipAuth: true },
+        );
+        const parsed = safeParseContract(tokenRefreshResponseSchema, res);
+        if (!parsed) {
+          throw new Error('auth/refresh-token returned an unexpected response shape');
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Issue (or rotate) the native channel's opaque device token. Bearer-gated —
+     * the server derives the deviceId from the JWT. Native apps mirror the
+     * returned token into the shared keychain via
+     * `KeyManager.setSharedDeviceToken`.
+     *
+     * @throws if the response does not match {@link deviceTokenIssueResponseSchema}.
+     */
+    async issueNativeDeviceToken(): Promise<string> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/device/token',
+          undefined,
+          { cache: false },
+        );
+        const parsed = safeParseContract(deviceTokenIssueResponseSchema, res);
+        if (!parsed) {
+          throw new Error('auth/device/token returned an unexpected response shape');
+        }
+        return parsed.deviceToken;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Build the top-level `GET /auth/device/bootstrap` URL for the cross-apex
+     * hop. The server validates `return_to` against the trusted-origin lane and
+     * echoes `state` back in the return fragment for CSRF verification.
+     */
+    buildBootstrapUrl(returnTo: string, state: string): string {
+      const base = this.getBaseURL().replace(/\/+$/, '');
+      const params = new URLSearchParams({ return_to: returnTo, state });
+      return `${base}/auth/device/bootstrap?${params.toString()}`;
+    }
+  };
+}

package/src/mixins/__tests__/OxyServices.deviceBoot.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Device-boot mixin tests. Stubs `makeRequest` so the tests run with no network
+ * and asserts each method's route/shape, contract validation, and the
+ * `skipAuth` flag on the refresh call.
+ */
+import type { AuthTokenBundle, TokenRefreshResponse, WebSessionResult } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+
+const BUNDLE: AuthTokenBundle = {
+  sessionId: 'sess-1',
+  accessToken: 'access-1',
+  refreshToken: 'refresh-abcdefghijkl',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  user: { id: 'user-1', name: {} } as AuthTokenBundle['user'],
+};
+
+const ROTATED: TokenRefreshResponse = {
+  accessToken: 'access-2',
+  refreshToken: 'refresh-mnopqrstuvwx',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  sessionId: 'sess-1',
+};
+
+describe('OxyServices.deviceBoot', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  describe('exchangeBootCode', () => {
+    it('POSTs the code and returns the validated bundle', async () => {
+      makeRequest.mockResolvedValueOnce(BUNDLE);
+      const result = await oxy.exchangeBootCode('code-123');
+      expect(result).toEqual(BUNDLE);
+      expect(makeRequest).toHaveBeenCalledWith('POST', '/auth/device/exchange', { code: 'code-123' }, { cache: false });
+    });
+
+    it('throws on an unexpected response shape', async () => {
+      makeRequest.mockResolvedValueOnce({ nope: true });
+      await expect(oxy.exchangeBootCode('code-123')).rejects.toThrow();
+    });
+  });
+
+  describe('requestWebSession', () => {
+    it('returns the session arm (bundle nested under `session` + deviceToken)', async () => {
+      const sessionArm: WebSessionResult = { reason: 'session', session: BUNDLE, deviceToken: 'device-abcdefghij' };
+      makeRequest.mockResolvedValueOnce(sessionArm);
+      const result = await oxy.requestWebSession();
+      expect(result).toEqual(sessionArm);
+      expect(makeRequest).toHaveBeenCalledWith('POST', '/auth/device/web-session', undefined, { cache: false });
+    });
+
+    it('returns the no-session arm', async () => {
+      const noSession: WebSessionResult = { reason: 'no_session', deviceToken: 'device-abcdefghij' };
+      makeRequest.mockResolvedValueOnce(noSession);
+      const result = await oxy.requestWebSession();
+      expect(result.reason).toBe('no_session');
+      expect(result).toEqual(noSession);
+    });
+
+    it('throws on the OLD bare-bundle shape (regression: server now wraps in a reason envelope)', async () => {
+      makeRequest.mockResolvedValueOnce(BUNDLE);
+      await expect(oxy.requestWebSession()).rejects.toThrow();
+    });
+
+    it('throws when the response matches neither arm', async () => {
+      makeRequest.mockResolvedValueOnce({ reason: 'weird' });
+      await expect(oxy.requestWebSession()).rejects.toThrow();
+    });
+  });
+
+  describe('refreshWithToken', () => {
+    it('POSTs with skipAuth and returns the rotated pair', async () => {
+      makeRequest.mockResolvedValueOnce(ROTATED);
+      const result = await oxy.refreshWithToken('refresh-abcdefghijkl');
+      expect(result).toEqual(ROTATED);
+      expect(makeRequest).toHaveBeenCalledWith(
+        'POST',
+        '/auth/refresh-token',
+        { refreshToken: 'refresh-abcdefghijkl' },
+        { cache: false, skipAuth: true },
+      );
+    });
+  });
+
+  describe('issueNativeDeviceToken', () => {
+    it('POSTs and returns just the token string', async () => {
+      makeRequest.mockResolvedValueOnce({ deviceToken: 'native-dt' });
+      expect(await oxy.issueNativeDeviceToken()).toBe('native-dt');
+      expect(makeRequest).toHaveBeenCalledWith('POST', '/auth/device/token', undefined, { cache: false });
+    });
+  });
+
+  describe('buildBootstrapUrl', () => {
+    it('builds the bootstrap URL with encoded params', () => {
+      const url = oxy.buildBootstrapUrl('https://accounts.oxy.so/home', 'st-1');
+      expect(url).toContain('http://test.invalid/auth/device/bootstrap?');
+      expect(url).toContain('return_to=https%3A%2F%2Faccounts.oxy.so%2Fhome');
+      expect(url).toContain('state=st-1');
+    });
+  });
+});