@baukit/integrations-client 0.7.2 → 0.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baukit/integrations-client",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Provider-neutral connection state, OAuth session coordination, and provider registration for web and native clients.",
   "license": "MIT",
   "author": "Patrick Koss",
@@ -30,6 +30,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],

package/src/connection-health.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  connectionStateFromServer,
+  reduceConnectionState,
+  type ConnectionState,
+} from './connection-health.js';
+
+describe('connection health', () => {
+  it.each([
+    ['healthy', 'connected', ['disconnect']],
+    ['degraded', 'error', ['retry']],
+    ['needs_reconnect', 'needs_reconnect', ['reconnect']],
+    ['failed', 'error', ['retry']],
+    ['revoked', 'needs_reconnect', ['reconnect']],
+    ['pending_revocation', 'revocation_pending', ['retry']],
+    ['disconnected', 'disconnected', ['connect']],
+  ] as const)('maps server state %s to %s', (serverState, status, actions) => {
+    const state = connectionStateFromServer({ state: serverState });
+    expect(state.status).toBe(status);
+    expect(state.availableActions).toEqual(actions);
+  });
+
+  it('never copies provider diagnostics into the user-facing state', () => {
+    const rawProviderError = 'invalid_grant: token=provider-secret';
+    const state = connectionStateFromServer({
+      state: 'degraded',
+      diagnosticCode: 'provider_unavailable',
+      providerDiagnostic: rawProviderError,
+    });
+
+    expect(state.diagnostic).toEqual({ code: 'provider_unavailable', source: 'server' });
+    expect(JSON.stringify(state)).not.toContain(rawProviderError);
+  });
+
+  it.each([
+    'provider failed with account 42',
+    'provider-failed',
+    'UPSTREAM_FAILURE',
+    `a${'b'.repeat(128)}`,
+  ])('drops unsafe diagnostic code %s', (diagnosticCode) => {
+    const state = connectionStateFromServer({
+      state: 'failed',
+      diagnosticCode,
+      providerDiagnostic: diagnosticCode,
+    });
+    expect(state.diagnostic).toBeUndefined();
+    expect(JSON.stringify(state)).not.toContain(diagnosticCode);
+  });
+
+  it('keeps reconnect intent when authorization is cancelled', () => {
+    const reconnectable = connectionStateFromServer({ state: 'needs_reconnect' });
+    const connecting = reduceConnectionState(reconnectable, { type: 'connect_requested' });
+    expect(connecting).toMatchObject({ status: 'connecting', operation: 'reconnect' });
+
+    const cancelled = reduceConnectionState(connecting, { type: 'auth_cancelled' });
+    expect(cancelled).toEqual({
+      status: 'needs_reconnect',
+      availableActions: ['reconnect'],
+      operation: 'reconnect',
+    });
+  });
+
+  it('moves a completed authorization to connected', () => {
+    const connecting = reduceConnectionState(disconnected(), { type: 'connect_requested' });
+    expect(reduceConnectionState(connecting, { type: 'auth_started' })).toBe(connecting);
+    expect(reduceConnectionState(connecting, { type: 'auth_returned' })).toEqual({
+      status: 'connected',
+      availableActions: ['disconnect'],
+    });
+  });
+
+  it('turns an authorization timeout into a retryable safe error', () => {
+    const connecting = reduceConnectionState(disconnected(), { type: 'connect_requested' });
+    const timedOut = reduceConnectionState(connecting, {
+      type: 'auth_timed_out',
+      diagnosticCode: 'oauth_start_timed_out',
+    });
+    expect(timedOut).toEqual({
+      status: 'error',
+      availableActions: ['retry'],
+      diagnostic: { code: 'oauth_start_timed_out', source: 'client' },
+      operation: 'connect',
+    });
+    expect(reduceConnectionState(timedOut, { type: 'retry' })).toEqual({
+      status: 'connecting',
+      availableActions: [],
+      operation: 'connect',
+    });
+  });
+
+  it('tracks disconnect and pending revocation retries', () => {
+    const connected = connectionStateFromServer({ state: 'active' });
+    const disconnecting = reduceConnectionState(connected, { type: 'disconnect_requested' });
+    expect(disconnecting).toMatchObject({ status: 'disconnecting', operation: 'disconnect' });
+
+    const pending = reduceConnectionState(disconnecting, { type: 'revocation_pending' });
+    expect(pending).toMatchObject({
+      status: 'revocation_pending',
+      availableActions: ['retry'],
+      operation: 'disconnect',
+    });
+    expect(reduceConnectionState(pending, { type: 'retry' })).toMatchObject({
+      status: 'disconnecting',
+      operation: 'disconnect',
+    });
+  });
+
+  it('ignores actions that are not available', () => {
+    const state = disconnected();
+    expect(reduceConnectionState(state, { type: 'disconnect_requested' })).toBe(state);
+    expect(reduceConnectionState(state, { type: 'retry' })).toBe(state);
+  });
+});
+
+function disconnected(): ConnectionState {
+  return connectionStateFromServer({ state: 'disconnected' });
+}

package/src/connection-health.ts

