@oxyhq/services 22.12.4 → 22.12.7

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

@@ -0,0 +1,326 @@
+import {
+  awaitOAuthPopupResult,
+  closeOAuthPopup,
+  navigateOAuthPopup,
+  openOAuthPopup,
+  OXY_OAUTH_POPUP_WINDOW_NAME,
+} from '../oauthPopup';
+import { OXY_OAUTH_CODE_MESSAGE_TYPE, OXY_OAUTH_ERROR_MESSAGE_TYPE } from '../oauthPopupMessages';
+import type { OAuthPopupHandle, OAuthPopupOutcome } from '../types';
+
+const IDP_ORIGIN = 'https://auth.oxy.so';
+const STATE = 'state-abc';
+
+interface ControllablePopup extends OAuthPopupHandle {
+  close: jest.Mock;
+  setClosed: () => void;
+}
+
+function fakePopup(): ControllablePopup {
+  let closed = false;
+  return {
+    get closed() {
+      return closed;
+    },
+    close: jest.fn(() => {
+      closed = true;
+    }),
+    location: { href: '' },
+    setClosed: () => {
+      closed = true;
+    },
+  };
+}
+
+function dispatchMessage(init: { data: unknown; origin: string; source: unknown }): void {
+  const event = new Event('message');
+  Object.assign(event, init);
+  window.dispatchEvent(event);
+}
+
+function codeMessage(source: unknown, state = STATE, origin = IDP_ORIGIN) {
+  return {
+    data: { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'code-1', state },
+    origin,
+    source,
+  };
+}
+
+/** Resolve the outcome, or `'pending'` when the promise has not settled yet. */
+async function outcomeOrPending(
+  promise: Promise<OAuthPopupOutcome>,
+): Promise<OAuthPopupOutcome | 'pending'> {
+  return Promise.race([
+    promise,
+    Promise.resolve().then(() => 'pending' as const),
+  ]);
+}
+
+describe('openOAuthPopup', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('opens an empty, named window so a second press reuses it', () => {
+    const handle = fakePopup();
+    const openSpy = jest
+      .spyOn(window, 'open')
+      .mockReturnValue(handle as unknown as Window);
+
+    expect(openOAuthPopup()).toBe(handle);
+    expect(openSpy).toHaveBeenCalledWith('', OXY_OAUTH_POPUP_WINDOW_NAME, expect.any(String));
+    // The window is navigated later, once the authorize URL exists.
+    expect(openSpy.mock.calls[0][0]).toBe('');
+  });
+
+  it('returns null when the browser blocks the popup', () => {
+    jest.spyOn(window, 'open').mockReturnValue(null);
+    expect(openOAuthPopup()).toBeNull();
+  });
+
+  it('returns null instead of throwing when window.open throws', () => {
+    jest.spyOn(window, 'open').mockImplementation(() => {
+      throw new Error('blocked');
+    });
+    expect(openOAuthPopup()).toBeNull();
+  });
+});
+
+describe('navigateOAuthPopup', () => {
+  it('points the popup at the authorize URL', () => {
+    const popup = fakePopup();
+    expect(navigateOAuthPopup(popup, `${IDP_ORIGIN}/authorize?x=1`)).toBe(true);
+    expect(popup.location.href).toBe(`${IDP_ORIGIN}/authorize?x=1`);
+  });
+
+  it('reports failure instead of throwing when the window is gone', () => {
+    const popup: OAuthPopupHandle = {
+      closed: true,
+      close: () => undefined,
+      get location(): { href: string } {
+        throw new Error('window closed');
+      },
+    };
+    expect(navigateOAuthPopup(popup, `${IDP_ORIGIN}/authorize`)).toBe(false);
+  });
+});
+
+describe('closeOAuthPopup', () => {
+  it('is a no-op for null and for an already-closed window', () => {
+    expect(() => closeOAuthPopup(null)).not.toThrow();
+    const popup = fakePopup();
+    popup.setClosed();
+    closeOAuthPopup(popup);
+    expect(popup.close).not.toHaveBeenCalled();
+  });
+
+  it('closes an open window and swallows a close that throws', () => {
+    const popup = fakePopup();
+    closeOAuthPopup(popup);
+    expect(popup.close).toHaveBeenCalledTimes(1);
+
+    const hostile: OAuthPopupHandle = {
+      closed: false,
+      close: () => {
+        throw new Error('denied');
+      },
+      location: { href: '' },
+    };
+    expect(() => closeOAuthPopup(hostile)).not.toThrow();
+  });
+});
+
+describe('awaitOAuthPopupResult', () => {
+  let addSpy: jest.SpyInstance;
+  let removeSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    addSpy = jest.spyOn(window, 'addEventListener');
+    removeSpy = jest.spyOn(window, 'removeEventListener');
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  /** Every exit path must leave zero listeners and zero timers behind. */
+  function expectFullCleanup(): void {
+    const registered = addSpy.mock.calls.filter(([type]) => type === 'message');
+    const removed = removeSpy.mock.calls.filter(([type]) => type === 'message');
+    expect(registered).toHaveLength(1);
+    expect(removed).toHaveLength(1);
+    expect(removed[0][1]).toBe(registered[0][1]);
+    expect(jest.getTimerCount()).toBe(0);
+  }
+
+  it('resolves with the authorization code on a valid message', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+    });
+
+    dispatchMessage(codeMessage(popup));
+
+    await expect(promise).resolves.toEqual({ kind: 'code', code: 'code-1', state: STATE });
+    expectFullCleanup();
+  });
+
+  it('resolves with a typed IdP error', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+    });
+
+    dispatchMessage({
+      data: {
+        type: OXY_OAUTH_ERROR_MESSAGE_TYPE,
+        error: 'access_denied',
+        errorDescription: 'user declined',
+        state: STATE,
+      },
+      origin: IDP_ORIGIN,
+      source: popup,
+    });
+
+    await expect(promise).resolves.toEqual({
+      kind: 'oauth-error',
+      error: 'access_denied',
+      errorDescription: 'user declined',
+    });
+    expectFullCleanup();
+  });
+
+  it('resolves with a state mismatch when our popup answers another request', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+    });
+
+    dispatchMessage(codeMessage(popup, 'a-different-state'));
+
+    await expect(promise).resolves.toEqual({ kind: 'state-mismatch' });
+    expectFullCleanup();
+  });
+
+  it.each([
+    ['a foreign origin', () => codeMessage(fakePopup(), STATE, 'https://evil.example')],
+    ['a foreign window', () => codeMessage(fakePopup())],
+  ])('keeps waiting after a message from %s', async (_label, build) => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+      timeoutMs: 60_000,
+    });
+
+    dispatchMessage(build());
+    expect(await outcomeOrPending(promise)).toBe('pending');
+
+    // The real popup can still complete the flow afterwards.
+    dispatchMessage(codeMessage(popup));
+    await expect(promise).resolves.toEqual({ kind: 'code', code: 'code-1', state: STATE });
+    expectFullCleanup();
+  });
+
+  it('keeps waiting after a malformed payload from the real popup', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+      timeoutMs: 60_000,
+    });
+
+    dispatchMessage({ data: { type: 'oxy:oauth:code' }, origin: IDP_ORIGIN, source: popup });
+    expect(await outcomeOrPending(promise)).toBe('pending');
+
+    dispatchMessage(codeMessage(popup));
+    await expect(promise).resolves.toEqual({ kind: 'code', code: 'code-1', state: STATE });
+    expectFullCleanup();
+  });
+
+  it('ignores a duplicate result: the first message wins and the listener is gone', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+    });
+
+    dispatchMessage(codeMessage(popup));
+    await expect(promise).resolves.toEqual({ kind: 'code', code: 'code-1', state: STATE });
+
+    // A late redelivery (or a second, contradicting message) reaches nothing.
+    expect(() =>
+      dispatchMessage({
+        data: { type: OXY_OAUTH_ERROR_MESSAGE_TYPE, error: 'access_denied', state: STATE },
+        origin: IDP_ORIGIN,
+        source: popup,
+      }),
+    ).not.toThrow();
+    await expect(promise).resolves.toEqual({ kind: 'code', code: 'code-1', state: STATE });
+    expectFullCleanup();
+  });
+
+  it('reports cancellation once the user closes the window', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+    });
+
+    popup.setClosed();
+    jest.advanceTimersByTime(1000);
+    // The close is not reported instantly: an already-queued message may still win.
+    expect(await outcomeOrPending(promise)).toBe('pending');
+
+    jest.advanceTimersByTime(400);
+    await expect(promise).resolves.toEqual({ kind: 'closed' });
+    expectFullCleanup();
+  });
+
+  it('lets a result that arrived just before the close win the race', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+    });
+
+    // The IdP posts its result and immediately closes itself.
+    popup.setClosed();
+    jest.advanceTimersByTime(1000);
+    dispatchMessage(codeMessage(popup));
+    jest.advanceTimersByTime(1000);
+
+    await expect(promise).resolves.toEqual({ kind: 'code', code: 'code-1', state: STATE });
+    expectFullCleanup();
+  });
+
+  it('times out when nothing ever answers', async () => {
+    const popup = fakePopup();
+    const promise = awaitOAuthPopupResult({
+      popup,
+      expectedOrigin: IDP_ORIGIN,
+      expectedState: STATE,
+      timeoutMs: 30_000,
+    });
+
+    jest.advanceTimersByTime(29_999);
+    expect(await outcomeOrPending(promise)).toBe('pending');
+
+    jest.advanceTimersByTime(1);
+    await expect(promise).resolves.toEqual({ kind: 'timed-out' });
+    expectFullCleanup();
+  });
+});

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

