@oxyhq/core 5.5.0 → 7.0.0

package/src/utils/__tests__/ssoReturn.test.ts

@@ -1,276 +0,0 @@
-/**
- * `parseSsoReturnFragment` — SSO return fragment parsing.
- *
- * The central IdP returns the RP via a top-level redirect with the bounce
- * result in the URL fragment. The parser must be pure, total (never throws),
- * and report `kind` strictly as one of `'ok' | 'none' | 'error'`, returning
- * `null` for anything that is not an oxy_sso fragment.
- */
-
-import type { SessionLoginResponse } from '../../models/session';
-import { consumeSsoReturn, parseSsoReturnFragment } from '../ssoReturn';
-import {
-  getSsoCallbackBootstrapScript,
-  ssoAttemptedKey,
-  ssoCallbackBootstrapKey,
-  ssoDestKey,
-  ssoNoSessionKey,
-  ssoStateKey,
-} from '../ssoBounce';
-
-class MemorySsoStorage implements Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> {
-  private readonly values = new Map<string, string>();
-
-  getItem(key: string): string | null {
-    return this.values.get(key) ?? null;
-  }
-
-  setItem(key: string, value: string): void {
-    this.values.set(key, value);
-  }
-
-  removeItem(key: string): void {
-    this.values.delete(key);
-  }
-}
-
-const ORIGIN = 'https://app.mention.earth';
-
-const exchangedSession: SessionLoginResponse = {
-  sessionId: 'sess_sso',
-  deviceId: 'device_sso',
-  accessToken: 'access_sso',
-  expiresAt: '2030-01-01T00:00:00.000Z',
-  user: { id: 'user_sso', username: 'sso-user' },
-};
-
-describe('parseSsoReturnFragment', () => {
-  describe('ok', () => {
-    it('parses a success fragment with code and state', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=ok&code=abc123&state=xyz');
-
-      expect(result).toEqual({ kind: 'ok', code: 'abc123', state: 'xyz' });
-    });
-
-    it('parses a success fragment without a leading #', () => {
-      const result = parseSsoReturnFragment('oxy_sso=ok&code=abc123&state=xyz');
-
-      expect(result).toEqual({ kind: 'ok', code: 'abc123', state: 'xyz' });
-    });
-
-    it('omits code when ok carries no code', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=ok&state=xyz');
-
-      expect(result).toEqual({ kind: 'ok', state: 'xyz' });
-      expect(result?.code).toBeUndefined();
-    });
-
-    it('URL-decodes percent-encoded values', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=ok&code=a%2Bb%2Fc&state=s%20t');
-
-      expect(result).toEqual({ kind: 'ok', code: 'a+b/c', state: 's t' });
-    });
-
-    it('ignores a stray reason on an ok outcome', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=ok&code=abc123&state=xyz&reason=no_cookie');
-
-      expect(result).toEqual({ kind: 'ok', code: 'abc123', state: 'xyz' });
-      expect(result?.reason).toBeUndefined();
-    });
-  });
-
-  describe('none', () => {
-    it('parses a none fragment and carries state but never a code', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=none&state=xyz');
-
-      expect(result).toEqual({ kind: 'none', state: 'xyz' });
-    });
-
-    it('ignores a stray code on a none outcome', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=none&code=leaked&state=xyz');
-
-      expect(result).toEqual({ kind: 'none', state: 'xyz' });
-      expect(result?.code).toBeUndefined();
-    });
-
-    it('carries a machine-readable reason on a none outcome', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=none&reason=no_cookie&state=xyz');
-
-      expect(result).toEqual({ kind: 'none', state: 'xyz', reason: 'no_cookie' });
-    });
-
-    it('omits reason when the none outcome carries none', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=none&state=xyz');
-
-      expect(result?.reason).toBeUndefined();
-    });
-  });
-
-  describe('error', () => {
-    it('parses an error fragment', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=error&state=xyz');
-
-      expect(result).toEqual({ kind: 'error', state: 'xyz' });
-    });
-
-    it('ignores a stray code on an error outcome', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=error&code=leaked');
-
-      expect(result).toEqual({ kind: 'error' });
-      expect(result?.code).toBeUndefined();
-    });
-
-    it('carries a machine-readable reason on an error outcome', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=error&reason=no_grant_establish');
-
-      expect(result).toEqual({ kind: 'error', reason: 'no_grant_establish' });
-    });
-  });
-
-  describe('null (not an oxy_sso fragment)', () => {
-    it('returns null for an empty string', () => {
-      expect(parseSsoReturnFragment('')).toBeNull();
-    });
-
-    it('returns null for a bare #', () => {
-      expect(parseSsoReturnFragment('#')).toBeNull();
-    });
-
-    it('returns null for undefined', () => {
-      expect(parseSsoReturnFragment(undefined)).toBeNull();
-    });
-
-    it('returns null for null', () => {
-      expect(parseSsoReturnFragment(null)).toBeNull();
-    });
-
-    it('returns null for a fragment without oxy_sso', () => {
-      expect(parseSsoReturnFragment('#access_token=foo&state=bar')).toBeNull();
-    });
-
-    it('returns null for an unrecognised oxy_sso value', () => {
-      expect(parseSsoReturnFragment('#oxy_sso=bogus&code=x')).toBeNull();
-    });
-
-    it('returns null for an empty oxy_sso value', () => {
-      expect(parseSsoReturnFragment('#oxy_sso=&code=x')).toBeNull();
-    });
-  });
-
-  describe('malformed / defensive', () => {
-    it('never throws and returns a valid kind for junk after the marker', () => {
-      const result = parseSsoReturnFragment('#oxy_sso=ok&=&&&code=c&&');
-
-      expect(result?.kind).toBe('ok');
-      expect(result?.code).toBe('c');
-    });
-
-    it('always reports a kind in the strict union', () => {
-      for (const input of [
-        '#oxy_sso=ok',
-        '#oxy_sso=none',
-        '#oxy_sso=error',
-      ]) {
-        const result = parseSsoReturnFragment(input);
-        expect(result).not.toBeNull();
-        expect(['ok', 'none', 'error']).toContain(result?.kind);
-      }
-    });
-  });
-});
-
-describe('consumeSsoReturn pre-hydration callback bootstrap', () => {
-  it('continues an ok callback after the HTML bootstrap moved the URL to a hydratable route', async () => {
-    const storage = new MemorySsoStorage();
-    const replaceStateCalls: string[] = [];
-    const dispatchPopState = jest.fn();
-    const hardRedirect = jest.fn();
-    const exchangeSsoCode = jest.fn(async (): Promise<SessionLoginResponse> => exchangedSession);
-
-    storage.setItem(ssoStateKey(ORIGIN), 'state-ok');
-    storage.setItem(ssoDestKey(ORIGIN), `${ORIGIN}/explore?tab=home#top`);
-    storage.setItem(ssoCallbackBootstrapKey(ORIGIN), '1');
-
-    const session = await consumeSsoReturn(
-      { exchangeSsoCode },
-      {
-        isWeb: () => true,
-        storage,
-        location: {
-          hash: '#oxy_sso=ok&code=opaque-code&state=state-ok',
-          origin: ORIGIN,
-          pathname: '/',
-          search: '',
-        },
-        history: {
-          replaceState: (_data: unknown, _unused: string, url?: string | URL | null): void => {
-            replaceStateCalls.push(String(url ?? ''));
-          },
-        },
-        dispatchPopState,
-        hardRedirect,
-      },
-    );
-
-    expect(session).toBe(exchangedSession);
-    expect(exchangeSsoCode).toHaveBeenCalledWith('opaque-code', 'state-ok');
-    expect(replaceStateCalls).toEqual(['/', '/explore?tab=home#top']);
-    expect(dispatchPopState).toHaveBeenCalledTimes(1);
-    expect(hardRedirect).not.toHaveBeenCalled();
-    expect(storage.getItem(ssoCallbackBootstrapKey(ORIGIN))).toBeNull();
-    expect(storage.getItem(ssoDestKey(ORIGIN))).toBeNull();
-    expect(storage.getItem(ssoNoSessionKey(ORIGIN))).toBeNull();
-  });
-
-  it('leaves a bootstrapped none callback with loop breakers set and no exchange', async () => {
-    const storage = new MemorySsoStorage();
-    const replaceStateCalls: string[] = [];
-    const dispatchPopState = jest.fn();
-    const hardRedirect = jest.fn();
-    const exchangeSsoCode = jest.fn(async (): Promise<SessionLoginResponse> => exchangedSession);
-
-    storage.setItem(ssoStateKey(ORIGIN), 'state-none');
-    storage.setItem(ssoDestKey(ORIGIN), `${ORIGIN}/library`);
-    storage.setItem(ssoCallbackBootstrapKey(ORIGIN), '1');
-
-    const session = await consumeSsoReturn(
-      { exchangeSsoCode },
-      {
-        isWeb: () => true,
-        storage,
-        location: {
-          hash: '#oxy_sso=none&state=state-none',
-          origin: ORIGIN,
-          pathname: '/',
-          search: '',
-        },
-        history: {
-          replaceState: (_data: unknown, _unused: string, url?: string | URL | null): void => {
-            replaceStateCalls.push(String(url ?? ''));
-          },
-        },
-        dispatchPopState,
-        hardRedirect,
-      },
-    );
-
-    expect(session).toBeNull();
-    expect(exchangeSsoCode).not.toHaveBeenCalled();
-    expect(replaceStateCalls).toEqual(['/']);
-    expect(dispatchPopState).not.toHaveBeenCalled();
-    expect(hardRedirect).toHaveBeenCalledWith(`${ORIGIN}/library`);
-    expect(storage.getItem(ssoCallbackBootstrapKey(ORIGIN))).toBeNull();
-    expect(storage.getItem(ssoDestKey(ORIGIN))).toBeNull();
-    expect(storage.getItem(ssoNoSessionKey(ORIGIN))).toBe('1');
-    expect(storage.getItem(ssoAttemptedKey(ORIGIN))).toBe('1');
-  });
-
-  it('exposes a pre-hydration script that preserves the SSO fragment', () => {
-    const script = getSsoCallbackBootstrapScript();
-
-    expect(script).toContain('/__oxy/sso-callback');
-    expect(script).toContain('oxy_sso=');
-    expect(script).toContain('window.history.replaceState');
-    expect(script).toContain('window.location.hash');
-  });
-});