@@ -0,0 +1,171 @@
+export type ConnectionStatus =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'needs_reconnect'
+  | 'disconnecting'
+  | 'revocation_pending'
+  | 'error';
+
+export type ConnectionAction = 'connect' | 'reconnect' | 'disconnect' | 'retry';
+
+export type ConnectionOperation = 'connect' | 'reconnect' | 'disconnect';
+
+export type ServerConnectionState =
+  | 'disconnected'
+  | 'active'
+  | 'connected'
+  | 'healthy'
+  | 'degraded'
+  | 'needs_reconnect'
+  | 'failed'
+  | 'revoked'
+  | 'pending_revocation';
+
+export interface ConnectionDiagnostic {
+  readonly code: string;
+  readonly source: 'client' | 'server';
+}
+
+export interface ConnectionState {
+  readonly status: ConnectionStatus;
+  readonly availableActions: readonly ConnectionAction[];
+  readonly diagnostic?: ConnectionDiagnostic;
+  readonly operation?: ConnectionOperation;
+}
+
+export interface ServerConnectionSnapshot {
+  readonly state: ServerConnectionState;
+  readonly diagnosticCode?: string | null;
+  readonly providerDiagnostic?: unknown;
+}
+
+export type ConnectionEvent =
+  | { readonly type: 'server_state'; readonly snapshot: ServerConnectionSnapshot }
+  | { readonly type: 'connect_requested' }
+  | { readonly type: 'auth_started' }
+  | { readonly type: 'auth_returned' }
+  | { readonly type: 'auth_cancelled' }
+  | { readonly type: 'auth_timed_out'; readonly diagnosticCode?: string }
+  | { readonly type: 'disconnect_requested' }
+  | { readonly type: 'revocation_pending'; readonly diagnosticCode?: string }
+  | { readonly type: 'retry' };
+
+const MAX_DIAGNOSTIC_CODE_LENGTH = 128;
+const DIAGNOSTIC_CODE_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+
+const ACTIONS = {
+  disconnected: ['connect'],
+  connecting: [],
+  connected: ['disconnect'],
+  needs_reconnect: ['reconnect'],
+  disconnecting: [],
+  revocation_pending: ['retry'],
+  error: ['retry'],
+} as const satisfies Record<ConnectionStatus, readonly ConnectionAction[]>;
+
+export function connectionStateFromServer(snapshot: ServerConnectionSnapshot): ConnectionState {
+  const diagnostic = serverDiagnostic(snapshot.diagnosticCode);
+  switch (snapshot.state) {
+    case 'active':
+    case 'connected':
+    case 'healthy':
+      return makeConnectionState('connected');
+    case 'needs_reconnect':
+    case 'revoked':
+      return makeConnectionState('needs_reconnect', { diagnostic, operation: 'reconnect' });
+    case 'degraded':
+    case 'failed':
+      return makeConnectionState('error', { diagnostic, operation: 'reconnect' });
+    case 'pending_revocation':
+      return makeConnectionState('revocation_pending', { diagnostic, operation: 'disconnect' });
+    case 'disconnected':
+      return makeConnectionState('disconnected');
+  }
+}
+
+export function reduceConnectionState(
+  state: ConnectionState,
+  event: ConnectionEvent,
+): ConnectionState {
+  switch (event.type) {
+    case 'server_state':
+      return connectionStateFromServer(event.snapshot);
+    case 'connect_requested': {
+      const action = state.status === 'needs_reconnect' ? 'reconnect' : 'connect';
+      if (!state.availableActions.includes(action)) return state;
+      return makeConnectionState('connecting', { operation: action });
+    }
+    case 'auth_started':
+      return state.status === 'connecting'
+        ? state
+        : makeConnectionState('connecting', {
+            operation: state.status === 'needs_reconnect' ? 'reconnect' : 'connect',
+          });
+    case 'auth_returned':
+      return makeConnectionState('connected');
+    case 'auth_cancelled':
+      return state.operation === 'reconnect'
+        ? makeConnectionState('needs_reconnect', { operation: 'reconnect' })
+        : makeConnectionState('disconnected');
+    case 'auth_timed_out':
+      return makeConnectionState('error', {
+        diagnostic: clientDiagnostic(event.diagnosticCode ?? 'oauth_timed_out'),
+        operation: state.operation === 'reconnect' ? 'reconnect' : 'connect',
+      });
+    case 'disconnect_requested':
+      return state.availableActions.includes('disconnect')
+        ? makeConnectionState('disconnecting', { operation: 'disconnect' })
+        : state;
+    case 'revocation_pending':
+      return makeConnectionState('revocation_pending', {
+        diagnostic: clientDiagnostic(event.diagnosticCode ?? 'revocation_pending'),
+        operation: 'disconnect',
+      });
+    case 'retry':
+      if (!state.availableActions.includes('retry')) return state;
+      return state.operation === 'disconnect'
+        ? makeConnectionState('disconnecting', { operation: 'disconnect' })
+        : makeConnectionState('connecting', {
+            operation: state.operation === 'reconnect' ? 'reconnect' : 'connect',
+          });
+  }
+}
+
+function makeConnectionState(
+  status: ConnectionStatus,
+  options: {
+    readonly diagnostic?: ConnectionDiagnostic | undefined;
+    readonly operation?: ConnectionOperation;
+  } = {},
+): ConnectionState {
+  return {
+    status,
+    availableActions: ACTIONS[status],
+    ...(options.diagnostic === undefined ? {} : { diagnostic: options.diagnostic }),
+    ...(options.operation === undefined ? {} : { operation: options.operation }),
+  };
+}
+
+function serverDiagnostic(code: string | null | undefined): ConnectionDiagnostic | undefined {
+  return diagnostic(code, 'server');
+}
+
+function clientDiagnostic(code: string | undefined): ConnectionDiagnostic | undefined {
+  return diagnostic(code, 'client');
+}
+
+function diagnostic(
+  code: string | null | undefined,
+  source: ConnectionDiagnostic['source'],
+): ConnectionDiagnostic | undefined {
+  if (
+    code === null ||
+    code === undefined ||
+    code.length > MAX_DIAGNOSTIC_CODE_LENGTH ||
+    !DIAGNOSTIC_CODE_PATTERN.test(code)
+  ) {
+    return undefined;
+  }
+  return { code, source };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './connection-health.js';
+export * from './oauth-session.js';
+export * from './provider-registry.js';

package/src/oauth-session.test.ts

@@ -0,0 +1,302 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  OAuthSessionCoordinator,
+  createReturnUrlValidator,
+  type BrowserPopupSession,
+  type OAuthClock,
+  type OAuthInFlightSession,
+  type OAuthSessionResult,
+  type OAuthSessionStorage,
+} from './oauth-session.js';
+
+const RETURN_URL = 'https://app.test/oauth/callback';
+const CALLBACK_URL = `${RETURN_URL}?code=authorization-code&state=nonce-1`;
+
+describe('OAuth session coordinator', () => {
+  it('reserves a browser popup before waiting for the authorization URL', async () => {
+    const authorization = deferred<string>();
+    const result = deferred<OAuthSessionResult>();
+    const navigate = vi.fn();
+    const popup = popupSession(result.promise, { navigate });
+    const browser = { openPlaceholder: vi.fn(() => popup) };
+    const fixture = coordinator({ browser });
+
+    const outcome = fixture.value.authorize({
+      platform: 'web',
+      returnUrl: RETURN_URL,
+      createAuthorizationUrl: vi.fn(() => authorization.promise),
+    });
+
+    expect(browser.openPlaceholder).toHaveBeenCalledWith({
+      placeholderUrl: 'about:blank',
+      returnUrl: RETURN_URL,
+      windowName: 'baukit-integration-oauth',
+    });
+    expect(navigate).not.toHaveBeenCalled();
+
+    authorization.resolve('https://accounts.test/authorize');
+    await settle();
+    expect(navigate).toHaveBeenCalledWith('https://accounts.test/authorize');
+    result.resolve({ type: 'success', returnUrl: CALLBACK_URL });
+
+    await expect(outcome).resolves.toEqual({
+      type: 'success',
+      callbackParams: { code: 'authorization-code', state: 'nonce-1' },
+    });
+    expect(fixture.storage.value).toBeNull();
+  });
+
+  it('runs a native auth session after the authorization URL is ready', async () => {
+    const run = vi.fn(() => Promise.resolve({ type: 'success', returnUrl: CALLBACK_URL } as const));
+    const native = {
+      run,
+      cancel: vi.fn(),
+    };
+    const fixture = coordinator({ native });
+
+    await expect(
+      fixture.value.authorize({
+        platform: 'native',
+        returnUrl: RETURN_URL,
+        createAuthorizationUrl: () => Promise.resolve('https://accounts.test/authorize'),
+      }),
+    ).resolves.toMatchObject({ type: 'success' });
+    expect(run).toHaveBeenCalledWith({
+      authorizationUrl: 'https://accounts.test/authorize',
+      returnUrl: RETURN_URL,
+    });
+  });
+
+  it('returns cancelled and clears its in-flight state', async () => {
+    const redirectAuthorize = vi.fn(() => Promise.resolve({ type: 'cancelled' } as const));
+    const redirect = {
+      authorize: redirectAuthorize,
+    };
+    const fixture = coordinator({
+      browser: { openPlaceholder: () => null },
+      redirect,
+    });
+
+    await expect(
+      fixture.value.authorize({
+        platform: 'web',
+        returnUrl: RETURN_URL,
+        createAuthorizationUrl: () => Promise.resolve('https://accounts.test/authorize'),
+      }),
+    ).resolves.toEqual({ type: 'cancelled' });
+    expect(redirectAuthorize).toHaveBeenCalledWith({
+      authorizationUrl: 'https://accounts.test/authorize',
+      returnUrl: RETURN_URL,
+    });
+    expect(fixture.storage.value).toBeNull();
+  });
+
+  it('times out a stalled authorization start and closes its reserved popup', async () => {
+    const close = vi.fn();
+    const navigate = vi.fn();
+    const popup = popupSession(Promise.resolve({ type: 'cancelled' }), { close, navigate });
+    const fixture = coordinator({ browser: { openPlaceholder: () => popup } });
+    const outcome = fixture.value.authorize({
+      platform: 'web',
+      returnUrl: RETURN_URL,
+      createAuthorizationUrl: () => new Promise<string>(() => undefined),
+    });
+    await settle();
+
+    fixture.clock.advance(1_000);
+
+    await expect(outcome).resolves.toEqual({ type: 'timed_out' });
+    expect(close).toHaveBeenCalledOnce();
+    expect(navigate).not.toHaveBeenCalled();
+    expect(fixture.storage.value).toBeNull();
+  });
+
+  it('rejects a return from another origin or path', async () => {
+    const fixture = coordinator();
+    await expect(
+      fixture.value.handleRedirect('https://app.test/oauth/other?state=nonce-1'),
+    ).resolves.toEqual({ type: 'invalid_return' });
+    await expect(
+      fixture.value.handleRedirect('https://app.test.evil/oauth/callback?state=nonce-1'),
+    ).resolves.toEqual({ type: 'invalid_return' });
+  });
+
+  it('returns storage mismatch when the callback state differs', async () => {
+    const storage = new MemoryStorage({
+      stateNonce: 'stored-nonce',
+      returnUrl: RETURN_URL,
+      createdAt: 0,
+    });
+    const fixture = coordinator({ storage });
+
+    await expect(fixture.value.handleRedirect(CALLBACK_URL)).resolves.toEqual({
+      type: 'storage_mismatch',
+    });
+    expect(storage.value?.stateNonce).toBe('stored-nonce');
+  });
+
+  it('handles a valid redirect after a same-tab navigation', async () => {
+    const storage = new MemoryStorage({
+      stateNonce: 'nonce-1',
+      returnUrl: RETURN_URL,
+      createdAt: 0,
+    });
+    const fixture = coordinator({ storage });
+
+    await expect(fixture.value.handleRedirect(CALLBACK_URL)).resolves.toEqual({
+      type: 'success',
+      callbackParams: { code: 'authorization-code', state: 'nonce-1' },
+    });
+  });
+
+  it('rejects duplicate callback parameters', async () => {
+    const storage = new MemoryStorage({
+      stateNonce: 'nonce-1',
+      returnUrl: RETURN_URL,
+      createdAt: 0,
+    });
+    const fixture = coordinator({ storage });
+
+    await expect(fixture.value.handleRedirect(`${CALLBACK_URL}&state=nonce-1`)).resolves.toEqual({
+      type: 'invalid_return',
+    });
+  });
+
+  it('discards a stale in-flight session before saving a new one', async () => {
+    const storage = new MemoryStorage({
+      stateNonce: 'old-nonce',
+      returnUrl: RETURN_URL,
+      createdAt: 0,
+    });
+    const clock = new ControlledClock(2_000);
+    const redirect = { authorize: () => Promise.resolve({ type: 'cancelled' } as const) };
+    const fixture = coordinator({ storage, clock, redirect });
+
+    await fixture.value.authorize({
+      platform: 'web',
+      returnUrl: RETURN_URL,
+      createAuthorizationUrl: () => Promise.resolve('https://accounts.test/authorize'),
+    });
+
+    expect(storage.events.slice(0, 3)).toEqual(['load', 'clear', 'save:nonce-1']);
+    expect(storage.value).toBeNull();
+  });
+
+  it('validates an exact custom-scheme authority and allowlisted path', () => {
+    const validate = createReturnUrlValidator({
+      origin: 'sample-app://oauth',
+      paths: ['/callback'],
+    });
+    expect(validate('sample-app://oauth/callback?state=one')).toBe(true);
+    expect(validate('sample-app://other/callback?state=one')).toBe(false);
+    expect(validate('sample-app://oauth/callback/extra?state=one')).toBe(false);
+  });
+});
+
+class MemoryStorage implements OAuthSessionStorage {
+  public readonly events: string[] = [];
+
+  public constructor(public value: OAuthInFlightSession | null = null) {}
+
+  public load(): Promise<OAuthInFlightSession | null> {
+    this.events.push('load');
+    return Promise.resolve(this.value);
+  }
+
+  public save(session: OAuthInFlightSession): Promise<void> {
+    this.events.push(`save:${session.stateNonce}`);
+    this.value = session;
+    return Promise.resolve();
+  }
+
+  public clear(): Promise<void> {
+    this.events.push('clear');
+    this.value = null;
+    return Promise.resolve();
+  }
+}
+
+class ControlledClock implements OAuthClock {
+  readonly #timers = new Map<object, { callback: () => void; dueAt: number }>();
+
+  public constructor(private currentTime = 0) {}
+
+  public now(): number {
+    return this.currentTime;
+  }
+
+  public setTimeout(callback: () => void, timeoutMs: number): object {
+    const handle = {};
+    this.#timers.set(handle, { callback, dueAt: this.currentTime + timeoutMs });
+    return handle;
+  }
+
+  public clearTimeout(handle: unknown): void {
+    if (typeof handle === 'object' && handle !== null) this.#timers.delete(handle);
+  }
+
+  public advance(milliseconds: number): void {
+    this.currentTime += milliseconds;
+    for (const [handle, timer] of this.#timers) {
+      if (timer.dueAt > this.currentTime) continue;
+      this.#timers.delete(handle);
+      timer.callback();
+    }
+  }
+}
+
+type CoordinatorOptions = ConstructorParameters<typeof OAuthSessionCoordinator>[0];
+
+function coordinator(
+  options: Partial<Omit<CoordinatorOptions, 'storage' | 'clock'>> & {
+    readonly storage?: MemoryStorage;
+    readonly clock?: ControlledClock;
+  } = {},
+) {
+  const storage = options.storage ?? new MemoryStorage();
+  const clock = options.clock ?? new ControlledClock();
+  return {
+    storage,
+    clock,
+    value: new OAuthSessionCoordinator({
+      timeoutMs: 1_000,
+      createStateNonce: () => 'nonce-1',
+      validateReturnUrl: createReturnUrlValidator({
+        origin: 'https://app.test',
+        paths: ['/oauth/callback'],
+      }),
+      ...options,
+      storage,
+      clock,
+    }),
+  };
+}
+
+function popupSession(
+  result: Promise<OAuthSessionResult>,
+  callbacks: {
+    readonly navigate?: (authorizationUrl: string) => void;
+    readonly close?: () => void;
+  } = {},
+): BrowserPopupSession {
+  return {
+    result,
+    navigate: callbacks.navigate ?? vi.fn(),
+    close: callbacks.close ?? vi.fn(),
+  };
+}
+
+function deferred<T>() {
+  let resolveValue: (value: T) => void = () => undefined;
+  const promise = new Promise<T>((resolve) => {
+    resolveValue = resolve;
+  });
+  return { promise, resolve: resolveValue };
+}
+
+async function settle(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+}

