@oxy.so/core 1.0.0

package/dist/cjs/utils/identityCacheSweep.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that can carry a single
+ * account's identity, and the one sweep that clears them.
+ *
+ * WHY THIS IS ONE LIST
+ * --------------------
+ * An Oxy account is readable under SEVERAL cache keys, and a write that only
+ * busts the key it happens to know about leaves every other one serving the
+ * pre-write snapshot for up to its TTL — from the caller's OWN in-memory cache,
+ * with a perfectly healthy server. That failure has already shipped twice with
+ * two different sets of keys:
+ *
+ *   - `updateAccount` busted `GET:/accounts/<id>` and the account lists, but a
+ *     profile screen reads `GET:/profiles/username/<name>` and
+ *     `GET:/users/<id>`, so a channel's new picture stayed invisible for the
+ *     full 5-minute profile TTL.
+ *   - `updateProfile` busted four of the six keys below, missing
+ *     `GET:/auth/lookup/` (the login-flow avatar/display-name lookup) and
+ *     `GET:/profiles/resolve` (handle resolution) — two independently-drifted
+ *     copies of a list that has to agree.
+ *
+ * So the list lives here, once, and every writer calls
+ * {@link evictOxyIdentityCache}. Adding a new identity read means adding its key
+ * HERE and every writer inherits it.
+ *
+ * WHERE THE LINE IS DRAWN
+ * -----------------------
+ * These are the SINGLE-PROFILE reads — the account is the subject of the
+ * response and is addressable by id, handle, or session. Reads that merely
+ * CONTAIN an account among many (`GET:/profiles/search`,
+ * `GET:/users/<other>/followers`, `GET:/profiles/<other>/similar`) are
+ * deliberately NOT swept: an account cannot be located in them without the very
+ * lookup being invalidated, so sweeping them means sweeping the whole namespace
+ * on every identity change — a real cost on a backend consuming the
+ * cross-service invalidation signal, for a surface where a stale thumbnail
+ * expires on its own in ~2 minutes.
+ *
+ * WHY PREFIXES RATHER THAN EXACT KEYS
+ * -----------------------------------
+ * Only the by-id key can be built from a user id. The handle-keyed and
+ * session-keyed entries cannot — deriving a handle from an id needs the lookup
+ * we are invalidating, and the SDK never tracks active session ids centrally.
+ * Prefix sweeping is also what makes a USERNAME CHANGE correct: the entry under
+ * the OLD handle is unreachable by construction (nothing in the write response
+ * carries it), and a sweep targeted at the new handle alone would leave the old
+ * one serving the pre-rename profile until its TTL. Over-eviction costs a
+ * refetch; under-eviction serves wrong data.
+ *
+ * Platform-neutral by construction (no imports, no `OxyServices` reference) so
+ * the client mixins and the Node-only `@oxy.so/core/server` invalidation
+ * subscriber can share it without either pulling in the other.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXY_IDENTITY_CACHE_PREFIXES = void 0;
+exports.oxyUserByIdCacheKey = oxyUserByIdCacheKey;
+exports.evictOxyIdentityCache = evictOxyIdentityCache;
+/**
+ * Cache-key PREFIXES under which an account's identity can be served, for the
+ * reads whose key cannot be derived from a user id. Swept wholesale.
+ */
+exports.OXY_IDENTITY_CACHE_PREFIXES = [
+    // `getUserBySession` — keyed by session id, which the SDK never enumerates.
+    'GET:/session/user/',
+    // `getCurrentUser` (and `GET:/users/me/graph`, harmlessly included).
+    'GET:/users/me',
+    // `lookupUsername` — the pre-session login lookup; carries avatar + display name.
+    'GET:/auth/lookup/',
+    // `getProfileByUsername` — keyed by handle, including the pre-rename handle.
+    'GET:/profiles/username/',
+    // `resolveProfile` — keyed by fediverse handle in the query payload.
+    'GET:/profiles/resolve',
+];
+/**
+ * Build the exact cache key `getUserById` reads under. The only identity key
+ * derivable from a user id, so the only one that does not need a prefix sweep.
+ */
+function oxyUserByIdCacheKey(userId) {
+    return `GET:/users/${userId}`;
+}
+/**
+ * Sweep an `OxyServices` GET response cache of everything that could carry the
+ * given account's identity.
+ *
+ * @param oxy    - Anything exposing the SDK's two eviction methods.
+ * @param userId - The account whose by-id entry to drop. Optional: a caller
+ *                 that does not know the id still clears every handle-, session-
+ *                 and self-keyed entry, which is the majority of the surface.
+ */
+function evictOxyIdentityCache(oxy, userId) {
+    for (const prefix of exports.OXY_IDENTITY_CACHE_PREFIXES) {
+        oxy.clearCacheByPrefix(prefix);
+    }
+    if (userId) {
+        oxy.clearCacheEntry(oxyUserByIdCacheKey(userId));
+    }
+}

