@oxyhq/core 2.2.1 → 2.2.2

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

@@ -0,0 +1,401 @@
+/**
+ * `consumeSsoReturn` — the commit-free, security-critical kernel of the
+ * cross-domain SSO `sso-return` step.
+ *
+ * Every web seam is injected (storage / location / history / isWeb) so the
+ * full CSRF / fragment-strip-order / exchange / dest-restore / loop-breaker
+ * sequence is asserted deterministically without a DOM.
+ */
+
+import { consumeSsoReturn } from '../ssoReturn';
+import {
+  SSO_CALLBACK_PATH,
+  ssoStateKey,
+  ssoGuardKey,
+  ssoDestKey,
+  ssoNoSessionKey,
+} from '../ssoBounce';
+import type { SessionLoginResponse } from '../../models/session';
+
+const ORIGIN = 'https://mention.earth';
+
+function makeStorage(seed: Record<string, string> = {}) {
+  const map = new Map<string, string>(Object.entries(seed));
+  return {
+    map,
+    getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+    setItem: (k: string, v: string) => {
+      map.set(k, v);
+    },
+    removeItem: (k: string) => {
+      map.delete(k);
+    },
+  };
+}
+
+interface LocationParts {
+  hash: string;
+  origin: string;
+  pathname: string;
+  search: string;
+}
+
+function makeLocation(parts: Partial<LocationParts> = {}): LocationParts {
+  return {
+    hash: parts.hash ?? '',
+    origin: parts.origin ?? ORIGIN,
+    pathname: parts.pathname ?? SSO_CALLBACK_PATH,
+    search: parts.search ?? '',
+  };
+}
+
+function makeHistory() {
+  const calls: Array<[unknown, string, string | undefined]> = [];
+  return {
+    calls,
+    replaceState: (data: unknown, unused: string, url?: string | URL | null) => {
+      calls.push([data, unused, typeof url === 'string' ? url : undefined]);
+    },
+  };
+}
+
+const SESSION: SessionLoginResponse = {
+  sessionId: 'sess-1',
+  deviceId: 'dev-1',
+  expiresAt: '2099-01-01T00:00:00.000Z',
+  user: { id: 'u1', username: 'alice' },
+};
+
+function okExchange() {
+  return { exchangeSsoCode: jest.fn(async () => SESSION) };
+}
+
+describe('consumeSsoReturn', () => {
+  it('returns null off-web (isWeb false) and does nothing', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage();
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => false,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=ok&code=c&state=s' }),
+      history: makeHistory(),
+    });
+
+    expect(result).toBeNull();
+    expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+  });
+
+  it('returns null for a non-oxy fragment without touching any flags', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage();
+    const history = makeHistory();
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#section=about' }),
+      history,
+    });
+
+    expect(result).toBeNull();
+    expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+    expect(storage.map.has(ssoNoSessionKey(ORIGIN))).toBe(false);
+    // No fragment strip for an unrelated fragment.
+    expect(history.calls).toHaveLength(0);
+  });
+
+  it('sets NO_SESSION and returns null on a "none" outcome', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=none&state=s' }),
+      history: makeHistory(),
+    });
+
+    expect(result).toBeNull();
+    expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.has(ssoStateKey(ORIGIN))).toBe(false);
+    expect(storage.map.has(ssoGuardKey(ORIGIN))).toBe(false);
+  });
+
+  it('sets NO_SESSION and returns null on an "error" outcome', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=error&state=s' }),
+      history: makeHistory(),
+    });
+
+    expect(result).toBeNull();
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+  });
+
+  it('sets NO_SESSION and returns null on a state mismatch (CSRF)', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 'expected' });
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=ok&code=c&state=forged' }),
+      history: makeHistory(),
+    });
+
+    expect(result).toBeNull();
+    expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+  });
+
+  it('sets NO_SESSION and returns null when ok carries no code', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=ok&state=s' }),
+      history: makeHistory(),
+    });
+
+    expect(result).toBeNull();
+    expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+  });
+
+  it('exchanges, returns the session, strips the fragment, and removes state/guard keys on ok', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage({
+      [ssoStateKey(ORIGIN)]: 's',
+      [ssoGuardKey(ORIGIN)]: String(Date.now()),
+    });
+    const history = makeHistory();
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({
+        hash: '#oxy_sso=ok&code=opaque-code&state=s',
+        pathname: '/feed',
+        search: '?tab=home',
+      }),
+      history,
+    });
+
+    expect(result).toEqual(SESSION);
+    expect(oxy.exchangeSsoCode).toHaveBeenCalledWith('opaque-code');
+    expect(storage.map.has(ssoStateKey(ORIGIN))).toBe(false);
+    expect(storage.map.has(ssoGuardKey(ORIGIN))).toBe(false);
+    expect(storage.map.has(ssoNoSessionKey(ORIGIN))).toBe(false);
+    // Fragment stripped to pathname+search (the first replaceState).
+    expect(history.calls[0]?.[2]).toBe('/feed?tab=home');
+  });
+
+  it('strips the fragment BEFORE the exchange (opaque code never lingers)', async () => {
+    const order: string[] = [];
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+    const history = {
+      replaceState: () => {
+        order.push('replaceState');
+      },
+    };
+    const oxy = {
+      exchangeSsoCode: jest.fn(async () => {
+        order.push('exchange');
+        return SESSION;
+      }),
+    };
+
+    await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({
+        hash: '#oxy_sso=ok&code=c&state=s',
+        pathname: '/somewhere',
+      }),
+      history,
+    });
+
+    expect(order[0]).toBe('replaceState');
+    expect(order).toContain('exchange');
+    expect(order.indexOf('replaceState')).toBeLessThan(order.indexOf('exchange'));
+  });
+
+  it('sets NO_SESSION, returns null, and calls onExchangeError when the exchange throws', async () => {
+    const boom = new Error('exchange failed');
+    const oxy = {
+      exchangeSsoCode: jest.fn(async () => {
+        throw boom;
+      }),
+    };
+    const onExchangeError = jest.fn();
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=ok&code=c&state=s' }),
+      history: makeHistory(),
+      onExchangeError,
+    });
+
+    expect(result).toBeNull();
+    expect(onExchangeError).toHaveBeenCalledWith(boom);
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+  });
+
+  it('does not throw when the exchange throws and no onExchangeError hook is given', async () => {
+    const oxy = {
+      exchangeSsoCode: jest.fn(async () => {
+        throw new Error('boom');
+      }),
+    };
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+
+    await expect(
+      consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({ hash: '#oxy_sso=ok&code=c&state=s' }),
+        history: makeHistory(),
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it('sets NO_SESSION when the exchange resolves without a sessionId', async () => {
+    const oxy = {
+      exchangeSsoCode: jest.fn(async () => ({ sessionId: '' }) as SessionLoginResponse),
+    };
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=ok&code=c&state=s' }),
+      history: makeHistory(),
+    });
+
+    expect(result).toBeNull();
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+  });
+
+  describe('dest restore', () => {
+    it('restores a same-origin destination when on the callback path and removes the dest key', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: `${ORIGIN}/profile?x=1#frag`,
+      });
+      const history = makeHistory();
+
+      const result = await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=ok&code=c&state=s',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+      });
+
+      expect(result).toEqual(SESSION);
+      // First replaceState = fragment strip; last = dest restore.
+      const last = history.calls[history.calls.length - 1];
+      expect(last?.[2]).toBe('/profile?x=1#frag');
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+    });
+
+    it('restores a relative same-origin destination (new URL(dest, origin))', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: '/settings?tab=privacy',
+      });
+      const history = makeHistory();
+
+      await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=ok&code=c&state=s',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+      });
+
+      const last = history.calls[history.calls.length - 1];
+      expect(last?.[2]).toBe('/settings?tab=privacy');
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+    });
+
+    it('rejects a cross-origin (attacker-planted) destination but still removes the dest key', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: 'https://evil.example/phish',
+      });
+      const history = makeHistory();
+
+      await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=ok&code=c&state=s',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+      });
+
+      // Only the fragment-strip replaceState should have run — no dest restore.
+      expect(history.calls).toHaveLength(1);
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+    });
+
+    it('rejects a protocol-relative cross-origin destination', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: '//evil.example/phish',
+      });
+      const history = makeHistory();
+
+      await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=ok&code=c&state=s',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+      });
+
+      expect(history.calls).toHaveLength(1);
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+    });
+
+    it('does not restore dest when NOT on the callback path, but still removes the dest key', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: `${ORIGIN}/should-not-apply`,
+      });
+      const history = makeHistory();
+
+      await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=ok&code=c&state=s',
+          pathname: '/already-here',
+          search: '?a=1',
+        }),
+        history,
+      });
+
+      // Only the fragment strip ran.
+      expect(history.calls).toHaveLength(1);
+      expect(history.calls[0]?.[2]).toBe('/already-here?a=1');
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+    });
+  });
+});

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

