@oxyhq/core 2.1.2 → 2.2.1

package/src/mixins/__tests__/constructorAuthWebUrl.test.ts

@@ -1,29 +1,26 @@
 /**
- * `OxyServices` constructor first-party IdP auto-detection.
+ * `OxyServices` constructor central-IdP defaulting.
  *
- * `@oxyhq/services` 8.2.0 added cross-domain SSO that auto-detects the IdP as
- * `https://auth.<rp-apex>` via `autoDetectAuthWebUrl()`. That detection used to
- * run ONLY on the provider-`baseURL` branch of OxyContext — apps that construct
- * their OWN `OxyServices` instance and pass it to
- * `<OxyProvider oxyServices={...} />` never hit it, so an omitted `authWebUrl`
- * fell back to the hardcoded `DEFAULT_AUTH_URL` ('https://auth.oxy.so'),
- * forcing a third-party IdP and breaking Safari/Firefox cross-domain restore.
+ * TRUE central cross-domain SSO (Google/Meta/Clerk style, 2026-06-13) routes
+ * every Relying Party through ONE central IdP at `auth.oxy.so` — it owns the
+ * host-only `fedcm_session` cookie and the central session store. The SDK
+ * therefore defaults `authWebUrl` to the central IdP when the caller omits it,
+ * via `resolveCentralAuthUrl(config.authWebUrl)`.
  *
- * The constructor now derives `authWebUrl` itself when the caller omits it, so
- * BOTH construction paths behave identically:
- *   - web at `https://mention.earth` -> `https://auth.mention.earth`
- *   - native/SSR (no `window`)       -> undefined (mixins fall back to
- *     `DEFAULT_AUTH_URL`, exactly as before)
- *   - explicit `authWebUrl`          -> respected verbatim (explicit wins)
+ * This replaces the previous behaviour, where the constructor auto-detected a
+ * per-apex IdP (`auth.<rp-apex>`) from `window.location`. `autoDetectAuthWebUrl`
+ * is still exported for call sites that opt into per-apex resolution, but it is
+ * NO LONGER the constructor default.
+ *
+ * Contract:
+ *   - authWebUrl omitted, no window (native/SSR) -> 'https://auth.oxy.so'
+ *   - authWebUrl omitted, window present         -> 'https://auth.oxy.so'
+ *     (the page host is irrelevant — central only)
+ *   - authWebUrl explicit                        -> respected verbatim (wins)
  */
 
 import { OxyServices } from '../../OxyServices';
