@oxyhq/core 7.1.1 → 8.0.0

package/src/mixins/OxyServices.devices.ts

@@ -2,6 +2,7 @@
  * Device Methods Mixin
  */
 import type { OxyServicesBase } from '../OxyServices.base';
+import type { DeviceLinkedSession, DeviceLinkedSessionLogoutResponse } from '../models/interfaces';
 
 export function OxyServicesDevicesMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -54,11 +55,11 @@ export function OxyServicesDevicesMixin<T extends typeof OxyServicesBase>(Base:
      * @param sessionId - The session ID
      * @returns Array of device sessions
      */
-    async getDeviceSessions(sessionId: string): Promise<any[]> {
+    async getDeviceSessions(sessionId: string): Promise<DeviceLinkedSession[]> {
       try {
         // Use makeRequest for consistent error handling and optional caching
         // Cache disabled by default to ensure fresh session data
-        return await this.makeRequest<any[]>('GET', `/session/device/sessions/${sessionId}`, undefined, {
+        return await this.makeRequest<DeviceLinkedSession[]>('GET', `/session/device/sessions/${sessionId}`, undefined, {
           cache: false, // Don't cache sessions - always get fresh data
           deduplicate: true, // Deduplicate concurrent requests for same sessionId
         });
@@ -74,12 +75,12 @@ export function OxyServicesDevicesMixin<T extends typeof OxyServicesBase>(Base:
      * @param excludeCurrent - Whether to exclude the current session
      * @returns Logout result
      */
-    async logoutAllDeviceSessions(sessionId: string, deviceId?: string, excludeCurrent?: boolean): Promise<any> {
+    async logoutAllDeviceSessions(sessionId: string, deviceId?: string, excludeCurrent?: boolean): Promise<DeviceLinkedSessionLogoutResponse> {
       try {
-        const urlParams: any = {};
+        const urlParams: Record<string, string> = {};
         if (deviceId) urlParams.deviceId = deviceId;
         if (excludeCurrent) urlParams.excludeCurrent = 'true';
-        return await this.makeRequest('POST', `/session/device/logout-all/${sessionId}`, urlParams, { cache: false });
+        return await this.makeRequest<DeviceLinkedSessionLogoutResponse>('POST', `/session/device/logout-all/${sessionId}`, urlParams, { cache: false });
       } catch (error) {
         throw this.handleError(error);
       }

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

@@ -83,7 +83,7 @@ const appFixture: Application = {
   isOfficial: true,
   isInternal: false,
   capabilities: [],
-  redirectUris: ['https://mention.earth/__oxy/sso-callback'],
+  redirectUris: ['https://mention.earth/oauth/callback'],
   scopes: ['profile'],
   createdByUserId: 'u1',
   ownerAccountId: 'acc1',

package/src/models/interfaces.ts

@@ -645,8 +645,10 @@ export interface AssetUploadProgress {
   error?: string;
 }
 
-// Device Session interfaces
-export interface DeviceSession {
+// Device-linked session interfaces — the sessions that share one physical
+// device (GET /session/device/sessions/:sessionId). Distinct from the
+// server-authority `DeviceSession` Mongoose model / `DeviceSessionState`.
+export interface DeviceLinkedSession {
   sessionId: string;
   deviceId: string;
   deviceName: string;
@@ -658,12 +660,12 @@ export interface DeviceSession {
   createdAt?: string;
 }
 
-export interface DeviceSessionsResponse {
+export interface DeviceLinkedSessionsResponse {
   deviceId: string;
-  sessions: DeviceSession[];
+  sessions: DeviceLinkedSession[];
 }
 
-export interface DeviceSessionLogoutResponse {
+export interface DeviceLinkedSessionLogoutResponse {
   message: string;
   deviceId: string;
   sessionsTerminated: number;

package/src/server/index.ts

@@ -69,9 +69,3 @@ export { verifySecret } from './verifySecret';
 // 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/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
-// `/sso/establish-token` `return_to` cannot drift from what `/sso/establish`
-// validates.
-export { SSO_CALLBACK_PATH } from '../utils/ssoBounce';

package/src/session/accountDialogController.ts

@@ -3,7 +3,7 @@
  *
  * A framework-agnostic state machine + subscribe/getSnapshot store (the same
  * pattern {@link SessionClient} uses — no React, no RN) that both
- * `@oxyhq/services` (RN `OxyProvider`) and `@oxyhq/auth` (web `WebOxyProvider`)
+ * every `OxyProvider` platform variant (Expo/RN and RN-Web)
  * bind to via `useSyncExternalStore`, so the account chooser is ONE
  * implementation across the ecosystem instead of the five drifting copies it
  * replaces.

package/src/session/accountProjection.ts

@@ -5,7 +5,7 @@
  * merging the device's server-authoritative session set (`DeviceSessionState`
  * from {@link SessionClient}) with the caller's account graph (`AccountNode[]`
  * from `oxyServices.listAccounts()`), deduped by `accountId`. This lives in
- * `@oxyhq/core` so `@oxyhq/services` (RN) and `@oxyhq/auth` (web) — and
+ * `@oxyhq/core` so every `@oxyhq/services` platform variant — and
  * `auth.oxy.so` — all render the SAME list from the SAME logic and cannot
  * diverge.
  *

package/src/session/projectSessionState.ts

@@ -5,7 +5,7 @@ import type { User } from '../models/interfaces';
 /**
  * Pure projection helpers: `DeviceSessionState` (the device-scoped
  * multi-account session-sync state produced by `SessionClient`) -> the
- * shapes consumers (`@oxyhq/services`, `@oxyhq/auth`) render today
+ * shapes `@oxyhq/services` consumers render today
  * (`ClientSession[]`, an active session id, an active `User`).
  *
  * No I/O. The caller fetches profiles via

package/src/session/refresh.ts

@@ -1,11 +1,8 @@
 /**
  * Unified token refresh — THE single refresh implementation for web + native.
  *
- * Before device-first, refresh was duplicated: `@oxyhq/auth`'s
- * `session/tokenRefresh.ts` (per-apex `/auth/silent` iframe) and
- * `@oxyhq/services`'s `inSessionTokenRefresh.ts` (native shared-key). This
- * module replaces both with ONE persisted-refresh-token rotation shared by
- * every consumer:
+ * ONE persisted-refresh-token rotation shared by every consumer (it replaced
+ * the pre-device-first per-platform duplicates):
  *
  *  - `refreshPersistedSession` — arm 1 rotates the stored refresh-token family
  *    (`POST /auth/refresh-token`), planting + persisting the rotated pair; arm 2
@@ -16,9 +13,8 @@
  *  - `createAuthRefreshHandler` / `installAuthRefreshHandler` wire arm 1+2 into
  *    `HttpService.setAuthRefreshHandler`, keeping that layer's single-flight
  *    dedup + cooldown (this module does NOT reimplement them).
- *  - `startTokenRefreshScheduler` — a proactive scheduler (lifted from the
- *    better of the two prior duplicates, `@oxyhq/auth`'s `tokenRefresh.ts`),
- *    decoupled from any React / auth-sdk type: refreshes ~60s before `exp`,
+ *  - `startTokenRefreshScheduler` — a proactive scheduler decoupled from any
+ *    React type: refreshes ~60s before `exp`,
  *    re-arms on token change + web tab-focus, `.unref?.()`s its timer in Node.
  *
  * Framework-free; no module-level mutable state.

package/src/session/sessionClientHost.ts

@@ -7,8 +7,7 @@ import type { SessionClientHost } from './SessionClient';
  * `SessionClient` is host-agnostic: it only needs a REST + token surface.
  * `OxyServices` already exposes all of that except `getCurrentAccountId`,
  * which has no direct equivalent — the adapter holds a mutable ref set by
- * the caller (`OxyContext` in `@oxyhq/services`, `WebOxyProvider` in
- * `@oxyhq/auth`) via `setCurrentAccountId`.
+ * the caller (`OxyContext` in `@oxyhq/services`) via `setCurrentAccountId`.
  *
  * Shared here (rather than duplicated per consumer) because it is entirely
  * platform-agnostic: every method it calls exists identically on

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

@@ -234,10 +234,9 @@ describe('runColdBoot', () => {
     });
 
     /**
-     * Reproduces the production hang: a step whose `run()` promise NEVER
-     * settles (the FedCM-silent `navigator.credentials.get` that ignored its
-     * abort signal). WITHOUT a deadline the whole `runColdBoot` promise hangs
-     * forever and the terminal step never runs.
+     * A step whose `run()` promise NEVER settles (e.g. an async call that
+     * ignores its abort signal). WITHOUT a deadline the whole `runColdBoot`
+     * promise hangs forever and the terminal step never runs.
      */
     it('hangs forever when a step never settles and no deadline is set', async () => {
       const terminalRan = jest.fn();
@@ -247,7 +246,7 @@ describe('runColdBoot', () => {
         steps: [
           {
             id: 'never-settles',
-            // Never resolves or rejects — models the hung FedCM credential get.
+            // Never resolves or rejects — models a hung async call.
             run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
           },
           {
@@ -275,9 +274,8 @@ describe('runColdBoot', () => {
 
     /**
      * With `overallDeadlineMs` set, the non-settling step is abandoned at the
-     * deadline, the runner CONTINUES to the terminal step (so the cross-domain
-     * `/sso` bounce equivalent still fires), and the whole boot settles to
-     * `unauthenticated` within the bounded budget.
+     * deadline, the runner CONTINUES to the terminal step, and the whole boot
+     * settles to `unauthenticated` within the bounded budget.
      */
     it('abandons a non-settling step at the deadline and still runs the terminal step', async () => {
       const terminalRan = jest.fn();
@@ -310,12 +308,12 @@ describe('runColdBoot', () => {
     });
 
     /**
-     * The terminal step's synchronous side effect (the real `sso-bounce`
-     * navigates BEFORE its first await) must still execute when the deadline
-     * trips on an earlier step — the cross-domain fallback is preserved.
+     * A terminal step may run a synchronous side effect before its first
+     * `await`; that side effect must still execute when the deadline trips on
+     * an earlier step — the terminal fallback is preserved.
      */
     it('lets the terminal step fire its synchronous side effect after the deadline trips', async () => {
-      const bounced = jest.fn();
+      const terminalSideEffect = jest.fn();
 
       const outcomePromise = runColdBoot<TestSession>({
         overallDeadlineMs: 3000,
@@ -325,10 +323,10 @@ describe('runColdBoot', () => {
             run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
           },
           {
-            id: 'sso-bounce',
+            id: 'terminal',
             run: async (): Promise<ColdBootStepResult<TestSession>> => {
-              // Synchronous navigation side effect, exactly like the real bounce.
-              bounced();
+              // Synchronous side effect that fires before the first await.
+              terminalSideEffect();
               return { kind: 'skip' };
             },
           },
@@ -338,7 +336,7 @@ describe('runColdBoot', () => {
       await jest.advanceTimersByTimeAsync(3000);
       await outcomePromise;
 
-      expect(bounced).toHaveBeenCalledTimes(1);
+      expect(terminalSideEffect).toHaveBeenCalledTimes(1);
     });
 
     /**
@@ -375,29 +373,22 @@ describe('runColdBoot', () => {
   });
 
   /**
-   * End-to-end reproduction of the production FedCM-silent hang at the REAL
-   * overall deadline the SDK ships.
-   *
-   * `OxyContext` runs the web cold-boot chain with `COLD_BOOT_OVERALL_DEADLINE`
-   * (20000 ms): fedcm-silent → /auth/silent iframe → cookie restore →
-   * stored-session → /sso top-level bounce (terminal). The documented gotcha:
-   * `navigator.credentials.get({mediation:'silent'})` can sit pending forever,
-   * ignoring its AbortController. WITHOUT the overall deadline the whole chain
-   * hangs and the terminal `/sso` bounce never fires.
-   *
-   * These tests model that exact chain shape against the real deadline value and
-   * assert the runner (a) abandons the hung silent step at the deadline,
-   * (b) still fires the terminal bounce's synchronous side effect, and
+   * End-to-end deadline semantics over a longer chain at the real overall
+   * deadline a consumer arms (the runner itself has no default). Models a chain
+   * whose FIRST step never settles — its `run()` promise ignores the abort
+   * signal and stays pending — followed by several no-op steps and a terminal
+   * step. Asserts the runner (a) abandons the hung step at the deadline,
+   * (b) still fires the terminal step's synchronous side effect, and
    * (c) always settles within the bounded budget — it never hangs.
    */
-  describe('production cold-boot deadline semantics (FedCM-silent hang)', () => {
+  describe('long-chain overall-deadline semantics', () => {
     /**
-     * Mirror of `COLD_BOOT_OVERALL_DEADLINE` in
-     * `@oxyhq/services` `OxyContext` (the only consumer that arms the deadline).
-     * Kept as a local literal because core does not — and must not — import the
-     * services package; if the consumer's value changes, update this to match.
+     * Mirror of the overall-deadline value a consumer arms (e.g. `@oxyhq/services`
+     * cold boot — the only consumer that arms the deadline). Kept as a local
+     * literal because core does not — and must not — import a consumer package;
+     * if the consumer's value changes, update this to match.
      */
-    const COLD_BOOT_OVERALL_DEADLINE = 20000;
+    const OVERALL_DEADLINE = 20000;
 
     beforeEach(() => {
       jest.useFakeTimers();
@@ -407,55 +398,54 @@ describe('runColdBoot', () => {
       jest.useRealTimers();
     });
 
-    /** A step whose `run()` never settles — the hung `credentials.get`. */
-    const hungFedcmSilentStep = (): ColdBootStep<TestSession> => ({
-      id: 'fedcm-silent',
+    /** A step whose `run()` never settles — models a hung async call. */
+    const neverSettlingStep = (): ColdBootStep<TestSession> => ({
+      id: 'never-settles',
       run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
     });
 
-    it('abandons the hung fedcm-silent step at the 20s deadline and fires the terminal /sso bounce', async () => {
-      const ssoBounced = jest.fn();
+    it('abandons the hung step at the deadline and fires the terminal step', async () => {
+      const terminalRan = jest.fn();
       const onStepDeadline = jest.fn();
 
       const outcomePromise = runColdBoot<TestSession>({
-        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        overallDeadlineMs: OVERALL_DEADLINE,
         onStepDeadline,
         steps: [
-          hungFedcmSilentStep(),
+          neverSettlingStep(),
           // Every intermediate step has nothing to contribute on this load.
-          skipStep('auth-silent-iframe'),
-          skipStep('cookie-restore'),
-          skipStep('stored-session'),
+          skipStep('intermediate-1'),
+          skipStep('intermediate-2'),
+          skipStep('intermediate-3'),
           {
-            id: 'sso-bounce',
-            // Terminal: navigates synchronously before its first await, exactly
-            // like the real top-level `/sso` bounce.
+            id: 'terminal',
+            // Runs a synchronous side effect before its first await.
             run: async (): Promise<ColdBootStepResult<TestSession>> => {
-              ssoBounced();
+              terminalRan();
               return { kind: 'skip' };
             },
           },
         ],
       });
 
-      // Nothing settles before the deadline — the chain is "stuck" on silent.
-      await jest.advanceTimersByTimeAsync(COLD_BOOT_OVERALL_DEADLINE - 1);
-      expect(ssoBounced).not.toHaveBeenCalled();
+      // Nothing settles before the deadline — the chain is stuck on the first step.
+      await jest.advanceTimersByTimeAsync(OVERALL_DEADLINE - 1);
+      expect(terminalRan).not.toHaveBeenCalled();
 
-      // At the deadline the silent step is abandoned and the chain proceeds.
+      // At the deadline the hung step is abandoned and the chain proceeds.
       await jest.advanceTimersByTimeAsync(1);
       const outcome = await outcomePromise;
 
-      expect(onStepDeadline).toHaveBeenCalledWith('fedcm-silent');
-      expect(ssoBounced).toHaveBeenCalledTimes(1);
+      expect(onStepDeadline).toHaveBeenCalledWith('never-settles');
+      expect(terminalRan).toHaveBeenCalledTimes(1);
       expect(outcome).toEqual({ kind: 'unauthenticated' });
     });
 
     it('settles within the bounded budget instead of hanging forever', async () => {
       let settled = false;
       const outcomePromise = runColdBoot<TestSession>({
-        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
-        steps: [hungFedcmSilentStep(), skipStep('terminal')],
+        overallDeadlineMs: OVERALL_DEADLINE,
+        steps: [neverSettlingStep(), skipStep('terminal')],
       }).then((o) => {
         settled = true;
         return o;
@@ -463,7 +453,7 @@ describe('runColdBoot', () => {
 
       // Just before the deadline: still pending (proves the deadline, not an
       // accidental early settle, is what unblocks it).
-      await jest.advanceTimersByTimeAsync(COLD_BOOT_OVERALL_DEADLINE - 1);
+      await jest.advanceTimersByTimeAsync(OVERALL_DEADLINE - 1);
       expect(settled).toBe(false);
 
       await jest.advanceTimersByTimeAsync(1);
@@ -471,19 +461,19 @@ describe('runColdBoot', () => {
       expect(settled).toBe(true);
     });
 
-    it('does not penalize a fast silent success — it wins well before the deadline', async () => {
+    it('does not penalize a fast first-step success — it wins well before the deadline', async () => {
       const laterRan = jest.fn();
       const outcomePromise = runColdBoot<TestSession>({
-        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        overallDeadlineMs: OVERALL_DEADLINE,
         steps: [
           {
-            id: 'fedcm-silent',
+            id: 'first',
             run: async (): Promise<ColdBootStepResult<TestSession>> => {
               await Promise.resolve();
-              return { kind: 'session', session: { userId: 'u-silent' } };
+              return { kind: 'session', session: { userId: 'u-fast' } };
             },
           },
-          sessionStep('sso-bounce', 'u-should-not-run', laterRan),
+          sessionStep('terminal', 'u-should-not-run', laterRan),
         ],
       });
 
@@ -492,8 +482,8 @@ describe('runColdBoot', () => {
 
       expect(outcome).toEqual({
         kind: 'session',
-        via: 'fedcm-silent',
-        session: { userId: 'u-silent' },
+        via: 'first',
+        session: { userId: 'u-fast' },
       });
       expect(laterRan).not.toHaveBeenCalled();
     });

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

@@ -0,0 +1,154 @@
+import { createHash } from 'node:crypto';
+import {
+  buildOAuthAuthorizeUrl,
+  computeCodeChallenge,
+  DEFAULT_OAUTH_SCOPE,
+  generateOAuthState,
+  generatePkcePair,
+  OXY_AUTHORIZE_URL,
+} from '../oauthPkce';
+
+/** RFC 7636 unreserved subset produced by base64url (no `+`, `/`, `=`). */
+const BASE64URL_RE = /^[A-Za-z0-9\-_]+$/;
+
+/** Independent base64url(SHA-256(input)) via Node crypto for cross-checking. */
+function nodeCodeChallenge(verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+describe('computeCodeChallenge', () => {
+  it('matches the RFC 7636 Appendix B known-answer vector', async () => {
+    // From RFC 7636 §Appendix B: verifier -> S256 challenge.
+    const verifier = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
+    const expected = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';
+    await expect(computeCodeChallenge(verifier)).resolves.toBe(expected);
+  });
+
+  it('produces unpadded base64url (no +, /, or = characters)', async () => {
+    const challenge = await computeCodeChallenge('some-arbitrary-code-verifier-value-123');
+    expect(challenge).toMatch(BASE64URL_RE);
+    expect(challenge).not.toContain('=');
+  });
+
+  it('agrees with an independent Node crypto implementation', async () => {
+    const verifier = 'another_verifier-value.with~allowed_chars-0123456789';
+    await expect(computeCodeChallenge(verifier)).resolves.toBe(nodeCodeChallenge(verifier));
+  });
+
+  it('encodes the full 32-byte SHA-256 digest as 43 base64url chars', async () => {
+    const challenge = await computeCodeChallenge('x');
+    expect(challenge).toHaveLength(43);
+  });
+});
+
+describe('generatePkcePair', () => {
+  it('returns a verifier, challenge, and S256 method', async () => {
+    const pair = await generatePkcePair();
+    expect(pair.method).toBe('S256');
+    expect(typeof pair.codeVerifier).toBe('string');
+    expect(typeof pair.codeChallenge).toBe('string');
+  });
+
+  it('produces a verifier in the RFC 7636 length range with only unreserved chars', async () => {
+    const { codeVerifier } = await generatePkcePair();
+    expect(codeVerifier).toMatch(BASE64URL_RE);
+    expect(codeVerifier.length).toBeGreaterThanOrEqual(43);
+    expect(codeVerifier.length).toBeLessThanOrEqual(128);
+  });
+
+  it('derives the challenge as base64url(SHA-256(verifier))', async () => {
+    const { codeVerifier, codeChallenge } = await generatePkcePair();
+    await expect(computeCodeChallenge(codeVerifier)).resolves.toBe(codeChallenge);
+    expect(codeChallenge).toBe(nodeCodeChallenge(codeVerifier));
+  });
+
+  it('generates a fresh, unpredictable verifier on each call', async () => {
+    const [a, b] = await Promise.all([generatePkcePair(), generatePkcePair()]);
+    expect(a.codeVerifier).not.toBe(b.codeVerifier);
+    expect(a.codeChallenge).not.toBe(b.codeChallenge);
+  });
+});
+
+describe('generateOAuthState', () => {
+  it('returns an unreserved base64url token of 32 random bytes (43 chars)', async () => {
+    const state = await generateOAuthState();
+    expect(state).toMatch(BASE64URL_RE);
+    expect(state).toHaveLength(43);
+  });
+
+  it('is unique across calls', async () => {
+    const [a, b] = await Promise.all([generateOAuthState(), generateOAuthState()]);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('buildOAuthAuthorizeUrl', () => {
+  const base = {
+    clientId: 'oxy_dk_example',
+    redirectUri: 'https://merchant.co/auth/callback',
+    state: 'csrf-state-token',
+    codeChallenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
+  };
+
+  it('defaults to the Oxy authorize endpoint', () => {
+    const url = buildOAuthAuthorizeUrl(base);
+    expect(url.startsWith(`${OXY_AUTHORIZE_URL}?`)).toBe(true);
+    expect(OXY_AUTHORIZE_URL).toBe('https://auth.oxy.so/authorize');
+  });
+
+  it('includes every required OAuth authorization-code + PKCE parameter', () => {
+    const params = new URL(buildOAuthAuthorizeUrl(base)).searchParams;
+    expect(params.get('client_id')).toBe(base.clientId);
+    expect(params.get('redirect_uri')).toBe(base.redirectUri);
+    expect(params.get('response_type')).toBe('code');
+    expect(params.get('state')).toBe(base.state);
+    expect(params.get('scope')).toBe(DEFAULT_OAUTH_SCOPE);
+    expect(params.get('code_challenge')).toBe(base.codeChallenge);
+    expect(params.get('code_challenge_method')).toBe('S256');
+  });
+
+  it('defaults the scope to "openid profile"', () => {
+    const params = new URL(buildOAuthAuthorizeUrl(base)).searchParams;
+    expect(params.get('scope')).toBe('openid profile');
+  });
+
+  it('honors a custom scope', () => {
+    const params = new URL(
+      buildOAuthAuthorizeUrl({ ...base, scope: 'openid profile email wallet' }),
+    ).searchParams;
+    expect(params.get('scope')).toBe('openid profile email wallet');
+  });
+
+  it('honors an authorizeBaseUrl override', () => {
+    const url = buildOAuthAuthorizeUrl({
+      ...base,
+      authorizeBaseUrl: 'https://auth.merchant.co/authorize',
+    });
+    expect(url.startsWith('https://auth.merchant.co/authorize?')).toBe(true);
+    expect(new URL(url).searchParams.get('client_id')).toBe(base.clientId);
+  });
+
+  it('preserves a query string already present on authorizeBaseUrl', () => {
+    const params = new URL(
+      buildOAuthAuthorizeUrl({
+        ...base,
+        authorizeBaseUrl: 'https://auth.merchant.co/authorize?foo=bar&tenant=acme',
+      }),
+    ).searchParams;
+    // Pre-existing params survive alongside the OAuth params.
+    expect(params.get('foo')).toBe('bar');
+    expect(params.get('tenant')).toBe('acme');
+    expect(params.get('client_id')).toBe(base.clientId);
+    expect(params.get('code_challenge_method')).toBe('S256');
+  });
+
+  it('URL-encodes a redirect_uri that carries a query string and special chars', () => {
+    const redirectUri = 'https://merchant.co/auth/callback?next=/dashboard&lang=es';
+    const url = buildOAuthAuthorizeUrl({ ...base, redirectUri });
+    // The raw string must be percent-encoded (its own & must not leak as a delimiter).
+    expect(url).toContain('redirect_uri=https%3A%2F%2Fmerchant.co%2Fauth%2Fcallback');
+    expect(url).not.toContain('redirect_uri=https://merchant.co');
+    // Round-trips back to the exact original when parsed.
+    expect(new URL(url).searchParams.get('redirect_uri')).toBe(redirectUri);
+  });
+});

package/src/utils/accountUtils.ts

@@ -1,6 +1,6 @@
 /**
  * Shared account types and pure helper functions.
- * Used by both @oxyhq/services (React Native) and @oxyhq/auth (Web) account stores.
+ * Used by the @oxyhq/services account stores (Expo/RN and RN-Web).
  */
 
 import { translate } from '../i18n';