@@ -10,7 +10,7 @@
  * MULTIPART_TLDS guard.
  */
 
-import { autoDetectAuthWebUrl } from '../fapiAutoDetect';
+import { autoDetectAuthWebUrl, registrableApex } from '../fapiAutoDetect';
 
 function loc(hostname: string, protocol = 'https:'): Pick<Location, 'hostname' | 'protocol'> {
   return { hostname, protocol };
@@ -90,4 +90,65 @@ describe('autoDetectAuthWebUrl', () => {
       expect(autoDetectAuthWebUrl(loc('shop.com.au'))).toBeUndefined();
     });
   });
+
+  // Regression guard: the refactor to delegate host handling to `registrableApex`
+  // must not change any of the pre-existing return values.
+  describe('regression — unchanged values after registrableApex extraction', () => {
+    const cases: Array<[string, string | undefined]> = [
+      ['mention.earth', 'https://auth.mention.earth'],
+      ['www.mention.earth', 'https://auth.mention.earth'],
+      ['deep.app.homiio.com', 'https://auth.homiio.com'],
+      ['auth.oxy.so', 'https://auth.oxy.so'],
+      ['auth.mention.earth', 'https://auth.mention.earth'],
+      ['localhost', undefined],
+      ['192.168.1.10', undefined],
+      ['[::1]', undefined],
+      ['intranet', undefined],
+      ['', undefined],
+      ['foo.co.uk', undefined],
+    ];
+    it.each(cases)('autoDetectAuthWebUrl(%s) === %s', (hostname, expected) => {
+      const protocol = hostname === 'localhost' || hostname === '[::1]' ? 'http:' : 'https:';
+      expect(autoDetectAuthWebUrl(loc(hostname, protocol))).toBe(expected);
+    });
+  });
+});
+
+describe('registrableApex', () => {
+  it('returns the eTLD+1 for a normal two-label host', () => {
+    expect(registrableApex('mention.earth')).toBe('mention.earth');
+  });
+
+  it('strips subdomains down to the trailing two labels', () => {
+    expect(registrableApex('www.mention.earth')).toBe('mention.earth');
+    expect(registrableApex('deep.app.homiio.com')).toBe('homiio.com');
+  });
+
+  it('lower-cases the input', () => {
+    expect(registrableApex('WWW.Mention.EARTH')).toBe('mention.earth');
+  });
+
+  it('returns null for a multi-part public suffix (foo.co.uk -> null)', () => {
+    expect(registrableApex('foo.co.uk')).toBeNull();
+    expect(registrableApex('shop.com.au')).toBeNull();
+  });
+
+  it('returns null for IPv4 literals', () => {
+    expect(registrableApex('192.168.1.10')).toBeNull();
+    expect(registrableApex('10.0.0.1')).toBeNull();
+  });
+
+  it('returns null for IPv6 literals and hosts carrying a port', () => {
+    expect(registrableApex('[::1]')).toBeNull();
+    expect(registrableApex('mention.earth:3000')).toBeNull();
+  });
+
+  it('returns null for single-label hosts', () => {
+    expect(registrableApex('intranet')).toBeNull();
+    expect(registrableApex('localhost')).toBeNull();
+  });
+
+  it('returns null for empty input', () => {
+    expect(registrableApex('')).toBeNull();
+  });
 });

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