-
-// The hardcoded fallback the auth mixins resolve to when `authWebUrl` is unset
-// (`this.config.authWebUrl || DEFAULT_AUTH_URL`). Mirrors the static
-// `DEFAULT_AUTH_URL` on the redirect/popup mixins. Native/SSR must keep
-// resolving to this exact value after the constructor auto-detect change.
-const DEFAULT_AUTH_URL = 'https://auth.oxy.so';
+import { CENTRAL_AUTH_URL } from '../../utils/authWebUrl';
 
 function installWindowLocation(hostname: string, protocol = 'https:'): void {
   (globalThis as unknown as { window: unknown }).window = {
@@ -35,74 +32,54 @@ function clearWindow(): void {
   delete (globalThis as Record<string, unknown>).window;
 }
 
-describe('OxyServices constructor — first-party authWebUrl auto-detection', () => {
+describe('OxyServices constructor — central IdP defaulting', () => {
   afterEach(() => {
     clearWindow();
   });
 
-  it('leaves authWebUrl undefined on native/SSR (no window)', () => {
-    // No `window` is installed -> autoDetectAuthWebUrl() returns undefined.
+  it('defaults authWebUrl to the central IdP on native/SSR (no window)', () => {
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
 
-    expect(oxy.config.authWebUrl).toBeUndefined();
-    // Auth flows must still resolve to the hardcoded default on native.
-    expect(oxy.config.authWebUrl || DEFAULT_AUTH_URL).toBe('https://auth.oxy.so');
+    expect(oxy.config.authWebUrl).toBe(CENTRAL_AUTH_URL);
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
   });
 
-  it('derives auth.<apex> on web when authWebUrl is omitted', () => {
+  it('defaults to the central IdP on web regardless of page host', () => {
+    // The page is mention.earth, but central SSO never derives a per-apex IdP.
     installWindowLocation('mention.earth');
 
     const oxy = new OxyServices({ baseURL: 'https://api.mention.earth' });
 
-    expect(oxy.config.authWebUrl).toBe('https://auth.mention.earth');
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
   });
 
-  it('strips a leading subdomain down to the apex on web', () => {
+  it('defaults to the central IdP even on a subdomain page host', () => {
     installWindowLocation('www.homiio.com');
 
     const oxy = new OxyServices({ baseURL: 'https://api.homiio.com' });
 
-    expect(oxy.config.authWebUrl).toBe('https://auth.homiio.com');
-  });
-
-  it('derives auth.<host> for preview hosts (e.g. *.pages.dev)', () => {
-    installWindowLocation('foo.pages.dev');
-
-    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
-
-    expect(oxy.config.authWebUrl).toBe('https://auth.pages.dev');
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
   });
 
-  it('respects an explicit authWebUrl even when a window is present (explicit wins)', () => {
+  it('respects an explicit authWebUrl (explicit wins)', () => {
     installWindowLocation('mention.earth');
 
     const oxy = new OxyServices({
       baseURL: 'https://api.mention.earth',
-      authWebUrl: 'https://auth.oxy.so',
+      authWebUrl: 'https://auth.mention.earth',
     });
 
-    // The page is mention.earth, but the caller pinned auth.oxy.so — honour it.
-    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
+    // The caller pinned a per-apex IdP explicitly — honour it verbatim.
+    expect(oxy.config.authWebUrl).toBe('https://auth.mention.earth');
   });
 
   it('does not mutate the caller-supplied config object', () => {
-    installWindowLocation('mention.earth');
-
     const input = { baseURL: 'https://api.mention.earth' };
     const oxy = new OxyServices(input);
 
-    // The stored config carries the detected IdP...
-    expect(oxy.config.authWebUrl).toBe('https://auth.mention.earth');
+    // The stored config carries the central IdP default...
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
     // ...but the caller's own object reference is untouched.
     expect((input as { authWebUrl?: string }).authWebUrl).toBeUndefined();
   });
-
-  it('falls back to DEFAULT_AUTH_URL on host shapes auto-detect declines (localhost)', () => {
-    installWindowLocation('localhost', 'http:');
-
-    const oxy = new OxyServices({ baseURL: 'http://localhost:3000' });
-
-    expect(oxy.config.authWebUrl).toBeUndefined();
-    expect(oxy.config.authWebUrl || DEFAULT_AUTH_URL).toBe('https://auth.oxy.so');
-  });
 });

package/src/mixins/__tests__/sso.test.ts

@@ -0,0 +1,146 @@
+/**
+ * `OxyServices.exchangeSsoCode` / `generateSsoState` — central SSO client.
+ *
+ * `exchangeSsoCode(code)` POSTs the opaque single-use code to the session base
+ * URL (`getSessionBaseUrl()` — i.e. `api.oxy.so` by default) at `/sso/exchange`
+ * with NO credentials, then plants the returned access token via
+ * `httpService.setTokens(...)` — mirroring `exchangeIdTokenForSession` /
+ * `verifyChallenge`. NO token/JWT ever travels in the URL; the real token only
+ * arrives in this exchange response body.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import { generateSsoState } from '../OxyServices.sso';
+
+interface FetchCall {
+  url: string;
+  init: RequestInit;
+}
+
+function mockFetchOnce(body: unknown, ok = true, status = 200): { calls: FetchCall[] } {
+  const calls: FetchCall[] = [];
+  const fetchMock = jest.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    return {
+      ok,
+      status,
+      json: async () => body,
+    } as unknown as Response;
+  });
+  (globalThis as unknown as { fetch: typeof fetch }).fetch = fetchMock as unknown as typeof fetch;
+  return { calls };
+}
+
+const VALID_BODY = {
+  accessToken: 'access_sso',
+  sessionId: 'sess_sso',
+  expiresAt: new Date(Date.now() + 60_000).toISOString(),
+  authuser: 0,
+  user: { id: 'user_sso', username: 'ssouser', avatar: 'file_1' },
+};
+
+describe('OxyServices.exchangeSsoCode', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    (globalThis as unknown as { fetch: typeof fetch }).fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('POSTs the code to the API base /sso/exchange with no credentials', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { calls } = mockFetchOnce(VALID_BODY);
+
+    await oxy.exchangeSsoCode('opaque-code-123');
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://api.oxy.so/sso/exchange');
+    expect(calls[0].init.method).toBe('POST');
+    expect(calls[0].init.credentials).toBe('omit');
+    expect(JSON.parse(String(calls[0].init.body))).toEqual({ code: 'opaque-code-123' });
+  });
+
+  it('targets the configured sessionBaseUrl when set', async () => {
+    const oxy = new OxyServices({
+      baseURL: 'https://api.oxy.so',
+      sessionBaseUrl: 'https://api.mention.earth',
+    });
+    const { calls } = mockFetchOnce(VALID_BODY);
+
+    await oxy.exchangeSsoCode('opaque-code-123');
+
+    expect(calls[0].url).toBe('https://api.mention.earth/sso/exchange');
+  });
+
+  it('plants the access token via setTokens and returns the session', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    expect(oxy.hasValidToken()).toBe(false);
+    mockFetchOnce(VALID_BODY);
+
+    const session = await oxy.exchangeSsoCode('opaque-code-123');
+
+    expect(oxy.hasValidToken()).toBe(true);
+    expect(oxy.getAccessToken()).toBe('access_sso');
+    expect(session.sessionId).toBe('sess_sso');
+    expect(session.accessToken).toBe('access_sso');
+    expect(session.user).toEqual({ id: 'user_sso', username: 'ssouser', avatar: 'file_1' });
+    expect(session.expiresAt).toBe(VALID_BODY.expiresAt);
+  });
+
+  it('maps a user delivered as _id', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    mockFetchOnce({
+      accessToken: 'access_sso',
+      sessionId: 'sess_sso',
+      user: { _id: 'mongo_id', username: 'ssouser' },
+    });
+
+    const session = await oxy.exchangeSsoCode('opaque-code-123');
+
+    expect(session.user.id).toBe('mongo_id');
+  });
+
+  it('rejects an empty code without calling fetch', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { calls } = mockFetchOnce(VALID_BODY);
+
+    await expect(oxy.exchangeSsoCode('')).rejects.toThrow();
+    expect(calls).toHaveLength(0);
+  });
+
+  it('throws and does not plant a token on a non-2xx response', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    mockFetchOnce({ error: 'invalid_code' }, false, 400);
+
+    await expect(oxy.exchangeSsoCode('bad-code')).rejects.toThrow();
+    expect(oxy.hasValidToken()).toBe(false);
+  });
+
+  it('throws when the response carries no access token', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    mockFetchOnce({ sessionId: 'sess_sso', user: { id: 'u', username: 'x' } });
+
+    await expect(oxy.exchangeSsoCode('opaque-code-123')).rejects.toThrow();
+    expect(oxy.hasValidToken()).toBe(false);
+  });
+});
+
+describe('generateSsoState', () => {
+  it('returns a non-empty unique string (module-level helper)', () => {
+    const a = generateSsoState();
+    const b = generateSsoState();
+
+    expect(typeof a).toBe('string');
+    expect(a.length).toBeGreaterThan(0);
+    expect(a).not.toBe(b);
+  });
+
+  it('is also reachable as an instance method delegating to generateState', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    const state = oxy.generateSsoState();
+
+    expect(typeof state).toBe('string');
+    expect(state.length).toBeGreaterThan(0);
+  });
+});

package/src/mixins/index.ts

@@ -10,6 +10,7 @@ import { OxyServicesAuthMixin } from './OxyServices.auth';
 import { OxyServicesFedCMMixin } from './OxyServices.fedcm';
 import { OxyServicesPopupAuthMixin } from './OxyServices.popup';
 import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect';
+import { OxyServicesSsoMixin } from './OxyServices.sso';
 import { OxyServicesUserMixin } from './OxyServices.user';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
 import { OxyServicesLanguageMixin } from './OxyServices.language';
@@ -42,6 +43,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>>
@@ -99,6 +101,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesPopupAuthMixin,
     OxyServicesRedirectAuthMixin,
 
+    // Central cross-domain SSO (opaque-code exchange). After Popup so it can
+    // reuse the popup mixin's secure-random `generateState()`.
+    OxyServicesSsoMixin,
+
     // User management (requires auth)
     OxyServicesUserMixin,
     OxyServicesPrivacyMixin,

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

@@ -0,0 +1,40 @@
+/**
+ * `resolveCentralAuthUrl` / `CENTRAL_AUTH_URL` — central IdP resolution.
+ *
+ * Pure helper: an explicit non-empty value always wins; otherwise the central
+ * `auth.oxy.so` origin is returned. No DOM, no side effects.
+ */
+
+import { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from '../authWebUrl';
+
+describe('CENTRAL_AUTH_URL', () => {
+  it('is the central IdP origin with no trailing slash', () => {
+    expect(CENTRAL_AUTH_URL).toBe('https://auth.oxy.so');
+    expect(CENTRAL_AUTH_URL.endsWith('/')).toBe(false);
+  });
+});
+
+describe('resolveCentralAuthUrl', () => {
+  it('returns the central default when no explicit value is given', () => {
+    expect(resolveCentralAuthUrl()).toBe(CENTRAL_AUTH_URL);
+    expect(resolveCentralAuthUrl(undefined)).toBe('https://auth.oxy.so');
+  });
+
+  it('returns the explicit value when provided (explicit wins)', () => {
+    expect(resolveCentralAuthUrl('https://auth.mention.earth')).toBe(
+      'https://auth.mention.earth',
+    );
+  });
+
+  it('does not read any ambient DOM/window state', () => {
+    // Even with a window installed, the result is purely a function of the arg.
+    (globalThis as unknown as { window: unknown }).window = {
+      location: { hostname: 'mention.earth', protocol: 'https:' },
+    };
+    try {
+      expect(resolveCentralAuthUrl()).toBe('https://auth.oxy.so');
+    } finally {
+      delete (globalThis as Record<string, unknown>).window;
+    }
+  });
+});

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

@@ -0,0 +1,120 @@
+/**
+ * `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 { parseSsoReturnFragment } from '../ssoReturn';
+
+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' });
+    });
+  });
+
+  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();
+    });
+  });
+
+  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();
+    });
+  });
+
+  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);
+      }
+    });
+  });
+});

package/src/utils/authWebUrl.ts

@@ -0,0 +1,35 @@
+/**
+ * Central IdP (auth web) URL resolution for cross-domain SSO.
+ *
+ * The Oxy ecosystem runs a single, central Identity Provider at
+ * `auth.oxy.so`. For TRUE central cross-domain SSO (Google/Meta/Clerk style),
+ * FedCM and the opaque-code SSO bounce always target this one origin — it owns
+ * the host-only `fedcm_session` cookie and the central session store reachable
+ * via `api.oxy.so`. Relying Parties (mention.earth, homiio.com, alia.onl, …)
+ * delegate to it rather than standing up a per-apex IdP.
+ *
+ * This module is intentionally pure: it performs no DOM access, reads no
+ * `window`/`location`, and has no side effects. It is the single source of
+ * truth for the central IdP origin so call sites never hardcode the literal.
+ *
+ * Note: this is distinct from `autoDetectAuthWebUrl` (per-apex `auth.<rp-apex>`
+ * derivation). The central-SSO path deliberately does NOT auto-detect per-apex
+ * IdPs — it is central only. An explicitly-configured `authWebUrl` still wins.
+ */
+
+/**
+ * The canonical central Identity Provider origin for the Oxy ecosystem.
+ * No trailing slash.
+ */
+export const CENTRAL_AUTH_URL = 'https://auth.oxy.so';
+
+/**
+ * Resolve the central IdP origin, honouring an explicit override.
+ *
+ * @param explicit - A caller-supplied auth web URL, or `undefined`/empty to use
+ *   the central default. An explicit non-empty value always wins.
+ * @returns The explicit value when provided, otherwise {@link CENTRAL_AUTH_URL}.
+ */
+export function resolveCentralAuthUrl(explicit?: string): string {
+  return explicit ?? CENTRAL_AUTH_URL;
+}

package/src/utils/ssoReturn.ts

@@ -0,0 +1,94 @@
+/**
+ * Parse the SSO return fragment delivered by the central IdP.
+ *
+ * After a top-level redirect bounce to `auth.oxy.so/sso` (prompt=none), the
+ * central IdP returns the Relying Party to its `redirect_uri` with the result
+ * encoded in the URL fragment (the `#…` part). The fragment is used — not a
+ * query string — so the opaque single-use code never reaches a server access
+ * log, a `Referer` header, or browser history in a recoverable form.
+ *
+ * Three outcomes are possible:
+ *   - `#oxy_sso=ok&code=<opaque>&state=<state>` — the IdP had a session; the RP
+ *     exchanges `code` (via `oxy.exchangeSsoCode`) for the real session. NO
+ *     token/JWT ever appears in the URL — only the opaque code.
+ *   - `#oxy_sso=none&state=<state>` — the IdP had no session (prompt=none, user
+ *     not signed in centrally). The RP shows its own signed-out UI.
+ *   - `#oxy_sso=error&state=<state>` — the bounce failed. The RP recovers.
+ *
+ * This parser is pure and defensive: it never throws, and `kind` is strictly
+ * one of `'ok' | 'none' | 'error'`. It returns `null` when the fragment is not
+ * an oxy_sso fragment at all (i.e. `oxy_sso` is absent or an unrecognised
+ * value), so the caller can ignore unrelated fragments without special-casing.
+ */
+
+/**
+ * The recognised outcomes of an SSO bounce.
+ */
+export type SsoReturnKind = 'ok' | 'none' | 'error';
+
+/**
+ * The parsed result of an SSO return fragment.
+ *
+ * `code` is present only for `kind: 'ok'`. `state` echoes the CSRF state the RP
+ * generated for the bounce (when the IdP round-tripped it).
+ */
+export interface SsoReturnResult {
+  kind: SsoReturnKind;
+  code?: string;
+  state?: string;
+}
+
+const VALID_KINDS: ReadonlySet<string> = new Set<SsoReturnKind>(['ok', 'none', 'error']);
+
+/**
+ * Parse an SSO return fragment.
+ *
+ * @param hash - The URL fragment, with or without the leading `#`
+ *   (e.g. `location.hash`). May be `undefined`/empty.
+ * @returns The parsed result when `hash` is a recognised oxy_sso fragment,
+ *   otherwise `null`. Never throws.
+ */
+export function parseSsoReturnFragment(hash: string | undefined | null): SsoReturnResult | null {
+  if (typeof hash !== 'string' || hash.length === 0) {
+    return null;
+  }
+
+  // Strip a single leading '#'. A bare '#' (empty fragment) yields no params.
+  const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (raw.length === 0) {
+    return null;
+  }
+
+  let params: URLSearchParams;
+  try {
+    params = new URLSearchParams(raw);
+  } catch {
+    // URLSearchParams does not throw for malformed input in practice, but guard
+    // against any environment/polyfill that might so this stays total.
+    return null;
+  }
+
+  const kind = params.get('oxy_sso');
+  if (kind === null || !VALID_KINDS.has(kind)) {
+    // Not an oxy_sso fragment (absent or unrecognised value) — ignore it.
+    return null;
+  }
+
+  const result: SsoReturnResult = { kind: kind as SsoReturnKind };
+
+  const state = params.get('state');
+  if (state !== null && state.length > 0) {
+    result.state = state;
+  }
+
+  // The opaque code is only meaningful on success; ignore any stray `code` on
+  // none/error so callers never attempt an exchange for a non-ok outcome.
+  if (result.kind === 'ok') {
+    const code = params.get('code');
+    if (code !== null && code.length > 0) {
+      result.code = code;
+    }
+  }
+
+  return result;
+}