package/dist/cjs/utils/languageUtils.js

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = void 0;
+exports.getBaseLanguage = getBaseLanguage;
+exports.normalizeLocale = normalizeLocale;
+exports.isSupportedLocale = isSupportedLocale;
+exports.getLanguageMetadata = getLanguageMetadata;
+exports.getLanguageName = getLanguageName;
+exports.getNativeLanguageName = getNativeLanguageName;
+exports.isRTLLocale = isRTLLocale;
+exports.getUserLanguages = getUserLanguages;
+exports.getPrimaryLanguage = getPrimaryLanguage;
+/**
+ * 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.
+ */
+exports.SUPPORTED_LANGUAGES = [
+    // 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. */
+exports.FALLBACK_LOCALE = 'en-US';
+/** O(1) lookup of a catalog entry by its canonical code. */
+const LOCALE_BY_CODE = new Map(exports.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.
+ */
+function getBaseLanguage(locale) {
+    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`.
+ */
+function normalizeLocale(input) {
+    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.
+ */
+function isSupportedLocale(input) {
+    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.
+ */
+function getLanguageMetadata(code) {
+    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}.
+ */
+function getLanguageName(code) {
+    return getLanguageMetadata(code)?.name || code || exports.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}.
+ */
+function getNativeLanguageName(code) {
+    return getLanguageMetadata(code)?.nativeName || code || exports.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 = 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.
+ */
+function isRTLLocale(locale) {
+    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.
+ */
+function getUserLanguages(user) {
+    const source = user?.languages;
+    if (!Array.isArray(source))
+        return [];
+    const result = [];
+    const seen = new Set();
+    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.
+ */
+function getPrimaryLanguage(user) {
+    return getUserLanguages(user)[0];
+}

package/dist/cjs/utils/oauthPkce.js

@@ -0,0 +1,311 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.DEFAULT_OAUTH_SCOPE = exports.OXY_AUTHORIZE_URL = void 0;
+exports.computeCodeChallenge = computeCodeChallenge;
+exports.generatePkcePair = generatePkcePair;
+exports.generateOAuthState = generateOAuthState;
+exports.buildOAuthAuthorizeUrl = buildOAuthAuthorizeUrl;
+exports.normalizeOAuthRedirectUri = normalizeOAuthRedirectUri;
+exports.canonicalizeOAuthRedirectUri = canonicalizeOAuthRedirectUri;
+exports.persistOAuthReturnPath = persistOAuthReturnPath;
+exports.consumeOAuthReturnPath = consumeOAuthReturnPath;
+exports.persistOAuthHandshake = persistOAuthHandshake;
+exports.readOAuthHandshake = readOAuthHandshake;
+exports.clearOAuthHandshake = clearOAuthHandshake;
+const protocol_1 = require("@oxy.so/protocol");
+const logger_1 = require("../logger");
+/** The central Oxy IdP authorization endpoint used by default. */
+exports.OXY_AUTHORIZE_URL = 'https://auth.oxy.so/authorize';
+/** Default OAuth scope requested for a "Sign in with Oxy" third-party flow. */
+exports.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-_';
+/**
+ * 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) {
+    if ((0, protocol_1.isReactNative)()) {
+        const crypto = await (0, protocol_1.loadExpoCrypto)();
+        return Uint8Array.from(await crypto.getRandomBytesAsync(byteLength));
+    }
+    if ((0, protocol_1.isNodeJS)()) {
+        try {
+            const nodeCrypto = await (0, protocol_1.loadNodeCrypto)();
+            return Uint8Array.from(nodeCrypto.randomBytes(byteLength));
+        }
+        catch (error) {
+            logger_1.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) {
+    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) {
+    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.
+ */
+async function computeCodeChallenge(codeVerifier) {
+    const digestHex = await (0, protocol_1.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.
+ */
+async function generatePkcePair() {
+    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.
+ */
+async function generateOAuthState() {
+    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`.
+ */
+function buildOAuthAuthorizeUrl(params) {
+    const { authorizeBaseUrl = exports.OXY_AUTHORIZE_URL, clientId, redirectUri, scope = exports.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. */
+exports.OXY_OAUTH_STATE_STORAGE_KEY = 'oxy_oauth_state';
+/** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
+exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = 'oxy_oauth_code_verifier';
+/** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
+exports.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}.
+ */
+exports.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.
+ */
+function normalizeOAuthRedirectUri(input) {
+    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.
+ */
+function canonicalizeOAuthRedirectUri(redirectUri) {
+    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) {
+    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.
+ */
+function persistOAuthReturnPath(path) {
+    const store = globalThis.sessionStorage;
+    if (!store || !isSafeReturnPath(path))
+        return;
+    try {
+        store.setItem(exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY, path);
+    }
+    catch (error) {
+        // Non-fatal: the round trip still completes, it just lands on the origin.
+        logger_1.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.
+ */
+function consumeOAuthReturnPath() {
+    const store = globalThis.sessionStorage;
+    if (!store)
+        return null;
+    try {
+        const value = store.getItem(exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
+        store.removeItem(exports.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). */
+function persistOAuthHandshake(state, codeVerifier, redirectUri) {
+    const store = globalThis.sessionStorage;
+    try {
+        if (!store)
+            throw new Error('sessionStorage is unavailable');
+        store.setItem(exports.OXY_OAUTH_STATE_STORAGE_KEY, state);
+        store.setItem(exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, codeVerifier);
+        if (redirectUri) {
+            store.setItem(exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, canonicalizeOAuthRedirectUri(redirectUri));
+        }
+        return true;
+    }
+    catch (error) {
+        logger_1.logger.warn('Could not persist OAuth handshake to sessionStorage', { component: 'oauthPkce' }, error);
+        return false;
+    }
+}
+/** Read the persisted OAuth handshake, or `null` when absent. */
+function readOAuthHandshake() {
+    const store = globalThis.sessionStorage;
+    if (!store)
+        return null;
+    const state = store.getItem(exports.OXY_OAUTH_STATE_STORAGE_KEY);
+    const codeVerifier = store.getItem(exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+    if (!state || !codeVerifier)
+        return null;
+    const redirectUri = store.getItem(exports.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. */
+function clearOAuthHandshake() {
+    const store = globalThis.sessionStorage;
+    try {
+        store?.removeItem(exports.OXY_OAUTH_STATE_STORAGE_KEY);
+        store?.removeItem(exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+        store?.removeItem(exports.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(exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
+    }
+    catch {
+        // Best-effort cleanup only.
+    }
+}