@oxyhq/core 7.1.1 → 8.1.0

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';

package/src/utils/oauthPkce.ts

@@ -0,0 +1,189 @@
+/**
+ * OAuth 2.0 Authorization Code + PKCE helpers for "Sign in with Oxy" third-party
+ * sign-in.
+ *
+ * Third-party Relying Parties (SPAs, static sites, and native apps that are NOT
+ * Oxy first-party) authenticate through the standard OAuth flow against
+ * `auth.oxy.so/authorize` — never FedCM, SSO bounces, or Oxy session cookies.
+ * Public clients (no secret) prove possession of the authorization code with
+ * PKCE (RFC 7636, S256): the RP generates a random `code_verifier`, sends its
+ * `code_challenge = BASE64URL(SHA-256(code_verifier))` on the authorize
+ * redirect, and later replays the raw verifier on the token exchange.
+ *
+ * All cross-platform crypto (random bytes, SHA-256) is delegated to the shared
+ * `@oxyhq/protocol` platform loaders — the exact primitives the rest of core's
+ * crypto already uses — so these helpers run identically on web, Node, and
+ * React Native. No `require()`, so the ESM build stays bundler-clean.
+ */
+
+import { isNodeJS, isReactNative, loadExpoCrypto, loadNodeCrypto, sha256 } from '@oxyhq/protocol';
+import { logger } from './loggerUtils';
+
+/** The central Oxy IdP authorization endpoint used by default. */
+export const OXY_AUTHORIZE_URL = 'https://auth.oxy.so/authorize';
+
+/** Default OAuth scope requested for a "Sign in with Oxy" third-party flow. */
+export const DEFAULT_OAUTH_SCOPE = 'openid profile';
+
+/**
+ * Number of random bytes behind a PKCE `code_verifier`. 64 bytes → 86 base64url
+ * characters, comfortably inside RFC 7636 §4.1's required 43–128 range.
+ */
+const PKCE_VERIFIER_BYTES = 64;
+
+/** Number of random bytes behind an OAuth `state` (CSRF) token. */
+const OAUTH_STATE_BYTES = 32;
+
+/** RFC 4648 §5 base64url alphabet (URL- and filename-safe, no padding). */
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+/** A generated PKCE verifier/challenge pair. */
+export interface PkcePair {
+  /** The high-entropy secret replayed on the token exchange (kept client-side). */
+  codeVerifier: string;
+  /** `BASE64URL(SHA-256(codeVerifier))` — sent on the authorize redirect. */
+  codeChallenge: string;
+  /** The PKCE transformation method. Always `S256`. */
+  method: 'S256';
+}
+
+/** Parameters for {@link buildOAuthAuthorizeUrl}. */
+export interface BuildOAuthAuthorizeUrlParams {
+  /** Authorize endpoint; defaults to {@link OXY_AUTHORIZE_URL}. */
+  authorizeBaseUrl?: string;
+  /** The registered `ApplicationCredential` public key (`oxy_dk_…`). */
+  clientId: string;
+  /** Exact registered redirect URI to return the authorization code to. */
+  redirectUri: string;
+  /** Requested scope; defaults to {@link DEFAULT_OAUTH_SCOPE}. */
+  scope?: string;
+  /** Opaque CSRF token from {@link generateOAuthState}. */
+  state: string;
+  /** The PKCE `codeChallenge` from {@link generatePkcePair}. */
+  codeChallenge: string;
+}
+
+/**
+ * Cryptographically-secure random bytes, cross-platform.
+ *
+ * Mirrors the platform gating the rest of core's crypto already uses:
+ * `expo-crypto` on React Native, Node's built-in `crypto` on the server, and
+ * the Web Crypto API in the browser (also the fallback if Node's `crypto`
+ * fails to load in an unusual bundled-Node environment).
+ */
+async function getSecureRandomBytes(byteLength: number): Promise<Uint8Array> {
+  if (isReactNative()) {
+    const crypto = await loadExpoCrypto();
+    return Uint8Array.from(await crypto.getRandomBytesAsync(byteLength));
+  }
+
+  if (isNodeJS()) {
+    try {
+      const nodeCrypto = await loadNodeCrypto();
+      return Uint8Array.from(nodeCrypto.randomBytes(byteLength));
+    } catch (error) {
+      logger.warn(
+        '[oxy.oauth] Node crypto unavailable for PKCE random bytes, falling back to Web Crypto',
+        { component: 'oauthPkce' },
+        error,
+      );
+    }
+  }
+
+  const bytes = new Uint8Array(byteLength);
+  globalThis.crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+/** Encode raw bytes as unpadded base64url (RFC 4648 §5). */
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let output = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const byte0 = bytes[i];
+    const hasByte1 = i + 1 < bytes.length;
+    const hasByte2 = i + 2 < bytes.length;
+    const byte1 = hasByte1 ? bytes[i + 1] : 0;
+    const byte2 = hasByte2 ? bytes[i + 2] : 0;
+
+    output += BASE64URL_ALPHABET[byte0 >> 2];
+    output += BASE64URL_ALPHABET[((byte0 & 0x03) << 4) | (byte1 >> 4)];
+    if (hasByte1) {
+      output += BASE64URL_ALPHABET[((byte1 & 0x0f) << 2) | (byte2 >> 6)];
+    }
+    if (hasByte2) {
+      output += BASE64URL_ALPHABET[byte2 & 0x3f];
+    }
+  }
+  return output;
+}
+
+/** Decode a lowercase-hex string into its raw bytes. */
+function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Compute the PKCE S256 `code_challenge` for a given verifier:
+ * `BASE64URL(SHA-256(ASCII(codeVerifier)))` (RFC 7636 §4.2). The verifier is
+ * base64url (ASCII), so its UTF-8 and ASCII byte encodings are identical.
+ *
+ * Reuses `@oxyhq/protocol`'s cross-platform {@link sha256} (which returns
+ * lowercase hex); the digest bytes are recovered and re-encoded as base64url.
+ */
+export async function computeCodeChallenge(codeVerifier: string): Promise<string> {
+  const digestHex = await sha256(codeVerifier);
+  return bytesToBase64Url(hexToBytes(digestHex));
+}
+
+/**
+ * Generate a fresh PKCE verifier/challenge pair for an OAuth authorization-code
+ * flow. The verifier is 64 random bytes as base64url (86 chars, within RFC 7636
+ * §4.1's 43–128 range and drawn only from the unreserved set); the challenge is
+ * its S256 transform.
+ */
+export async function generatePkcePair(): Promise<PkcePair> {
+  const codeVerifier = bytesToBase64Url(await getSecureRandomBytes(PKCE_VERIFIER_BYTES));
+  const codeChallenge = await computeCodeChallenge(codeVerifier);
+  return { codeVerifier, codeChallenge, method: 'S256' };
+}
+
+/**
+ * Generate an opaque, single-use OAuth `state` token (32 random bytes as
+ * base64url) for CSRF protection across the authorize redirect.
+ */
+export async function generateOAuthState(): Promise<string> {
+  return bytesToBase64Url(await getSecureRandomBytes(OAUTH_STATE_BYTES));
+}
+
+/**
+ * Build the `auth.oxy.so/authorize` redirect URL for an OAuth authorization-code
+ * + PKCE (S256) flow. Built via the WHATWG `URL` API so a custom
+ * `authorizeBaseUrl` that already carries a query string keeps its existing
+ * params (the OAuth params are merged in, not clobbered by a naive `?` concat).
+ * All values are percent-encoded by `URL.searchParams`.
+ */
+export function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlParams): string {
+  const {
+    authorizeBaseUrl = OXY_AUTHORIZE_URL,
+    clientId,
+    redirectUri,
+    scope = DEFAULT_OAUTH_SCOPE,
+    state,
+    codeChallenge,
+  } = params;
+
+  const url = new URL(authorizeBaseUrl);
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('state', state);
+  url.searchParams.set('scope', scope);
+  url.searchParams.set('code_challenge', codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+
+  return url.toString();
+}

package/src/utils/platform.ts

@@ -104,7 +104,7 @@ export function setPlatformOS(os: PlatformOS): void {
  *
  * Native defines a global `window` but no `document`, so the DOM probe — not a
  * bare `window` check — is the reliable discriminator. This is the single
- * source of truth consumed by `@oxyhq/services` and `@oxyhq/auth` (both dropped
+ * source of truth consumed by `@oxyhq/services` (which dropped
  * their local copies), so every consumer shares the exact same predicate.
  *
  * NOTE: this is a live runtime probe (not the cached `getPlatformOS()` verdict)

package/dist/cjs/utils/ssoBounce.js

@@ -1,24 +0,0 @@
-"use strict";
-/**
- * SSO callback path constant.
- *
- * The client SSO-bounce machinery (per-origin sessionStorage keys, the bounce
- * URL builder, the `guardActive` / `allowSsoBounce` / `getSsoCallbackBootstrapScript`
- * predicates, …) was removed in the device-first cutover — RP apps no longer
- * bounce through `auth.oxy.so`. The one survivor is this path constant, still
- * referenced by the api SSO controller and the IdP (both lista B, gated on the
- * ecosystem bump). `@oxyhq/core/server` re-exports it for the api.
- *
- * LEGACY(old-sdk): `SSO_CALLBACK_PATH` survives ONLY for the lista-B api/IdP SSO
- * surface. Deletable once Homiio/Allo/Alia/Syra are bumped off the old SDK AND
- * CloudWatch `/oxy/ecs` shows the `/sso*` + `/fedcm/*` routes quiet — the
- * F-final sweep should remove this file then.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SSO_CALLBACK_PATH = void 0;
-/**
- * The RP callback path the central IdP redirects back to after a legacy SSO
- * bounce. Kept as the single source of truth so the api/IdP never hardcode the
- * literal.
- */
-exports.SSO_CALLBACK_PATH = '/__oxy/sso-callback';

package/dist/esm/utils/ssoBounce.js

@@ -1,21 +0,0 @@
-/**
- * SSO callback path constant.
- *
- * The client SSO-bounce machinery (per-origin sessionStorage keys, the bounce
- * URL builder, the `guardActive` / `allowSsoBounce` / `getSsoCallbackBootstrapScript`
- * predicates, …) was removed in the device-first cutover — RP apps no longer
- * bounce through `auth.oxy.so`. The one survivor is this path constant, still
- * referenced by the api SSO controller and the IdP (both lista B, gated on the
- * ecosystem bump). `@oxyhq/core/server` re-exports it for the api.
- *
- * LEGACY(old-sdk): `SSO_CALLBACK_PATH` survives ONLY for the lista-B api/IdP SSO
- * surface. Deletable once Homiio/Allo/Alia/Syra are bumped off the old SDK AND
- * CloudWatch `/oxy/ecs` shows the `/sso*` + `/fedcm/*` routes quiet — the
- * F-final sweep should remove this file then.
- */
-/**
- * The RP callback path the central IdP redirects back to after a legacy SSO
- * bounce. Kept as the single source of truth so the api/IdP never hardcode the
- * literal.
- */
-export const SSO_CALLBACK_PATH = '/__oxy/sso-callback';

package/dist/types/utils/ssoBounce.d.ts

@@ -1,21 +0,0 @@
-/**
- * SSO callback path constant.
- *
- * The client SSO-bounce machinery (per-origin sessionStorage keys, the bounce
- * URL builder, the `guardActive` / `allowSsoBounce` / `getSsoCallbackBootstrapScript`
- * predicates, …) was removed in the device-first cutover — RP apps no longer
- * bounce through `auth.oxy.so`. The one survivor is this path constant, still
- * referenced by the api SSO controller and the IdP (both lista B, gated on the
- * ecosystem bump). `@oxyhq/core/server` re-exports it for the api.
- *
- * LEGACY(old-sdk): `SSO_CALLBACK_PATH` survives ONLY for the lista-B api/IdP SSO
- * surface. Deletable once Homiio/Allo/Alia/Syra are bumped off the old SDK AND
- * CloudWatch `/oxy/ecs` shows the `/sso*` + `/fedcm/*` routes quiet — the
- * F-final sweep should remove this file then.
- */
-/**
- * The RP callback path the central IdP redirects back to after a legacy SSO
- * bounce. Kept as the single source of truth so the api/IdP never hardcode the
- * literal.
- */
-export declare const SSO_CALLBACK_PATH = "/__oxy/sso-callback";