@oxy.so/core 1.0.0

package/src/utils/languageUtils.ts

@@ -0,0 +1,256 @@
+/**
+ * Locale utilities for OxyServices.
+ *
+ * The Oxy platform models account languages as full BCP-47 locales
+ * (`language-REGION`, e.g. `es-ES`, `es-MX`, `pt-BR`). Region is significant:
+ * "Spanish (Spain)" is a different locale than "Spanish (Mexico)". A user's
+ * account locales live on `User.languages` as an ordered list with the PRIMARY
+ * (UI) locale first — there is no singular `language` field.
+ *
+ * This module is the single source of truth for the supported-locale catalog
+ * and every locale operation the SDK exposes: parsing base subtags, canonical
+ * normalization, validation, metadata lookup, and resolving a user's locales.
+ * It is pure and side-effect free.
+ */
+
+import type { User } from '../models/interfaces';
+
+/**
+ * A supported BCP-47 locale in the Oxy catalog.
+ */
+export interface SupportedLanguage {
+  /** Canonical BCP-47 locale tag, `language-REGION` (e.g. `'es-ES'`). */
+  code: string;
+  /** ISO 639-1 base language subtag, lowercased (e.g. `'es'`). */
+  language: string;
+  /** ISO 3166-1 alpha-2 region subtag, uppercased (e.g. `'ES'`). */
+  region: string;
+  /** English display name, `'Language (Region)'` (e.g. `'Spanish (Spain)'`). */
+  name: string;
+  /** Endonym — the name as written in the locale itself (e.g. `'Español (España)'`). */
+  nativeName: string;
+  /** `true` when the locale is written right-to-left. Omitted for LTR locales. */
+  rtl?: boolean;
+}
+
+/**
+ * The supported-locale catalog. Ordered by prominence for display; the order
+ * is not otherwise significant. Every entry is a full `language-REGION` tag,
+ * with the base subtag lowercased and the region uppercased.
+ */
+export const SUPPORTED_LANGUAGES: readonly SupportedLanguage[] = [
+  // English
+  { code: 'en-US', language: 'en', region: 'US', name: 'English (United States)', nativeName: 'English (United States)' },
+  { code: 'en-GB', language: 'en', region: 'GB', name: 'English (United Kingdom)', nativeName: 'English (United Kingdom)' },
+  { code: 'en-AU', language: 'en', region: 'AU', name: 'English (Australia)', nativeName: 'English (Australia)' },
+  { code: 'en-CA', language: 'en', region: 'CA', name: 'English (Canada)', nativeName: 'English (Canada)' },
+  { code: 'en-IN', language: 'en', region: 'IN', name: 'English (India)', nativeName: 'English (India)' },
+
+  // Spanish
+  { code: 'es-ES', language: 'es', region: 'ES', name: 'Spanish (Spain)', nativeName: 'Español (España)' },
+  { code: 'es-MX', language: 'es', region: 'MX', name: 'Spanish (Mexico)', nativeName: 'Español (México)' },
+  { code: 'es-US', language: 'es', region: 'US', name: 'Spanish (United States)', nativeName: 'Español (Estados Unidos)' },
+  { code: 'es-AR', language: 'es', region: 'AR', name: 'Spanish (Argentina)', nativeName: 'Español (Argentina)' },
+  { code: 'es-CO', language: 'es', region: 'CO', name: 'Spanish (Colombia)', nativeName: 'Español (Colombia)' },
+
+  // Portuguese
+  { code: 'pt-BR', language: 'pt', region: 'BR', name: 'Portuguese (Brazil)', nativeName: 'Português (Brasil)' },
+  { code: 'pt-PT', language: 'pt', region: 'PT', name: 'Portuguese (Portugal)', nativeName: 'Português (Portugal)' },
+
+  // French
+  { code: 'fr-FR', language: 'fr', region: 'FR', name: 'French (France)', nativeName: 'Français (France)' },
+  { code: 'fr-CA', language: 'fr', region: 'CA', name: 'French (Canada)', nativeName: 'Français (Canada)' },
+
+  // German
+  { code: 'de-DE', language: 'de', region: 'DE', name: 'German (Germany)', nativeName: 'Deutsch (Deutschland)' },
+  { code: 'de-AT', language: 'de', region: 'AT', name: 'German (Austria)', nativeName: 'Deutsch (Österreich)' },
+  { code: 'de-CH', language: 'de', region: 'CH', name: 'German (Switzerland)', nativeName: 'Deutsch (Schweiz)' },
+
+  // Italian
+  { code: 'it-IT', language: 'it', region: 'IT', name: 'Italian (Italy)', nativeName: 'Italiano (Italia)' },
+
+  // Dutch
+  { code: 'nl-NL', language: 'nl', region: 'NL', name: 'Dutch (Netherlands)', nativeName: 'Nederlands (Nederland)' },
+  { code: 'nl-BE', language: 'nl', region: 'BE', name: 'Dutch (Belgium)', nativeName: 'Nederlands (België)' },
+
+  // Nordic
+  { code: 'sv-SE', language: 'sv', region: 'SE', name: 'Swedish (Sweden)', nativeName: 'Svenska (Sverige)' },
+  { code: 'nb-NO', language: 'nb', region: 'NO', name: 'Norwegian Bokmål (Norway)', nativeName: 'Norsk bokmål (Norge)' },
+  { code: 'da-DK', language: 'da', region: 'DK', name: 'Danish (Denmark)', nativeName: 'Dansk (Danmark)' },
+  { code: 'fi-FI', language: 'fi', region: 'FI', name: 'Finnish (Finland)', nativeName: 'Suomi (Suomi)' },
+
+  // Central & Eastern Europe
+  { code: 'pl-PL', language: 'pl', region: 'PL', name: 'Polish (Poland)', nativeName: 'Polski (Polska)' },
+  { code: 'cs-CZ', language: 'cs', region: 'CZ', name: 'Czech (Czechia)', nativeName: 'Čeština (Česko)' },
+  { code: 'sk-SK', language: 'sk', region: 'SK', name: 'Slovak (Slovakia)', nativeName: 'Slovenčina (Slovensko)' },
+  { code: 'hu-HU', language: 'hu', region: 'HU', name: 'Hungarian (Hungary)', nativeName: 'Magyar (Magyarország)' },
+  { code: 'ro-RO', language: 'ro', region: 'RO', name: 'Romanian (Romania)', nativeName: 'Română (România)' },
+  { code: 'bg-BG', language: 'bg', region: 'BG', name: 'Bulgarian (Bulgaria)', nativeName: 'Български (България)' },
+  { code: 'hr-HR', language: 'hr', region: 'HR', name: 'Croatian (Croatia)', nativeName: 'Hrvatski (Hrvatska)' },
+  { code: 'sr-RS', language: 'sr', region: 'RS', name: 'Serbian (Serbia)', nativeName: 'Српски (Србија)' },
+  { code: 'sl-SI', language: 'sl', region: 'SI', name: 'Slovenian (Slovenia)', nativeName: 'Slovenščina (Slovenija)' },
+  { code: 'lt-LT', language: 'lt', region: 'LT', name: 'Lithuanian (Lithuania)', nativeName: 'Lietuvių (Lietuva)' },
+  { code: 'lv-LV', language: 'lv', region: 'LV', name: 'Latvian (Latvia)', nativeName: 'Latviešu (Latvija)' },
+  { code: 'et-EE', language: 'et', region: 'EE', name: 'Estonian (Estonia)', nativeName: 'Eesti (Eesti)' },
+  { code: 'uk-UA', language: 'uk', region: 'UA', name: 'Ukrainian (Ukraine)', nativeName: 'Українська (Україна)' },
+  { code: 'ru-RU', language: 'ru', region: 'RU', name: 'Russian (Russia)', nativeName: 'Русский (Россия)' },
+  { code: 'el-GR', language: 'el', region: 'GR', name: 'Greek (Greece)', nativeName: 'Ελληνικά (Ελλάδα)' },
+
+  // Turkish
+  { code: 'tr-TR', language: 'tr', region: 'TR', name: 'Turkish (Türkiye)', nativeName: 'Türkçe (Türkiye)' },
+
+  // Catalan
+  { code: 'ca-ES', language: 'ca', region: 'ES', name: 'Catalan (Spain)', nativeName: 'Català (Espanya)' },
+
+  // East, South & Southeast Asia
+  { code: 'ja-JP', language: 'ja', region: 'JP', name: 'Japanese (Japan)', nativeName: '日本語 (日本)' },
+  { code: 'ko-KR', language: 'ko', region: 'KR', name: 'Korean (South Korea)', nativeName: '한국어 (대한민국)' },
+  { code: 'zh-CN', language: 'zh', region: 'CN', name: 'Chinese (Simplified, China)', nativeName: '中文 (中国)' },
+  { code: 'zh-TW', language: 'zh', region: 'TW', name: 'Chinese (Traditional, Taiwan)', nativeName: '中文 (台灣)' },
+  { code: 'zh-HK', language: 'zh', region: 'HK', name: 'Chinese (Traditional, Hong Kong)', nativeName: '中文 (香港)' },
+  { code: 'hi-IN', language: 'hi', region: 'IN', name: 'Hindi (India)', nativeName: 'हिन्दी (भारत)' },
+  { code: 'bn-BD', language: 'bn', region: 'BD', name: 'Bengali (Bangladesh)', nativeName: 'বাংলা (বাংলাদেশ)' },
+  { code: 'id-ID', language: 'id', region: 'ID', name: 'Indonesian (Indonesia)', nativeName: 'Bahasa Indonesia (Indonesia)' },
+  { code: 'ms-MY', language: 'ms', region: 'MY', name: 'Malay (Malaysia)', nativeName: 'Bahasa Melayu (Malaysia)' },
+  { code: 'th-TH', language: 'th', region: 'TH', name: 'Thai (Thailand)', nativeName: 'ไทย (ประเทศไทย)' },
+  { code: 'vi-VN', language: 'vi', region: 'VN', name: 'Vietnamese (Vietnam)', nativeName: 'Tiếng Việt (Việt Nam)' },
+
+  // Right-to-left
+  { code: 'ar-SA', language: 'ar', region: 'SA', name: 'Arabic (Saudi Arabia)', nativeName: 'العربية (السعودية)', rtl: true },
+  { code: 'ar-EG', language: 'ar', region: 'EG', name: 'Arabic (Egypt)', nativeName: 'العربية (مصر)', rtl: true },
+  { code: 'he-IL', language: 'he', region: 'IL', name: 'Hebrew (Israel)', nativeName: 'עברית (ישראל)', rtl: true },
+  { code: 'fa-IR', language: 'fa', region: 'IR', name: 'Persian (Iran)', nativeName: 'فارسی (ایران)', rtl: true },
+  { code: 'ur-PK', language: 'ur', region: 'PK', name: 'Urdu (Pakistan)', nativeName: 'اردو (پاکستان)', rtl: true },
+];
+
+/** Canonical fallback locale used when a display value cannot be resolved. */
+export const FALLBACK_LOCALE = 'en-US';
+
+/** O(1) lookup of a catalog entry by its canonical code. */
+const LOCALE_BY_CODE: ReadonlyMap<string, SupportedLanguage> = new Map(
+  SUPPORTED_LANGUAGES.map((entry) => [entry.code, entry]),
+);
+
+/**
+ * Extract the base language subtag from a locale, lowercased.
+ *
+ * Tolerant of bare base subtags and of extra subtags (script/variant):
+ * `'es-ES'` → `'es'`, `'es'` → `'es'`, `'zh-Hant-TW'` → `'zh'`. Returns an
+ * empty string for empty input.
+ */
+export function getBaseLanguage(locale: string): string {
+  return locale.trim().toLowerCase().split('-')[0] ?? '';
+}
+
+/**
+ * Normalize a locale string to its canonical `language-REGION` form when it is
+ * a supported locale, otherwise `undefined`.
+ *
+ * Canonicalization lowercases the base subtag and uppercases the region
+ * subtag (`'es-es'` → `'es-ES'`, `'EN-us'` → `'en-US'`) and validates the
+ * result against {@link SUPPORTED_LANGUAGES}. A bare base subtag (`'es'`) has
+ * no region and is therefore not a locale — it returns `undefined`.
+ */
+export function normalizeLocale(input: string): string | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+
+  const parts = trimmed.split('-');
+  if (parts.length < 2) return undefined;
+
+  const base = parts[0]?.toLowerCase();
+  const region = parts[parts.length - 1]?.toUpperCase();
+  if (!base || !region) return undefined;
+
+  const canonical = `${base}-${region}`;
+  return LOCALE_BY_CODE.has(canonical) ? canonical : undefined;
+}
+
+/**
+ * Whether `input` resolves to a supported BCP-47 locale.
+ */
+export function isSupportedLocale(input: string): boolean {
+  return normalizeLocale(input) !== undefined;
+}
+
+/**
+ * Resolve catalog metadata for a locale.
+ *
+ * @param code - A locale tag (any case; e.g. `'es-ES'`, `'es-es'`).
+ * @returns The {@link SupportedLanguage} entry, or `null` when the tag is empty
+ *   or not a supported locale.
+ */
+export function getLanguageMetadata(code: string | null | undefined): SupportedLanguage | null {
+  if (!code) return null;
+  const canonical = normalizeLocale(code);
+  if (!canonical) return null;
+  return LOCALE_BY_CODE.get(canonical) ?? null;
+}
+
+/**
+ * English display name for a locale (e.g. `'Spanish (Spain)'`).
+ * Falls back to the input tag, then {@link FALLBACK_LOCALE}.
+ */
+export function getLanguageName(code: string | null | undefined): string {
+  return getLanguageMetadata(code)?.name || code || FALLBACK_LOCALE;
+}
+
+/**
+ * Native display name (endonym) for a locale (e.g. `'Español (España)'`).
+ * Falls back to the input tag, then {@link FALLBACK_LOCALE}.
+ */
+export function getNativeLanguageName(code: string | null | undefined): string {
+  return getLanguageMetadata(code)?.nativeName || code || FALLBACK_LOCALE;
+}
+
+/**
+ * Base language subtags whose scripts are written right-to-left. Used to drive
+ * `I18nManager.forceRTL(...)` on React Native and `<html dir="rtl">` on web.
+ * Includes Arabic (`ar`), Hebrew (`he` / legacy `iw`), Persian (`fa`), and
+ * Urdu (`ur`).
+ */
+const RTL_LANGUAGE_BASES: ReadonlySet<string> = new Set(['ar', 'he', 'iw', 'fa', 'ur']);
+
+/**
+ * Whether a locale (or bare base subtag) is written right-to-left. Unknown
+ * tags are treated as left-to-right.
+ */
+export function isRTLLocale(locale?: string | null): boolean {
+  if (!locale) return false;
+  return RTL_LANGUAGE_BASES.has(getBaseLanguage(locale));
+}
+
+/**
+ * Resolve the ordered list of account locales for a user, primary first.
+ *
+ * Reads `user.languages` (the only source — there is no singular `language`
+ * field), then normalizes each entry to its canonical `language-REGION` form,
+ * drops non-string and unsupported entries, and de-duplicates while preserving
+ * first-seen order. Pure and side-effect free — never throws on bad input.
+ */
+export function getUserLanguages(user: Pick<User, 'languages'> | null | undefined): string[] {
+  const source = user?.languages;
+  if (!Array.isArray(source)) return [];
+
+  const result: string[] = [];
+  const seen = new Set<string>();
+
+  for (const entry of source) {
+    if (typeof entry !== 'string') continue;
+    const canonical = normalizeLocale(entry);
+    if (!canonical || seen.has(canonical)) continue;
+    seen.add(canonical);
+    result.push(canonical);
+  }
+
+  return result;
+}
+
+/**
+ * Resolve the single PRIMARY locale for a user (the first entry from
+ * {@link getUserLanguages}), or `undefined` when the user has no supported
+ * locale.
+ */
+export function getPrimaryLanguage(user: Pick<User, 'languages'> | null | undefined): string | undefined {
+  return getUserLanguages(user)[0];
+}

