@oxyhq/services 22.12.4 → 22.12.7

package/src/ui/oauth/browserAuthTransport.ts

@@ -0,0 +1,187 @@
+/**
+ * The single web entry point for third-party "Sign in with Oxy".
+ *
+ * Picks the transport (`popup` or `redirect`), drives it, and returns ONE typed
+ * result — so callers (`OxySignInButton`, and any RP with its own button) never
+ * touch `window.open`, `postMessage`, or the token exchange themselves.
+ *
+ * Popup mode keeps the relying party mounted: its route, scroll position, and
+ * unsaved state survive because the tab never navigates. Redirect mode is the
+ * compatibility fallback, and is also where popup mode lands when the browser
+ * blocks the window — a blocked popup must still sign the user in, not dead-end.
+ *
+ * Native is NOT handled here: `openAuthorizeUrlNative` (an in-app auth session)
+ * remains the native lane and is untouched by this module.
+ */
+
+import { logger, persistOAuthHandshake } from '@oxyhq/core';
+import type { OxyServices } from '@oxyhq/core';
+import { redirectToAuthorize } from '../components/oauthNavigation';
+import { isWebBrowser } from '../utils/isWebBrowser';
+import { completeOAuthCode } from './completeOAuthCode';
+import { prepareAuthorizeRequest } from './oauthHandshake';
+import { awaitOAuthPopupResult, closeOAuthPopup, navigateOAuthPopup, openOAuthPopup } from './oauthPopup';
+import type {
+  OAuthPopupHandle,
+  OAuthSessionCommitInput,
+  WebAuthMode,
+  WebOAuthRedirectReason,
+  WebOAuthSignInResult,
+} from './types';
+
+/** Provider-owned wiring for a web sign-in — everything that is not per-press. */
+export interface WebOAuthTransportContext {
+  /** The provider's `webAuthMode`. */
+  mode: WebAuthMode;
+  oxyServices: OxyServices;
+  /** The app's registered client id; `null` disables third-party sign-in. */
+  clientId: string | null;
+  /** Authorize endpoint override (local/staging deployments). */
+  authorizeBaseUrl?: string;
+  /** `sessionMode: 'identity'` — no third-party OAuth lane exists by design. */
+  identityBound: boolean;
+  /** The provider's session commit funnel. */
+  commitSession: (input: OAuthSessionCommitInput) => Promise<void>;
+}
+
+/** Per-press inputs for {@link startWebOAuthSignIn}. */
+export interface StartWebOAuthSignInOptions {
+  /** EXACT registered redirect URI for this application. */
+  redirectUri: string;
+  /**
+   * The popup to drive, when the caller already opened one.
+   *
+   * - omitted — this call opens the window itself, which is only valid when it
+   *   was invoked SYNCHRONOUSLY from the user's click (gesture attribution);
+   * - `null` — the caller tried and the browser blocked it: fall back to a
+   *   full-page redirect;
+   * - a handle — use exactly this window.
+   *
+   * Callers that must `await` before signing in (resolving the application, for
+   * instance) have to open the window in their press handler and pass it here;
+   * a window opened after an `await` is silently blocked by every browser.
+   */
+  popup?: OAuthPopupHandle | null;
+  /** Requested scope; defaults to the SDK's standard sign-in scope. */
+  scope?: string;
+  /** Popup timeout override (ms). */
+  timeoutMs?: number;
+}
+
+export async function startWebOAuthSignIn(
+  context: WebOAuthTransportContext,
+  options: StartWebOAuthSignInOptions,
+): Promise<WebOAuthSignInResult> {
+  if (!isWebBrowser()) {
+    closeOAuthPopup(options.popup ?? null);
+    return { status: 'unsupported', reason: 'no-browser' };
+  }
+  if (context.identityBound) {
+    closeOAuthPopup(options.popup ?? null);
+    return { status: 'unsupported', reason: 'identity-bound' };
+  }
+  if (!context.clientId) {
+    closeOAuthPopup(options.popup ?? null);
+    return { status: 'unsupported', reason: 'missing-client-id' };
+  }
+
+  // Claim the window BEFORE the first `await` below, so a caller that invoked us
+  // straight from the click still has gesture attribution. An explicit `null`
+  // means the caller already tried and was blocked.
+  const popup =
+    context.mode === 'popup' && options.popup === undefined ? openOAuthPopup() : options.popup ?? null;
+
+  if (context.mode === 'redirect') {
+    closeOAuthPopup(popup);
+    return startRedirectSignIn(context, options, 'redirect-mode');
+  }
+  if (!popup) {
+    logger.warn('OAuth sign-in popup was blocked; falling back to a full-page redirect', {
+      component: 'browserAuthTransport',
+    });
+    return startRedirectSignIn(context, options, 'popup-blocked');
+  }
+
+  const prepared = await prepareAuthorizeRequest({
+    clientId: context.clientId,
+    redirectUri: options.redirectUri,
+    authorizeBaseUrl: context.authorizeBaseUrl,
+    scope: options.scope,
+    responseMode: 'web_message',
+  });
+
+  if (!navigateOAuthPopup(popup, prepared.authorizeUrl)) {
+    closeOAuthPopup(popup);
+    return startRedirectSignIn(context, options, 'popup-navigation-failed');
+  }
+
+  const outcome = await awaitOAuthPopupResult({
+    popup,
+    expectedOrigin: prepared.authorizeOrigin,
+    expectedState: prepared.handshake.state,
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+  });
+  // The IdP closes itself after delivering; this covers every other outcome
+  // (timeout, mismatch, an error the IdP reported before closing).
+  closeOAuthPopup(popup);
+
+  switch (outcome.kind) {
+    case 'code': {
+      const completion = await completeOAuthCode({
+        oxyServices: context.oxyServices,
+        clientId: context.clientId,
+        code: outcome.code,
+        returnedState: outcome.state,
+        handshake: prepared.handshake,
+        redirectUri: options.redirectUri,
+        commitSession: context.commitSession,
+      });
+      return completion.ok
+        ? { status: 'signed-in' }
+        : { status: 'failed', reason: completion.reason };
+    }
+    case 'oauth-error':
+      return {
+        status: 'failed',
+        reason: 'idp-error',
+        description: outcome.errorDescription ?? outcome.error,
+      };
+    case 'state-mismatch':
+      return { status: 'failed', reason: 'state-mismatch' };
+    case 'closed':
+      return { status: 'cancelled' };
+    case 'timed-out':
+      return { status: 'timed-out' };
+    case 'unsupported':
+      return { status: 'unsupported', reason: 'no-browser' };
+  }
+}
+
+/**
+ * Full-page hand-off to the IdP. The document is destroyed by the navigation, so
+ * the handshake MUST reach `sessionStorage` first — without it the return trip
+ * cannot validate `state`, and starting the redirect anyway would strand the
+ * user at a callback that can only refuse them.
+ */
+async function startRedirectSignIn(
+  context: WebOAuthTransportContext,
+  options: StartWebOAuthSignInOptions,
+  via: WebOAuthRedirectReason,
+): Promise<WebOAuthSignInResult> {
+  // Narrowed by the caller; repeated here so this helper is safe on its own.
+  if (!context.clientId) return { status: 'unsupported', reason: 'missing-client-id' };
+
+  const prepared = await prepareAuthorizeRequest({
+    clientId: context.clientId,
+    redirectUri: options.redirectUri,
+    authorizeBaseUrl: context.authorizeBaseUrl,
+    scope: options.scope,
+  });
+
+  if (!persistOAuthHandshake(prepared.handshake.state, prepared.handshake.codeVerifier)) {
+    return { status: 'failed', reason: 'handshake-storage' };
+  }
+
+  redirectToAuthorize(prepared.authorizeUrl);
+  return { status: 'redirecting', via };
+}

