@oxy.so/services 1.0.0

package/src/ui/oauth/__tests__/sharedCompletionPath.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Both web transports MUST finish through the same completion function.
+ *
+ * A duplicated exchange/commit implementation is how the popup and redirect
+ * lanes would silently drift apart on `state` validation, PKCE replay, or the
+ * session commit — so this suite mocks `completeOAuthCode` and proves each lane
+ * routes through it and performs no exchange of its own.
+ */
+
+jest.mock('../completeOAuthCode', () => ({
+  completeOAuthCode: jest.fn(),
+}));
+jest.mock('../../components/oauthNavigation', () => ({
+  redirectToAuthorize: jest.fn(),
+}));
+
+import type { OxyServices } from '@oxy.so/core';
+import {
+  OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
+  OXY_OAUTH_STATE_STORAGE_KEY,
+} from '@oxy.so/core';
+import { tryCompleteOAuthReturn } from '../../utils/oauthReturn';
+import { startWebOAuthSignIn, type WebOAuthTransportContext } from '../browserAuthTransport';
+import { completeOAuthCode } from '../completeOAuthCode';
+import { OXY_OAUTH_CODE_MESSAGE_TYPE } from '../oauthPopupMessages';
+import type { CompleteOAuthCodeInput } from '../completeOAuthCode';
+import type { OAuthPopupHandle } from '../types';
+
+const mockCompleteOAuthCode = completeOAuthCode as jest.Mock;
+
+const CLIENT_ID = 'oxy_dk_test';
+const REDIRECT_URI = 'https://mention.earth';
+const IDP_ORIGIN = 'https://auth.oxy.so';
+
+function fakePopup(): OAuthPopupHandle {
+  return { closed: false, close: jest.fn(), location: { href: '' } };
+}
+
+function makeContext(mode: 'popup' | 'redirect'): WebOAuthTransportContext & {
+  exchangeOAuthCode: jest.Mock;
+} {
+  const exchangeOAuthCode = jest.fn();
+  return {
+    mode,
+    oxyServices: { exchangeOAuthCode } as unknown as OxyServices,
+    clientId: CLIENT_ID,
+    authorizeBaseUrl: `${IDP_ORIGIN}/authorize`,
+    identityBound: false,
+    commitSession: jest.fn().mockResolvedValue(undefined),
+    exchangeOAuthCode,
+  };
+}
+
+async function waitForAuthorizeUrl(popup: OAuthPopupHandle): Promise<URL> {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (popup.location.href) return new URL(popup.location.href);
+    await new Promise((resolve) => {
+      setTimeout(resolve, 5);
+    });
+  }
+  throw new Error('the popup was never navigated to the authorize URL');
+}
+
+describe('shared OAuth completion path', () => {
+  beforeEach(() => {
+    mockCompleteOAuthCode.mockReset();
+    mockCompleteOAuthCode.mockResolvedValue({ ok: true });
+    globalThis.sessionStorage?.clear();
+    window.history.replaceState({}, '', '/');
+  });
+
+  it('the popup transport completes through completeOAuthCode with its in-memory handshake', async () => {
+    const context = makeContext('popup');
+    const popup = fakePopup();
+
+    const pending = startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI, popup });
+    const authorizeUrl = await waitForAuthorizeUrl(popup);
+    const state = authorizeUrl.searchParams.get('state');
+    const event = new Event('message');
+    Object.assign(event, {
+      data: { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'code-1', state },
+      origin: IDP_ORIGIN,
+      source: popup,
+    });
+    window.dispatchEvent(event);
+
+    await expect(pending).resolves.toEqual({ status: 'signed-in' });
+
+    expect(mockCompleteOAuthCode).toHaveBeenCalledTimes(1);
+    const input = mockCompleteOAuthCode.mock.calls[0][0] as CompleteOAuthCodeInput;
+    expect(input.code).toBe('code-1');
+    expect(input.clientId).toBe(CLIENT_ID);
+    expect(input.redirectUri).toBe(REDIRECT_URI);
+    expect(input.returnedState).toBe(state);
+    expect(input.handshake?.state).toBe(state);
+    expect(input.handshake?.codeVerifier).toEqual(expect.any(String));
+    // Nothing was persisted, so there is nothing for this lane to clean up.
+    expect(input.cleanup).toBeUndefined();
+    // The transport never exchanges the code itself.
+    expect(context.exchangeOAuthCode).not.toHaveBeenCalled();
+  });
+
+  it('the redirect return leg completes through completeOAuthCode with the persisted handshake', async () => {
+    const exchangeOAuthCode = jest.fn();
+    const oxyServices = { exchangeOAuthCode } as unknown as OxyServices;
+    sessionStorage.setItem(OXY_OAUTH_STATE_STORAGE_KEY, 'state-from-storage');
+    sessionStorage.setItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, 'verifier-from-storage');
+    window.history.replaceState({}, '', '/feed?code=code-2&state=state-from-storage');
+
+    await expect(
+      tryCompleteOAuthReturn({
+        oxyServices,
+        clientId: CLIENT_ID,
+        authRedirectUri: REDIRECT_URI,
+        commitSession: jest.fn().mockResolvedValue(undefined),
+      }),
+    ).resolves.toBe(true);
+
+    expect(mockCompleteOAuthCode).toHaveBeenCalledTimes(1);
+    const input = mockCompleteOAuthCode.mock.calls[0][0] as CompleteOAuthCodeInput;
+    expect(input.code).toBe('code-2');
+    expect(input.returnedState).toBe('state-from-storage');
+    expect(input.handshake).toEqual({
+      state: 'state-from-storage',
+      codeVerifier: 'verifier-from-storage',
+    });
+    expect(input.redirectUri).toBe(REDIRECT_URI);
+    // This lane DOES have persisted state + a dirty URL to clear.
+    expect(typeof input.cleanup).toBe('function');
+    // The return leg never exchanges the code itself.
+    expect(exchangeOAuthCode).not.toHaveBeenCalled();
+  });
+
+  it('reports the shared path failing rather than committing a session', async () => {
+    mockCompleteOAuthCode.mockResolvedValue({ ok: false, reason: 'state-mismatch' });
+    sessionStorage.setItem(OXY_OAUTH_STATE_STORAGE_KEY, 'state-from-storage');
+    sessionStorage.setItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, 'verifier-from-storage');
+    window.history.replaceState({}, '', '/?code=code-3&state=state-from-storage');
+
+    await expect(
+      tryCompleteOAuthReturn({
+        oxyServices: { exchangeOAuthCode: jest.fn() } as unknown as OxyServices,
+        clientId: CLIENT_ID,
+        commitSession: jest.fn().mockResolvedValue(undefined),
+      }),
+    ).resolves.toBe(false);
+  });
+
+  it('never reaches the shared path without a clientId', async () => {
+    window.history.replaceState({}, '', '/?code=code-4&state=state-from-storage');
+
+    await expect(
+      tryCompleteOAuthReturn({
+        oxyServices: { exchangeOAuthCode: jest.fn() } as unknown as OxyServices,
+        clientId: null,
+        commitSession: jest.fn().mockResolvedValue(undefined),
+      }),
+    ).resolves.toBe(false);
+    expect(mockCompleteOAuthCode).not.toHaveBeenCalled();
+  });
+
+  it('never reaches the shared path when the IdP returned an error instead of a code', async () => {
+    window.history.replaceState({}, '', '/?error=access_denied&state=state-from-storage');
+
+    await expect(
+      tryCompleteOAuthReturn({
+        oxyServices: { exchangeOAuthCode: jest.fn() } as unknown as OxyServices,
+        clientId: CLIENT_ID,
+        commitSession: jest.fn().mockResolvedValue(undefined),
+      }),
+    ).resolves.toBe(false);
+    expect(mockCompleteOAuthCode).not.toHaveBeenCalled();
+  });
+});

package/src/ui/oauth/browserAuthTransport.ts

@@ -0,0 +1,193 @@
+/**
+ * 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 '@oxy.so/core';
+import type { OxyServices } from '@oxy.so/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');
+  }
+
+  try {
+    const prepared = await prepareAuthorizeRequest({
+      clientId: context.clientId,
+      redirectUri: options.redirectUri,
+      authorizeBaseUrl: context.authorizeBaseUrl,
+      scope: options.scope,
+      responseMode: 'web_message',
+    });
+
+    if (!navigateOAuthPopup(popup, prepared.authorizeUrl)) {
+      return startRedirectSignIn(context, options, 'popup-navigation-failed');
+    }
+
+    const outcome = await awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: prepared.authorizeOrigin,
+      expectedState: prepared.handshake.state,
+      redirectUri: options.redirectUri,
+      ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    });
+
+    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' };
+    }
+  } finally {
+    // Covers throws after open (prepare/exchange/commit) and every settled outcome.
+    closeOAuthPopup(popup);
+  }
+}
+
+/**
+ * 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,
+    options.redirectUri,
+  )) {
+    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 '@oxy.so/core';
+import { logger } from '@oxy.so/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' };
+  }
+}