@oxy.so/services 1.0.0

package/src/ui/oauth/explicitOAuthConsent.ts

@@ -0,0 +1,272 @@
+/**
+ * Explicit OAuth consent for an already-authenticated Oxy user.
+ *
+ * This is deliberately separate from sign-in routing. First-party applications
+ * normally use the account dialog, but a consent-required scope (for example
+ * `acting-as:offline`) still has to go through the OAuth authorize surface. The
+ * caller must invoke this operation from a real user gesture; it never runs on
+ * mount, retries silently, or grants anything locally.
+ */
+
+import type { OxyServices, PublicApplication } from "@oxy.so/core";
+import { openAuthorizeUrlNative } from "../components/oauthNavigation";
+import { startWebOAuthSignIn } from "./browserAuthTransport";
+import { completeOAuthCode } from "./completeOAuthCode";
+import { prepareAuthorizeRequest } from "./oauthHandshake";
+import { closeOAuthPopup, openOAuthPopup } from "./oauthPopup";
+import type {
+	OAuthPopupHandle,
+	OAuthSessionCommitInput,
+	WebAuthMode,
+	WebOAuthFailureReason,
+	WebOAuthRedirectReason,
+} from "./types";
+
+export interface RequestOAuthConsentOptions {
+	/** Exact, registered redirect URI. It is never inferred or normalized. */
+	redirectUri: string;
+	/** Exact application scopes to present to the user, in caller-supplied order. */
+	scopes: readonly string[];
+	/** Optional timeout for the web popup lane. */
+	timeoutMs?: number;
+}
+
+export type OAuthConsentFailureReason =
+	| WebOAuthFailureReason
+	| "invalid-redirect-uri"
+	| "invalid-scopes"
+	| "scope-not-configured"
+	| "client-resolution-failed"
+	| "native-callback-invalid"
+	| "state-mismatch"
+	| "exchange-failed"
+	| "subject-mismatch";
+
+export type OAuthConsentUnsupportedReason =
+	| "missing-client-id"
+	| "identity-bound"
+	| "not-authenticated"
+	| "unsupported-platform";
+
+export type OAuthConsentResult =
+	| { status: "consented" }
+	| { status: "redirecting"; via: WebOAuthRedirectReason }
+	| { status: "cancelled" }
+	| { status: "timed-out" }
+	| {
+			status: "failed";
+			reason: OAuthConsentFailureReason;
+			description?: string;
+	  }
+	| { status: "unsupported"; reason: OAuthConsentUnsupportedReason };
+
+export interface OAuthConsentContext {
+	platform: "web" | "native" | "unsupported";
+	mode: WebAuthMode;
+	oxyServices: OxyServices;
+	clientId: string | null;
+	authorizeBaseUrl?: string;
+	identityBound: boolean;
+	/** User who triggered the consent request; a different returned subject is rejected. */
+	expectedUserId: string | null;
+	commitSession: (input: OAuthSessionCommitInput) => Promise<void>;
+}
+
+const EXACT_SCOPE = /^[a-z][a-z0-9-]*(?::[a-z0-9-]+)+$/;
+
+function hasExactRedirectUri(value: string): boolean {
+	if (!value || value !== value.trim() || /\s/.test(value)) return false;
+	try {
+		const parsed = new URL(value);
+		return (
+			Boolean(parsed.protocol) &&
+			!parsed.username &&
+			!parsed.password &&
+			!parsed.hash
+		);
+	} catch {
+		return false;
+	}
+}
+
+function hasExactScopes(scopes: readonly string[]): boolean {
+	if (scopes.length === 0 || new Set(scopes).size !== scopes.length)
+		return false;
+	return scopes.every(
+		(scope) => scope === scope.trim() && EXACT_SCOPE.test(scope),
+	);
+}
+
+function parseNativeCallback(
+	redirectUrl: string,
+	expectedRedirectUri: string,
+):
+	| { kind: "code"; code: string; state: string }
+	| { kind: "error"; description?: string }
+	| { kind: "invalid" } {
+	const separator = expectedRedirectUri.includes("?") ? "&" : "?";
+	if (!redirectUrl.startsWith(`${expectedRedirectUri}${separator}`)) {
+		return { kind: "invalid" };
+	}
+
+	const response = redirectUrl.slice(expectedRedirectUri.length + 1);
+	const params = new URLSearchParams(response);
+	if (params.getAll("code").length > 1 || params.getAll("state").length > 1) {
+		return { kind: "invalid" };
+	}
+	const error = params.get("error");
+	if (error) {
+		const description = params.get("error_description");
+		return description ? { kind: "error", description } : { kind: "error" };
+	}
+	const code = params.get("code");
+	const state = params.get("state");
+	if (!code || !state) return { kind: "invalid" };
+	return { kind: "code", code, state };
+}
+
+/**
+ * Ask the current user to grant exact application scopes through Oxy OAuth.
+ *
+ * Scope syntax is checked before any window opens. After that, the exact client
+ * id resolves its public Application and every requested scope must be present
+ * in that application's configured scope list. Unknown, trimmed, duplicated or
+ * reordered-by-the-SDK values are never sent to the IdP.
+ */
+export async function requestOAuthConsent(
+	context: OAuthConsentContext,
+	options: RequestOAuthConsentOptions,
+): Promise<OAuthConsentResult> {
+	if (!hasExactRedirectUri(options.redirectUri)) {
+		return { status: "failed", reason: "invalid-redirect-uri" };
+	}
+	if (!hasExactScopes(options.scopes)) {
+		return { status: "failed", reason: "invalid-scopes" };
+	}
+	if (!context.clientId) {
+		return { status: "unsupported", reason: "missing-client-id" };
+	}
+	if (context.identityBound) {
+		return { status: "unsupported", reason: "identity-bound" };
+	}
+	if (!context.expectedUserId) {
+		return { status: "unsupported", reason: "not-authenticated" };
+	}
+	if (context.platform === "unsupported") {
+		return { status: "unsupported", reason: "unsupported-platform" };
+	}
+
+	// Claim a popup before the first await. This function is only safe when the
+	// caller invokes it directly from the user's confirmation gesture.
+	const popup: OAuthPopupHandle | null =
+		context.platform === "web" && context.mode === "popup"
+			? openOAuthPopup()
+			: null;
+
+	let application: PublicApplication;
+	try {
+		application = await context.oxyServices.getPublicApplication(
+			context.clientId,
+		);
+	} catch {
+		closeOAuthPopup(popup);
+		return { status: "failed", reason: "client-resolution-failed" };
+	}
+
+	const configuredScopes = new Set(application.scopes);
+	if (options.scopes.some((scope) => !configuredScopes.has(scope))) {
+		closeOAuthPopup(popup);
+		return { status: "failed", reason: "scope-not-configured" };
+	}
+
+	const scope = options.scopes.join(" ");
+	let subjectMismatch = false;
+	const commitExactSubject = async (
+		input: OAuthSessionCommitInput,
+	): Promise<void> => {
+		if (input.userId !== context.expectedUserId) {
+			subjectMismatch = true;
+			throw new Error("OAuth consent returned a different user");
+		}
+		await context.commitSession(input);
+	};
+
+	if (context.platform === "web") {
+		const result = await startWebOAuthSignIn(
+			{
+				mode: context.mode,
+				oxyServices: context.oxyServices,
+				clientId: context.clientId,
+				authorizeBaseUrl: context.authorizeBaseUrl,
+				identityBound: false,
+				commitSession: commitExactSubject,
+			},
+			{
+				redirectUri: options.redirectUri,
+				scope,
+				...(context.mode === "popup" ? { popup } : {}),
+				...(options.timeoutMs !== undefined
+					? { timeoutMs: options.timeoutMs }
+					: {}),
+			},
+		);
+		if (subjectMismatch)
+			return { status: "failed", reason: "subject-mismatch" };
+		switch (result.status) {
+			case "signed-in":
+				return { status: "consented" };
+			case "redirecting":
+			case "cancelled":
+			case "timed-out":
+				return result;
+			case "failed":
+				return {
+					status: "failed",
+					reason: result.reason,
+					...(result.description ? { description: result.description } : {}),
+				};
+			case "unsupported":
+				return { status: "unsupported", reason: "unsupported-platform" };
+		}
+	}
+
+	closeOAuthPopup(popup);
+	const prepared = await prepareAuthorizeRequest({
+		clientId: context.clientId,
+		redirectUri: options.redirectUri,
+		authorizeBaseUrl: context.authorizeBaseUrl,
+		scope,
+	});
+	const { redirectUrl } = await openAuthorizeUrlNative(
+		prepared.authorizeUrl,
+		options.redirectUri,
+		{ allowExternalFallback: false },
+	);
+	if (!redirectUrl) return { status: "cancelled" };
+
+	const callback = parseNativeCallback(redirectUrl, options.redirectUri);
+	if (callback.kind === "error") {
+		return {
+			status: "failed",
+			reason: "idp-error",
+			...(callback.description ? { description: callback.description } : {}),
+		};
+	}
+	if (callback.kind === "invalid") {
+		return { status: "failed", reason: "native-callback-invalid" };
+	}
+
+	const completion = await completeOAuthCode({
+		oxyServices: context.oxyServices,
+		clientId: context.clientId,
+		code: callback.code,
+		returnedState: callback.state,
+		handshake: prepared.handshake,
+		redirectUri: options.redirectUri,
+		commitSession: commitExactSubject,
+	});
+	if (subjectMismatch) return { status: "failed", reason: "subject-mismatch" };
+	return completion.ok
+		? { status: "consented" }
+		: { status: "failed", reason: completion.reason };
+}

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 '@oxy.so/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,277 @@
+/**
+ * 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 { canonicalizeOAuthRedirectUri, logger } from '@oxy.so/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);
+  }
+}
+
+/**
+ * When the IdP falls back to a top-level redirect inside the popup (no usable
+ * `window.opener`), a same-origin `redirect_uri` is readable from the opener.
+ * Cross-origin redirects remain opaque and are not handled here.
+ */
+function readSameOriginRedirectOutcome(
+  popup: OAuthPopupHandle,
+  redirectUri: string,
+  expectedState: string,
+): OAuthPopupOutcome | null {
+  try {
+    const href = popup.location.href;
+    if (!href) return null;
+
+    const popupUrl = new URL(href);
+    const expected = new URL(canonicalizeOAuthRedirectUri(redirectUri));
+    if (popupUrl.origin !== expected.origin) return null;
+    if (popupUrl.pathname !== expected.pathname) return null;
+
+    const oauthError = popupUrl.searchParams.get('error');
+    if (oauthError) {
+      const errorDescription = popupUrl.searchParams.get('error_description') ?? undefined;
+      return {
+        kind: 'oauth-error',
+        error: oauthError,
+        ...(errorDescription ? { errorDescription } : {}),
+      };
+    }
+
+    const code = popupUrl.searchParams.get('code');
+    if (!code) return null;
+
+    const state = popupUrl.searchParams.get('state');
+    if (!state || state !== expectedState) return { kind: 'state-mismatch' };
+    return { kind: 'code', code, state };
+  } catch {
+    // Cross-origin navigation — the popup URL is opaque to the opener.
+    return null;
+  }
+}
+
+/** 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;
+  /**
+   * EXACT registered redirect URI for this attempt. When the IdP cannot
+   * `postMessage` (no usable opener) it falls back to redirecting the popup;
+   * if that lands on the same origin, the result is read from the popup URL.
+   */
+  redirectUri: 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,
+    redirectUri,
+    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(() => {
+      const redirectOutcome = readSameOriginRedirectOutcome(popup, redirectUri, expectedState);
+      if (redirectOutcome) {
+        settle(redirectOutcome);
+        return;
+      }
+
+      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);
+  });
+}