@oxy.so/core 1.0.0

package/dist/esm/utils/oauthPkce.js

@@ -0,0 +1,297 @@
+/**
+ * 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/index.js';
+/** 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-_';
+/**
+ * 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 (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) {
+    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.
+ */
+export async function computeCodeChallenge(codeVerifier) {
+    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() {
+    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() {
+    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) {
+    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) {
+    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) {
+    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.
+ */
+export function persistOAuthReturnPath(path) {
+    const store = globalThis.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() {
+    const store = globalThis.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, codeVerifier, redirectUri) {
+    const store = globalThis.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() {
+    const store = globalThis.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() {
+    const store = globalThis.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.
+    }
+}

package/dist/esm/utils/officialOrigins.js

@@ -0,0 +1,59 @@
+/**
+ * Official first-party web origin allowlist — shared by OAuth redirect
+ * validation and the server-side trusted-origin checks.
+ */
+import { CENTRAL_IDP_APEX } from './authWebUrl.js';
+import { registrableApex } from './registrableApex.js';
+/** Official first-party registrable apexes (mirrors API trusted origins). */
+const OFFICIAL_APEXES = new Set([
+    'oxy.so',
+    'fairco.in',
+    'mention.earth',
+    'homiio.com',
+    'alia.onl',
+    'syra.fm',
+    'allo.you',
+    'tnp.network',
+    'moovo.now',
+    'mercaria.co',
+]);
+/**
+ * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
+ * or `[::1]` on any port, http or https).
+ */
+export function isLoopbackOrigin(origin) {
+    try {
+        const parsed = new URL(origin);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return false;
+        }
+        const host = parsed.hostname.toLowerCase();
+        return host === 'localhost' || host === '127.0.0.1' || host === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether an origin belongs to the official Oxy web ecosystem. */
+export function isOfficialWebOrigin(origin) {
+    if (isLoopbackOrigin(origin)) {
+        return true;
+    }
+    try {
+        const parsed = new URL(origin);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            return false;
+        }
+        const host = parsed.hostname.toLowerCase();
+        if (host === CENTRAL_IDP_APEX || host.endsWith(`.${CENTRAL_IDP_APEX}`)) {
+            return true;
+        }
+        const apex = registrableApex(host);
+        return apex != null && OFFICIAL_APEXES.has(apex);
+    }
+    catch {
+        return false;
+    }
+}
+/** @deprecated Use {@link isOfficialWebOrigin}. */
+export const isAllowedDeviceJoinOrigin = isOfficialWebOrigin;

package/dist/esm/utils/oxyServiceEnvironment.js

@@ -0,0 +1,16 @@
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxy.so/core` has zero dependency on `@oxy.so/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+export const OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'];

package/dist/esm/utils/platform.js

@@ -0,0 +1,110 @@
+/**
+ * Platform Detection Utility
+ *
+ * Provides platform detection WITHOUT importing from 'react-native'.
+ * This allows core modules to be used in web/Node.js environments
+ * without bundlers failing on react-native imports.
+ */
+/**
+ * Typed view over `globalThis` for the RN-platform marker, avoiding an `any`
+ * cast at each access site.
+ */
+function rnPlatformGlobal() {
+    return globalThis;
+}
+/**
+ * Detect the current platform without importing react-native
+ *
+ * Detection order:
+ * 1. Check for React Native's Platform object on globalThis (set by RN runtime)
+ * 2. Check for Node.js environment
+ * 3. Check for browser environment
+ * 4. Fall back to 'unknown'
+ */
+function detectPlatform() {
+    // Check if React Native Platform is available globally (set by RN runtime)
+    // This avoids static imports while still detecting RN environment
+    const rnPlatform = rnPlatformGlobal().__REACT_NATIVE_PLATFORM__;
+    if (rnPlatform) {
+        return rnPlatform;
+    }
+    // Check navigator.product for React Native
+    if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+        // We're in React Native but Platform wasn't set globally
+        // Try to get OS from userAgent or default to 'unknown'
+        return 'unknown';
+    }
+    // Check for Node.js environment
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        return 'web'; // Treat Node.js as 'web' for compatibility (no native features)
+    }
+    // Check for browser/web environment
+    if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+        return 'web';
+    }
+    return 'unknown';
+}
+// Cache the platform detection result
+let cachedPlatform = null;
+/**
+ * Get the current platform OS
+ * Safe to call from any environment (web, Node.js, React Native)
+ */
+export function getPlatformOS() {
+    if (cachedPlatform === null) {
+        cachedPlatform = detectPlatform();
+    }
+    return cachedPlatform;
+}
+/**
+ * Check if running on web platform (browser or Node.js)
+ */
+export function isWeb() {
+    return getPlatformOS() === 'web';
+}
+/**
+ * Check if running in a native app (iOS or Android)
+ */
+export function isNative() {
+    const os = getPlatformOS();
+    return os === 'ios' || os === 'android';
+}
+/**
+ * Check if running on iOS
+ */
+export function isIOS() {
+    return getPlatformOS() === 'ios';
+}
+/**
+ * Check if running on Android
+ */
+export function isAndroid() {
+    return getPlatformOS() === 'android';
+}
+/**
+ * Set the platform OS explicitly
+ * Called by React Native entry point to register the platform
+ * This allows lazy detection in environments where react-native is available
+ */
+export function setPlatformOS(os) {
+    cachedPlatform = os;
+    rnPlatformGlobal().__REACT_NATIVE_PLATFORM__ = os;
+}
+/**
+ * True only in a real web browser (a DOM is present), false on React Native
+ * and Node/SSR.
+ *
+ * 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 `@oxy.so/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)
+ * because it must reflect the actual DOM availability at call time in the
+ * consumer's bundle.
+ */
+export function isWebBrowser() {
+    return (typeof window !== 'undefined' &&
+        typeof document !== 'undefined' &&
+        typeof document.documentElement !== 'undefined');
+}

package/dist/esm/utils/profileLinks.js

@@ -0,0 +1,60 @@
+function cleanUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Normalizes a user's profile links into a clean display shape.
+ *
+ * Pure, no side effects, no I/O.
+ *
+ * - Prefers `linksMetadata` when it is a non-empty array: maps each entry to
+ *   `{ id, title, url, description, image }`, using `entry.id` when present and
+ *   falling back to the entry index. `title`, `description`, and `image` are
+ *   carried through only when they are present strings. Entries without a
+ *   non-empty string `url` are dropped.
+ * - Otherwise falls back to the legacy `links` string array: maps each string to
+ *   `{ id: <index>, url }` (no title/description/image). Empty/non-string values
+ *   are dropped.
+ * - Returns `[]` when both are absent or empty (including when `linksMetadata`
+ *   is present but every entry is dropped — it does NOT fall back to `links`).
+ *
+ * URLs are trimmed and blanks are filtered out. This does NOT add a scheme such
+ * as `https://`; prefixing is a display concern left to the caller.
+ */
+export function normalizeProfileLinks(linksMetadata, links) {
+    if (Array.isArray(linksMetadata) && linksMetadata.length > 0) {
+        const result = [];
+        linksMetadata.forEach((entry, index) => {
+            const url = cleanUrl(entry?.url);
+            if (!url)
+                return;
+            const id = typeof entry?.id === 'string' && entry.id.trim().length > 0
+                ? entry.id
+                : String(index);
+            const title = typeof entry?.title === 'string' ? entry.title : undefined;
+            const description = typeof entry?.description === 'string' ? entry.description : undefined;
+            const image = typeof entry?.image === 'string' ? entry.image : undefined;
+            result.push({
+                id,
+                url,
+                ...(title !== undefined ? { title } : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(image !== undefined ? { image } : {}),
+            });
+        });
+        return result;
+    }
+    if (Array.isArray(links) && links.length > 0) {
+        const result = [];
+        links.forEach((value, index) => {
+            const url = cleanUrl(value);
+            if (!url)
+                return;
+            result.push({ id: String(index), url });
+        });
+        return result;
+    }
+    return [];
+}

package/dist/esm/utils/redactUrl.js

@@ -0,0 +1,26 @@
+/**
+ * URL redaction for logging.
+ *
+ * Asset URLs the API hands back for private assets carry a scoped, short-lived
+ * media token (`mt=…`) in their query string. That token is a bearer credential
+ * for the underlying object, so it must never land in a log line, breadcrumb,
+ * or metric — a captured log would otherwise grant read access until the token
+ * expires. Query strings on API URLs can also carry other sensitive params, so
+ * we redact the whole query rather than allow-listing one key.
+ *
+ * `redactUrlQuery` returns the URL's path portion with a `?<redacted>` marker
+ * when a query string is present, and the input unchanged otherwise. It is
+ * defensive: any input that does not parse as a URL is passed through as-is,
+ * except that a bare `?query` tail is still stripped so a relative path with a
+ * query never leaks.
+ */
+export function redactUrlQuery(url) {
+    if (typeof url !== 'string' || url.length === 0) {
+        return url;
+    }
+    const queryIndex = url.indexOf('?');
+    if (queryIndex === -1) {
+        return url;
+    }
+    return `${url.slice(0, queryIndex)}?<redacted>`;
+}

package/dist/esm/utils/registrableApex.js

@@ -0,0 +1,42 @@
+/**
+ * Registrable-apex (eTLD+1) host kernel.
+ *
+ * The client FAPI auto-detection helper was removed in the device-first cutover
+ * (which is why this file is now named for what it actually is, not the old
+ * `fapiAutoDetect`). What survives is the pure registrable-domain kernel, still
+ * used by the `@oxy.so/core/server` CORS layer (the `*.oxy.so` same-apex trust
+ * check) and its re-export surface.
+ */
+import { getDomain } from 'tldts';
+/**
+ * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
+ * Suffix List, including private hosted suffixes.
+ *
+ * Performs NO protocol handling and builds NO URL — it only answers "what is
+ * the registrable domain of this host, or is that undefinable?".
+ *
+ * Returns `null` (apex undefinable) for:
+ *   - empty input;
+ *   - IPv4 literals (`192.168.1.10`);
+ *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
+ *   - single-label hosts (`intranet`, `localhost`);
+ *   - public suffixes without a registrable label (e.g. `co.uk`, `github.io`).
+ *
+ * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
+ * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
+ */
+export function registrableApex(hostname) {
+    if (!hostname)
+        return null;
+    const host = hostname.toLowerCase();
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(host))
+        return null;
+    // IPv6 literals are bracketed; any remaining ':' implies a port — neither
+    // yields a registrable apex.
+    if (host.startsWith('[') || host.includes(':'))
+        return null;
+    // The Public Suffix List (private suffixes included) is the source of truth
+    // for what an attacker can register. A multi-part public suffix like `co.uk`
+    // or a hosted suffix like `github.io` returns no registrable domain.
+    return getDomain(host, { allowPrivateDomains: true });
+}