package/src/oauth-session.ts

@@ -0,0 +1,314 @@
+export interface OAuthInFlightSession {
+  readonly stateNonce: string;
+  readonly returnUrl: string;
+  readonly createdAt: number;
+}
+
+export interface OAuthSessionStorage {
+  load(): Promise<OAuthInFlightSession | null>;
+  save(session: OAuthInFlightSession): Promise<void>;
+  clear(): Promise<void>;
+}
+
+export interface OAuthClock {
+  now(): number;
+  setTimeout(callback: () => void, timeoutMs: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export type OAuthSessionResult =
+  { readonly type: 'success'; readonly returnUrl: string } | { readonly type: 'cancelled' };
+
+export interface BrowserPopupSession {
+  readonly result: Promise<OAuthSessionResult>;
+  navigate(authorizationUrl: string): void;
+  close(): void;
+}
+
+export interface BrowserPopupOpener {
+  openPlaceholder(input: {
+    readonly placeholderUrl: string;
+    readonly returnUrl: string;
+    readonly windowName: string;
+  }): BrowserPopupSession | null;
+}
+
+export interface NativeAuthSessionRunner {
+  run(input: {
+    readonly authorizationUrl: string;
+    readonly returnUrl: string;
+  }): Promise<OAuthSessionResult>;
+  cancel(): void;
+}
+
+export interface OAuthRedirectHandler {
+  authorize(input: {
+    readonly authorizationUrl: string;
+    readonly returnUrl: string;
+  }): Promise<OAuthSessionResult>;
+}
+
+export interface OAuthReturnUrlPolicy {
+  readonly origin: string;
+  readonly paths: readonly string[];
+}
+
+export type OAuthReturnUrlValidator = (returnUrl: string) => boolean;
+
+export type OAuthSessionOutcome =
+  | {
+      readonly type: 'success';
+      readonly callbackParams: Readonly<Record<string, string>>;
+    }
+  | { readonly type: 'cancelled' }
+  | { readonly type: 'timed_out' }
+  | { readonly type: 'invalid_return' }
+  | { readonly type: 'storage_mismatch' };
+
+export interface OAuthSessionCoordinatorOptions {
+  readonly storage: OAuthSessionStorage;
+  readonly clock: OAuthClock;
+  readonly timeoutMs: number;
+  readonly createStateNonce: () => string;
+  readonly validateReturnUrl: OAuthReturnUrlValidator;
+  readonly browser?: BrowserPopupOpener;
+  readonly native?: NativeAuthSessionRunner;
+  readonly redirect?: OAuthRedirectHandler;
+  readonly placeholderUrl?: string;
+  readonly windowName?: string;
+}
+
+export interface OAuthAuthorizationRequest {
+  readonly platform: 'web' | 'native';
+  readonly returnUrl: string;
+  readonly createAuthorizationUrl: (input: {
+    readonly stateNonce: string;
+    readonly returnUrl: string;
+  }) => Promise<string>;
+}
+
+const DEFAULT_PLACEHOLDER_URL = 'about:blank';
+const DEFAULT_WINDOW_NAME = 'baukit-integration-oauth';
+const TIMED_OUT = Symbol('timed_out');
+
+export class OAuthSessionCoordinator {
+  readonly #options: OAuthSessionCoordinatorOptions;
+
+  public constructor(options: OAuthSessionCoordinatorOptions) {
+    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+      throw new TypeError('OAuth timeout must be a positive finite number.');
+    }
+    this.#options = options;
+  }
+
+  public async authorize(request: OAuthAuthorizationRequest): Promise<OAuthSessionOutcome> {
+    if (!this.#options.validateReturnUrl(request.returnUrl)) return { type: 'invalid_return' };
+
+    const stateNonce = this.#options.createStateNonce();
+    if (stateNonce.length === 0) throw new TypeError('OAuth state nonce must not be empty.');
+
+    const popup = request.platform === 'web' ? this.openBrowserPopup(request.returnUrl) : null;
+    const operation = this.performAuthorization(request, stateNonce, popup);
+    const result = await this.withTimeout(operation, () => {
+      popup?.close();
+      if (request.platform === 'native') this.#options.native?.cancel();
+    });
+
+    if (result === TIMED_OUT) {
+      await this.clearIfCurrent(stateNonce);
+      return { type: 'timed_out' };
+    }
+    return result;
+  }
+
+  public async handleRedirect(returnUrl: string): Promise<OAuthSessionOutcome> {
+    return this.completeReturn(returnUrl);
+  }
+
+  public async discardStaleSession(): Promise<boolean> {
+    const stored = await this.#options.storage.load();
+    if (stored === null || !this.isStale(stored)) return false;
+    await this.#options.storage.clear();
+    return true;
+  }
+
+  private openBrowserPopup(returnUrl: string): BrowserPopupSession | null {
+    const browser = this.#options.browser;
+    if (browser === undefined) return null;
+    return browser.openPlaceholder({
+      placeholderUrl: this.#options.placeholderUrl ?? DEFAULT_PLACEHOLDER_URL,
+      returnUrl,
+      windowName: this.#options.windowName ?? DEFAULT_WINDOW_NAME,
+    });
+  }
+
+  private async performAuthorization(
+    request: OAuthAuthorizationRequest,
+    stateNonce: string,
+    popup: BrowserPopupSession | null,
+  ): Promise<OAuthSessionOutcome> {
+    await this.discardStaleSession();
+    await this.#options.storage.save({
+      stateNonce,
+      returnUrl: request.returnUrl,
+      createdAt: this.#options.clock.now(),
+    });
+    const authorizationUrl = await request.createAuthorizationUrl({
+      stateNonce,
+      returnUrl: request.returnUrl,
+    });
+
+    let sessionResult: OAuthSessionResult;
+    if (request.platform === 'native') {
+      const native = this.#options.native;
+      if (native === undefined) throw new TypeError('Native OAuth runner is required.');
+      sessionResult = await native.run({ authorizationUrl, returnUrl: request.returnUrl });
+    } else if (popup !== null) {
+      popup.navigate(authorizationUrl);
+      sessionResult = await popup.result;
+    } else {
+      const redirect = this.#options.redirect;
+      if (redirect === undefined) throw new TypeError('Browser OAuth handler is required.');
+      sessionResult = await redirect.authorize({
+        authorizationUrl,
+        returnUrl: request.returnUrl,
+      });
+    }
+
+    if (sessionResult.type === 'cancelled') {
+      await this.clearIfCurrent(stateNonce);
+      return { type: 'cancelled' };
+    }
+    return this.completeReturn(sessionResult.returnUrl, stateNonce);
+  }
+
+  private async completeReturn(
+    returnUrl: string,
+    expectedStateNonce?: string,
+  ): Promise<OAuthSessionOutcome> {
+    if (!this.#options.validateReturnUrl(returnUrl)) return { type: 'invalid_return' };
+    const callbackParams = parseCallbackParams(returnUrl);
+    if (callbackParams === null) return { type: 'invalid_return' };
+
+    const stored = await this.#options.storage.load();
+    if (stored === null) return { type: 'storage_mismatch' };
+    if (this.isStale(stored)) {
+      await this.#options.storage.clear();
+      return { type: 'timed_out' };
+    }
+    if (
+      (expectedStateNonce !== undefined && stored.stateNonce !== expectedStateNonce) ||
+      callbackParams['state'] !== stored.stateNonce
+    ) {
+      return { type: 'storage_mismatch' };
+    }
+    if (!sameReturnEndpoint(stored.returnUrl, returnUrl)) return { type: 'invalid_return' };
+
+    await this.#options.storage.clear();
+    return { type: 'success', callbackParams };
+  }
+
+  private isStale(session: OAuthInFlightSession): boolean {
+    const elapsed = this.#options.clock.now() - session.createdAt;
+    return elapsed < 0 || elapsed >= this.#options.timeoutMs;
+  }
+
+  private async clearIfCurrent(stateNonce: string): Promise<void> {
+    const stored = await this.#options.storage.load();
+    if (stored?.stateNonce === stateNonce) await this.#options.storage.clear();
+  }
+
+  private async withTimeout<T>(
+    operation: Promise<T>,
+    onTimeout: () => void,
+  ): Promise<T | typeof TIMED_OUT> {
+    let timer: unknown;
+    const timeout = new Promise<typeof TIMED_OUT>((resolve) => {
+      timer = this.#options.clock.setTimeout(() => {
+        try {
+          onTimeout();
+        } finally {
+          resolve(TIMED_OUT);
+        }
+      }, this.#options.timeoutMs);
+    });
+    try {
+      return await Promise.race([operation, timeout]);
+    } finally {
+      this.#options.clock.clearTimeout(timer);
+    }
+  }
+}
+
+export function createReturnUrlValidator(policy: OAuthReturnUrlPolicy): OAuthReturnUrlValidator {
+  const origin = parseOrigin(policy.origin);
+  const paths = new Set(policy.paths.map(normalizeAllowedPath));
+  if (paths.size === 0) throw new TypeError('At least one OAuth return path is required.');
+  return (returnUrl) => {
+    const parsed = parseUrl(returnUrl);
+    return (
+      parsed !== null &&
+      parsed.username === '' &&
+      parsed.password === '' &&
+      exactOrigin(parsed) === origin &&
+      paths.has(parsed.pathname)
+    );
+  };
+}
+
+function parseOrigin(origin: string): string {
+  const parsed = parseUrl(origin);
+  if (
+    parsed?.username !== '' ||
+    parsed.password !== '' ||
+    (parsed.pathname !== '' && parsed.pathname !== '/') ||
+    parsed.search !== '' ||
+    parsed.hash !== ''
+  ) {
+    throw new TypeError('OAuth return origin must contain only a scheme and authority.');
+  }
+  return exactOrigin(parsed);
+}
+
+function normalizeAllowedPath(path: string): string {
+  if (!path.startsWith('/') || path.includes('?') || path.includes('#')) {
+    throw new TypeError('OAuth return paths must be absolute paths without a query or fragment.');
+  }
+  const parsed = new URL(path, 'https://baukit.invalid');
+  if (parsed.pathname !== path) throw new TypeError('OAuth return paths must be normalized.');
+  return path;
+}
+
+function parseCallbackParams(returnUrl: string): Readonly<Record<string, string>> | null {
+  const parsed = parseUrl(returnUrl);
+  if (parsed === null) return null;
+  const values: Record<string, string> = {};
+  for (const [key, value] of parsed.searchParams) {
+    if (Object.hasOwn(values, key)) return null;
+    values[key] = value;
+  }
+  return Object.freeze(values);
+}
+
+function sameReturnEndpoint(expected: string, actual: string): boolean {
+  const expectedUrl = parseUrl(expected);
+  const actualUrl = parseUrl(actual);
+  return (
+    expectedUrl !== null &&
+    actualUrl !== null &&
+    exactOrigin(expectedUrl) === exactOrigin(actualUrl) &&
+    expectedUrl.pathname === actualUrl.pathname
+  );
+}
+
+function exactOrigin(url: URL): string {
+  return url.origin === 'null' ? `${url.protocol}//${url.host}` : url.origin;
+}
+
+function parseUrl(value: string): URL | null {
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}

