@oxy.so/services 6.2.0 → 8.1.0

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

@@ -0,0 +1,198 @@
+/**
+ * The browser bridge, the app half (ADR 0029 D2): the window opens from the
+ * press, carries a PKCE-bound request, accepts only its own answer, joins, and
+ * always closes.
+ */
+import { createHash } from 'node:crypto';
+import { OxyServices } from '@oxy.so/core';
+import {
+  OXY_BRIDGE_CODE_MESSAGE_TYPE,
+  OXY_BRIDGE_ERROR_MESSAGE_TYPE,
+  OXY_BRIDGE_WINDOW_NAME,
+  openBridgeWindow,
+  readBridgeMessage,
+  resolveBridgeOrigin,
+  runBrowserBridge,
+} from '../browserBridge';
+import { trackDeviceCredential } from '../../session/deviceCredentialTracker';
+import type { OAuthPopupHandle } from '../types';
+
+const AUTH = 'https://auth.oxy.so';
+const APP = 'https://mention.earth';
+
+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 dispatchMessage(init: { data: unknown; origin: string; source: unknown }): void {
+  const event = new Event('message');
+  Object.assign(event, init);
+  window.dispatchEvent(event);
+}
+
+/** Wait until the popup has been navigated to the bridge, and read its query. */
+async function navigated(popup: OAuthPopupHandle): Promise<URL> {
+  for (let i = 0; i < 100 && !popup.location.href; i += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  return new URL(popup.location.href);
+}
+
+afterEach(() => jest.restoreAllMocks());
+
+describe('resolveBridgeOrigin', () => {
+  it('is auth.oxy.so by default and follows an authorize override', () => {
+    expect(resolveBridgeOrigin()).toBe(AUTH);
+    expect(resolveBridgeOrigin('http://localhost:8105/authorize')).toBe('http://localhost:8105');
+    expect(resolveBridgeOrigin('not a url')).toBeNull();
+  });
+});
+
+describe('openBridgeWindow', () => {
+  it('opens an empty, tiny, separately named window', () => {
+    const handle = fakePopup();
+    const open = jest.spyOn(window, 'open').mockReturnValue(handle as unknown as Window);
+    expect(openBridgeWindow()).toBe(handle);
+    expect(open).toHaveBeenCalledWith('', OXY_BRIDGE_WINDOW_NAME, expect.stringContaining('width=1,height=1'));
+  });
+
+  it('is null when blocked or when open throws', () => {
+    jest.spyOn(window, 'open').mockReturnValue(null);
+    expect(openBridgeWindow()).toBeNull();
+    jest.spyOn(window, 'open').mockImplementation(() => {
+      throw new Error('blocked');
+    });
+    expect(openBridgeWindow()).toBeNull();
+  });
+});
+
+describe('readBridgeMessage', () => {
+  const popup = fakePopup();
+  const context = { expectedOrigin: AUTH, expectedState: 'st', popup };
+  const code = { type: OXY_BRIDGE_CODE_MESSAGE_TYPE, code: 'c1', state: 'st' };
+
+  it('accepts only its own window, origin and state', () => {
+    expect(readBridgeMessage({ origin: AUTH, source: popup as never, data: code }, context)).toEqual({ kind: 'code', code: 'c1' });
+    expect(readBridgeMessage({ origin: 'https://evil.example', source: popup as never, data: code }, context).kind).toBe('ignore');
+    expect(readBridgeMessage({ origin: AUTH, source: fakePopup() as never, data: code }, context).kind).toBe('ignore');
+    expect(readBridgeMessage({ origin: AUTH, source: popup as never, data: { ...code, state: 'other' } }, context).kind).toBe('ignore');
+    expect(readBridgeMessage({ origin: AUTH, source: popup as never, data: 'nope' }, context).kind).toBe('ignore');
+    expect(
+      readBridgeMessage(
+        { origin: AUTH, source: popup as never, data: { type: OXY_BRIDGE_ERROR_MESSAGE_TYPE, error: 'x', state: 'st' } },
+        context,
+      ),
+    ).toEqual({ kind: 'error', error: 'x' });
+  });
+});
+
+describe('runBrowserBridge', () => {
+  it('navigates with a PKCE-bound request, joins with the verifier, and closes', async () => {
+    const oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    const join = jest.spyOn(oxy.devices, 'joinBrowser').mockResolvedValue({ deviceId: 'dev-1', deviceSecret: 'app-secret' });
+    const popup = fakePopup();
+
+    const result = runBrowserBridge({ popup, bridgeOrigin: AUTH, oxyServices: oxy, clientId: 'oxy_dk_1', redirectUri: APP });
+    const url = await navigated(popup);
+    expect(url.origin + url.pathname).toBe(`${AUTH}/bridge`);
+    expect(url.searchParams.get('client_id')).toBe('oxy_dk_1');
+    expect(url.searchParams.get('redirect_uri')).toBe(APP);
+    expect(url.searchParams.get('code_challenge_method')).toBe('S256');
+    const state = url.searchParams.get('state');
+    const challenge = url.searchParams.get('code_challenge');
+
+    dispatchMessage({ origin: 'https://evil.example', source: popup, data: { type: OXY_BRIDGE_CODE_MESSAGE_TYPE, code: 'forged', state } });
+    dispatchMessage({ origin: AUTH, source: popup, data: { type: OXY_BRIDGE_CODE_MESSAGE_TYPE, code: 'code-1', state } });
+
+    expect(await result).toEqual({ ok: true, deviceId: 'dev-1', deviceSecret: 'app-secret' });
+    const [request] = join.mock.calls[0];
+    expect(request.code).toBe('code-1');
+    expect(request.clientId).toBe('oxy_dk_1');
+    expect(request.redirectUri).toBe(APP);
+    // The verifier is the one whose S256 digest was sent as the challenge.
+    expect(createHash('sha256').update(request.codeVerifier).digest('base64url')).toBe(challenge);
+    expect(popup.close).toHaveBeenCalled();
+  });
+
+  it('reports a bridge error, a closed window and a timeout, closing the window each time', async () => {
+    const oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    const join = jest.spyOn(oxy.devices, 'joinBrowser');
+
+    let popup = fakePopup();
+    let result = runBrowserBridge({ popup, bridgeOrigin: AUTH, oxyServices: oxy, clientId: 'c', redirectUri: APP });
+    let state = (await navigated(popup)).searchParams.get('state');
+    dispatchMessage({ origin: AUTH, source: popup, data: { type: OXY_BRIDGE_ERROR_MESSAGE_TYPE, error: 'invalid_client', state } });
+    expect(await result).toEqual({ ok: false, reason: 'bridge-error' });
+    expect(popup.close).toHaveBeenCalled();
+
+    popup = fakePopup();
+    result = runBrowserBridge({ popup, bridgeOrigin: AUTH, oxyServices: oxy, clientId: 'c', redirectUri: APP });
+    await navigated(popup);
+    popup.close();
+    expect(await result).toEqual({ ok: false, reason: 'closed' });
+
+    popup = fakePopup();
+    result = runBrowserBridge({ popup, bridgeOrigin: AUTH, oxyServices: oxy, clientId: 'c', redirectUri: APP, timeoutMs: 50 });
+    state = (await navigated(popup)).searchParams.get('state');
+    expect(state).toBeTruthy();
+    expect(await result).toEqual({ ok: false, reason: 'timed-out' });
+    expect(popup.close).toHaveBeenCalled();
+    expect(join).not.toHaveBeenCalled();
+  });
+
+  it('a failed join is a failed bridge, never a thrown error', async () => {
+    const oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    jest.spyOn(oxy.devices, 'joinBrowser').mockRejectedValue(new Error('invalid_grant'));
+    const popup = fakePopup();
+    const result = runBrowserBridge({ popup, bridgeOrigin: AUTH, oxyServices: oxy, clientId: 'c', redirectUri: APP });
+    const state = (await navigated(popup)).searchParams.get('state');
+    dispatchMessage({ origin: AUTH, source: popup, data: { type: OXY_BRIDGE_CODE_MESSAGE_TYPE, code: 'code-1', state } });
+    expect(await result).toEqual({ ok: false, reason: 'join-failed' });
+  });
+});
+
+describe('trackDeviceCredential', () => {
+  it('knows the held credential synchronously once the store has been read', async () => {
+    let stored: { sessionId: string; userId: string; deviceId?: string; deviceSecret?: string } | null = null;
+    const store = trackDeviceCredential({
+      load: async () => stored,
+      save: async (state) => {
+        stored = state;
+        return true;
+      },
+      clear: async () => {
+        stored = null;
+      },
+    });
+    expect(store.heldDeviceCredential()).toBeUndefined();
+    await store.load();
+    expect(store.heldDeviceCredential()).toBeNull();
+    await store.save({ sessionId: '', userId: '', deviceId: 'd', deviceSecret: 's' });
+    expect(store.heldDeviceCredential()).toEqual({ deviceId: 'd', deviceSecret: 's' });
+    await store.clear();
+    expect(store.heldDeviceCredential()).toBeNull();
+  });
+});
+
+describe('hasPersistedSessionCredential', () => {
+  it('a credential without an account cannot bring a lost session back', async () => {
+    const { hasPersistedSessionCredential } = await import('../../utils/deviceCredential');
+    const store = (state: unknown) => ({ load: async () => state, save: async () => true, clear: async () => undefined }) as never;
+    expect(await hasPersistedSessionCredential(store({ sessionId: 's', userId: 'u', deviceId: 'd', deviceSecret: 'x' }))).toBe(true);
+    expect(await hasPersistedSessionCredential(store({ sessionId: '', userId: '', deviceId: 'd', deviceSecret: 'x' }))).toBe(false);
+    expect(await hasPersistedSessionCredential(store(null))).toBe(false);
+  });
+});

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

@@ -15,7 +15,7 @@ const SESSION = {
 };
 
 function makeOxyServices(exchange: jest.Mock): OxyServices {
-  return { exchangeOAuthCode: exchange } as unknown as OxyServices;
+  return { auth: { oauth: { exchangeCode: exchange } } } as unknown as OxyServices;
 }
 
 describe('completeOAuthCode', () => {

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

@@ -44,16 +44,16 @@ function makeContext(
 		platform,
 		mode: "popup",
 		oxyServices: {
-			getPublicApplication,
-			exchangeOAuthCode,
+			apps: { getPublic: getPublicApplication },
+			auth: { oauth: { exchangeCode: exchangeOAuthCode } },
 		} as unknown as OxyServices,
 		clientId: CLIENT_ID,
 		identityBound: false,
 		expectedUserId: USER_ID,
 		commitSession,
 		...overrides,
-		getPublicApplication,
-		exchangeOAuthCode,
+		apps: { getPublic: getPublicApplication },
+		auth: { oauth: { exchangeCode: exchangeOAuthCode } },
 	};
 }
 
@@ -148,7 +148,7 @@ describe("requestOAuthConsent", () => {
 		expect(authorizeUrl?.searchParams.get("code_challenge_method")).toBe(
 			"S256",
 		);
-		const exchange = context.exchangeOAuthCode.mock.calls[0][0];
+		const exchange = context.auth.oauth.exchangeCode.mock.calls[0][0];
 		await expect(computeCodeChallenge(exchange.codeVerifier)).resolves.toBe(
 			authorizeUrl?.searchParams.get("code_challenge"),
 		);
@@ -167,7 +167,7 @@ describe("requestOAuthConsent", () => {
 				scopes: EXACT_SCOPES,
 			}),
 		).resolves.toEqual({ status: "failed", reason: "native-callback-invalid" });
-		expect(wrongTarget.exchangeOAuthCode).not.toHaveBeenCalled();
+		expect(wrongTarget.auth.oauth.exchangeCode).not.toHaveBeenCalled();
 
 		const wrongState = makeContext("native");
 		openNative.mockResolvedValueOnce({
@@ -179,7 +179,7 @@ describe("requestOAuthConsent", () => {
 				scopes: EXACT_SCOPES,
 			}),
 		).resolves.toEqual({ status: "failed", reason: "state-mismatch" });
-		expect(wrongState.exchangeOAuthCode).not.toHaveBeenCalled();
+		expect(wrongState.auth.oauth.exchangeCode).not.toHaveBeenCalled();
 		expect(wrongState.commitSession).not.toHaveBeenCalled();
 	});
 
@@ -199,7 +199,7 @@ describe("requestOAuthConsent", () => {
 					scopes,
 				}),
 			).resolves.toEqual({ status: "failed", reason: "invalid-scopes" });
-			expect(context.getPublicApplication).not.toHaveBeenCalled();
+			expect(context.apps.getPublic).not.toHaveBeenCalled();
 			expect(openNative).not.toHaveBeenCalled();
 		},
 	);