package/src/utils/oauthPkce.ts

@@ -0,0 +1,392 @@
+/**
+ * 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
+ * `@oxy.so/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 '@oxy.so/protocol';
+import { logger } from '../logger';
+
+/** 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;
+  /**
+   * OAuth `prompt` parameter — `login` forces a fresh authentication even when
+   * the IdP already has a session, `consent` forces the consent screen even for
+   * an already-granted scope. Both are ordinary OAuth/OIDC and are here for
+   * third-party relying parties building their own authorize link.
+   *
+   * `'none'` is deliberately NOT in this union. It is the silent-SSO value, and
+   * it was the only value this SDK ever sent — from the cold-boot cross-origin
+   * restore deleted in #691 phase 7b. Accepting it again would hand consumers a
+   * one-line rebuild of the automatic, gesture-less full-page bounce to the IdP
+   * that the popup transport exists to eliminate.
+   */
+  prompt?: 'login' | 'consent';
+  /**
+   * How the IdP should deliver the authorization response. Omitted (the
+   * default) means the ordinary top-level redirect back to `redirectUri`.
+   *
+   * `web_message` asks the IdP to `postMessage` the result to its opener
+   * instead, so a popup sign-in never navigates the relying party's tab. It is
+   * a REQUEST, not a guarantee: an IdP with no opener still redirects, which is
+   * why the popup transport must handle both outcomes. Only the authorization
+   * code, the `state`, and a typed OAuth error ever cross that channel — never
+   * a token, device secret, or the PKCE verifier, which the opener keeps.
+   */
+  responseMode?: 'web_message';
+}
+
+/**
+ * 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 `@oxy.so/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');
+  if (params.prompt) {
+    url.searchParams.set('prompt', params.prompt);
+  }
+  if (params.responseMode) {
+    url.searchParams.set('response_mode', params.responseMode);
+  }
+
+  return url.toString();
+}
+
+/** `sessionStorage` key for the OAuth CSRF `state` across an authorize redirect. */
+export const OXY_OAUTH_STATE_STORAGE_KEY = 'oxy_oauth_state';
+
+/** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
+export const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = 'oxy_oauth_code_verifier';
+
+/** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
+export const OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = 'oxy.oauth_redirect_uri';
+
+/**
+ * `sessionStorage` key for the in-app path to return to after an authorize
+ * round trip. See {@link persistOAuthReturnPath}.
+ */
+export const OXY_OAUTH_RETURN_PATH_STORAGE_KEY = 'oxy.oauth_return_path';
+
+/**
+ * Normalize a redirect URI to its origin. Official Oxy apps register apex
+ * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ *
+ * This is why the path cannot ride along in `redirect_uri`, and why
+ * {@link persistOAuthReturnPath} exists: the authorize round trip always lands
+ * back on the bare origin, so the page the user was on has to be carried
+ * out-of-band and restored on return.
+ */
+export function normalizeOAuthRedirectUri(input: string): string {
+  try {
+    return new URL(input).origin;
+  } catch {
+    return input;
+  }
+}
+
+/**
+ * Collapse `https://app.example/` → `https://app.example` for OAuth binding.
+ * Path-qualified redirect URIs are preserved — matches the API token exchange.
+ */
+export function canonicalizeOAuthRedirectUri(redirectUri: string): string {
+  try {
+    const parsed = new URL(redirectUri);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      return redirectUri;
+    }
+    if (parsed.pathname === '/' && !parsed.search && !parsed.hash) {
+      return parsed.origin;
+    }
+    return redirectUri;
+  } catch {
+    return redirectUri;
+  }
+}
+
+/**
+ * Is this a safe same-origin path to restore into the address bar?
+ *
+ * Only site-relative paths are accepted. `//evil.com` and `/\evil.com` are
+ * rejected because browsers resolve both as protocol-relative *absolute* URLs —
+ * without this check, anything able to write one key of `sessionStorage` could
+ * turn the post-authorize restore into an open redirect.
+ */
+function isSafeReturnPath(value: string): boolean {
+  if (!value.startsWith('/')) return false;
+  if (value.startsWith('//') || value.startsWith('/\\')) return false;
+  if (value.length > 2048) return false;
+  return true;
+}
+
+/**
+ * Remember the page the user was on before a full-page authorize redirect.
+ *
+ * Silent cross-origin restore navigates the whole tab to the IdP and back, and
+ * `redirect_uri` must be a registered apex origin, so the browser returns to
+ * `/` no matter which page the visit started on. Without this, every deep link
+ * — a shared URL, a search result, an ad landing page — silently became the
+ * home page for signed-out visitors on their first navigation in a tab.
+ *
+ * Stored next to the PKCE handshake it belongs to, and cleared by
+ * {@link clearOAuthHandshake} so a stale entry can never be applied to an
+ * unrelated later navigation.
+ */
+export function persistOAuthReturnPath(path: string): void {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  if (!store || !isSafeReturnPath(path)) return;
+  try {
+    store.setItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY, path);
+  } catch (error) {
+    // Non-fatal: the round trip still completes, it just lands on the origin.
+    logger.warn(
+      'Could not persist OAuth return path to sessionStorage',
+      { component: 'oauthPkce' },
+      error,
+    );
+  }
+}
+
+/**
+ * Read and remove the persisted return path, or `null` when there is none or
+ * it failed validation.
+ *
+ * Single-use by design: it is consumed on the first return so a leftover value
+ * cannot redirect a later navigation in the same tab.
+ */
+export function consumeOAuthReturnPath(): string | null {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  if (!store) return null;
+  try {
+    const value = store.getItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
+    store.removeItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
+    if (!value || !isSafeReturnPath(value)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist the OAuth handshake for a full-page redirect return (web only). */
+export function persistOAuthHandshake(
+  state: string,
+  codeVerifier: string,
+  redirectUri?: string,
+): boolean {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  try {
+    if (!store) throw new Error('sessionStorage is unavailable');
+    store.setItem(OXY_OAUTH_STATE_STORAGE_KEY, state);
+    store.setItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, codeVerifier);
+    if (redirectUri) {
+      store.setItem(
+        OXY_OAUTH_REDIRECT_URI_STORAGE_KEY,
+        canonicalizeOAuthRedirectUri(redirectUri),
+      );
+    }
+    return true;
+  } catch (error) {
+    logger.warn(
+      'Could not persist OAuth handshake to sessionStorage',
+      { component: 'oauthPkce' },
+      error,
+    );
+    return false;
+  }
+}
+
+/** Read the persisted OAuth handshake, or `null` when absent. */
+export function readOAuthHandshake(): {
+  state: string;
+  codeVerifier: string;
+  redirectUri?: string;
+} | null {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  if (!store) return null;
+  const state = store.getItem(OXY_OAUTH_STATE_STORAGE_KEY);
+  const codeVerifier = store.getItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+  if (!state || !codeVerifier) return null;
+  const redirectUri = store.getItem(OXY_OAUTH_REDIRECT_URI_STORAGE_KEY) ?? undefined;
+  return redirectUri ? { state, codeVerifier, redirectUri } : { state, codeVerifier };
+}
+
+/** Drop persisted OAuth handshake keys after a successful or aborted return. */
+export function clearOAuthHandshake(): void {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  try {
+    store?.removeItem(OXY_OAUTH_STATE_STORAGE_KEY);
+    store?.removeItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+    store?.removeItem(OXY_OAUTH_REDIRECT_URI_STORAGE_KEY);
+    // The return path belongs to this handshake. Leaving it behind would let a
+    // later, unrelated navigation in the same tab be redirected by it.
+    store?.removeItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
+  } catch {
+    // Best-effort cleanup only.
+  }
+}