@@ -0,0 +1,189 @@
+import {
+  OXY_OAUTH_CODE_MESSAGE_TYPE,
+  OXY_OAUTH_ERROR_MESSAGE_TYPE,
+  parseOAuthPopupMessage,
+  readOAuthPopupMessage,
+} from '../oauthPopupMessages';
+import type { OAuthPopupHandle } from '../types';
+
+const IDP_ORIGIN = 'https://auth.oxy.so';
+const STATE = 'state-abc';
+
+/** A stand-in for the popup `Window`; identity is all the validator compares. */
+function fakePopup(): OAuthPopupHandle {
+  return { closed: false, close: () => undefined, location: { href: '' } };
+}
+
+/**
+ * Build a `message` event with attacker-controllable fields. jsdom's
+ * `MessageEvent` constructor refuses a non-`Window` `source`, so the event is
+ * assembled the way the browser hands it to the listener instead.
+ */
+function makeMessageEvent(init: {
+  data: unknown;
+  origin: string;
+  source: unknown;
+}): MessageEvent {
+  const event = new Event('message');
+  Object.assign(event, init);
+  return event as MessageEvent;
+}
+
+describe('parseOAuthPopupMessage', () => {
+  it('accepts a well-formed code message', () => {
+    expect(
+      parseOAuthPopupMessage({ type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c1', state: STATE }),
+    ).toEqual({ type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c1', state: STATE });
+  });
+
+  it('accepts a well-formed error message and its optional fields', () => {
+    expect(
+      parseOAuthPopupMessage({
+        type: OXY_OAUTH_ERROR_MESSAGE_TYPE,
+        error: 'access_denied',
+        errorDescription: 'user said no',
+        state: STATE,
+      }),
+    ).toEqual({
+      type: OXY_OAUTH_ERROR_MESSAGE_TYPE,
+      error: 'access_denied',
+      errorDescription: 'user said no',
+      state: STATE,
+    });
+  });
+
+  it('drops optional error fields that are not non-empty strings', () => {
+    expect(
+      parseOAuthPopupMessage({
+        type: OXY_OAUTH_ERROR_MESSAGE_TYPE,
+        error: 'server_error',
+        errorDescription: 42,
+        state: '',
+      }),
+    ).toEqual({ type: OXY_OAUTH_ERROR_MESSAGE_TYPE, error: 'server_error' });
+  });
+
+  it('never surfaces extra properties a sender smuggled in', () => {
+    const parsed = parseOAuthPopupMessage({
+      type: OXY_OAUTH_CODE_MESSAGE_TYPE,
+      code: 'c1',
+      state: STATE,
+      accessToken: 'leaked',
+      deviceSecret: 'leaked',
+    });
+    expect(parsed).toEqual({ type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c1', state: STATE });
+  });
+
+  it.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['a string', 'oxy:oauth:code'],
+    ['a number', 7],
+    ['an array', [{ type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c', state: STATE }]],
+    ['an unknown type', { type: 'oxy:oauth:token', code: 'c', state: STATE }],
+    ['a code message with no code', { type: OXY_OAUTH_CODE_MESSAGE_TYPE, state: STATE }],
+    ['a code message with an empty code', { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: '', state: STATE }],
+    ['a code message with no state', { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c' }],
+    ['a code message with a non-string code', { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 1, state: STATE }],
+    ['an error message with no error', { type: OXY_OAUTH_ERROR_MESSAGE_TYPE, state: STATE }],
+  ])('rejects %s', (_label, data) => {
+    expect(parseOAuthPopupMessage(data)).toBeNull();
+  });
+});
+
+describe('readOAuthPopupMessage', () => {
+  const popup = fakePopup();
+  const context = { expectedOrigin: IDP_ORIGIN, expectedState: STATE, popup };
+
+  it('returns the code when origin, source, shape and state all match', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({
+        data: { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c1', state: STATE },
+        origin: IDP_ORIGIN,
+        source: popup,
+      }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'code', code: 'c1', state: STATE });
+  });
+
+  it('ignores a message from another origin, even with a valid payload', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({
+        data: { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'evil', state: STATE },
+        origin: 'https://evil.example',
+        source: popup,
+      }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'ignore' });
+  });
+
+  it('ignores a message from a window that is not the popup we opened', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({
+        data: { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'evil', state: STATE },
+        origin: IDP_ORIGIN,
+        source: fakePopup(),
+      }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'ignore' });
+  });
+
+  it('ignores a message with no source at all', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({
+        data: { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c1', state: STATE },
+        origin: IDP_ORIGIN,
+        source: null,
+      }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'ignore' });
+  });
+
+  it('ignores a malformed payload from the real popup', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({ data: { hello: 'world' }, origin: IDP_ORIGIN, source: popup }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'ignore' });
+  });
+
+  it('reports a state mismatch on a code message bound to another request', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({
+        data: { type: OXY_OAUTH_CODE_MESSAGE_TYPE, code: 'c1', state: 'other-state' },
+        origin: IDP_ORIGIN,
+        source: popup,
+      }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'state-mismatch' });
+  });
+
+  it('accepts an error message that carries no state', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({
+        data: { type: OXY_OAUTH_ERROR_MESSAGE_TYPE, error: 'access_denied' },
+        origin: IDP_ORIGIN,
+        source: popup,
+      }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'oauth-error', error: 'access_denied' });
+  });
+
+  it('reports a state mismatch on an error message bound to another request', () => {
+    const verdict = readOAuthPopupMessage(
+      makeMessageEvent({
+        data: { type: OXY_OAUTH_ERROR_MESSAGE_TYPE, error: 'access_denied', state: 'other' },
+        origin: IDP_ORIGIN,
+        source: popup,
+      }),
+      context,
+    );
+    expect(verdict).toEqual({ kind: 'state-mismatch' });
+  });
+});

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 '@oxyhq/core';
+import {
+  OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
+  OXY_OAUTH_STATE_STORAGE_KEY,
+} from '@oxyhq/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();
+  });
+});