package/src/utils/fapiAutoDetect.ts

@@ -1,91 +0,0 @@
-/**
- * Auto-detect the FAPI (IdP) URL from the current browser hostname.
- *
- * This is the canonical cross-domain IdP-resolution primitive for the Oxy
- * ecosystem. Both candidate cross-domain SSO designs derive `auth.<rp-apex>`
- * through this helper; do not fork it.
- *
- * Clerk-style multi-domain SSO depends on the IdP being reachable on a
- * subdomain of the RP's own apex (e.g. `auth.mention.earth` CNAMEd to the
- * central Oxy IdP). That way every FedCM endpoint, the session cookie,
- * and any redirect target are same-site with the RP — the only way
- * to get first-party cookies in Safari ITP and Firefox Total Cookie
- * Protection.
- *
- * This helper computes `https://auth.<rp-apex>` from
- * `window.location.hostname` so a consuming app doesn't have to pass
- * `authWebUrl` explicitly. Returns `undefined` for environments where
- * auto-detection would be wrong:
- *
- *   - SSR / non-browser (no `window`).
- *   - `localhost`, `127.0.0.1`, IPv4/IPv6 literals.
- *   - Hostnames with fewer than two labels.
- *   - Hostnames where a registrable domain cannot be determined from the
- *     Public Suffix List, including private hosted suffixes such as
- *     `github.io`, `pages.dev`, and `netlify.app`.
- *
- * When the page is already loaded ON the IdP itself (`auth.<anything>`),
- * the helper returns the current origin so the SDK keeps everything
- * same-origin instead of hopping to a different IdP host.
- *
- * The IdP backend independently derives `iss`, `provider_urls`, and the
- * `fedcm.json` icon URLs from the request host
- * (`packages/auth/server/index.ts`), so an honest CNAME pair is all that
- * is required for end-to-end FedCM correctness — no per-RP config.
- */
-
-import { getDomain } from 'tldts';
-
-/**
- * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
- * Suffix List, including private hosted 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`);
- *   - 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: 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;
-  // 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, so
-  // deriving `auth.<apex>` against it is impossible — `getDomain` returns null.
-  return getDomain(host, { allowPrivateDomains: true });
-}
-
-export function autoDetectAuthWebUrl(
-  location: Pick<Location, 'hostname' | 'protocol'> | undefined =
-    typeof window !== 'undefined' ? window.location : undefined
-): string | undefined {
-  if (!location) return undefined;
-  const { hostname, protocol } = location;
-  if (!hostname) return undefined;
-  if (protocol !== 'https:' && protocol !== 'http:') return undefined;
-  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 apex = registrableApex(hostname);
-  if (apex === null) return undefined;
-  return `${protocol}//auth.${apex}`;
-}

package/src/utils/ssoEstablish.ts

@@ -1,174 +0,0 @@
-/**
- * Post-claim durable-session establish hop (web device-flow / "Sign in with
- * Oxy" QR).
- *
- * A WEB device-flow claim (`claimSessionByToken`) plants only IN-MEMORY tokens:
- * unlike a redirect/FedCM/silent sign-in, it never causes the IdP to plant a
- * `fedcm_session` cookie. So a reload has nothing to restore from — the
- * silent-iframe and `/sso` paths find no IdP session and the session is lost.
- *
- * This primitive closes that gap. AFTER the claim has committed and the session
- * has been durably persisted, it performs ONE top-level establish hop through
- * the RP's own per-apex IdP host (`auth.<rp-apex>`), reusing the EXISTING
- * `/sso/establish` endpoint: the server mints a short-lived, host+audience-bound
- * establish-token and returns a fully-formed establish URL; navigating to it
- * plants the durable first-party `fedcm_session` cookie and bounces back to the
- * RP callback with an opaque code the standard `sso-return` cold-boot step
- * exchanges.
- *
- * It reuses the SAME per-origin `sessionStorage` bounce contract
- * (`ssoStateKey` / `ssoGuardKey` / `ssoDestKey`) that {@link buildSsoBounceUrl}
- * primes for the terminal `/sso` bounce, so the post-bounce `sso-return` step
- * (`consumeSsoReturn`) validates the CSRF `state`, exchanges the code, and
- * restores the user's real destination with no extra wiring.
- *
- * Contract:
- *  - WEB only — off-web / native it is a no-op returning `false`.
- *  - NEVER fires while sitting on the central IdP origin (that would loop the
- *    IdP against itself).
- *  - Bounce state is persisted ONLY after the establish-URL request succeeds, so
- *    a failed request leaves no stale state behind.
- *  - SINGLE attempt: the caller invokes this exactly once per successful claim.
- *    On ANY failure it does NOT navigate and returns `false`, leaving the
- *    committed in-memory session exactly as-is (the user is no worse off than
- *    before this hop existed).
- *  - Total: never throws. Failures are reported via {@link deps.onError} only.
- */
-
-import {
-  ssoStateKey,
-  ssoGuardKey,
-  ssoDestKey,
-  ssoNavigate,
-  isCentralIdPOrigin,
-} from './ssoBounce';
-import { generateSsoState } from '../mixins/OxyServices.sso';
-
-/**
- * The minimal SDK surface this hop needs: mint a server-formed establish URL
- * bound to the caller's own session for an approved RP origin. Structural so the
- * primitive is unit-testable with a stub and never imports the full client.
- */
-export interface SsoEstablishClient {
-  requestSsoEstablishUrl(
-    origin: string,
-    state: string,
-  ): Promise<{ establishUrl: string }>;
-}
-
-/**
- * Injectable web seams for {@link establishIdpSessionAfterClaim}. Every seam is
- * overridable so the primitive is fully unit-testable with fakes and so native
- * callers rely on the defaults (which resolve to `window.*` only when a browser
- * is present). Defaults are evaluated lazily inside the function so importing
- * this module never touches `window`.
- */
-export interface EstablishAfterClaimDeps {
-  /** Per-tab SSO bounce store. Default: `window.sessionStorage`. */
-  storage?: Pick<Storage, 'getItem' | 'setItem'>;
-  /** The current location. Default: `window.location`. */
-  location?: Pick<Location, 'origin' | 'href'>;
-  /** Top-level navigation seam. Default: {@link ssoNavigate} (`location.assign`). */
-  navigate?: (url: string) => void;
-  /**
-   * Whether the current environment is a web browser with usable
-   * `sessionStorage`. Default: `typeof window !== 'undefined' && typeof
-   * window.sessionStorage !== 'undefined'`.
-   */
-  isWeb?: () => boolean;
-  /** CSRF state generator. Default: {@link generateSsoState}. */
-  generateState?: () => string;
-  /** Epoch-ms clock for the bounce guard. Default: `Date.now`. */
-  now?: () => number;
-  /**
-   * Optional debug hook invoked with the thrown error when the establish
-   * request (or state persistence) fails. NEVER rethrown. Default: no-op.
-   */
-  onError?: (error: unknown) => void;
-}
-
-/**
- * Perform the post-claim establish hop. Returns `true` when a navigation to the
- * establish URL was initiated (the document is being torn down and replaced by
- * the IdP), `false` on every no-op / failure path.
- *
- * @param client - The exchange surface (`oxyServices.requestSsoEstablishUrl`).
- * @param deps - Injectable web seams; see {@link EstablishAfterClaimDeps}.
- */
-export async function establishIdpSessionAfterClaim(
-  client: SsoEstablishClient,
-  deps: EstablishAfterClaimDeps = {},
-): Promise<boolean> {
-  const isWeb =
-    deps.isWeb ??
-    (() =>
-      typeof window !== 'undefined' &&
-      typeof window.sessionStorage !== 'undefined');
-
-  if (!isWeb()) {
-    return false;
-  }
-
-  const storage = deps.storage ?? window.sessionStorage;
-  const location = deps.location ?? window.location;
-  const navigate = deps.navigate ?? ssoNavigate;
-  const generateState = deps.generateState ?? generateSsoState;
-  const now = deps.now ?? (() => Date.now());
-
-  const origin = location.origin;
-
-  // Never establish while sitting on the central IdP itself — that would bounce
-  // the IdP against itself. (The device-flow claim can only happen on an RP.)
-  if (isCentralIdPOrigin(origin)) {
-    return false;
-  }
-
-  const state = generateState();
-
-  let establishUrl: string;
-  try {
-    const result = await client.requestSsoEstablishUrl(origin, state);
-    if (
-      !result ||
-      typeof result.establishUrl !== 'string' ||
-      result.establishUrl.length === 0
-    ) {
-      return false;
-    }
-    establishUrl = result.establishUrl;
-
-    // Defense-in-depth before a TOP-LEVEL navigation: the establish URL is
-    // server-formed, but never follow anything that is not a well-formed https
-    // `/sso/establish` on an `auth.` host. A malformed or unexpected URL aborts
-    // silently (no navigation, no state persisted) — same total/no-throw
-    // contract — rather than navigating the document somewhere unintended.
-    let parsedEstablishUrl: URL;
-    try {
-      parsedEstablishUrl = new URL(establishUrl);
-    } catch {
-      return false;
-    }
-    if (
-      parsedEstablishUrl.protocol !== 'https:' ||
-      parsedEstablishUrl.pathname !== '/sso/establish' ||
-      !parsedEstablishUrl.hostname.toLowerCase().startsWith('auth.')
-    ) {
-      return false;
-    }
-
-    // Persist the bounce state ONLY now that the request has succeeded and the
-    // URL is validated — so a failed/rejected request never leaves stale state
-    // behind. This is the exact contract the terminal `/sso` bounce primes via
-    // `buildSsoBounceUrl`, so the post-bounce `sso-return` step (`consumeSsoReturn`)
-    // validates `state`, exchanges the returned code, and restores the dest.
-    storage.setItem(ssoStateKey(origin), state);
-    storage.setItem(ssoGuardKey(origin), String(now()));
-    storage.setItem(ssoDestKey(origin), location.href);
-  } catch (error) {
-    deps.onError?.(error);
-    return false;
-  }
-
-  navigate(establishUrl);
-  return true;
-}