@@ -213,7 +213,7 @@ describe("requestOAuthConsent", () => {
 			}),
 		).resolves.toEqual({ status: "failed", reason: "scope-not-configured" });
 		expect(openNative).not.toHaveBeenCalled();
-		expect(context.exchangeOAuthCode).not.toHaveBeenCalled();
+		expect(context.auth.oauth.exchangeCode).not.toHaveBeenCalled();
 	});
 
 	it.each([
@@ -228,14 +228,14 @@ describe("requestOAuthConsent", () => {
 			await expect(
 				requestOAuthConsent(context, { redirectUri, scopes: EXACT_SCOPES }),
 			).resolves.toEqual({ status: "failed", reason: "invalid-redirect-uri" });
-			expect(context.getPublicApplication).not.toHaveBeenCalled();
+			expect(context.apps.getPublic).not.toHaveBeenCalled();
 			expect(openNative).not.toHaveBeenCalled();
 		},
 	);
 
 	it("does not commit or report consent when OAuth returns another user", async () => {
 		const context = makeContext("native");
-		context.exchangeOAuthCode.mockResolvedValue({
+		context.auth.oauth.exchangeCode.mockResolvedValue({
 			sessionId: "other-session",
 			accessToken: "other-token",
 			user: { id: "another-user" },

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

@@ -42,12 +42,12 @@ function makeContext(mode: 'popup' | 'redirect'): WebOAuthTransportContext & {
   const exchangeOAuthCode = jest.fn();
   return {
     mode,
-    oxyServices: { exchangeOAuthCode } as unknown as OxyServices,
+    oxyServices: { auth: { oauth: { exchangeCode: exchangeOAuthCode } } } as unknown as OxyServices,
     clientId: CLIENT_ID,
     authorizeBaseUrl: `${IDP_ORIGIN}/authorize`,
     identityBound: false,
     commitSession: jest.fn().mockResolvedValue(undefined),
-    exchangeOAuthCode,
+    auth: { oauth: { exchangeCode: exchangeOAuthCode } },
   };
 }
 
@@ -97,12 +97,12 @@ describe('shared OAuth completion path', () => {
     // 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();
+    expect(context.auth.oauth.exchangeCode).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;
+    const oxyServices = { auth: { oauth: { exchangeCode: 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');
@@ -139,7 +139,7 @@ describe('shared OAuth completion path', () => {
 
     await expect(
       tryCompleteOAuthReturn({
-        oxyServices: { exchangeOAuthCode: jest.fn() } as unknown as OxyServices,
+        oxyServices: { auth: { oauth: { exchangeCode: jest.fn() } } } as unknown as OxyServices,
         clientId: CLIENT_ID,
         commitSession: jest.fn().mockResolvedValue(undefined),
       }),
@@ -151,7 +151,7 @@ describe('shared OAuth completion path', () => {
 
     await expect(
       tryCompleteOAuthReturn({
-        oxyServices: { exchangeOAuthCode: jest.fn() } as unknown as OxyServices,
+        oxyServices: { auth: { oauth: { exchangeCode: jest.fn() } } } as unknown as OxyServices,
         clientId: null,
         commitSession: jest.fn().mockResolvedValue(undefined),
       }),
@@ -164,7 +164,7 @@ describe('shared OAuth completion path', () => {
 
     await expect(
       tryCompleteOAuthReturn({
-        oxyServices: { exchangeOAuthCode: jest.fn() } as unknown as OxyServices,
+        oxyServices: { auth: { oauth: { exchangeCode: jest.fn() } } } as unknown as OxyServices,
         clientId: CLIENT_ID,
         commitSession: jest.fn().mockResolvedValue(undefined),
       }),

package/src/ui/oauth/browserBridge.ts

@@ -0,0 +1,234 @@
+/**
+ * The browser bridge, the app half (ADR 0029 D2).
+ *
+ * Different domains share no storage, so the browser's ONE Oxy session lives on
+ * auth.oxy.so. The first time a person presses sign-in in an Oxy web app that
+ * holds no device credential, the app opens `auth.oxy.so/bridge` from that press:
+ * a page with no UI that proves (or registers) auth.oxy.so's device, posts this
+ * app a one-use code bound to its client id, its exact redirect URI and a PKCE
+ * challenge, and closes. The app redeems the code with the verifier only it
+ * holds (`POST /session/device/join`) and from then on holds its own credential
+ * on the shared device — it never opens the bridge again.
+ *
+ * Three browser realities, the same ones as the OAuth popup (`oauthPopup.ts`):
+ * the window must be opened SYNCHRONOUSLY from the press (gesture attribution),
+ * so it is opened empty and navigated once the PKCE pair exists; a cross-origin
+ * window fires nothing when it closes, so `closed` is polled; and its result
+ * arrives only as a `postMessage`, accepted from the auth origin and from that
+ * exact window, carrying this attempt's `state`.
+ *
+ * Nothing here is required for signing in: a blocked window, a timeout or any
+ * failure only means this app signs in on a device of its own, as before.
+ */
+
+import { AUTH_WEB_ORIGIN, generateOAuthState, generatePkcePair, logger } from '@oxy.so/core';
+import type { OxyServices } from '@oxy.so/core';
+import type { OAuthPopupHandle } from './types';
+
+/** `postMessage` discriminator for a join code from the bridge. */
+export const OXY_BRIDGE_CODE_MESSAGE_TYPE = 'oxy:bridge:code';
+/** `postMessage` discriminator for a bridge that could not produce a code. */
+export const OXY_BRIDGE_ERROR_MESSAGE_TYPE = 'oxy:bridge:error';
+
+/** Its own name, so it never reuses (and navigates away) the sign-in popup. */
+export const OXY_BRIDGE_WINDOW_NAME = 'oxy-bridge';
+
+/**
+ * How long the bridge may take (ms). It normally answers in a few hundred ms; the
+ * ceiling only stops a wedged window from holding the attempt open.
+ */
+export const DEFAULT_BRIDGE_TIMEOUT_MS = 15_000;
+
+const CLOSE_POLL_INTERVAL_MS = 250;
+const CLOSE_GRACE_MS = 300;
+
+/** The auth origin the bridge lives on: the authorize override's, else auth.oxy.so. */
+export function resolveBridgeOrigin(authorizeBaseUrl?: string): string | null {
+  if (!authorizeBaseUrl) return AUTH_WEB_ORIGIN;
+  try {
+    const origin = new URL(authorizeBaseUrl).origin;
+    return origin.startsWith('http') ? origin : null;
+  } catch {
+    return null;
+  }
+}
+
+interface BridgeHost {
+  open?: (url: string, target: string, features: string) => OAuthPopupHandle | null;
+  addEventListener?: (type: 'message', listener: (event: MessageEvent) => void) => void;
+  removeEventListener?: (type: 'message', listener: (event: MessageEvent) => void) => void;
+  screenX?: number;
+  screenY?: number;
+  outerWidth?: number;
+  outerHeight?: number;
+}
+
+function bridgeHost(): BridgeHost | null {
+  const win = (globalThis as { window?: BridgeHost }).window;
+  return win ?? null;
+}
+
+/**
+ * Open the bridge window, EMPTY, as small as the browser allows and centred over
+ * the app. MUST be called synchronously from the press. Returns `null` when the
+ * browser blocked it or there is no DOM — never throws.
+ */
+export function openBridgeWindow(): OAuthPopupHandle | null {
+  const win = bridgeHost();
+  if (!win || typeof win.open !== 'function') return null;
+  const left = Math.round((win.screenX ?? 0) + (win.outerWidth ?? 0) / 2);
+  const top = Math.round((win.screenY ?? 0) + (win.outerHeight ?? 0) / 2);
+  const features = `popup=yes,width=1,height=1,left=${left},top=${top},menubar=no,toolbar=no,location=no,status=no`;
+  try {
+    return win.open('', OXY_BRIDGE_WINDOW_NAME, features) ?? null;
+  } catch (error) {
+    logger.debug('Could not open the browser bridge window', { component: 'browserBridge' }, error);
+    return null;
+  }
+}
+
+function closeBridgeWindow(popup: OAuthPopupHandle): void {
+  try {
+    if (!popup.closed) popup.close();
+  } catch {
+    // Already gone.
+  }
+}
+
+/** The fields of a `message` event the verdict reads. */
+interface BridgeMessageEvent {
+  origin: string;
+  source: unknown;
+  data: unknown;
+}
+
+/** Verdict for one `message` event. */
+export type BridgeMessageVerdict =
+  | { kind: 'ignore' }
+  | { kind: 'code'; code: string }
+  | { kind: 'error'; error: string };
+
+/**
+ * Classify one `message` event. Accepted only from the bridge origin AND the
+ * exact window this attempt opened, in one of the two shapes, with this
+ * attempt's `state`; everything else is page noise and ignored.
+ */
+export function readBridgeMessage(
+  event: BridgeMessageEvent,
+  context: { expectedOrigin: string; expectedState: string; popup: unknown },
+): BridgeMessageVerdict {
+  if (event.origin !== context.expectedOrigin) return { kind: 'ignore' };
+  if (event.source !== context.popup) return { kind: 'ignore' };
+  const data = event.data as Record<string, unknown> | null;
+  if (typeof data !== 'object' || data === null) return { kind: 'ignore' };
+  if (data.state !== context.expectedState) return { kind: 'ignore' };
+  if (data.type === OXY_BRIDGE_CODE_MESSAGE_TYPE && typeof data.code === 'string' && data.code.length > 0) {
+    return { kind: 'code', code: data.code };
+  }
+  if (data.type === OXY_BRIDGE_ERROR_MESSAGE_TYPE && typeof data.error === 'string') {
+    return { kind: 'error', error: data.error };
+  }
+  return { kind: 'ignore' };
+}
+
+export interface RunBrowserBridgeOptions {
+  /** The window {@link openBridgeWindow} returned from the press. */
+  popup: OAuthPopupHandle;
+  /** Where the bridge lives ({@link resolveBridgeOrigin}). */
+  bridgeOrigin: string;
+  oxyServices: OxyServices;
+  /** This app's registered client id. */
+  clientId: string;
+  /** This app's EXACT registered redirect URI; its origin is where the code is posted. */
+  redirectUri: string;
+  /** @default DEFAULT_BRIDGE_TIMEOUT_MS */
+  timeoutMs?: number;
+}
+
+export type BrowserBridgeResult =
+  | { ok: true; deviceId: string; deviceSecret: string }
+  | { ok: false; reason: 'closed' | 'timed-out' | 'bridge-error' | 'join-failed' | 'no-browser' };
+
+/**
+ * Drive an opened bridge window to a device credential for this app. Settles
+ * exactly once, closes the window whatever the outcome, and never rejects.
+ */
+export async function runBrowserBridge(options: RunBrowserBridgeOptions): Promise<BrowserBridgeResult> {
+  const { popup, bridgeOrigin, oxyServices, clientId, redirectUri } = options;
+  const host = bridgeHost();
+  if (!host || typeof host.addEventListener !== 'function' || typeof host.removeEventListener !== 'function') {
+    closeBridgeWindow(popup);
+    return { ok: false, reason: 'no-browser' };
+  }
+  try {
+    const [pkce, state] = await Promise.all([generatePkcePair(), generateOAuthState()]);
+    const url = new URL('/bridge', bridgeOrigin);
+    url.searchParams.set('client_id', clientId);
+    url.searchParams.set('redirect_uri', redirectUri);
+    url.searchParams.set('state', state);
+    url.searchParams.set('code_challenge', pkce.codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    try {
+      popup.location.href = url.toString();
+    } catch {
+      return { ok: false, reason: 'closed' };
+    }
+
+    const verdict = await awaitBridgeMessage(host, {
+      popup,
+      expectedOrigin: bridgeOrigin,
+      expectedState: state,
+      timeoutMs: options.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    });
+    if (verdict.kind !== 'code') return { ok: false, reason: verdict.kind };
+
+    try {
+      const joined = await oxyServices.devices.joinBrowser({
+        code: verdict.code,
+        codeVerifier: pkce.codeVerifier,
+        clientId,
+        redirectUri,
+      });
+      return { ok: true, deviceId: joined.deviceId, deviceSecret: joined.deviceSecret };
+    } catch (error) {
+      logger.warn('Joining the browser device failed', { component: 'browserBridge' }, error);
+      return { ok: false, reason: 'join-failed' };
+    }
+  } catch (error) {
+    logger.warn('The browser bridge failed', { component: 'browserBridge' }, error);
+    return { ok: false, reason: 'bridge-error' };
+  } finally {
+    closeBridgeWindow(popup);
+  }
+}
+
+function awaitBridgeMessage(
+  host: BridgeHost,
+  context: { popup: OAuthPopupHandle; expectedOrigin: string; expectedState: string; timeoutMs: number },
+): Promise<{ kind: 'code'; code: string } | { kind: 'closed' | 'timed-out' | 'bridge-error' }> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let closeGrace: ReturnType<typeof setTimeout> | null = null;
+    const onMessage = (event: MessageEvent): void => {
+      const verdict = readBridgeMessage(event, context);
+      if (verdict.kind === 'code') settle({ kind: 'code', code: verdict.code });
+      else if (verdict.kind === 'error') settle({ kind: 'bridge-error' });
+    };
+    const timeout = setTimeout(() => settle({ kind: 'timed-out' }), context.timeoutMs);
+    const poll = setInterval(() => {
+      if (!context.popup.closed || closeGrace !== null) return;
+      // The bridge posts and THEN closes; let an already-queued message win.
+      closeGrace = setTimeout(() => settle({ kind: 'closed' }), CLOSE_GRACE_MS);
+    }, CLOSE_POLL_INTERVAL_MS);
+    function settle(outcome: { kind: 'code'; code: string } | { kind: 'closed' | 'timed-out' | 'bridge-error' }): void {
+      if (settled) return;
+      settled = true;
+      host.removeEventListener?.('message', onMessage);
+      clearTimeout(timeout);
+      clearInterval(poll);
+      if (closeGrace !== null) clearTimeout(closeGrace);
+      resolve(outcome);
+    }
+    host.addEventListener?.('message', onMessage);
+  });
+}

package/src/ui/oauth/completeOAuthCode.ts

@@ -68,7 +68,7 @@ export async function completeOAuthCode(
   }
 
   try {
-    const result = await input.oxyServices.exchangeOAuthCode({
+    const result = await input.oxyServices.auth.oauth.exchangeCode({
       code: input.code,
       clientId: input.clientId,
       redirectUri: input.redirectUri,

package/src/ui/oauth/explicitOAuthConsent.ts

@@ -165,7 +165,7 @@ export async function requestOAuthConsent(
 
 	let application: PublicApplication;
 	try {
-		application = await context.oxyServices.getPublicApplication(
+		application = await context.oxyServices.apps.getPublic(
 			context.clientId,
 		);
 	} catch {

package/src/ui/runtime/createOxyRuntime.ts

@@ -1,16 +1,8 @@
 import type { DeviceDirectory, DeviceSessionState } from '@oxy.so/contracts';
-import type { ClientSession, DeviceContext, User } from '@oxy.so/core';
-import {
-  accountIdsOf,
-  activeSessionIdOf,
-  activeUserOf,
-  deviceStateToClientSessions,
-  mergeSessions as mergeSessionLists,
-  normalizeAndSortSessions,
-  normalizeUserIdentity,
-  resolveActiveContext,
-  sessionsArraysEqual,
-} from '@oxy.so/core';
+import type { ClientSession, User } from '@oxy.so/core';
+import type { DeviceContext } from '@oxy.so/core/session';
+import { accountIdsOf, activeSessionIdOf, activeUserOf, deviceStateToClientSessions, resolveActiveContext } from '@oxy.so/core/session';
+import { mergeSessions as mergeSessionLists, normalizeAndSortSessions, normalizeUserIdentity, sessionsArraysEqual } from '@oxy.so/core';
 import type { IdentitySessionBinding } from '../session/identityBinding';
 import type { OxyRuntimeSnapshot, OxyRuntimeStatus, OxyTokenStatus } from './types';
 
@@ -36,8 +28,8 @@ export interface SubjectTransition {
  * pretends to implement.
  */
 export interface RuntimeClient {
-  getAccessToken(): string | null;
-  getUsersByIds(ids: string[]): Promise<User[]>;
+  session: { readonly accessToken: string | null };
+  users: { getMany(ids: string[]): Promise<User[]> };
 }
 
 export interface RuntimeSessionClient {
@@ -257,7 +249,7 @@ export function createOxyRuntime(config: OxyRuntimeConfig): OxyRuntime {
     error: null,
     storageReady: false,
     tokenReady: true,
-    hasAccessToken: Boolean(oxyServices.getAccessToken()),
+    hasAccessToken: Boolean(oxyServices.session.accessToken),
     authResolved: false,
     switching: false,
   };
@@ -423,7 +415,7 @@ export function createOxyRuntime(config: OxyRuntimeConfig): OxyRuntime {
     const ids = accountIdsOf(state);
     let users: User[] = [];
     try {
-      users = ids.length > 0 ? await oxyServices.getUsersByIds(ids) : [];
+      users = ids.length > 0 ? await oxyServices.users.getMany(ids) : [];
     } catch (fetchError) {
       logger('Failed to resolve account profiles during the device projection', fetchError);
       return;

package/src/ui/runtime/runtimeContext.tsx

@@ -1,6 +1,7 @@
 import { createContext, useContext } from 'react';
 import type { DeviceDirectory } from '@oxy.so/contracts';
-import type { DeviceContext, User } from '@oxy.so/core';
+import type { DeviceContext } from '@oxy.so/core/session';
+import type { User } from '@oxy.so/core';
 import type { OxyRuntime } from './createOxyRuntime';
 import type { OxyRuntimeStatus } from './types';
 import { useRuntimeSelector, useRuntimeSnapshot } from './useRuntimeSnapshot';

package/src/ui/runtime/types.ts

@@ -1,5 +1,6 @@
 import type { DeviceDirectory, DeviceSessionState } from '@oxy.so/contracts';
-import type { ClientSession, DeviceContext, User } from '@oxy.so/core';
+import type { ClientSession, User } from '@oxy.so/core';
+import type { DeviceContext } from '@oxy.so/core/session';
 
 /**
  * The runtime's coarse verdict about this device's session.