@oxyhq/core 5.5.0 → 7.0.0

package/dist/esm/utils/coldBoot.js

@@ -3,19 +3,21 @@
  * authentication resolution.
  *
  * On a fresh page load / app launch the SDK may have several ways to recover an
- * existing session (silent FedCM, a persisted refresh token, a cross-domain
- * claim, a redirect SSO return, ...). They must be attempted in a deterministic
- * order*, and the FIRST one that yields a session wins — every later step is
- * skipped. This module encodes exactly that contract and nothing else.
+ * existing session (a persisted refresh-token family, a shared-keychain
+ * identity, a cross-domain boot-fragment return, ...). They must be attempted
+ * in a deterministic order, and the FIRST one that yields a session wins —
+ * every later step is skipped. This module encodes exactly that contract and
+ * nothing else.
  *
  * Design constraints (all enforced):
  *   - PURE: no DOM, no `navigator`, no `window`, no React, no platform globals.
  *   - NO module-level mutable state. Every call to {@link runColdBoot} is fully
  *     self-contained, so it is safe under bundler re-evaluation (e.g. the Metro
- *     web bundle, which is precisely why the FedCM silent-SSO guard had to live
- *     in consumers rather than a core singleton).
- *   - Architecture-agnostic: both candidate cross-domain SSO designs consume
- *     this same primitive; it knows nothing about HOW a step resolves a session.
+ *     web bundle — the reason any run-once guard for a step must live in the
+ *     calling consumer, never in a core module-level singleton).
+ *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
+ *     session; `runSessionColdBoot` (`boot/coldBootV2.ts`) is the current
+ *     device-first consumer.
  *
  * A step is skipped (without running) when its `enabled` predicate returns
  * false. Any thrown error — from either `enabled` or `run` — is reported via

package/dist/esm/utils/platform.js

@@ -83,3 +83,21 @@ export function setPlatformOS(os) {
     cachedPlatform = os;
     globalThis.__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 `@oxyhq/services` and `@oxyhq/auth` (both 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/registrableApex.js

@@ -0,0 +1,46 @@
+/**
+ * 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 server-side by the api's device-first same-apex trust checks
+ * (`deviceAuth.ts`'s `POST /auth/device/web-session`, via `sameSite.ts`'s
+ * `isSameSiteTrustedRequest`) and the `@oxyhq/core/server` CORS/re-export layer.
+ *
+ * `registrableApex` is NOT legacy — the device-first same-apex check is a live
+ * consumer, so this kernel stays regardless of the SSO/FedCM removal.
+ */
+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 });
+}

package/dist/esm/utils/ssoBounce.js

