@oxyhq/core 2.2.1 → 2.3.0

package/src/utils/fapiAutoDetect.ts

@@ -47,7 +47,7 @@
  * before relying on this helper, otherwise auto-detection silently bails to
  * `undefined` and the consumer must pass `authWebUrl` explicitly.
  */
-const MULTIPART_TLDS: ReadonlySet<string> = new Set([
+export const MULTIPART_TLDS: ReadonlySet<string> = new Set([
   'co.uk',
   'com.au',
   'co.jp',
@@ -60,6 +60,42 @@ const MULTIPART_TLDS: ReadonlySet<string> = new Set([
   'com.sg',
 ]);
 
+/**
+ * Compute the bare registrable apex (eTLD+1) of a hostname, guarding against
+ * multi-part public suffixes.
+ *
+ * This is the pure host-handling kernel shared by {@link autoDetectAuthWebUrl}
+ * and the IdP worker — it performs NO protocol handling, NO `auth.` prefixing,
+ * 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`);
+ *   - hosts whose trailing two labels form a known multi-part public suffix
+ *     (e.g. `foo.co.uk`), where `labels.slice(-2)` would yield an
+ *     attacker-registrable suffix (`co.uk`) rather than a real registrable
+ *     domain. Such hosts MUST configure `authWebUrl` explicitly.
+ *
+ * @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: string): string | null {
+  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;
+  const labels = host.split('.');
+  if (labels.length < 2) return null;
+  const lastTwo = labels.slice(-2).join('.');
+  if (MULTIPART_TLDS.has(lastTwo)) return null;
+  return lastTwo;
+}
+
 export function autoDetectAuthWebUrl(
   location: Pick<Location, 'hostname' | 'protocol'> | undefined =
     typeof window !== 'undefined' ? window.location : undefined
@@ -71,12 +107,12 @@ export function autoDetectAuthWebUrl(
   if (hostname === 'localhost' || hostname === '127.0.0.1') return undefined;
   if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname)) return undefined;
   if (hostname.startsWith('[')) return undefined;
+  // Already ON the IdP — keep everything same-origin instead of hopping to a
+  // sibling host.
   if (hostname.startsWith('auth.')) {
     return `${protocol}//${hostname}`;
   }
-  const labels = hostname.split('.');
-  if (labels.length < 2) return undefined;
-  if (MULTIPART_TLDS.has(labels.slice(-2).join('.'))) return undefined;
-  const apex = labels.slice(-2).join('.');
+  const apex = registrableApex(hostname);
+  if (apex === null) return undefined;
   return `${protocol}//auth.${apex}`;
 }

package/src/utils/ssoBounce.ts

@@ -0,0 +1,198 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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 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.
+ *
+ * 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.
+ */
+
+import { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from './authWebUrl';
+
+/**
+ * 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.
+ */
+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 = 30_000;
+
+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:';
+
+/** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
+export function ssoStateKey(origin: string): string {
+  return `${STATE_KEY_PREFIX}${origin}`;
+}
+
+/** Per-origin bounce guard key (a timestamp; loop breaker + self-heal TTL). */
+export function ssoGuardKey(origin: string): string {
+  return `${GUARD_KEY_PREFIX}${origin}`;
+}
+
+/** Per-origin destination key (the real URL to restore after the callback). */
+export function ssoDestKey(origin: string): string {
+  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: string): string {
+  return `${NO_SESSION_KEY_PREFIX}${origin}`;
+}
+
+/**
+ * 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: string): void {
+  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: string,
+  state: string,
+  authWebUrl?: string,
+): string {
+  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: string): boolean {
+  let centralOrigin: string;
+  try {
+    centralOrigin = new URL(CENTRAL_AUTH_URL).origin;
+  } catch {
+    return false;
+  }
+  let candidateOrigin: string;
+  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: Pick<Storage, 'getItem'>,
+  origin: string,
+  now: number = Date.now(),
+): boolean {
+  let raw: string | null;
+  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;
+}

package/src/utils/ssoReturn.ts

@@ -21,6 +21,15 @@
  * value), so the caller can ignore unrelated fragments without special-casing.
  */
 
+import type { SessionLoginResponse } from '../models/session';
+import {
+  SSO_CALLBACK_PATH,
+  ssoStateKey,
+  ssoGuardKey,
+  ssoDestKey,
+  ssoNoSessionKey,
+} from './ssoBounce';
+
 /**
  * The recognised outcomes of an SSO bounce.
  */
@@ -92,3 +101,162 @@ export function parseSsoReturnFragment(hash: string | undefined | null): SsoRetu
 
   return result;
 }
+
+/**
+ * Injectable dependencies for {@link consumeSsoReturn}.
+ *
+ * Every web seam (storage, location, history, web-detection) is injectable so
+ * the function is fully unit-testable with fakes and so SSR / native callers
+ * can supply their own (or rely on the defaults, which resolve to `window.*`
+ * only when a browser is present). Defaults are evaluated lazily inside
+ * `consumeSsoReturn` so importing this module never touches `window`.
+ */
+export interface ConsumeSsoReturnDeps {
+  /** Per-tab SSO state store. Default: `window.sessionStorage`. */
+  storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+  /** The current location. Default: `window.location`. */
+  location?: Pick<Location, 'hash' | 'origin' | 'pathname' | 'search'>;
+  /** History API for fragment stripping / dest restore. Default: `window.history`. */
+  history?: Pick<History, 'replaceState'>;
+  /**
+   * Whether the current environment is a web browser with usable
+   * `sessionStorage`. Default: `typeof window !== 'undefined' && typeof
+   * window.sessionStorage !== 'undefined'`.
+   */
+  isWeb?: () => boolean;
+  /**
+   * Optional debug hook invoked with the thrown error when the code exchange
+   * fails. NEVER rethrown — `consumeSsoReturn` is total. Default: no-op.
+   */
+  onExchangeError?: (error: unknown) => void;
+}
+
+/**
+ * Consume an SSO return: the commit-free, security-critical kernel of the
+ * cross-domain SSO `sso-return` cold-boot step.
+ *
+ * This performs the CSRF/fragment/exchange/dest-restore/loop-breaker sequence
+ * and RETURNS the exchanged session (or `null`). It deliberately does NOT
+ * commit any UI/auth state — each provider commits its own way AROUND this
+ * (e.g. `@oxyhq/services` `OxyContext` calls its `handleWebSSOSession`,
+ * `@oxyhq/auth` `WebOxyProvider` updates its React state). Hoisting the kernel
+ * here keeps the two providers byte-for-byte identical on the parts that matter
+ * for security (state validation, fragment stripping order, loop prevention).
+ *
+ * Security/loop invariants (preserved exactly from both former copies):
+ *   - The fragment is stripped via `history.replaceState` FIRST — before the
+ *     exchange — so the opaque code never lingers in the URL, browser history,
+ *     or a `Referer` header even if a later step throws.
+ *   - `state` must match (CSRF). A mismatch or a missing code sets the
+ *     NO_SESSION flag so `sso-bounce` is disabled (no rebounce loop).
+ *   - `none`/`error` outcomes set the NO_SESSION flag (the load2 half of the
+ *     loop proof).
+ *   - A throwing exchange is caught, reported via `onExchangeError`, and
+ *     treated exactly like "no session" (never loops, never rethrows).
+ *   - After a successful exchange landing on {@link SSO_CALLBACK_PATH}, the real
+ *     destination is restored from the DEST key — same-origin only (an
+ *     attacker-planted cross-origin or relative-evil dest is rejected). The
+ *     DEST key is removed unconditionally.
+ *
+ * Total: this function NEVER throws. Off-web it is a no-op returning `null`.
+ *
+ * @param oxy - The exchange surface (`oxyServices.exchangeSsoCode`).
+ * @param deps - Injectable web seams; see {@link ConsumeSsoReturnDeps}.
+ * @returns The exchanged session on success, otherwise `null`.
+ */
+export async function consumeSsoReturn(
+  oxy: { exchangeSsoCode: (code: string) => Promise<SessionLoginResponse> },
+  deps: ConsumeSsoReturnDeps = {},
+): Promise<SessionLoginResponse | null> {
+  const isWeb =
+    deps.isWeb ??
+    (() =>
+      typeof window !== 'undefined' &&
+      typeof window.sessionStorage !== 'undefined');
+
+  if (!isWeb()) {
+    return null;
+  }
+
+  const storage = deps.storage ?? window.sessionStorage;
+  const location = deps.location ?? window.location;
+  const history = deps.history ?? window.history;
+  const onExchangeError = deps.onExchangeError;
+
+  const ret = parseSsoReturnFragment(location.hash);
+  if (!ret) {
+    // Not an oxy_sso fragment — nothing to do (do NOT touch any flags).
+    return null;
+  }
+
+  const origin = location.origin;
+  const expectedState = storage.getItem(ssoStateKey(origin));
+  const stateOk = !!ret.state && !!expectedState && ret.state === expectedState;
+
+  // Strip the fragment FIRST so the opaque code never lingers in the address
+  // bar, history, or a `Referer` — even if a later step throws.
+  history.replaceState(null, '', location.pathname + location.search);
+  storage.removeItem(ssoStateKey(origin));
+
+  // The in-flight bounce is now resolved — drop its guard so a later cold boot
+  // (e.g. after sign-out) can bounce again.
+  storage.removeItem(ssoGuardKey(origin));
+
+  const markNoSession = () => {
+    storage.setItem(ssoNoSessionKey(origin), '1');
+  };
+
+  if (ret.kind === 'none' || ret.kind === 'error') {
+    // The central IdP had no session (or the bounce failed). Record it so we do
+    // not bounce again this tab — the definitive loop breaker.
+    markNoSession();
+    return null;
+  }
+
+  if (!stateOk || !ret.code) {
+    // Forged / replayed / stale fragment, or a malformed ok with no code. Treat
+    // exactly like "no session": never exchange, never loop.
+    markNoSession();
+    return null;
+  }
+
+  let session: SessionLoginResponse | undefined;
+  try {
+    session = await oxy.exchangeSsoCode(ret.code);
+  } catch (error) {
+    onExchangeError?.(error);
+    markNoSession();
+    return null;
+  }
+
+  if (!session?.sessionId) {
+    markNoSession();
+    return null;
+  }
+
+  // If we landed on the internal callback path, restore the user's real
+  // destination (captured at bounce time). Same-origin only — never honour a
+  // cross-origin destination that could have been planted to redirect the
+  // freshly signed-in user. `new URL(dest, origin)` tolerates relative dests
+  // and is still re-checked against the page origin.
+  if (location.pathname === SSO_CALLBACK_PATH) {
+    const dest = storage.getItem(ssoDestKey(origin));
+    if (dest) {
+      try {
+        const destUrl = new URL(dest, origin);
+        if (destUrl.origin === origin) {
+          history.replaceState(
+            null,
+            '',
+            destUrl.pathname + destUrl.search + destUrl.hash,
+          );
+        }
+      } catch {
+        // Malformed stored destination — leave the URL on the callback path.
+      }
+    }
+  }
+  storage.removeItem(ssoDestKey(origin));
+
+  return session;
+}