@oxyhq/core 5.2.1 → 5.4.0

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

@@ -0,0 +1,204 @@
+/**
+ * `establishIdpSessionAfterClaim` — the post-claim durable-session hop.
+ *
+ * After a WEB device-flow ("Sign in with Oxy" QR) claim commits, the app holds
+ * only in-memory tokens: no `fedcm_session` cookie was ever planted at the IdP,
+ * so a reload cannot re-mint a token. This primitive performs ONE top-level
+ * establish hop (via the RP-minted establish-URL) so the per-apex IdP cookie is
+ * planted and a reload restores via the existing `sso-return` / silent-iframe
+ * paths.
+ *
+ * Invariants pinned here:
+ *  - web only (no-op off-web / native);
+ *  - never fires while sitting on the central IdP origin (would loop);
+ *  - persists the SAME bounce state (`ssoStateKey`/`ssoGuardKey`/`ssoDestKey`)
+ *    the `buildSsoBounceUrl` machinery primes, so the post-bounce `sso-return`
+ *    step validates the state, exchanges the code, and restores the dest;
+ *  - persists ONLY after the establish-URL request succeeds (no stale state on
+ *    failure);
+ *  - navigates exactly once, to the server-returned establish URL;
+ *  - total: an establish-request failure leaves the committed in-memory session
+ *    untouched, does NOT navigate, and returns `false` (user no worse off).
+ */
+
+import { establishIdpSessionAfterClaim } from '../ssoEstablish';
+import {
+  ssoStateKey,
+  ssoGuardKey,
+  ssoDestKey,
+} from '../ssoBounce';
+import { CENTRAL_AUTH_URL } from '../authWebUrl';
+
+const RP_ORIGIN = 'https://accounts.oxy.so';
+const RP_HREF = 'https://accounts.oxy.so/settings';
+const ESTABLISH_URL =
+  'https://auth.oxy.so/sso/establish?et=jwt.abc.def&return_to=https%3A%2F%2Faccounts.oxy.so%2F__oxy%2Fsso-callback&state=state-xyz';
+
+function makeStorage(): {
+  storage: Pick<Storage, 'getItem' | 'setItem'>;
+  map: Map<string, string>;
+} {
+  const map = new Map<string, string>();
+  return {
+    map,
+    storage: {
+      getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+      setItem: (k: string, v: string) => {
+        map.set(k, v);
+      },
+    },
+  };
+}
+
+describe('establishIdpSessionAfterClaim', () => {
+  it('requests the establish URL with the RP origin + generated state and navigates once (web)', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async (origin: string, state: string) => {
+      expect(origin).toBe(RP_ORIGIN);
+      expect(state).toBe('state-xyz');
+      return { establishUrl: ESTABLISH_URL };
+    });
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+        generateState: () => 'state-xyz',
+        now: () => 1_700_000_000_000,
+      },
+    );
+
+    expect(result).toBe(true);
+    expect(requestSsoEstablishUrl).toHaveBeenCalledTimes(1);
+    expect(navigated).toEqual([ESTABLISH_URL]);
+
+    // Bounce state persisted so the post-bounce `sso-return` step validates it.
+    expect(map.get(ssoStateKey(RP_ORIGIN))).toBe('state-xyz');
+    expect(map.get(ssoGuardKey(RP_ORIGIN))).toBe(String(1_700_000_000_000));
+    expect(map.get(ssoDestKey(RP_ORIGIN))).toBe(RP_HREF);
+  });
+
+  it('is a no-op off-web (native): no request, no navigation, no state', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: ESTABLISH_URL }));
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => false,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(requestSsoEstablishUrl).not.toHaveBeenCalled();
+    expect(navigated).toEqual([]);
+    expect(map.size).toBe(0);
+  });
+
+  it('never fires while sitting on the central IdP origin (loop guard)', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: ESTABLISH_URL }));
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: new URL(CENTRAL_AUTH_URL).origin, href: `${CENTRAL_AUTH_URL}/` },
+        navigate: (url) => navigated.push(url),
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(requestSsoEstablishUrl).not.toHaveBeenCalled();
+    expect(navigated).toEqual([]);
+    expect(map.size).toBe(0);
+  });
+
+  it('on an establish-request failure: no navigation, no persisted state, returns false (single attempt)', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const onError = jest.fn();
+    const requestSsoEstablishUrl = jest.fn(async () => {
+      throw new Error('403 unapproved origin');
+    });
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+        generateState: () => 'state-xyz',
+        onError,
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(requestSsoEstablishUrl).toHaveBeenCalledTimes(1);
+    expect(navigated).toEqual([]);
+    // No stale bounce state left behind on failure.
+    expect(map.size).toBe(0);
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not navigate when the server returns no establish URL', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: '' }));
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+        generateState: () => 'state-xyz',
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(navigated).toEqual([]);
+    expect(map.size).toBe(0);
+  });
+
+  it.each([
+    ['unparseable', 'not a url'],
+    ['non-https (http)', 'http://auth.oxy.so/sso/establish?et=x&state=s'],
+    ['wrong path', 'https://auth.oxy.so/evil?et=x&state=s'],
+    ['non-auth host', 'https://evil.oxy.so/sso/establish?et=x&state=s'],
+  ])(
+    'aborts silently (no navigation, no state) for a %s establish URL',
+    async (_label, badUrl) => {
+      const { storage, map } = makeStorage();
+      const navigated: string[] = [];
+      const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: badUrl }));
+
+      const result = await establishIdpSessionAfterClaim(
+        { requestSsoEstablishUrl },
+        {
+          isWeb: () => true,
+          storage,
+          location: { origin: RP_ORIGIN, href: RP_HREF },
+          navigate: (url) => navigated.push(url),
+          generateState: () => 'state-xyz',
+        },
+      );
+
+      expect(result).toBe(false);
+      expect(navigated).toEqual([]);
+      expect(map.size).toBe(0);
+    },
+  );
+});

package/src/utils/ssoBounce.ts

@@ -135,18 +135,18 @@ export function ssoPriorSessionKey(origin: string): string {
  * 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` / the FedCM
- * credential association) would otherwise let `fedcm-silent` / 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, those silent cold-boot steps are skipped while the Gmail-style
- * returning-account fast-path is otherwise preserved.
+ * 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, FedCM, account switch, device
+ *   - 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.
  *
@@ -303,8 +303,8 @@ export function guardActive(
  * 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 steps that can re-mint a session from a
- * still-live IdP session WITHOUT user intent — `fedcm-silent` and the per-apex
+ * 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.

package/src/utils/ssoEstablish.ts

@@ -0,0 +1,174 @@
+/**
+ * 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;
+}