@@ -1,352 +1,21 @@
 /**
- * Central cross-domain SSO bounce — per-origin sessionStorage keys, the bounce
- * URL builder, and the small pure predicates shared by every consumer's
- * cold-boot `sso-return` / `sso-bounce` steps and bfcache `pageshow`
- * re-evaluation.
+ * SSO callback path constant.
  *
- * This is the single source of truth for the SSO bounce wire/storage contract.
- * `@oxyhq/auth` (`WebOxyProvider`) and `@oxyhq/services` (`OxyContext`) both
- * consume these helpers so the two providers behave identically.
+ * 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.
  *
- * TRUE central SSO (Google/Meta/Clerk style) works like this for a Relying
- * Party (mention.earth, homiio.com, alia.onl, …) with no local session:
- *
- *   1. `sso-bounce` (terminal, once): a TOP-LEVEL navigation to
- *      `auth.oxy.so/sso?prompt=none&client_id=<origin>&return_to=<origin>{@link SSO_CALLBACK_PATH}&state=<s>`.
- *      Before navigating it records, in this origin's `sessionStorage`, the
- *      CSRF `state` ({@link ssoStateKey}), a guard timestamp ({@link ssoGuardKey},
- *      the loop breaker), and the real destination URL ({@link ssoDestKey}) to
- *      restore after the callback.
- *   2. The central IdP worker reads its first-party `fedcm_session`, mints a
- *      session, stores it under an opaque single-use `code`, and 303-redirects
- *      back to `<origin>{@link SSO_CALLBACK_PATH}#oxy_sso=ok&code=<code>&state=<s>`
- *      (or `#oxy_sso=none` / `#oxy_sso=error`).
- *   3. `sso-return` parses the fragment (`parseSsoReturnFragment`), validates
- *      `state`, exchanges the `code` via `oxyServices.exchangeSsoCode`, commits
- *      the session, then restores the original destination.
- *
- * Loop proof (logged-out): first load all steps skip → `sso-bounce` sets
- * guard/state/dest + the outcome-independent attempted-flag
- * ({@link ssoAttemptedKey}) and navigates; the IdP (no central session) returns
- * `#oxy_sso=none`; the callback load's `sso-return` sees `none`, sets the
- * NO_SESSION flag ({@link ssoNoSessionKey}), and `sso-bounce` is then disabled.
- * Exactly ONE bounce, no loop. An interrupted bounce (user hit back
- * mid-redirect) self-heals once the {@link SSO_GUARD_TTL_MS} guard TTL lapses.
- * The attempted-flag is the definitive, outcome-INDEPENDENT loop breaker: it is
- * set pre-bounce so even if the return-side NO_SESSION write never lands, the
- * bounce can never re-fire this tab after the self-heal TTL lapses.
- *
- * All state lives in `sessionStorage` (per tab, cleared on tab close) and is
- * keyed per-origin so two RPs hosted in the same browser never collide. The
- * key strings and the 30s TTL are a wire/storage contract — they MUST match
- * the values the IdP and every consumer expect and must not change lightly.
+ * 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.
  */