package/src/ui/oauth/completeOAuthCode.ts

@@ -0,0 +1,93 @@
+/**
+ * The ONE path from an OAuth authorization code to a committed session.
+ *
+ * Both web transports end here — the popup with an in-memory handshake, the
+ * redirect lane with one read back from `sessionStorage` — so state validation,
+ * the PKCE exchange, the session commit, and handshake cleanup exist exactly
+ * once. Duplicating any of those per transport is how the two lanes would drift
+ * apart on the security-critical steps.
+ *
+ * Ordering is deliberate and load-bearing:
+ *   1. validate `state` BEFORE anything is sent to the token endpoint,
+ *   2. exchange the code for a session,
+ *   3. run `cleanup` (drop the persisted handshake / strip `?code=` from the
+ *      URL) BEFORE the commit, so a stale code can never re-enter the exchange,
+ *   4. commit the session.
+ *
+ * `cleanup` runs exactly once on EVERY exit path, including a state mismatch
+ * and a failed exchange.
+ */
+
+import type { OxyServices } from '@oxyhq/core';
+import { logger } from '@oxyhq/core';
+import type { OAuthCompletionResult, OAuthHandshake, OAuthSessionCommitInput } from './types';
+
+/** Inputs for {@link completeOAuthCode}. */
+export interface CompleteOAuthCodeInput {
+  oxyServices: OxyServices;
+  /** The registered `ApplicationCredential` public key (`oxy_dk_…`). */
+  clientId: string;
+  /** The single-use authorization code the IdP issued. */
+  code: string;
+  /** The `state` the IdP returned, or `null` when it sent none. */
+  returnedState: string | null;
+  /**
+   * The handshake this RP started the authorize request with, or `null` when it
+   * is gone (never stored, expired, or a different tab's). A missing handshake
+   * is treated exactly like a mismatched `state`: no exchange is attempted.
+   */
+  handshake: OAuthHandshake | null;
+  /** EXACT redirect URI sent on the authorize request — OAuth requires a match. */
+  redirectUri: string;
+  /** The provider's session commit funnel. */
+  commitSession: (input: OAuthSessionCommitInput) => Promise<void>;
+  /**
+   * Transport-specific teardown, invoked once after the exchange settles and
+   * before the commit. The redirect lane strips `?code=` and clears the
+   * persisted handshake; the popup lane has nothing persisted and omits it.
+   */
+  cleanup?: () => void;
+}
+
+export async function completeOAuthCode(
+  input: CompleteOAuthCodeInput,
+): Promise<OAuthCompletionResult> {
+  let cleaned = false;
+  const runCleanup = (): void => {
+    if (cleaned) return;
+    cleaned = true;
+    input.cleanup?.();
+  };
+
+  if (!input.handshake || !input.returnedState || input.handshake.state !== input.returnedState) {
+    logger.warn('OAuth completion rejected: missing or mismatched state', {
+      component: 'completeOAuthCode',
+    });
+    runCleanup();
+    return { ok: false, reason: 'state-mismatch' };
+  }
+
+  try {
+    const result = await input.oxyServices.exchangeOAuthCode({
+      code: input.code,
+      clientId: input.clientId,
+      redirectUri: input.redirectUri,
+      codeVerifier: input.handshake.codeVerifier,
+    });
+    runCleanup();
+    await input.commitSession({
+      sessionId: result.sessionId,
+      accessToken: result.accessToken,
+      deviceId: result.deviceId,
+      deviceSecret: result.deviceSecret,
+      userId: result.user.id,
+      expiresAt: result.expiresAt,
+      user: result.user,
+    });
+    return { ok: true };
+  } catch (error) {
+    logger.warn('OAuth code exchange failed', { component: 'completeOAuthCode' }, error);
+    runCleanup();
+    return { ok: false, reason: 'exchange-failed' };
+  }
+}

