@oxyhq/services 22.12.4 → 22.12.7

package/src/ui/context/oxyContextTypes.ts

@@ -1,8 +1,10 @@
 import type { ReactNode } from 'react';
-import type { OxyServices, User, SessionLoginResponse, AccountNode, CreateAccountInput, ClientSession, AccountDialogController, AccountDialogView, ApiError, SessionClient } from '@oxyhq/core';
+import type { OxyServices, User, SessionLoginResponse, AccountNode, CreateAccountInput, ClientSession, AccountDialogController, AccountDialogView, ApiError, SessionClient, SessionMode } from '@oxyhq/core';
 import type { UseFollowHook } from '../hooks/useFollow.types';
 import type { useLanguageManagement } from '../hooks/useLanguageManagement';
 import type { RouteName } from '../navigation/routes';
+import type { StartWebOAuthSignInOptions } from '../oauth/browserAuthTransport';
+import type { WebAuthMode, WebOAuthSignInResult } from '../oauth/types';
 
 export interface OxyContextState {
   user: User | null;
@@ -26,6 +28,19 @@ export interface OxyContextState {
    */
   isAuthResolved: boolean;
   isStorageReady: boolean;
+  /**
+   * Who owns this provider's session (see `OxyProviderProps.sessionMode`).
+   *
+   * `'account'` — the device's active account; any app on the device can switch
+   * it and this client follows. `'identity'` — the owner of the local primary
+   * identity key, permanently: a sibling app's account switch never changes this
+   * client's user or bearer, and every account-graph mutation
+   * (`switchToAccount` / `switchSession`) rejects with `IdentityBoundSessionError`
+   * while `accounts` stays empty and the account dialog never opens.
+   */
+  sessionMode: SessionMode;
+  /** How web third-party sign-in reaches the IdP (see `OxyProviderProps.webAuthMode`). */
+  webAuthMode: WebAuthMode;
   error: string | null;
   /** Active UI locale (`language-REGION`): the account's primary locale when signed in, else the guest/device locale. */
   currentLanguage: string;
@@ -79,6 +94,24 @@ export interface OxyContextState {
   revokeSuspiciousSignIn: () => Promise<void>;
   handleWebSession: (session: SessionLoginResponse) => Promise<void>;
 
+  /**
+   * Run a WEB third-party OAuth sign-in (authorization code + PKCE) end to end
+   * using this provider's `webAuthMode`, and commit the resulting session.
+   *
+   * This is the shared operation `OxySignInButton` delegates to; RPs that ship
+   * their own button call it directly and never implement popup listeners, a
+   * token exchange, or `state` validation themselves. Returns a typed result —
+   * closing the popup and running out of time are values, not exceptions.
+   *
+   * In popup mode the window MUST be opened during the user's click: either
+   * call this synchronously from the press handler (it opens one itself), or
+   * call `openOAuthPopup()` there and pass the handle as `popup`.
+   *
+   * No-op outside a browser and in `sessionMode: 'identity'`, both of which
+   * resolve to `{ status: 'unsupported' }`.
+   */
+  startWebOAuthSignIn: (options: StartWebOAuthSignInOptions) => Promise<WebOAuthSignInResult>;
+
   logout: (targetSessionId?: string) => Promise<void>;
   logoutAll: () => Promise<void>;
   switchSession: (sessionId: string) => Promise<User>;
@@ -133,6 +166,17 @@ export interface OxyContextProviderProps {
   authorizeBaseUrl?: string;
   storageKeyPrefix?: string;
   clientId?: string;
+  /**
+   * Who owns this provider's session. See `OxyProviderProps.sessionMode` for the
+   * full contract.
+   * @default 'account'
+   */
+  sessionMode?: SessionMode;
+  /**
+   * Transport for WEB third-party sign-in. See `OxyProviderProps.webAuthMode`.
+   * @default 'redirect'
+   */
+  webAuthMode?: WebAuthMode;
   /** Sync device credentials to auth.oxy.so after interactive sign-in. @default true */
   hubSync?: boolean;
   onAuthStateChange?: (user: User | null) => void;

package/src/ui/context/useOxyAccountGraph.ts

@@ -6,12 +6,19 @@ import { useAuthStore } from '../stores/authStore';
 import { isUnauthorizedStatus } from './oxyContextHelpers';
 import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
 import { ASSET_DOWNLOAD_URLS_QUERY_KEY } from '../hooks/useResolvedFileUrls';
+import { IdentityBoundSessionError } from '../session';
 import type { CommitInput } from './oxyContextTypes';
 
 interface UseOxyAccountGraphParams {
   isAuthenticated: boolean;
   tokenReady: boolean;
   initialized: boolean;
+  /**
+   * `sessionMode: 'identity'`. The account graph is a switcher surface, and an
+   * identity-bound client authenticates as the owner of the local identity key —
+   * permanently. The graph is therefore never fetched and every switch rejects.
+   */
+  identityBound: boolean;
   oxyServices: OxyServices;
   sessionClient: SessionClient;
   syncFromClient: () => Promise<void>;
@@ -25,6 +32,7 @@ export function useOxyAccountGraph({
   isAuthenticated,
   tokenReady,
   initialized,
+  identityBound,
   oxyServices,
   sessionClient,
   syncFromClient,
@@ -36,7 +44,7 @@ export function useOxyAccountGraph({
   const [accounts, setAccounts] = useState<AccountNode[]>([]);
 
   const refreshAccounts = useCallback(async (): Promise<void> => {
-    if (!isAuthenticated || !tokenReady || !oxyServices.getAccessToken()) {
+    if (identityBound || !isAuthenticated || !tokenReady || !oxyServices.getAccessToken()) {
       setAccounts([]);
       return;
     }
@@ -53,14 +61,14 @@ export function useOxyAccountGraph({
         loggerUtil.debug('Failed to load accounts', { component: 'OxyContext' }, err as unknown);
       }
     }
-  }, [isAuthenticated, oxyServices, tokenReady, clearSessionStateRef]);
+  }, [identityBound, isAuthenticated, oxyServices, tokenReady, clearSessionStateRef]);
 
   useEffect(() => {
-    if (isAuthenticated && initialized && tokenReady) {
+    if (!identityBound && isAuthenticated && initialized && tokenReady) {
       refreshAccounts();
       void accountDialogControllerRef.current?.refresh();
     }
-  }, [isAuthenticated, initialized, tokenReady, refreshAccounts, accountDialogControllerRef]);
+  }, [identityBound, isAuthenticated, initialized, tokenReady, refreshAccounts, accountDialogControllerRef]);
 
   const runPostAccountSwitchSideEffects = useCallback(async (): Promise<void> => {
     resetSessionScopedStores();
@@ -74,6 +82,12 @@ export function useOxyAccountGraph({
 
   const switchToAccount = useCallback(
     async (accountId: string): Promise<void> => {
+      if (identityBound) {
+        // Loud rejection, never a silent no-op: a resolved promise here would
+        // read to the caller as a completed switch that simply left the user
+        // unchanged, which is exactly the confusion this mode must avoid.
+        throw new IdentityBoundSessionError('switchToAccount');
+      }
       const deviceState = sessionClient.getState();
       if (deviceState?.accounts.some((account) => account.accountId === accountId)) {
         await sessionClient.switchAccount(accountId);
@@ -102,7 +116,7 @@ export function useOxyAccountGraph({
       );
       await runPostAccountSwitchSideEffects();
     },
-    [oxyServices, sessionClient, syncFromClient, commitSession, runPostAccountSwitchSideEffects],
+    [identityBound, oxyServices, sessionClient, syncFromClient, commitSession, runPostAccountSwitchSideEffects],
   );
 
   const createAccount = useCallback(

package/src/ui/hooks/useSwitchableAccounts.ts

@@ -22,7 +22,18 @@ const EMPTY_SNAPSHOT: AccountDialogSnapshot = {
     loading: false,
     error: null,
     switchingAccountId: null,
-    signIn: { phase: 'idle', authorizeCode: null, qrPayload: null, expiresAt: null, error: null },
+    signIn: {
+        phase: 'idle',
+        authorizeCode: null,
+        qrPayload: null,
+        expiresAt: null,
+        error: null,
+        route: null,
+        routeFailed: false,
+        pushSentAt: null,
+        openedAt: null,
+        progress: 'idle',
+    },
     commonsAvailability: 'unknown',
 };
 

package/src/ui/index.ts

@@ -26,7 +26,6 @@ export { RequireOxyAuth } from './components/RequireOxyAuth';
 export type { RequireOxyAuthProps, RequireOxyAuthPrompt } from './components/RequireOxyAuth';
 export { default as FollowButton } from './components/FollowButton';
 export { default as OxyPayButton } from './components/OxyPayButton';
-export { FontLoader, setupFonts } from './components/FontLoader';
 export { default as ProfileButton } from './components/ProfileButton';
 
 // Context + hooks

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

@@ -0,0 +1,335 @@
+// The platform redirect is spied on so no real navigation happens and the
+// authorize URL each lane hands to the browser can be asserted.
+jest.mock('../../components/oauthNavigation', () => ({
+  redirectToAuthorize: jest.fn(),
+}));
+
+import type { OxyServices } from '@oxyhq/core';
+import {
+  computeCodeChallenge,
+  OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
+  OXY_OAUTH_STATE_STORAGE_KEY,
+} from '@oxyhq/core';
+import { redirectToAuthorize } from '../../components/oauthNavigation';
+import {
+  startWebOAuthSignIn,
+  type WebOAuthTransportContext,
+} from '../browserAuthTransport';
+import { OXY_OAUTH_CODE_MESSAGE_TYPE, OXY_OAUTH_ERROR_MESSAGE_TYPE } from '../oauthPopupMessages';
+import type { OAuthPopupHandle } from '../types';
+
+const mockRedirect = redirectToAuthorize as jest.Mock;
+
+const CLIENT_ID = 'oxy_dk_test';
+const REDIRECT_URI = 'https://mention.earth';
+const AUTHORIZE_BASE_URL = 'https://auth.oxy.so/authorize';
+const IDP_ORIGIN = 'https://auth.oxy.so';
+
+const SESSION = {
+  sessionId: 'sess-1',
+  deviceId: 'dev-1',
+  deviceSecret: 'secret-1',
+  accessToken: 'token-1',
+  expiresAt: '2099-01-01T00:00:00.000Z',
+  user: { id: 'user-1', username: 'nate' },
+};
+
+interface ControllablePopup extends OAuthPopupHandle {
+  close: jest.Mock;
+}
+
+function fakePopup(): ControllablePopup {
+  let closed = false;
+  return {
+    get closed() {
+      return closed;
+    },
+    close: jest.fn(() => {
+      closed = true;
+    }),
+    location: { href: '' },
+  };
+}
+
+function makeContext(
+  overrides: Partial<WebOAuthTransportContext> = {},
+): WebOAuthTransportContext & { exchangeOAuthCode: jest.Mock; commitSession: jest.Mock } {
+  const exchangeOAuthCode = jest.fn().mockResolvedValue(SESSION);
+  const commitSession = jest.fn().mockResolvedValue(undefined);
+  const base: WebOAuthTransportContext = {
+    mode: 'popup',
+    oxyServices: { exchangeOAuthCode } as unknown as OxyServices,
+    clientId: CLIENT_ID,
+    authorizeBaseUrl: AUTHORIZE_BASE_URL,
+    identityBound: false,
+    commitSession,
+  };
+  return { ...base, ...overrides, exchangeOAuthCode, commitSession };
+}
+
+/** Wait for the transport to finish preparing PKCE and navigate the popup. */
+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');
+}
+
+function dispatchFromPopup(data: unknown, source: unknown, origin = IDP_ORIGIN): void {
+  const event = new Event('message');
+  Object.assign(event, { data, origin, source });
+  window.dispatchEvent(event);
+}
+
+describe('startWebOAuthSignIn', () => {
+  beforeEach(() => {
+    mockRedirect.mockClear();
+    globalThis.sessionStorage?.clear();
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('popup mode', () => {
+    it('signs in without navigating the relying party', async () => {
+      const context = makeContext();
+      const popup = fakePopup();
+
+      const pending = startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI, popup });
+      const authorizeUrl = await waitForAuthorizeUrl(popup);
+
+      // The IdP is asked for the popup channel, with the standard PKCE binding.
+      expect(authorizeUrl.origin).toBe(IDP_ORIGIN);
+      expect(authorizeUrl.searchParams.get('response_mode')).toBe('web_message');
+      expect(authorizeUrl.searchParams.get('client_id')).toBe(CLIENT_ID);
+      expect(authorizeUrl.searchParams.get('redirect_uri')).toBe(REDIRECT_URI);
+      expect(authorizeUrl.searchParams.get('code_challenge_method')).toBe('S256');
+
+      const state = authorizeUrl.searchParams.get('state');
+      dispatchFromPopup(
+        { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'code-1', state },
+        popup,
+      );
+
+      await expect(pending).resolves.toEqual({ status: 'signed-in' });
+      expect(mockRedirect).not.toHaveBeenCalled();
+
+      // The verifier the main window replays is the one behind the challenge it
+      // sent — the popup never saw either.
+      const exchangeArgs = context.exchangeOAuthCode.mock.calls[0][0];
+      expect(exchangeArgs.code).toBe('code-1');
+      expect(exchangeArgs.redirectUri).toBe(REDIRECT_URI);
+      await expect(computeCodeChallenge(exchangeArgs.codeVerifier)).resolves.toBe(
+        authorizeUrl.searchParams.get('code_challenge'),
+      );
+
+      expect(context.commitSession).toHaveBeenCalledTimes(1);
+      // Nothing about the popup handshake is left in storage.
+      expect(sessionStorage.getItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY)).toBeNull();
+      expect(sessionStorage.getItem(OXY_OAUTH_STATE_STORAGE_KEY)).toBeNull();
+    });
+
+    it('opens the window itself when the caller did not pre-open one', async () => {
+      const context = makeContext();
+      const popup = fakePopup();
+      const openSpy = jest.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+
+      const pending = startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI });
+      const authorizeUrl = await waitForAuthorizeUrl(popup);
+      dispatchFromPopup(
+        {
+          type: OXY_OAUTH_CODE_MESSAGE_TYPE,
+          code: 'code-1',
+          state: authorizeUrl.searchParams.get('state'),
+        },
+        popup,
+      );
+
+      await expect(pending).resolves.toEqual({ status: 'signed-in' });
+      expect(openSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('falls back to a full-page redirect when the popup was blocked', async () => {
+      const context = makeContext();
+
+      const result = await startWebOAuthSignIn(context, {
+        redirectUri: REDIRECT_URI,
+        popup: null,
+      });
+
+      expect(result).toEqual({ status: 'redirecting', via: 'popup-blocked' });
+      expect(mockRedirect).toHaveBeenCalledTimes(1);
+      // The fallback is a plain redirect request — no popup channel.
+      const url = new URL(mockRedirect.mock.calls[0][0]);
+      expect(url.searchParams.get('response_mode')).toBeNull();
+      // …and its handshake survives the navigation.
+      expect(sessionStorage.getItem(OXY_OAUTH_STATE_STORAGE_KEY)).toBe(
+        url.searchParams.get('state'),
+      );
+      expect(sessionStorage.getItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY)).toBeTruthy();
+      expect(context.exchangeOAuthCode).not.toHaveBeenCalled();
+    });
+
+    it('falls back to a full-page redirect when the popup cannot be navigated', async () => {
+      const context = makeContext();
+      const deadPopup: OAuthPopupHandle = {
+        closed: false,
+        close: jest.fn(),
+        get location(): { href: string } {
+          throw new Error('window closed');
+        },
+      };
+
+      const result = await startWebOAuthSignIn(context, {
+        redirectUri: REDIRECT_URI,
+        popup: deadPopup,
+      });
+
+      expect(result).toEqual({ status: 'redirecting', via: 'popup-navigation-failed' });
+      expect(mockRedirect).toHaveBeenCalledTimes(1);
+    });
+
+    it('surfaces a typed IdP error and closes the window', async () => {
+      const context = makeContext();
+      const popup = fakePopup();
+
+      const pending = startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI, popup });
+      const authorizeUrl = await waitForAuthorizeUrl(popup);
+      dispatchFromPopup(
+        {
+          type: OXY_OAUTH_ERROR_MESSAGE_TYPE,
+          error: 'access_denied',
+          errorDescription: 'user declined',
+          state: authorizeUrl.searchParams.get('state'),
+        },
+        popup,
+      );
+
+      await expect(pending).resolves.toEqual({
+        status: 'failed',
+        reason: 'idp-error',
+        description: 'user declined',
+      });
+      expect(context.exchangeOAuthCode).not.toHaveBeenCalled();
+      expect(popup.close).toHaveBeenCalled();
+    });
+
+    it('refuses a result carrying the wrong state', async () => {
+      const context = makeContext();
+      const popup = fakePopup();
+
+      const pending = startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI, popup });
+      await waitForAuthorizeUrl(popup);
+      dispatchFromPopup(
+        { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'code-1', state: 'forged-state' },
+        popup,
+      );
+
+      await expect(pending).resolves.toEqual({ status: 'failed', reason: 'state-mismatch' });
+      expect(context.exchangeOAuthCode).not.toHaveBeenCalled();
+      expect(context.commitSession).not.toHaveBeenCalled();
+    });
+
+    it('reports a timeout when the popup never answers', async () => {
+      const context = makeContext();
+      const popup = fakePopup();
+
+      const result = await startWebOAuthSignIn(context, {
+        redirectUri: REDIRECT_URI,
+        popup,
+        timeoutMs: 20,
+      });
+
+      expect(result).toEqual({ status: 'timed-out' });
+      expect(popup.close).toHaveBeenCalled();
+      expect(context.exchangeOAuthCode).not.toHaveBeenCalled();
+    });
+
+    it('reports a failed exchange', async () => {
+      const context = makeContext();
+      context.exchangeOAuthCode.mockRejectedValue(new Error('invalid_grant'));
+      const popup = fakePopup();
+
+      const pending = startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI, popup });
+      const authorizeUrl = await waitForAuthorizeUrl(popup);
+      dispatchFromPopup(
+        {
+          type: OXY_OAUTH_CODE_MESSAGE_TYPE,
+          code: 'code-1',
+          state: authorizeUrl.searchParams.get('state'),
+        },
+        popup,
+      );
+
+      await expect(pending).resolves.toEqual({ status: 'failed', reason: 'exchange-failed' });
+      expect(context.commitSession).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('redirect mode', () => {
+    it('hands the top-level document to the IdP and persists the handshake', async () => {
+      const context = makeContext({ mode: 'redirect' });
+
+      const result = await startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI });
+
+      expect(result).toEqual({ status: 'redirecting', via: 'redirect-mode' });
+      expect(mockRedirect).toHaveBeenCalledTimes(1);
+      const url = new URL(mockRedirect.mock.calls[0][0]);
+      expect(url.searchParams.get('response_mode')).toBeNull();
+      expect(url.searchParams.get('client_id')).toBe(CLIENT_ID);
+      expect(sessionStorage.getItem(OXY_OAUTH_STATE_STORAGE_KEY)).toBe(
+        url.searchParams.get('state'),
+      );
+    });
+
+    it('never opens a window, even if one was handed to it', async () => {
+      const context = makeContext({ mode: 'redirect' });
+      const popup = fakePopup();
+      const openSpy = jest.spyOn(window, 'open');
+
+      await startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI, popup });
+
+      expect(openSpy).not.toHaveBeenCalled();
+      expect(popup.close).toHaveBeenCalledTimes(1);
+      expect(popup.location.href).toBe('');
+    });
+
+    it('aborts instead of redirecting when the handshake cannot be persisted', async () => {
+      const context = makeContext({ mode: 'redirect' });
+      jest.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+        throw new Error('storage is disabled');
+      });
+
+      const result = await startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI });
+
+      expect(result).toEqual({ status: 'failed', reason: 'handshake-storage' });
+      expect(mockRedirect).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('inapplicable configurations', () => {
+    it('refuses an identity-bound provider and closes any popup it was given', async () => {
+      const context = makeContext({ identityBound: true });
+      const popup = fakePopup();
+
+      const result = await startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI, popup });
+
+      expect(result).toEqual({ status: 'unsupported', reason: 'identity-bound' });
+      expect(popup.close).toHaveBeenCalledTimes(1);
+      expect(mockRedirect).not.toHaveBeenCalled();
+    });
+
+    it('refuses a provider with no clientId', async () => {
+      const context = makeContext({ clientId: null });
+
+      const result = await startWebOAuthSignIn(context, { redirectUri: REDIRECT_URI });
+
+      expect(result).toEqual({ status: 'unsupported', reason: 'missing-client-id' });
+      expect(mockRedirect).not.toHaveBeenCalled();
+    });
+  });
+});

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

@@ -0,0 +1,142 @@
+import type { OxyServices } from '@oxyhq/core';
+import { completeOAuthCode } from '../completeOAuthCode';
+import type { OAuthSessionCommitInput } from '../types';
+
+const HANDSHAKE = { state: 'state-abc', codeVerifier: 'verifier-xyz' };
+const REDIRECT_URI = 'https://mention.earth';
+
+const SESSION = {
+  sessionId: 'sess-1',
+  deviceId: 'dev-1',
+  deviceSecret: 'secret-1',
+  accessToken: 'token-1',
+  expiresAt: '2099-01-01T00:00:00.000Z',
+  user: { id: 'user-1', username: 'nate', avatar: 'a1' },
+};
+
+function makeOxyServices(exchange: jest.Mock): OxyServices {
+  return { exchangeOAuthCode: exchange } as unknown as OxyServices;
+}
+
+describe('completeOAuthCode', () => {
+  it('exchanges the code and commits the session it returns', async () => {
+    const exchange = jest.fn().mockResolvedValue(SESSION);
+    const committed: OAuthSessionCommitInput[] = [];
+
+    const result = await completeOAuthCode({
+      oxyServices: makeOxyServices(exchange),
+      clientId: 'oxy_dk_test',
+      code: 'code-1',
+      returnedState: HANDSHAKE.state,
+      handshake: HANDSHAKE,
+      redirectUri: REDIRECT_URI,
+      commitSession: async (input) => {
+        committed.push(input);
+      },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(exchange).toHaveBeenCalledWith({
+      code: 'code-1',
+      clientId: 'oxy_dk_test',
+      redirectUri: REDIRECT_URI,
+      codeVerifier: HANDSHAKE.codeVerifier,
+    });
+    expect(committed).toEqual([
+      {
+        sessionId: 'sess-1',
+        accessToken: 'token-1',
+        deviceId: 'dev-1',
+        deviceSecret: 'secret-1',
+        userId: 'user-1',
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        user: SESSION.user,
+      },
+    ]);
+  });
+
+  it('cleans up BEFORE committing, so a stale code cannot re-enter the exchange', async () => {
+    const order: string[] = [];
+    const result = await completeOAuthCode({
+      oxyServices: makeOxyServices(jest.fn().mockResolvedValue(SESSION)),
+      clientId: 'oxy_dk_test',
+      code: 'code-1',
+      returnedState: HANDSHAKE.state,
+      handshake: HANDSHAKE,
+      redirectUri: REDIRECT_URI,
+      commitSession: async () => {
+        order.push('commit');
+      },
+      cleanup: () => {
+        order.push('cleanup');
+      },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(order).toEqual(['cleanup', 'commit']);
+  });
+
+  it.each([
+    ['a mismatched state', 'someone-elses-state', HANDSHAKE],
+    ['no returned state', null, HANDSHAKE],
+    ['no stored handshake', HANDSHAKE.state, null],
+  ])('refuses to exchange the code with %s', async (_label, returnedState, handshake) => {
+    const exchange = jest.fn();
+    const commitSession = jest.fn();
+    const cleanup = jest.fn();
+
+    const result = await completeOAuthCode({
+      oxyServices: makeOxyServices(exchange),
+      clientId: 'oxy_dk_test',
+      code: 'code-1',
+      returnedState,
+      handshake,
+      redirectUri: REDIRECT_URI,
+      commitSession,
+      cleanup,
+    });
+
+    expect(result).toEqual({ ok: false, reason: 'state-mismatch' });
+    expect(exchange).not.toHaveBeenCalled();
+    expect(commitSession).not.toHaveBeenCalled();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports a failed exchange without throwing, and still cleans up', async () => {
+    const cleanup = jest.fn();
+    const commitSession = jest.fn();
+
+    const result = await completeOAuthCode({
+      oxyServices: makeOxyServices(jest.fn().mockRejectedValue(new Error('invalid_grant'))),
+      clientId: 'oxy_dk_test',
+      code: 'code-1',
+      returnedState: HANDSHAKE.state,
+      handshake: HANDSHAKE,
+      redirectUri: REDIRECT_URI,
+      commitSession,
+      cleanup,
+    });
+
+    expect(result).toEqual({ ok: false, reason: 'exchange-failed' });
+    expect(commitSession).not.toHaveBeenCalled();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports a failed commit without throwing, and cleans up exactly once', async () => {
+    const cleanup = jest.fn();
+
+    const result = await completeOAuthCode({
+      oxyServices: makeOxyServices(jest.fn().mockResolvedValue(SESSION)),
+      clientId: 'oxy_dk_test',
+      code: 'code-1',
+      returnedState: HANDSHAKE.state,
+      handshake: HANDSHAKE,
+      redirectUri: REDIRECT_URI,
+      commitSession: jest.fn().mockRejectedValue(new Error('commit blew up')),
+      cleanup,
+    });
+
+    expect(result).toEqual({ ok: false, reason: 'exchange-failed' });
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+});