-import { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from './authWebUrl.js';
 /**
- * The RP callback path the central IdP redirects back to after a bounce. The
- * SSO result is delivered in the fragment of this URL; the `sso-return` step
- * consumes it and then restores the user's real destination (stored under
- * {@link ssoDestKey}), so the user never lingers on this internal path.
+ * 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';
-/**
- * Self-healing TTL (ms) for the bounce guard. An in-flight bounce sets a
- * timestamp guard; if the bounce is interrupted before the callback lands
- * (e.g. the user navigates back mid-redirect), the guard would otherwise pin
- * the RP signed-out forever. After this window the guard is treated as stale
- * and a fresh single bounce is permitted. 30s comfortably exceeds a real
- * redirect round-trip while keeping a crash short-lived.
- */
-export const SSO_GUARD_TTL_MS = 30000;
-const STATE_KEY_PREFIX = 'oxy_sso_state:';
-const GUARD_KEY_PREFIX = 'oxy_sso_guard:';
-const DEST_KEY_PREFIX = 'oxy_sso_dest:';
-const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
-const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
-const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
-const PRIOR_SESSION_KEY_PREFIX = 'oxy_sso_prior_session:';
-const SIGNED_OUT_KEY_PREFIX = 'oxy_signed_out:';
-const OUTCOME_KEY_PREFIX = 'oxy_sso_outcome:';
-/** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
-export function ssoStateKey(origin) {
-    return `${STATE_KEY_PREFIX}${origin}`;
-}
-/** Per-origin bounce guard key (a timestamp; loop breaker + self-heal TTL). */
-export function ssoGuardKey(origin) {
-    return `${GUARD_KEY_PREFIX}${origin}`;
-}
-/** Per-origin destination key (the real URL to restore after the callback). */
-export function ssoDestKey(origin) {
-    return `${DEST_KEY_PREFIX}${origin}`;
-}
-/**
- * Per-origin "the central IdP has no session for me" key. Set after a
- * `none`/`error` return (or a failed/forged exchange) so `sso-bounce` does not
- * fire again this tab — the definitive loop breaker.
- */
-export function ssoNoSessionKey(origin) {
-    return `${NO_SESSION_KEY_PREFIX}${origin}`;
-}
-/**
- * Per-origin, OUTCOME-INDEPENDENT once-guard. Set in `sessionStorage` BEFORE
- * the terminal SSO bounce navigates. Gates the bounce so the silent
- * cross-domain probe fires AT MOST ONCE per tab session — independent of
- * whether the return-side NO_SESSION flag ever lands. The definitive loop
- * breaker; survives the 30s self-heal `ssoGuardKey` TTL. Cleared only on an
- * explicit sign-out/clear so a later cold boot (after the user signs in
- * centrally) can probe again.
- */
-export function ssoAttemptedKey(origin) {
-    return `${ATTEMPTED_KEY_PREFIX}${origin}`;
-}
-/**
- * Per-origin DURABLE "this device/origin has had a signed-in Oxy session
- * before" hint.
- *
- * Unlike every other key in this module — which lives in per-tab
- * `sessionStorage` — this hint is written to DURABLE storage (web
- * `localStorage`; the services provider uses its own `storageKeyPrefix`-scoped
- * key in `@oxyhq/services`). It is set whenever a session is established or
- * restored and survives a session expiring; it is cleared ONLY on an explicit
- * full sign-out. It exists purely to drive {@link allowSsoBounce}: a returning
- * visitor (hint present) whose local session has lapsed still gets ONE terminal
- * `/sso` establish bounce to recover a session that lives only at the central
- * IdP, while a truly first-time anonymous visitor is never force-bounced.
- */
-export function ssoPriorSessionKey(origin) {
-    return `${PRIOR_SESSION_KEY_PREFIX}${origin}`;
-}
-/**
- * Per-origin DURABLE "the user DELIBERATELY signed out on this device/origin"
- * flag.
- *
- * Like {@link ssoPriorSessionKey} this lives in DURABLE storage (web
- * `localStorage`; services uses its own `storageKeyPrefix`-scoped key), NOT the
- * per-tab `sessionStorage` the loop-breaker keys use — it must survive a reload.
- *
- * It exists purely to suppress AUTOMATIC silent restore after a deliberate
- * sign-out: a still-live IdP session (the central `fedcm_session`) would
- * otherwise let the per-apex `/auth/silent` iframe re-mint a session on the
- * very next cold boot, so a user who pressed "Sign out" gets silently signed
- * back in on reload. With this flag set, that silent cold-boot step is
- * skipped while the Gmail-style returning-account fast-path is otherwise
- * preserved.
- *
- * Lifecycle (mirrors the existing gate machinery — set on a definitive event,
- * cleared on its inverse):
- *   - SET on EXPLICIT full sign-out (alongside clearing the prior-session hint
- *     and the SSO bounce state).
- *   - CLEARED on ANY deliberate sign-in (password, account switch, device
- *     claim) so a real sign-in fully re-enables silent restore — there is no
- *     "stuck signed out" state.
- *
- * NOTE: this gates only AUTOMATIC/silent restore. An INTERACTIVE sign-in always
- * clears it first, so the user can always sign back in.
- */
-export function ssoSignedOutKey(origin) {
-    return `${SIGNED_OUT_KEY_PREFIX}${origin}`;
-}
-/**
- * Per-origin key holding the LAST consumed SSO-return outcome (`ok` | `none` |
- * `error`, plus an optional machine-readable `reason` on the non-`ok` outcomes).
- *
- * Lives in per-tab `sessionStorage` like the other loop-breaker keys, and for
- * the same reason: a `none`/`error` return HARD-navigates the RP off the
- * internal callback path back to its real destination (a fresh document load),
- * so the outcome an RP wants to render ("the central IdP had no session — show a
- * branded sign-in screen instead of bouncing again") must survive that
- * round-trip. The RP reads it on the destination load to decide whether an
- * AUTOMATIC (guard-driven) sign-in should re-bounce or defer to a user gesture.
- *
- * Written as a small JSON blob (`{kind, reason?}`). Set whenever a return is
- * consumed; cleared on a successful session commit and on an explicit
- * user-gesture sign-in / full sign-out (so a deliberate retry is never
- * suppressed by a prior automatic none/error).
- */
-export function ssoOutcomeKey(origin) {
-    return `${OUTCOME_KEY_PREFIX}${origin}`;
-}
-/**
- * Per-origin marker written by the pre-hydration callback bootstrap.
- *
- * Static Expo exports render unknown paths as `+not-found`; on
- * `/__oxy/sso-callback` that can fail hydration before the React provider has a
- * chance to run `consumeSsoReturn`. The bootstrap runs in the HTML head, moves
- * the URL to a hydratable route while preserving the SSO fragment, and writes
- * this marker so `consumeSsoReturn` still restores the original destination as
- * if the page were physically on the callback path.
- */
-export function ssoCallbackBootstrapKey(origin) {
-    return `${CALLBACK_BOOTSTRAP_KEY_PREFIX}${origin}`;
-}
-/**
- * Inline script for Expo/static web apps.
- *
- * Must run before the app bundle hydrates. It is intentionally tiny and
- * dependency-free: if the browser lands on the internal callback route with an
- * Oxy SSO fragment, it marks the handoff and rewrites the path to `/` while
- * preserving `#oxy_sso=...`. The normal SDK cold-boot `sso-return` step then
- * consumes the fragment from a route that can hydrate. If the internal route is
- * reached without a valid SSO fragment, it leaves the route via a hard root
- * navigation because there is no session material to preserve.
- */
-export function getSsoCallbackBootstrapScript() {
-    const callbackPath = JSON.stringify(SSO_CALLBACK_PATH);
-    const bootstrapPrefix = JSON.stringify(CALLBACK_BOOTSTRAP_KEY_PREFIX);
-    return `(function(){var p=${callbackPath};if(window.location.pathname!==p)return;var h=window.location.hash||"";if(!/(?:^#|&)oxy_sso=(?:ok|none|error)(?:&|$)/.test(h)){window.location.replace("/");return;}try{window.sessionStorage.setItem(${bootstrapPrefix}+window.location.origin,"1");}catch(e){window.__oxySsoCallbackBootstrapError=e instanceof Error?e.message:String(e);}try{window.history.replaceState(null,"","/"+h);}catch(e){window.__oxySsoCallbackBootstrapError=e instanceof Error?e.message:String(e);window.location.replace("/"+h);}})();`;
-}
-/**
- * Perform the terminal top-level SSO bounce navigation.
- *
- * A thin wrapper over `window.location.assign(url)` so the single navigation
- * seam lives in one place (and stays mockable in tests, where jsdom's
- * `Location.assign` is a non-configurable native method). In production this is
- * exactly `window.location.assign` — the document is torn down and replaced by
- * the central IdP page. Off-browser (SSR / native) it is a no-op: native never
- * bounces.
- */
-export function ssoNavigate(url) {
-    if (typeof window === 'undefined' || typeof window.location === 'undefined') {
-        return;
-    }
-    window.location.assign(url);
-}
-/**
- * Build the central IdP `/sso` bounce URL for an RP.
- *
- * Pure (no DOM access) so it is unit-testable and shared by every consumer's
- * terminal `sso-bounce` step. The IdP reads `client_id` (the RP origin) and
- * `return_to` to mint an origin-bound opaque code and 303-redirect back.
- *
- * The IdP base is resolved via {@link resolveCentralAuthUrl} so an explicit
- * `authWebUrl` override (e.g. a staging IdP) drives the SSO bounce exactly the
- * way it drives FedCM. When omitted, the central default {@link CENTRAL_AUTH_URL}
- * is used.
- *
- * @param origin - The RP origin (`window.location.origin`).
- * @param state - The CSRF state minted for this bounce.
- * @param authWebUrl - Optional explicit IdP base URL override. Falls back to
- *   the central default when `undefined`/empty.
- * @returns The absolute `<idp-origin>/sso?...` URL string.
- */
-export function buildSsoBounceUrl(origin, state, authWebUrl) {
-    const url = new URL('/sso', resolveCentralAuthUrl(authWebUrl));
-    url.searchParams.set('prompt', 'none');
-    url.searchParams.set('client_id', origin);
-    url.searchParams.set('return_to', origin + SSO_CALLBACK_PATH);
-    url.searchParams.set('state', state);
-    return url.toString();
-}
-/**
- * Whether `origin` IS the central IdP origin. The RP must NEVER bounce while
- * sitting on `auth.oxy.so` itself — doing so would loop the IdP against itself.
- *
- * Both sides are normalised via `new URL(...).origin` so a trailing-slash or
- * path difference never defeats the guard. Returns `false` on any parse
- * failure (an unparseable candidate is, by definition, not the central IdP).
- */
-export function isCentralIdPOrigin(origin) {
-    let centralOrigin;
-    try {
-        centralOrigin = new URL(CENTRAL_AUTH_URL).origin;
-    }
-    catch {
-        return false;
-    }
-    let candidateOrigin;
-    try {
-        candidateOrigin = new URL(origin).origin;
-    }
-    catch {
-        return false;
-    }
-    return candidateOrigin === centralOrigin;
-}
-/**
- * Read the bounce guard and decide whether it is still ACTIVE.
- *
- * Active means: a guard value is present AND it parses to a finite timestamp
- * AND less than {@link SSO_GUARD_TTL_MS} has elapsed since it was set. An active
- * guard disables `sso-bounce` (a bounce is already in flight this tab). A
- * missing, malformed, or expired guard is NOT active, so a fresh bounce may
- * proceed (this is the 30s self-heal for an interrupted bounce).
- *
- * Defensive: a `getItem` that throws (e.g. a locked/disabled storage) is
- * treated as "not active" so the guard never wedges the flow.
- *
- * @param storage - The session storage to read (injected for testability).
- * @param origin - The page origin whose guard to evaluate.
- * @param now - Current epoch ms (injected for deterministic tests). Defaults to
- *   `Date.now()`.
- */
-export function guardActive(storage, origin, now = Date.now()) {
-    let raw;
-    try {
-        raw = storage.getItem(ssoGuardKey(origin));
-    }
-    catch {
-        return false;
-    }
-    if (raw === null || raw.length === 0) {
-        return false;
-    }
-    const ts = Number(raw);
-    if (!Number.isFinite(ts)) {
-        return false;
-    }
-    return now - ts < SSO_GUARD_TTL_MS;
-}
-/**
- * Whether AUTOMATIC silent restore is SUPPRESSED for this origin because the
- * user deliberately signed out (the durable {@link ssoSignedOutKey} flag).
- *
- * When `true`, the silent cold-boot step that can re-mint a session from a
- * still-live IdP session WITHOUT user intent — the per-apex
- * `/auth/silent` iframe — MUST be skipped, so a user who pressed "Sign out" is
- * not silently signed back in on the next reload. Interactive sign-in clears the
- * flag, so this never blocks a deliberate re-sign-in.
- *
- * Defensive: a `getItem` that throws (locked/disabled storage) is treated as NOT
- * suppressed, so the gate fails toward the normal restore behaviour rather than
- * wedging the user out.
- *
- * @param storage - The DURABLE storage to read (web `localStorage`; injected for
- *   testability).
- * @param origin - The page origin whose signed-out flag to evaluate.
- */
-export function silentRestoreSuppressed(storage, origin) {
-    try {
-        return storage.getItem(ssoSignedOutKey(origin)) === '1';
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Decide whether the terminal `/sso` establish-bounce is ALLOWED for this
- * visitor (the smart `enabled` gate for the `sso-bounce` cold-boot step).
- *
- * The terminal bounce is the ONLY cold-boot step that can recover a session
- * that lives SOLELY at the central IdP — the cross-apex Relying-Party case
- * (e.g. `mention.earth`, a different apex from `oxy.so`) whose device-local
- * session has expired and whose `Domain=oxy.so` refresh cookie never reaches
- * `api.<apex>`. It is also what plants the first-party per-apex `fedcm_session`
- * cookie that the EARLIER `silent-iframe` step later relies on. So it must fire
- * for a RETURNING user, yet it must NOT force a truly first-time anonymous
- * visitor off to the IdP.
- *
- *   - ALLOW when there is a prior-signed-in hint OR a local session was
- *     recovered this boot (a returning user) — so a central-only cross-domain
- *     session recovers via ONE bounce, after which the per-apex cookie is
- *     planted and subsequent loads restore silently with no bounce.
- *   - else (no hint, no local session) SUPPRESS — a first-time anonymous
- *     visitor browses without a forced redirect.
- *
- * This is the smart DEFAULT and the ONLY behaviour: apps never configure it.
- * It is also the GATE DECISION ONLY — callers still apply the per-tab loop
- * guards (`ssoAttemptedKey`, `ssoNoSessionKey`, {@link guardActive}) so an
- * allowed bounce still fires at most once per cold boot.
- */
-export function allowSsoBounce(gate) {
-    return gate.hasPriorSession || gate.hasLocalSession;
-}

package/dist/esm/utils/validationUtils.js

@@ -32,6 +32,62 @@ export function isValidUsername(username) {
 export function isValidPassword(password) {
     return PASSWORD_REGEX.test(password);
 }
+/**
+ * Display-name character policy.
+ *
+ * A clean display name is composed ONLY of:
+ *   - letters of any script (`\p{L}`),
+ *   - combining marks / accents (`\p{M}`, e.g. the acute accent in a decomposed
+ *     "é"),
+ *   - Unicode space separators (`\p{Zs}`: the ASCII space, NBSP, ideographic
+ *     space, …) — but NOT control whitespace such as tab, newline, or carriage
+ *     return, which would break layout or enable multi-line spoofing,
+ *   - the straight apostrophe (`'`, e.g. "O'Brien").
+ *
+ * Everything else is rejected: emoji (🐧), symbols (⁂ ⏚), `:emoji:` shortcodes,
+ * digits, hyphens, dots, control whitespace (tab/newline/CR), and any other
+ * punctuation. The allowed set `\p{L}\p{M}\p{Zs}'` explicitly EXCLUDES `<`, `>`,
+ * `&`, and `"`, so a value that passes this predicate can never contain an
+ * HTML/XSS vector.
+ *
+ * This is the SINGLE definition of the policy, shared between the API 400-gate
+ * (`@oxyhq/api` `displayNameSanitize.ts`) and client-side inline validation
+ * (the RN profile editor) so the two can never drift. It is platform-agnostic
+ * (no react/react-native/expo).
+ */
+/**
+ * Single test for the presence of a disallowed character (non-global). The
+ * whitespace class is `\p{Zs}` (space separators only), NOT `\s` — the latter
+ * would admit tab/newline/carriage return, which break layout and enable
+ * multi-line spoofing.
+ */
+const DISALLOWED_PROBE = /[^\p{L}\p{M}\p{Zs}']/u;
+/**
+ * Single test for the presence of an orphaned combining mark (non-global) — a
+ * `\p{M}` not attached to a base letter (string start, whitespace, the
+ * apostrophe, or a position vacated by a stripped character). A mark preceded by
+ * `\p{L}` (a base letter, e.g. the decomposed accent in "Renée") or by another
+ * `\p{M}` (a multi-mark cluster) is NOT matched because the negative lookbehind
+ * fails at its position.
+ */
+const ORPHANED_MARK_PROBE = /(?<![\p{L}\p{M}])\p{M}/u;
+/**
+ * Whether `raw` already satisfies the display-name policy, i.e. it contains no
+ * disallowed characters AND no orphaned combining marks. Used to REJECT native
+ * (signup / profile edit) names with a 400 rather than silently stripping them,
+ * and to validate inline in the client editor.
+ *
+ * The orphaned-mark probe runs on the NFC-normalized form so a legitimate
+ * decomposed accent (`e`+◌́) — which normalization recomposes into `é` — is NOT
+ * rejected, while a lone, base-less mark (e.g. `"༘"`) IS.
+ *
+ * The function only checks the character set; an empty or whitespace-only string
+ * is considered valid (`true`). Call sites that require a non-empty name enforce
+ * that separately.
+ */
+export function isValidDisplayName(raw) {
+    return (!DISALLOWED_PROBE.test(raw) && !ORPHANED_MARK_PROBE.test(raw.normalize('NFC')));
+}
 /**
  * Validate required string
  */