package/src/ui/oauth/legacyRedirectLanes.ts

@@ -0,0 +1,43 @@
+/**
+ * The legacy, redirect-mode-only lanes that navigate the RP's TOP-LEVEL window
+ * to the IdP without a user gesture.
+ *
+ * `webAuthMode: 'popup'` exists to guarantee exactly one thing: the relying
+ * party never leaves its route. Two mechanics in this SDK break that guarantee,
+ * because each replaces the whole document on its own initiative:
+ *
+ * 1. **Cold-boot silent restore** — a full-page `prompt=none` authorize bounce
+ *    to `auth.oxy.so` when the device-secret mint finds no local session
+ *    (`maybeStartSilentOAuthRestore`, called from `runProviderColdBoot`).
+ * 2. **Post-sign-in hub sync** — a full-page hop to `auth.oxy.so/sync` that
+ *    plants this device's credential on the IdP hub so OTHER origins can later
+ *    run lane 1 (`syncHubAfterSignIn`, called from the `commitSession` funnel).
+ *
+ * Both belong to the redirect transport and are kept only for the migration
+ * window (issue #691, "Cold boot and cross-domain behavior"). In popup mode a
+ * domain with no local credential simply resolves SIGNED OUT, and the user's
+ * next explicit "Continue with Oxy" opens the popup — from a real user gesture,
+ * never automatically.
+ *
+ * NOT covered here, and correctly enabled in BOTH modes: navigations the user
+ * asked for. When the browser blocks the popup, `startWebOAuthSignIn` still
+ * falls back to a full-page redirect rather than dead-ending the sign-in, and
+ * `tryCompleteOAuthReturn` still consumes a `?code=` that is already on the URL.
+ *
+ * PHASE 7b: once the pilot flips the default transport to `'popup'`, this
+ * predicate and BOTH lanes above are deleted outright. Grepping this symbol
+ * finds every site that has to go.
+ */
+
+import type { WebAuthMode } from './types';
+
+/**
+ * Whether a provider running `webAuthMode` may perform an SDK-initiated,
+ * non-gesture, full-page navigation to the IdP.
+ *
+ * `true` only for `'redirect'` — still the default and the compatibility path,
+ * whose behaviour must stay byte-for-byte unchanged.
+ */
+export function allowsAutomaticIdpRedirect(webAuthMode: WebAuthMode): boolean {
+  return webAuthMode === 'redirect';
+}