package/src/provider-registry.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { connectionStateFromServer } from './connection-health.js';
+import { createProviderRegistry } from './provider-registry.js';
+
+describe('provider registry', () => {
+  it('keeps product data and connectors in registration order', () => {
+    const startCalendarOAuth = () => Promise.resolve('calendar');
+    const startStorageOAuth = () => Promise.resolve('storage');
+    const registry = createProviderRegistry([
+      {
+        id: 'calendar',
+        labelKey: 'integrations.calendar',
+        capabilities: ['read_events', 'write_events'],
+        connector: { startOAuth: startCalendarOAuth, icon: 'calendar-icon' },
+        connection: connectionStateFromServer({ state: 'healthy' }),
+      },
+      {
+        id: 'storage',
+        labelKey: 'integrations.storage',
+        capabilities: ['read_files'],
+        connector: { startOAuth: startStorageOAuth, icon: 'storage-icon' },
+        connection: connectionStateFromServer({ state: 'revoked' }),
+      },
+    ] as const);
+
+    expect(registry.list().map(({ id }) => id)).toEqual(['calendar', 'storage']);
+    expect(registry.get('calendar')).toMatchObject({
+      currentState: 'connected',
+      availableActions: ['disconnect'],
+    });
+    expect(registry.get('calendar')?.connector?.startOAuth).toBe(startCalendarOAuth);
+    expect(registry.get('storage')).toMatchObject({
+      currentState: 'needs_reconnect',
+      availableActions: ['reconnect'],
+    });
+    expect(registry.get('storage')?.capabilities).toEqual(['read_files']);
+    expectTypeOf(registry.get('calendar')?.connector?.startOAuth).toEqualTypeOf<
+      (() => Promise<string>) | undefined
+    >();
+  });
+
+  it('copies caller-owned arrays', () => {
+    const capabilities: string[] = ['read'];
+    const registry = createProviderRegistry([
+      {
+        id: 'documents',
+        labelKey: 'integrations.documents',
+        capabilities,
+        connection: connectionStateFromServer({ state: 'healthy' }),
+      },
+    ]);
+    capabilities.push('write');
+    expect(registry.get('documents')?.capabilities).toEqual(['read']);
+  });
+
+  it('overlays connection states without changing the original registry', () => {
+    const registry = createProviderRegistry([
+      {
+        id: 'calendar',
+        labelKey: 'integrations.calendar',
+        capabilities: ['read_events'],
+        connector: { startOAuth: () => Promise.resolve() },
+      },
+      {
+        id: 'storage',
+        labelKey: 'integrations.storage',
+        capabilities: ['read_files'],
+        connector: { startOAuth: () => Promise.resolve() },
+      },
+    ] as const);
+
+    const connected = registry.withConnectionStates(
+      new Map([['calendar', connectionStateFromServer({ state: 'healthy' })]]),
+    );
+
+    expect(registry.get('calendar')).toMatchObject({
+      currentState: 'disconnected',
+      availableActions: [],
+    });
+    expect(connected.get('calendar')).toMatchObject({
+      currentState: 'connected',
+      availableActions: ['disconnect'],
+    });
+    expect(connected.get('storage')).toMatchObject({
+      currentState: 'disconnected',
+      availableActions: [],
+    });
+    expect(connected.get('calendar')?.connector).toBe(registry.get('calendar')?.connector);
+    expect(connected.list().map(({ id }) => id)).toEqual(['calendar', 'storage']);
+  });
+
+  it('accepts record state overlays and ignores unknown state IDs', () => {
+    const registry = createProviderRegistry([
+      {
+        id: 'calendar',
+        labelKey: 'integrations.calendar',
+        capabilities: ['read_events'],
+      },
+    ] as const);
+    const states = {
+      calendar: connectionStateFromServer({ state: 'revoked' }),
+      unknown: connectionStateFromServer({ state: 'healthy' }),
+    };
+
+    const connected = registry.withConnectionStates(states);
+
+    expect(connected.get('calendar')).toMatchObject({
+      currentState: 'needs_reconnect',
+      availableActions: ['reconnect'],
+    });
+    expect(connected.get('unknown')).toBeUndefined();
+  });
+
+  it('rejects duplicate product IDs', () => {
+    expect(() =>
+      createProviderRegistry([
+        {
+          id: 'duplicate',
+          labelKey: 'first',
+          capabilities: [],
+          connection: connectionStateFromServer({ state: 'healthy' }),
+        },
+        {
+          id: 'duplicate',
+          labelKey: 'second',
+          capabilities: [],
+          connection: connectionStateFromServer({ state: 'disconnected' }),
+        },
+      ]),
+    ).toThrow('Provider IDs must be unique.');
+  });
+});