@@ -0,0 +1,148 @@
+/**
+ * Central SSO bounce helpers — per-origin key builders, the bounce URL builder,
+ * the central-IdP predicate, and the self-healing guard.
+ *
+ * These are a wire/storage contract shared with the IdP and every consumer, so
+ * the exact key strings, the 30s TTL, and the same-origin / parse-failure
+ * behaviour are all asserted explicitly.
+ */
+
+import {
+  SSO_CALLBACK_PATH,
+  SSO_GUARD_TTL_MS,
+  ssoStateKey,
+  ssoGuardKey,
+  ssoDestKey,
+  ssoNoSessionKey,
+  buildSsoBounceUrl,
+  isCentralIdPOrigin,
+  guardActive,
+} from '../ssoBounce';
+import { CENTRAL_AUTH_URL } from '../authWebUrl';
+
+describe('SSO bounce constants', () => {
+  it('pins the callback path and guard TTL (wire/storage contract)', () => {
+    expect(SSO_CALLBACK_PATH).toBe('/__oxy/sso-callback');
+    expect(SSO_GUARD_TTL_MS).toBe(30_000);
+  });
+});
+
+describe('per-origin key builders', () => {
+  const origin = 'https://mention.earth';
+
+  it('builds the exact contracted key strings', () => {
+    expect(ssoStateKey(origin)).toBe('oxy_sso_state:https://mention.earth');
+    expect(ssoGuardKey(origin)).toBe('oxy_sso_guard:https://mention.earth');
+    expect(ssoDestKey(origin)).toBe('oxy_sso_dest:https://mention.earth');
+    expect(ssoNoSessionKey(origin)).toBe('oxy_sso_no_session:https://mention.earth');
+  });
+
+  it('namespaces keys per origin so two RPs never collide', () => {
+    expect(ssoStateKey('https://a.test')).not.toBe(ssoStateKey('https://b.test'));
+  });
+});
+
+describe('buildSsoBounceUrl', () => {
+  const origin = 'https://mention.earth';
+
+  it('targets the central IdP /sso with all required params (default base)', () => {
+    const url = new URL(buildSsoBounceUrl(origin, 'state-123'));
+
+    expect(url.origin).toBe('https://auth.oxy.so');
+    expect(url.pathname).toBe('/sso');
+    expect(url.searchParams.get('prompt')).toBe('none');
+    expect(url.searchParams.get('client_id')).toBe(origin);
+    expect(url.searchParams.get('return_to')).toBe(origin + SSO_CALLBACK_PATH);
+    expect(url.searchParams.get('state')).toBe('state-123');
+  });
+
+  it('honours an explicit authWebUrl override (staging IdP)', () => {
+    const url = new URL(
+      buildSsoBounceUrl(origin, 'state-xyz', 'https://auth.mention.earth'),
+    );
+
+    expect(url.origin).toBe('https://auth.mention.earth');
+    expect(url.pathname).toBe('/sso');
+    expect(url.searchParams.get('client_id')).toBe(origin);
+    expect(url.searchParams.get('state')).toBe('state-xyz');
+  });
+
+  it('falls back to the central default for an empty override', () => {
+    const url = new URL(buildSsoBounceUrl(origin, 's', undefined));
+    expect(url.origin).toBe('https://auth.oxy.so');
+  });
+});
+
+describe('isCentralIdPOrigin', () => {
+  it('matches the central IdP origin', () => {
+    expect(isCentralIdPOrigin('https://auth.oxy.so')).toBe(true);
+    expect(isCentralIdPOrigin(CENTRAL_AUTH_URL)).toBe(true);
+  });
+
+  it('normalises a trailing-slash / path candidate via URL origin', () => {
+    expect(isCentralIdPOrigin('https://auth.oxy.so/')).toBe(true);
+    expect(isCentralIdPOrigin('https://auth.oxy.so/sso')).toBe(true);
+  });
+
+  it('rejects a non-central origin', () => {
+    expect(isCentralIdPOrigin('https://mention.earth')).toBe(false);
+    expect(isCentralIdPOrigin('https://auth.mention.earth')).toBe(false);
+  });
+
+  it('returns false for an unparseable candidate', () => {
+    expect(isCentralIdPOrigin('not a url')).toBe(false);
+    expect(isCentralIdPOrigin('')).toBe(false);
+  });
+});
+
+describe('guardActive', () => {
+  const origin = 'https://mention.earth';
+
+  function storageWith(value: string | null): Pick<Storage, 'getItem'> {
+    return { getItem: (key: string) => (key === ssoGuardKey(origin) ? value : null) };
+  }
+
+  it('is active for a present, fresh guard', () => {
+    const now = 1_000_000;
+    const storage = storageWith(String(now - 1_000)); // 1s old, well under TTL
+    expect(guardActive(storage, origin, now)).toBe(true);
+  });
+
+  it('is inactive for a present but stale guard (older than TTL)', () => {
+    const now = 1_000_000;
+    const storage = storageWith(String(now - SSO_GUARD_TTL_MS - 1));
+    expect(guardActive(storage, origin, now)).toBe(false);
+  });
+
+  it('is inactive for a guard exactly at the TTL boundary (strict <)', () => {
+    const now = 1_000_000;
+    const storage = storageWith(String(now - SSO_GUARD_TTL_MS));
+    expect(guardActive(storage, origin, now)).toBe(false);
+  });
+
+  it('is inactive when the guard is missing', () => {
+    expect(guardActive(storageWith(null), origin, 1_000_000)).toBe(false);
+  });
+
+  it('is inactive for an empty-string guard value', () => {
+    expect(guardActive(storageWith(''), origin, 1_000_000)).toBe(false);
+  });
+
+  it('is inactive for a malformed (non-numeric) guard value', () => {
+    expect(guardActive(storageWith('not-a-number'), origin, 1_000_000)).toBe(false);
+  });
+
+  it('is inactive (never throws) when getItem itself throws', () => {
+    const throwing: Pick<Storage, 'getItem'> = {
+      getItem: () => {
+        throw new Error('storage locked');
+      },
+    };
+    expect(guardActive(throwing, origin, 1_000_000)).toBe(false);
+  });
+
+  it('defaults now to Date.now() when omitted', () => {
+    const storage = storageWith(String(Date.now() - 500));
+    expect(guardActive(storage, origin)).toBe(true);
+  });
+});

package/src/utils/authWebUrl.ts

@@ -17,11 +17,23 @@
  * IdPs — it is central only. An explicitly-configured `authWebUrl` still wins.
  */
 
+/**
+ * The registrable apex (eTLD+1) of the Oxy ecosystem's central Identity
+ * Provider. The central IdP is reachable at `auth.${CENTRAL_IDP_APEX}` and the
+ * ID-token assertion issuer is always `https://auth.${CENTRAL_IDP_APEX}`
+ * regardless of which per-apex `auth.<rp>` host served a given request.
+ *
+ * Kept as a standalone constant so the IdP worker and the SDK derive the same
+ * literal from one source of truth (the worker imports it to brand assertions).
+ */
+export const CENTRAL_IDP_APEX = 'oxy.so';
+
 /**
  * The canonical central Identity Provider origin for the Oxy ecosystem.
- * No trailing slash.
+ * No trailing slash. Derived from {@link CENTRAL_IDP_APEX} so the apex and the
+ * full origin never drift apart.
  */
-export const CENTRAL_AUTH_URL = 'https://auth.oxy.so';
+export const CENTRAL_AUTH_URL = `https://auth.${CENTRAL_IDP_APEX}`;
 
 /**
  * Resolve the central IdP origin, honouring an explicit override.