package/src/ui/oauth/oauthHandshake.ts

@@ -0,0 +1,74 @@
+/**
+ * The RP half of an OAuth authorize request: a fresh CSRF `state` + PKCE pair,
+ * and the authorize URL built from them.
+ *
+ * Both web transports start here, and the ONLY difference between them is one
+ * parameter: `popup` asks the IdP for `response_mode=web_message` so the result
+ * comes back to `window.opener` instead of navigating the RP's tab. Everything
+ * else — `S256` PKCE, exact registered `redirect_uri`, random `state` — is
+ * identical, which is what lets both lanes converge on one completion path.
+ */
+
+import { buildOAuthAuthorizeUrl, generateOAuthState, generatePkcePair } from '@oxyhq/core';
+import type { OAuthHandshake } from './types';
+
+/** Inputs for {@link prepareAuthorizeRequest}. */
+export interface PrepareAuthorizeRequestParams {
+  /** The registered `ApplicationCredential` public key (`oxy_dk_…`). */
+  clientId: string;
+  /** EXACT registered redirect URI. The token exchange must replay this value. */
+  redirectUri: string;
+  /** Authorize endpoint override; defaults to the production Oxy IdP. */
+  authorizeBaseUrl?: string;
+  /** Requested scope; defaults to the SDK's standard sign-in scope. */
+  scope?: string;
+  /**
+   * Ask the IdP to deliver the result to `window.opener` via `postMessage`
+   * instead of redirecting. Set ONLY by the popup transport. It is a request,
+   * not a guarantee — an IdP with no opener still redirects.
+   */
+  responseMode?: 'web_message';
+}
+
+/** A ready-to-use authorize request plus the secrets that finish it. */
+export interface PreparedAuthorizeRequest {
+  /** Fully-built `auth.oxy.so/authorize` URL. */
+  authorizeUrl: string;
+  /**
+   * Exact origin of {@link authorizeUrl}. The popup transport accepts
+   * `postMessage` from this origin and no other.
+   */
+  authorizeOrigin: string;
+  /** The `state` + PKCE verifier this request is bound to. */
+  handshake: OAuthHandshake;
+}
+
+/**
+ * Generate a fresh handshake and build the authorize URL around it.
+ *
+ * The verifier is returned to the caller and never stored here: the popup
+ * transport keeps it in memory for the lifetime of the attempt, and the
+ * redirect transport persists it through `persistOAuthHandshake` because a
+ * full-page navigation destroys the running document.
+ */
+export async function prepareAuthorizeRequest(
+  params: PrepareAuthorizeRequestParams,
+): Promise<PreparedAuthorizeRequest> {
+  const [pkce, state] = await Promise.all([generatePkcePair(), generateOAuthState()]);
+
+  const authorizeUrl = buildOAuthAuthorizeUrl({
+    authorizeBaseUrl: params.authorizeBaseUrl,
+    clientId: params.clientId,
+    redirectUri: params.redirectUri,
+    scope: params.scope,
+    state,
+    codeChallenge: pkce.codeChallenge,
+    ...(params.responseMode ? { responseMode: params.responseMode } : {}),
+  });
+
+  return {
+    authorizeUrl,
+    authorizeOrigin: new URL(authorizeUrl).origin,
+    handshake: { state, codeVerifier: pkce.codeVerifier },
+  };
+}

package/src/ui/oauth/oauthPopup.ts