package/src/provider-registry.ts

@@ -0,0 +1,130 @@
+import type { ConnectionAction, ConnectionState, ConnectionStatus } from './connection-health.js';
+
+export interface ProviderRegistration<
+  ProviderId extends string,
+  LabelKey extends string,
+  Capability extends string,
+  Connector = undefined,
+> {
+  readonly id: ProviderId;
+  readonly labelKey: LabelKey;
+  readonly capabilities: readonly Capability[];
+  readonly connector?: Connector;
+  readonly connection?: ConnectionState;
+}
+
+export interface RegisteredProvider<
+  ProviderId extends string,
+  LabelKey extends string,
+  Capability extends string,
+  Connector = undefined,
+> {
+  readonly id: ProviderId;
+  readonly labelKey: LabelKey;
+  readonly capabilities: readonly Capability[];
+  readonly connector?: Connector;
+  readonly currentState: ConnectionStatus;
+  readonly availableActions: readonly ConnectionAction[];
+}
+
+export type ProviderConnectionStates<ProviderId extends string> =
+  ReadonlyMap<ProviderId, ConnectionState> | Readonly<Partial<Record<ProviderId, ConnectionState>>>;
+
+type ProviderDefinition<
+  ProviderId extends string,
+  LabelKey extends string,
+  Capability extends string,
+  Connector,
+> = Omit<ProviderRegistration<ProviderId, LabelKey, Capability, Connector>, 'connection'>;
+
+export class ProviderRegistry<
+  ProviderId extends string,
+  LabelKey extends string,
+  Capability extends string,
+  Connector = undefined,
+> {
+  readonly #definitions: readonly ProviderDefinition<ProviderId, LabelKey, Capability, Connector>[];
+  readonly #providers: readonly RegisteredProvider<ProviderId, LabelKey, Capability, Connector>[];
+  readonly #byId: ReadonlyMap<
+    string,
+    RegisteredProvider<ProviderId, LabelKey, Capability, Connector>
+  >;
+
+  public constructor(
+    registrations: readonly ProviderRegistration<ProviderId, LabelKey, Capability, Connector>[],
+  ) {
+    const definitions = registrations.map((registration) =>
+      Object.freeze({
+        id: registration.id,
+        labelKey: registration.labelKey,
+        capabilities: Object.freeze([...registration.capabilities]),
+        ...('connector' in registration ? { connector: registration.connector } : {}),
+      }),
+    );
+    const ids = new Set(definitions.map((definition) => definition.id));
+    if (ids.size !== definitions.length) throw new TypeError('Provider IDs must be unique.');
+
+    const providers = definitions.map((definition, index) => {
+      const connection = registrations[index]?.connection;
+      return Object.freeze({
+        ...definition,
+        currentState: connection?.status ?? 'disconnected',
+        availableActions: Object.freeze(
+          connection === undefined ? [] : [...connection.availableActions],
+        ),
+      });
+    });
+    this.#definitions = Object.freeze(definitions);
+    this.#providers = Object.freeze(providers);
+    this.#byId = new Map(providers.map((provider) => [provider.id, provider]));
+  }
+
+  public list(): readonly RegisteredProvider<ProviderId, LabelKey, Capability, Connector>[] {
+    return this.#providers;
+  }
+
+  public get(
+    providerId: string,
+  ): RegisteredProvider<ProviderId, LabelKey, Capability, Connector> | undefined {
+    return this.#byId.get(providerId);
+  }
+
+  public withConnectionStates(
+    states: ProviderConnectionStates<ProviderId>,
+  ): ProviderRegistry<ProviderId, LabelKey, Capability, Connector> {
+    const registrations = this.#definitions.map((definition) => {
+      const connection = getConnectionState(states, definition.id);
+      return {
+        ...definition,
+        ...(connection === undefined ? {} : { connection }),
+      };
+    });
+    return new ProviderRegistry<ProviderId, LabelKey, Capability, Connector>(registrations);
+  }
+}
+
+export function createProviderRegistry<
+  ProviderId extends string,
+  LabelKey extends string,
+  Capability extends string,
+  Connector = undefined,
+>(
+  registrations: readonly ProviderRegistration<ProviderId, LabelKey, Capability, Connector>[],
+): ProviderRegistry<ProviderId, LabelKey, Capability, Connector> {
+  return new ProviderRegistry(registrations);
+}
+
+function getConnectionState<ProviderId extends string>(
+  states: ProviderConnectionStates<ProviderId>,
+  providerId: ProviderId,
+): ConnectionState | undefined {
+  if (isReadonlyMap(states)) return states.get(providerId);
+  if (!Object.hasOwn(states, providerId)) return undefined;
+  return states[providerId];
+}
+
+function isReadonlyMap<ProviderId extends string>(
+  states: ProviderConnectionStates<ProviderId>,
+): states is ReadonlyMap<ProviderId, ConnectionState> {
+  return typeof Reflect.get(states, 'get') === 'function';
+}