@@ -0,0 +1,219 @@
+/**
+ * Popup lifecycle for the web OAuth transport.
+ *
+ * Owns the window itself — opening it, navigating it, watching it, and tearing
+ * every listener and timer down — and nothing else: message validation lives in
+ * `oauthPopupMessages.ts`, and the code exchange in `completeOAuthCode.ts`.
+ *
+ * Three browser realities shape this module:
+ *
+ * - **Gesture attribution.** `window.open` only succeeds while the user's click
+ *   is still being handled. Anything awaited first (resolving the application,
+ *   generating PKCE) loses it and the popup is silently blocked. So the window
+ *   is opened EMPTY up front and navigated once the authorize URL exists —
+ *   the same shape as `passkeyHubPopup.ts`.
+ * - **No close event.** A cross-origin popup fires nothing when the user
+ *   dismisses it; polling `closed` is the only mechanism (as in core's
+ *   `AccountDialogController.watchPopup`).
+ * - **No cross-origin reads.** The popup's URL, title, and document are all
+ *   opaque. The authorization result arrives ONLY as a `postMessage`.
+ */
+
+import { logger } from '@oxyhq/core';
+import { readOAuthPopupMessage } from './oauthPopupMessages';
+import type { OAuthPopupHandle, OAuthPopupOutcome } from './types';
+
+/**
+ * Window name for the sign-in popup. Naming the target means a second press
+ * REUSES the same window instead of stacking a new one behind the first.
+ */
+export const OXY_OAUTH_POPUP_WINDOW_NAME = 'oxy-oauth';
+
+/** Chrome-free window roughly sized for the IdP's sign-in / QR surface. */
+const POPUP_FEATURES = 'popup=yes,width=460,height=700,menubar=no,toolbar=no,location=no,status=no';
+
+/**
+ * How long a popup sign-in may stay unanswered (ms).
+ *
+ * Generous on purpose: the IdP surface can involve scanning a QR and approving
+ * on a phone, so this tracks the authorize handle's own ~5-minute lifetime
+ * rather than a UI-scale timeout. It is a backstop against a wedged popup, not
+ * a pace-setter — a user who gives up closes the window and gets the faster
+ * `closed` outcome.
+ */
+export const DEFAULT_OAUTH_POPUP_TIMEOUT_MS = 300_000;
+
+/** How often the popup's `closed` flag is sampled (ms). */
+const CLOSE_POLL_INTERVAL_MS = 1000;
+
+/**
+ * Grace period (ms) after `closed` flips before reporting cancellation.
+ *
+ * The IdP posts its result and THEN closes itself. Both land as separate tasks,
+ * so a poll tick that happens to fall between them would otherwise turn a
+ * successful sign-in into a "user cancelled". One short grace window lets the
+ * already-queued message win.
+ */
+const CLOSE_GRACE_MS = 400;
+
+/** The `message` half of the DOM host, absent on native and during SSR. */
+interface MessageEventHost {
+  addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+  removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+
+/** The `open` half of the DOM host, absent on native and during SSR. */
+interface PopupOpenerHost {
+  open?: (url: string, target: string, features: string) => OAuthPopupHandle | null;
+}
+
+function messageEventHost(): MessageEventHost | null {
+  const win = (globalThis as { window?: Partial<MessageEventHost> }).window;
+  if (!win || typeof win.addEventListener !== 'function' || typeof win.removeEventListener !== 'function') {
+    return null;
+  }
+  return win as MessageEventHost;
+}
+
+/**
+ * Open a new, EMPTY sign-in popup.
+ *
+ * MUST be called SYNCHRONOUSLY from a user-gesture handler, before any `await`.
+ * Returns `null` when the browser blocked it, when `window.open` threw, and on
+ * hosts with no DOM (native / SSR) — never throws, because "no popup" is an
+ * ordinary outcome the caller answers by falling back to a redirect.
+ */
+export function openOAuthPopup(): OAuthPopupHandle | null {
+  const win = (globalThis as { window?: PopupOpenerHost }).window;
+  if (!win || typeof win.open !== 'function') return null;
+  try {
+    return win.open('', OXY_OAUTH_POPUP_WINDOW_NAME, POPUP_FEATURES) ?? null;
+  } catch (error) {
+    logger.warn('Could not open the OAuth sign-in popup', { component: 'oauthPopup' }, error);
+    return null;
+  }
+}
+
+/**
+ * Point an already-open popup at the authorize URL. Returns `false` when the
+ * assignment threw (a window closed between opening and navigating), so the
+ * caller can fall back to a redirect instead of waiting on a dead window.
+ */
+export function navigateOAuthPopup(popup: OAuthPopupHandle, url: string): boolean {
+  try {
+    popup.location.href = url;
+    return true;
+  } catch (error) {
+    logger.warn('Could not navigate the OAuth sign-in popup', { component: 'oauthPopup' }, error);
+    return false;
+  }
+}
+
+/** Close the popup if it is still open. Idempotent, null-safe, never throws. */
+export function closeOAuthPopup(popup: OAuthPopupHandle | null): void {
+  if (!popup || popup.closed) return;
+  try {
+    popup.close();
+  } catch (error) {
+    logger.debug('OAuth popup close failed', { component: 'oauthPopup' }, error);
+  }
+}
+
+/** Inputs for {@link awaitOAuthPopupResult}. */
+export interface AwaitOAuthPopupOptions {
+  /** The exact window reference returned by {@link openOAuthPopup}. */
+  popup: OAuthPopupHandle;
+  /** Exact origin the IdP will post from (`new URL(authorizeUrl).origin`). */
+  expectedOrigin: string;
+  /** The CSRF `state` sent on the authorize request. */
+  expectedState: string;
+  /** @default DEFAULT_OAUTH_POPUP_TIMEOUT_MS */
+  timeoutMs?: number;
+}
+
+/**
+ * Wait for the popup to deliver an authorization result.
+ *
+ * Settles EXACTLY once, with a typed outcome for every path — code, IdP error,
+ * state mismatch, user-closed, timeout — and removes its listener, its close
+ * poll, and both timers before resolving, whatever the outcome. Messages that
+ * arrive after settling reach nothing, so a duplicate delivery is inert.
+ *
+ * Never rejects: closing the window and running out of time are expected
+ * outcomes, not exceptions.
+ */
+export function awaitOAuthPopupResult(
+  options: AwaitOAuthPopupOptions,
+): Promise<OAuthPopupOutcome> {
+  const { popup, expectedOrigin, expectedState, timeoutMs = DEFAULT_OAUTH_POPUP_TIMEOUT_MS } =
+    options;
+
+  const host = messageEventHost();
+  if (!host) return Promise.resolve({ kind: 'unsupported' });
+
+  return new Promise<OAuthPopupOutcome>((resolve) => {
+    let settled = false;
+    let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+    let closeGraceTimer: ReturnType<typeof setTimeout> | null = null;
+    let closePoll: ReturnType<typeof setInterval> | null = null;
+
+    const onMessage = (event: MessageEvent): void => {
+      const verdict = readOAuthPopupMessage(event, { expectedOrigin, expectedState, popup });
+      switch (verdict.kind) {
+        case 'ignore':
+          return;
+        case 'code':
+          settle({ kind: 'code', code: verdict.code, state: verdict.state });
+          return;
+        case 'oauth-error':
+          settle({
+            kind: 'oauth-error',
+            error: verdict.error,
+            ...(verdict.errorDescription ? { errorDescription: verdict.errorDescription } : {}),
+          });
+          return;
+        case 'state-mismatch':
+          settle({ kind: 'state-mismatch' });
+          return;
+      }
+    };
+
+    const cleanup = (): void => {
+      host.removeEventListener('message', onMessage);
+      if (timeoutTimer !== null) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = null;
+      }
+      if (closeGraceTimer !== null) {
+        clearTimeout(closeGraceTimer);
+        closeGraceTimer = null;
+      }
+      if (closePoll !== null) {
+        clearInterval(closePoll);
+        closePoll = null;
+      }
+    };
+
+    function settle(outcome: OAuthPopupOutcome): void {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(outcome);
+    }
+
+    host.addEventListener('message', onMessage);
+
+    timeoutTimer = setTimeout(() => settle({ kind: 'timed-out' }), timeoutMs);
+
+    closePoll = setInterval(() => {
+      if (!popup.closed) return;
+      // Stop sampling immediately: the window is gone and only the in-flight
+      // message (if any) can still change the outcome.
+      if (closePoll !== null) {
+        clearInterval(closePoll);
+        closePoll = null;
+      }
+      closeGraceTimer = setTimeout(() => settle({ kind: 'closed' }), CLOSE_GRACE_MS);
+    }, CLOSE_POLL_INTERVAL_MS);
+  });
+}