diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58e10b0..b9c44be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,18 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
 ## [Unreleased]
 
 ### Changed
+- **Authentication and connection lifecycle extracted into `ConnectionSession`**
+  (#276 Phase 2). OAuth PKCE login/refresh, Basic-auth probing, IdP config
+  resolution, identity, sign-in/out, and the cross-tab dashboard auth handoff
+  now live in `src/application/connection-session.ts` — constructible without
+  `App`/`AppState`/DOM, with rendering inverted through an injected
+  `onAuthLost` shell callback (the session never renders or toasts). The app
+  exposes it as `app.conn`; `app.chCtx` remains the same single live ClickHouse
+  context object (now session-owned). The scalar auth fields
+  (`token`/`refreshToken`/`authMode`/`chAuth`/`basicUserClaim`/`idpId`) left
+  the `App` contract; view/bootstrap-consumed members stay as one-line
+  delegates slated for removal in the issue's Phase 5. Behavior, storage keys,
+  handoff message pinning, and error strings are byte-identical.
 - **Query execution extracted into an application service** (#276 Phases 0–1,
   the first step of the app.ts → services refactor). The shared
   request/stream/normalize core (`runReadInto`) and the multiquery-script
diff --git a/src/application/connection-session.ts b/src/application/connection-session.ts
new file mode 100644
index 0000000..6085b68
--- /dev/null
+++ b/src/application/connection-session.ts
@@ -0,0 +1,467 @@
+// #276 Phase 2's ConnectionSession — auth + config + ClickHouse connection
+// lifecycle (OAuth PKCE login/refresh, Basic probing, IdP config resolution,
+// cross-tab auth handoff), constructible without App/AppState/DOM; no imports
+// from src/ui/** or src/editor/** (check:arch enforces). Rendering is the
+// shell's job — auth loss surfaces through the injected `onAuthLost` callback,
+// never a render/toast call. This is a byte-for-byte port of the auth/config/
+// connection lifecycle that used to live inline in src/ui/app.ts (see that
+// file's history around the OAuth/basic-auth/handoff sections) — comments
+// below are carried over, adapted only where the code itself moved (e.g.
+// `app.token` becomes a closed-over local, `ss`/`loc`/`win` become the
+// injected `deps.storage`/`deps.location`/`deps.win`, and a couple of
+// `app.renderApp()`/`renderLoginApp()` calls are gone because rendering isn't
+// this module's job any more — see each call site below for the specific
+// note). `openDashboard` itself (opening the new tab) stays app-side; this
+// module only owns the credential-grant half of the handoff.
+
+import { decodeJwtPayload, isTokenExpired } from '../core/jwt.js';
+import { generatePKCE, randomState } from '../core/pkce.js';
+import type { PkceCrypto } from '../core/pkce.js';
+import { configBase } from '../core/dashboard.js';
+import { resolveTarget } from '../core/target.js';
+import {
+  snapshotAuth, restoreAuth, hasAuth, isAuthRequest, isAuthGrant, AUTH_REQUEST, AUTH_GRANT,
+} from '../core/auth-handoff.js';
+import type { AuthSnapshot, StorageLike } from '../core/auth-handoff.js';
+import { buildAuthorizeUrl, refreshTokens, bearerFromTokens } from '../net/oauth.js';
+import { memoizeConfig, loadConfigDoc, resolveIdp } from '../net/oauth-config.js';
+import type { ConfigDoc, ResolvedIdpConfig, ChAuthKind } from '../net/oauth-config.js';
+import type { ChCtx as NetChCtx, queryJson } from '../net/ch-client.js';
+
+// ── Injected dependency seam ─────────────────────────────────────────────────
+
+/** The sessionStorage-like surface this module needs — `core/auth-handoff.js`'s
+ *  canonical `StorageLike` plus `removeItem` (the token/handoff bookkeeping
+ *  below removes one-shot keys alongside `getItem`/`setItem`). */
+export interface SessionStorageLike extends StorageLike {
+  removeItem(key: string): void;
+}
+
+/** The minimal Web Crypto surface PKCE generation needs — real Web Crypto
+ *  (browser `crypto` or Node's `webcrypto`) or an injectable stub: exactly
+ *  `core/pkce.js`'s own `PkceCrypto` seam, re-exported under this session's
+ *  naming so deps read uniformly. A real `Crypto` object satisfies it without
+ *  a cast; a test stub only implements two members. */
+export type SessionCrypto = PkceCrypto;
+
+/** Every side effect this session needs, injected as a narrow bag — mirrors
+ *  `query-execution-service.ts`'s own `QueryExecutionDeps` seam. Production
+ *  wires the real browser/env objects (`main.js`'s bootstrap resolves
+ *  `handoffMs`/`handoffListenMs` defaults before constructing the session —
+ *  this module never defaults them itself); tests inject plain stubs. */
+export interface ConnectionSessionDeps {
+  fetch: typeof fetch;
+  storage: SessionStorageLike;
+  /** `href` is WRITTEN (the OAuth redirect assigns it) as well as read. */
+  location: { origin: string; pathname: string; search: string; href: string };
+  crypto: SessionCrypto;
+  /** Cross-tab auth-handoff listeners/timeouts. */
+  win: Pick<Window, 'addEventListener' | 'removeEventListener' | 'setTimeout'>;
+  /** Basic-auth sign-in probe. */
+  queryJson: typeof queryJson;
+  /** The child's own wait for a grant once it asks (a same-origin reply is
+   *  near-instant, so this is short) — resolved by the caller; the historical
+   *  4000ms env default stays app-side. */
+  handoffMs: number;
+  /** How long the opener keeps listening for a request — far longer than
+   *  `handoffMs` because it must survive the child's cold JS load before the
+   *  child can even ask; a short opener window would drop a slow tab's
+   *  request and force a needless re-login. The historical 30000ms env
+   *  default stays app-side. */
+  handoffListenMs: number;
+  /** Auth was lost (no token / expired-and-unrefreshable / CH rejected a
+   *  valid login). The session never renders — it calls this and lets the
+   *  shell decide how to show the login screen. */
+  onAuthLost: (detail?: string) => void;
+}
+
+// ── The ClickHouse auth context ──────────────────────────────────────────────
+
+/** The live ClickHouse auth context this session owns — `origin`/
+ *  `authConfirmed` are mutated IN PLACE by `signOut`/`connectBasic`/
+ *  `applyAuthSnapshot` here, and by `net/ch-client.js`'s `authedFetch` (its
+ *  own one-shot latch) — this ONE object is never reconstructed, only ever
+ *  mutated, so a caller holding a reference (or passing it straight into
+ *  ch-client's functions) always observes the current auth state. Assignable
+ *  to `net/ch-client.js`'s own `ChCtx` (whose `authConfirmed`/`authHeader`
+ *  are optional there, since some callers build a throwaway ctx without
+ *  them — this session always supplies both, matching the stricter
+ *  `ui/app.types.ts` `ChCtx` shape the rest of the app already reads through,
+ *  redeclared here rather than imported since `src/application/**` may not
+ *  import `src/ui/**`). */
+export interface SessionChCtx {
+  fetch: typeof fetch;
+  origin: string;
+  authConfirmed: boolean;
+  getToken(): Promise<string | null>;
+  refresh(): Promise<boolean>;
+  authHeader(token: string): string;
+  onSignedOut(detail?: string): void;
+}
+
+// ── The session ───────────────────────────────────────────────────────────
+
+/** The auth + config + ClickHouse connection lifecycle, constructible without
+ *  App/AppState/DOM. See `createConnectionSession` for construction/seeding
+ *  and each method below for the ported behavior. */
+export interface ConnectionSession {
+  readonly basePath: string;
+  readonly hostHint: string;
+  readonly chCtx: SessionChCtx;
+
+  // state accessors (test-support + shell display; do not log values)
+  token(): string | null;
+  refreshToken(): string | null;
+  authMode(): 'oauth' | 'basic';
+  idpId(): string | null;
+  chAuth(): ChAuthKind;
+  basicUserClaim(): string;
+  isSignedIn(): boolean;
+  email(): string;
+  host(): string;
+
+  // config
+  loadIdps(): Promise<ConfigDoc>;
+  selectIdp(id: string): void;
+  resolveConfig(): Promise<ResolvedIdpConfig>;
+  ensureConfig(): Promise<ResolvedIdpConfig | null>;
+
+  // lifecycle
+  setTokens(id: string, refresh?: string): void;
+  getToken(): Promise<string | null>;
+  beginOAuth(idpId?: string, targetOrigin?: string): Promise<void>;
+  connectBasic(input: { username: string; password: string; host?: string }): Promise<void>;
+  signOut(): void;
+  ensureFreshToken(): Promise<boolean>;
+
+  // cross-tab handoff (message contract: core/auth-handoff)
+  grantHandoffTo(child: Window): void;
+  receiveAuthHandoff(env: { opener?: Window | null }): Promise<boolean>;
+}
+
+export function createConnectionSession(deps: ConnectionSessionDeps): ConnectionSession {
+  const { storage: ss, location: loc, crypto: cryptoObj, fetch: fetchFn, win, queryJson: queryJsonFn } = deps;
+
+  // Two ways to be signed in: OAuth (a JWT bearer, the default) or 'basic' —
+  // a ClickHouse username/password sent as Authorization: Basic, optionally
+  // against another host. A live basic session is restored from sessionStorage
+  // (ch_basic_*), mirroring how the OAuth token is restored below.
+  let token: string | null = ss.getItem('oauth_id_token');
+  let refreshTok: string | null = ss.getItem('oauth_refresh_token');
+  let authMode: 'oauth' | 'basic' = ss.getItem('ch_basic_auth') ? 'basic' : 'oauth';
+  const basicCreds = (): string | null => ss.getItem('ch_basic_auth');
+  const basicUser = (): string => ss.getItem('ch_basic_user') || '';
+  const originHost = (o: string): string => { try { return new URL(o).host; } catch { return ''; } };
+
+  // config.json may list several IdPs. Fetch the doc once; resolve OIDC
+  // discovery per selected IdP. The chosen IdP id is persisted so it survives
+  // the OAuth redirect (like oauth_state) and drives token exchange/refresh.
+  // configBase strips a trailing `/dashboard` so config.json / OAuth discovery
+  // resolve from the SPA base (`/sql/config.json`) on the dashboard route too.
+  // The same base is the single source of truth for the workbench<->dashboard
+  // links (openDashboard, the dashboard's Back link) rather than hardcoding
+  // `/sql` in several shapes.
+  const basePath = configBase(loc.pathname);
+  const loadDoc = memoizeConfig(() => loadConfigDoc(fetchFn, basePath));
+  const resolvedCache = new Map<string, Promise<ResolvedIdpConfig>>();
+  let idpId: string | null = ss.getItem('oauth_idp') || null;
+  function selectIdp(id: string): void { idpId = id; ss.setItem('oauth_idp', id); }
+  async function resolveConfig(): Promise<ResolvedIdpConfig> {
+    const { idps } = await loadDoc();
+    const chosen = idps.find((i) => i.id === idpId) || idps[0];
+    idpId = chosen.id;
+    if (!resolvedCache.has(chosen.id)) resolvedCache.set(chosen.id, resolveIdp(fetchFn, chosen));
+    return resolvedCache.get(chosen.id)!;
+  }
+
+  // A `?host=` query param pre-fills the credential server address on the login
+  // screen (and disables SSO, which only targets the serving host).
+  const hostHint = new URLSearchParams(loc.search || '').get('host') || '';
+
+  // isSignedIn uses ZERO skew (bufferSeconds=0) — it's a point-in-time "is the
+  // token still technically valid right now" check (drives whether the
+  // workbench renders at all). getToken (below) uses the default 60s skew
+  // instead — it drives whether a QUERY is about to be sent with a token that
+  // will likely have expired by the time the request lands, so it refreshes
+  // proactively before that happens. Same isTokenExpired call, deliberately
+  // different bufferSeconds for deliberately different questions.
+  const isSignedIn = (): boolean => (authMode === 'basic'
+    ? !!basicCreds()
+    : !!token && !isTokenExpired(token, 0));
+
+  // The CH-facing identity for the current token — what currentUser() will be:
+  // for ch_auth=basic it's the Basic username (honouring basicUserClaim); for
+  // bearer it's the email the token-processor keys on. Shared by authHeader and
+  // the header display so the UI never shows a different claim than CH sees.
+  function chUsername(p: Record<string, unknown>): string {
+    return String((chAuthVal === 'basic' && basicUserClaimVal && p[basicUserClaimVal])
+      || p.email || p.preferred_username || p.sub || '');
+  }
+  const email = (): string => (authMode === 'basic'
+    ? basicUser()
+    : chUsername(decodeJwtPayload(token)));
+
+  function setTokens(id: string, refresh?: string): void {
+    token = id;
+    ss.setItem('oauth_id_token', id);
+    if (refresh) {
+      refreshTok = refresh;
+      ss.setItem('oauth_refresh_token', refresh);
+    }
+    // The PKCE verifier + CSRF state are one-shot — done with them once we hold
+    // tokens. (The refresh path also lands here; they're already gone → no-op.)
+    ss.removeItem('oauth_verifier');
+    ss.removeItem('oauth_state');
+  }
+  function clearTokens(): void {
+    token = null;
+    refreshTok = null;
+    idpId = null;
+    authMode = 'oauth';
+    chCtx.origin = loc.origin;
+    chCtx.authConfirmed = false; // a fresh sign-in starts unconfirmed again
+    ['oauth_id_token', 'oauth_refresh_token', 'oauth_verifier', 'oauth_state', 'oauth_idp', 'oauth_origin',
+      'ch_basic_auth', 'ch_basic_user', 'ch_basic_origin'].forEach((k) => ss.removeItem(k));
+  }
+  // `signOut` is exactly today's app.ts `clearTokens()` — no render. (app.ts's
+  // own `app.signOut` additionally re-renders the login screen; that's the
+  // shell's job now, done by whatever caller notices signOut() was called.)
+  const signOut = (): void => clearTokens();
+
+  // --- OAuth -------------------------------------------------------------
+  async function beginOAuth(idpArg?: string, targetOrigin?: string): Promise<void> {
+    if (idpArg) selectIdp(idpArg);
+    // A picked saved-connection can target another cluster: stash its origin so
+    // the rebuilt chCtx (after the redirect reload) POSTs the bearer there.
+    // Survives the redirect like oauth_state/oauth_idp; cleared for serving-host SSO.
+    if (targetOrigin) ss.setItem('oauth_origin', targetOrigin);
+    else ss.removeItem('oauth_origin');
+    const cfg = await resolveConfig();
+    const { verifier, challenge } = await generatePKCE(cryptoObj);
+    const state = randomState(cryptoObj);
+    ss.setItem('oauth_verifier', verifier);
+    ss.setItem('oauth_state', state);
+    loc.href = buildAuthorizeUrl(cfg, {
+      redirectUri: loc.origin + loc.pathname,
+      challenge,
+      state,
+    });
+  }
+
+  async function refresh(): Promise<boolean> {
+    // Basic credentials don't expire and can't be refreshed; a surviving 401
+    // means the password is wrong → authedFetch falls through to onSignedOut.
+    if (authMode === 'basic') return false;
+    const cfg = await resolveConfig();
+    const tokens = await refreshTokens(fetchFn, cfg, refreshTok);
+    const bearer = bearerFromTokens(tokens, cfg.bearer);
+    if (!bearer) return false;
+    // `bearer` is only ever truthy when `tokens` (its own source) is non-null.
+    setTokens(bearer, tokens?.refresh_token);
+    return true;
+  }
+
+  async function getToken(): Promise<string | null> {
+    // In basic mode the stored credential is the "token" authedFetch carries.
+    if (authMode === 'basic') return basicCreds();
+    if (!token) return null;
+    if (!isTokenExpired(token)) return token;
+    if (await refresh()) return token;
+    clearTokens();
+    return null;
+  }
+
+  // --- ClickHouse context --------------------------------------------------
+  // How the token is presented to CH. 'bearer' (token_processor) or 'basic'
+  // (OSS + a verifier like ch-jwt-verify, where the JWT is the Basic password
+  // and the username is the token's email). Resolved from config by ensureConfig.
+  let chAuthVal: ChAuthKind = 'bearer';
+  // Which claim becomes the Basic username (per-IdP, from config). Empty → the
+  // default chain. Lets one IdP map to a CH username distinct from another's.
+  let basicUserClaimVal = '';
+  function authHeader(t: string): string {
+    // Basic mode: `t` is already base64(user:pass) — send it verbatim.
+    if (authMode === 'basic') return 'Basic ' + t;
+    if (chAuthVal !== 'basic') return 'Bearer ' + t;
+    const user = chUsername(decodeJwtPayload(t));
+    return 'Basic ' + btoa(unescape(encodeURIComponent(user + ':' + t)));
+  }
+  const chCtx: SessionChCtx = {
+    fetch: fetchFn,
+    // Where queries POST: the serving origin for OAuth, or the (possibly
+    // cross-origin) target chosen at credential sign-in for basic mode.
+    origin: authMode === 'basic'
+      ? (ss.getItem('ch_basic_origin') || loc.origin)
+      : (ss.getItem('oauth_origin') || loc.origin),
+    // Flips true after the first 2xx; gates whether a later 401/403 is treated
+    // as a sign-in failure (only before auth is confirmed) or a query error.
+    authConfirmed: false,
+    getToken,
+    refresh,
+    authHeader,
+    // detail is set when CH rejects a *valid* login (authorization denial); the
+    // no-arg calls (no token / expired + refresh failed) fall back to expiry.
+    onSignedOut: (detail?: string) => {
+      clearTokens();
+      deps.onAuthLost(detail || 'Your session expired — please sign in again.');
+    },
+  };
+
+  // Load config (once) and apply the CH auth mode before any query runs.
+  // Fail-soft: if config can't be loaded we keep the current mode (bearer)
+  // rather than blocking the query.
+  async function ensureConfig(): Promise<ResolvedIdpConfig | null> {
+    // Basic mode needs no OAuth config — the auth scheme is fixed.
+    if (authMode === 'basic') return null;
+    try {
+      const cfg = await resolveConfig();
+      chAuthVal = cfg.chAuth;
+      basicUserClaimVal = cfg.basicUserClaim || '';
+      return cfg;
+    } catch {
+      return null;
+    }
+  }
+
+  // --- credentials (HTTP Basic) sign-in ----------------------------------
+  // Validate a ClickHouse username/password against `host` (blank → the serving
+  // host) with a probe query, then commit the session (NO render — the shell
+  // re-renders after connectBasic resolves; app.ts's own `connect` used to call
+  // `app.renderApp()` here, which is the shell's job now). The probe uses a
+  // throwaway ctx so a bad password surfaces CH's own reason here (rejected as
+  // a thrown Error) instead of auto-triggering onAuthLost.
+  async function connectBasic({ username, password, host }: { username: string; password: string; host?: string }): Promise<void> {
+    const user = String(username || '').trim();
+    const target = resolveTarget(host, loc.origin);
+    const creds = btoa(unescape(encodeURIComponent(user + ':' + (password || ''))));
+    const probeCtx: NetChCtx = {
+      fetch: fetchFn,
+      origin: target,
+      getToken: async () => creds,
+      authHeader: () => 'Basic ' + creds,
+      refresh: async () => false,
+      onSignedOut: (detail?: string) => { throw new Error(detail || 'Authentication failed'); },
+    };
+    await queryJsonFn(probeCtx, 'SELECT 1');
+    // Probe passed → commit the session and switch the live ctx to the target.
+    authMode = 'basic';
+    ss.setItem('ch_basic_auth', creds);
+    ss.setItem('ch_basic_user', user);
+    ss.setItem('ch_basic_origin', target);
+    chCtx.origin = target;
+  }
+
+  // --- dashboard (#149 D1) -------------------------------------------------
+  // ensureConfig + getToken, resolving (and refreshing) the auth token ONCE.
+  // The dashboard calls this before fanning tiles out, so the tiles never each
+  // race an expired-token refresh (a rotating refresh token used N-ways at once
+  // would invalidate itself), and a single sign-out is handled by the caller
+  // instead of N tiles each firing onSignedOut. Also used by bootstrap to
+  // refresh a handed-off-but-expired token before falling back to login.
+  async function ensureFreshToken(): Promise<boolean> {
+    await ensureConfig();
+    return !!(await getToken());
+  }
+
+  // One-time cross-tab auth handoff. The dashboard opens in a new same-origin
+  // tab whose sessionStorage starts empty; rather than force a second sign-in,
+  // this (opener) side grants its live credentials once when the child asks.
+  // Both sides pin the target origin AND the peer window; a timeout stops the
+  // opener listening if the child never asks. Message contract: core/auth-handoff.
+  // Two windows: the child waits `handoffMs` for a grant once it *asks* (a
+  // same-origin reply is near-instant, so this is short); the opener listens far
+  // longer (`handoffListenMs`) because it must survive the child's cold JS load
+  // before the child can ask — a short opener window would drop a slow tab's
+  // request and force a needless re-login.
+  function grantHandoffTo(child: Window): void {
+    const onMsg = (e: MessageEvent): void => {
+      if (!isAuthRequest(e, loc.origin, child)) return;
+      const creds = snapshotAuth(ss);
+      // Only grant when we actually hold credentials — never hand over an empty
+      // snapshot (which the child would have to reject anyway).
+      if (hasAuth(creds)) child.postMessage({ type: AUTH_GRANT, creds }, loc.origin);
+      win.removeEventListener('message', onMsg);
+    };
+    win.addEventListener('message', onMsg);
+    win.setTimeout(() => win.removeEventListener('message', onMsg), deps.handoffListenMs);
+  }
+
+  // Restore a handed-off credential snapshot into BOTH this tab's sessionStorage
+  // and the already-constructed in-memory auth fields — token/authMode/idp/origin
+  // were snapshotted from an empty ss at construction, so writing keys back alone
+  // wouldn't take effect until a reload.
+  function applyAuthSnapshot(creds: AuthSnapshot): void {
+    restoreAuth(ss, creds);
+    if (creds.ch_basic_auth) {
+      authMode = 'basic';
+      chCtx.origin = creds.ch_basic_origin || loc.origin;
+    } else {
+      if (creds.oauth_id_token) setTokens(creds.oauth_id_token, creds.oauth_refresh_token);
+      if (creds.oauth_idp) idpId = creds.oauth_idp;
+      chCtx.origin = creds.oauth_origin || loc.origin;
+    }
+  }
+  // Child side: ask the opener for credentials once. Resolves true once a valid
+  // grant is applied; false when there's no opener or the request times out (a
+  // cold/bookmarked visit → the caller falls through to the normal login flow).
+  function receiveAuthHandoff(handoffEnv: { opener?: Window | null }): Promise<boolean> {
+    return new Promise((resolve) => {
+      const opener = handoffEnv.opener;
+      if (!opener) { resolve(false); return; }
+      let done = false;
+      const finish = (ok: boolean): void => {
+        if (done) return;
+        done = true;
+        win.removeEventListener('message', onMsg);
+        resolve(ok);
+      };
+      const onMsg = (e: MessageEvent): void => {
+        if (!isAuthGrant(e, loc.origin, opener)) return;
+        // `e.data` is a real handoff grant `{type, creds}` once isAuthGrant has
+        // confirmed `type` — `AuthMessageEvent`'s own contract type only pins
+        // `type` (the shared predicate's whole point); `creds` rides alongside.
+        const data = e.data as { type?: string; creds?: AuthSnapshot } | null;
+        // Ignore an empty grant (opener signed out / mid-sign-in) — keep waiting so
+        // the request times out into the normal login rather than falsely
+        // reporting success with no credentials applied.
+        if (!hasAuth(data?.creds)) return;
+        applyAuthSnapshot(data!.creds!);
+        finish(true);
+      };
+      win.addEventListener('message', onMsg);
+      opener.postMessage({ type: AUTH_REQUEST }, loc.origin);
+      win.setTimeout(() => finish(false), deps.handoffMs);
+    });
+  }
+
+  return {
+    basePath,
+    hostHint,
+    chCtx,
+    token: () => token,
+    refreshToken: () => refreshTok,
+    authMode: () => authMode,
+    idpId: () => idpId,
+    chAuth: () => chAuthVal,
+    basicUserClaim: () => basicUserClaimVal,
+    isSignedIn,
+    email,
+    // The host queries actually go to. chCtx.origin already resolves to the basic
+    // target, the picked OAuth cluster (oauth_origin), or the serving origin — so a
+    // cross-origin OAuth connection shows the cluster, not localhost. (URL.host drops
+    // a default :443, so a 443 cluster shows a bare hostname; an 8443 one shows :8443.)
+    host: () => originHost(chCtx.origin) || 'clickhouse',
+    loadIdps: loadDoc,
+    selectIdp,
+    resolveConfig,
+    ensureConfig,
+    setTokens,
+    getToken,
+    beginOAuth,
+    connectBasic,
+    signOut,
+    ensureFreshToken,
+    grantHandoffTo,
+    receiveAuthHandoff,
+  };
+}
diff --git a/src/core/jwt.ts b/src/core/jwt.ts
index ba1167e..4fb3bd6 100644
--- a/src/core/jwt.ts
+++ b/src/core/jwt.ts
@@ -4,7 +4,8 @@
 
 /** A decoded JWT payload — `exp` (seconds since epoch) is the one claim this
  *  module reads itself; other claims (email/preferred_username/sub/…) pass
- *  through untyped for `app.js`'s `chUsername`. */
+ *  through untyped for the ConnectionSession's `chUsername`
+ *  (`application/connection-session.ts`, #276 Phase 2). */
 export interface JwtPayload {
   exp?: number;
   [key: string]: unknown;
diff --git a/src/core/pkce.ts b/src/core/pkce.ts
index d598513..f0a54e2 100644
--- a/src/core/pkce.ts
+++ b/src/core/pkce.ts
@@ -7,13 +7,13 @@
  *  `ArrayBuffer`-backed form (`new Uint8Array(n)`'s actual type) since
  *  lib.dom's own `Crypto.getRandomValues` requires exactly that, not the
  *  wider `ArrayBufferLike` (which also admits `SharedArrayBuffer`). */
-interface RandomBytesSource {
+export interface RandomBytesSource {
   getRandomValues(array: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
 }
 
 /** The minimal Web Crypto surface `generatePKCE` uses — real Web Crypto (the
  *  global `crypto`, browser or Node's `webcrypto`) or an injectable stub. */
-interface PkceCrypto extends RandomBytesSource {
+export interface PkceCrypto extends RandomBytesSource {
   subtle: { digest(algorithm: string, data: BufferSource): Promise<ArrayBuffer> };
 }
 
diff --git a/src/ui/app.ts b/src/ui/app.ts
index 14079f1..eac7393 100644
--- a/src/ui/app.ts
+++ b/src/ui/app.ts
@@ -23,13 +23,11 @@ import type {
 } from '../core/param-pipeline.js';
 import { hasOptionalBlocks } from '../core/optional-blocks.js';
 import { saveJSON, saveStr } from '../core/storage.js';
-import { decodeJwtPayload, isTokenExpired } from '../core/jwt.js';
 import { sqlString, inferQueryName, shortVersion, supportsExplainPretty, userShortName, withStatementBreak, detectSqlFormat, isSchemaMutatingSql, prepareExportSql, formatBytes, formatRows } from '../core/format.js';
 import { EXPLAIN_VIEWS, parseExplain, detectExplainView, buildExplainQuery } from '../core/explain.js';
 import { buildSchemaGraph, expandLineage } from '../core/schema-graph.js';
 import { buildCardGraph } from '../core/schema-cards.js';
 import type { SchemaCardColumnRow } from '../core/schema-cards.js';
-import { resolveTarget } from '../core/target.js';
 import { toTSV, formatFileMeta, exportFilename, scriptExportName } from '../core/export.js';
 import { newResult, parseErrorPos, findExceptionFrame } from '../core/stream.js';
 import { buildResultSource } from '../core/query-source.js';
@@ -45,14 +43,8 @@ import {
 import type { SpecValidatorEntry, QuerySpecValidationService } from '../core/spec-draft.js';
 import type { SpecDiagnostic } from '../editor/spec-editor.types.js';
 import { assembleReferenceData, buildCompletions } from '../core/completions.js';
-import { generatePKCE, randomState } from '../core/pkce.js';
-import { configBase } from '../core/dashboard.js';
 import { isQuerylessPanel } from '../core/panel-cfg.js';
 import { isKpiPanel, panelExecution } from '../core/panel-execution.js';
-import { snapshotAuth, restoreAuth, hasAuth, isAuthRequest, isAuthGrant, AUTH_REQUEST, AUTH_GRANT } from '../core/auth-handoff.js';
-import type { AuthSnapshot } from '../core/auth-handoff.js';
-import * as oauthCfg from '../net/oauth-config.js';
-import * as oauth from '../net/oauth.js';
 import * as ch from '../net/ch-client.js';
 import { createNoopPort } from '../editor/editor-port.js';
 import type { EditorPort } from '../editor/editor-port.types.js';
@@ -93,11 +85,12 @@ import { openShortcuts } from './shortcuts.js';
 import { startDrag } from './splitters.js';
 import type { DragCtx, DragRect, DragStartEvent, SplitterAxis } from './splitters.js';
 import { flashToast } from './toast.js';
-import type { App, ActionsRegistry, SchemaFocus, ChCtx as AppChCtx } from './app.types.js';
+import type { App, ActionsRegistry, SchemaFocus } from './app.types.js';
 import type { CreateAppEnv } from '../env.types.js';
 import type { SchemaGraphFocus, SchemaGraphNode, SchemaGraphEdge } from '../core/schema-graph.js';
 import type { LineageFocus } from '../net/ch-client.js';
 import { createQueryExecutionService } from '../application/query-execution-service.js';
+import { createConnectionSession } from '../application/connection-session.js';
 
 /** Optional globals a plain browser page (or the CM6/Chart/dagre UMD bundles a
  *  `<script>` tag might attach) can carry that aren't in the standard `Window`
@@ -224,8 +217,6 @@ export function createApp(env: CreateAppEnv = {}): App {
     hardenedVars: new Set<string>(),
     root: env.root || doc.getElementById('root'),
     document: doc,
-    token: ss.getItem('oauth_id_token'),
-    refreshToken: ss.getItem('oauth_refresh_token'),
     // Charting seam: the Chart.js constructor (injected so tests stub it) and a
     // CSS-custom-property reader (canvas needs real colors, not `var(--x)`).
     Chart: env.Chart || win.Chart,
@@ -273,38 +264,6 @@ export function createApp(env: CreateAppEnv = {}): App {
   // browser with showSaveFilePicker also has showDirectoryPicker).
   app.canExportScript = () => !!app.showDirectoryPicker && app.isSecureContext;
 
-  // Two ways to be signed in: OAuth (a JWT bearer, the default) or 'basic' —
-  // a ClickHouse username/password sent as Authorization: Basic, optionally
-  // against another host. A live basic session is restored from sessionStorage
-  // (ch_basic_*), mirroring how the OAuth token is restored above.
-  app.authMode = ss.getItem('ch_basic_auth') ? 'basic' : 'oauth';
-  const basicCreds = () => ss.getItem('ch_basic_auth');
-  const basicUser = () => ss.getItem('ch_basic_user') || '';
-  const originHost = (o: string): string => { try { return new URL(o).host; } catch { return ''; } };
-
-  // config.json may list several IdPs. Fetch the doc once; resolve OIDC
-  // discovery per selected IdP. The chosen IdP id is persisted so it survives
-  // the OAuth redirect (like oauth_state) and drives token exchange/refresh.
-  // configBase strips a trailing `/dashboard` so config.json / OAuth discovery
-  // resolve from the SPA base (`/sql/config.json`) on the dashboard route too.
-  // The same base is the single source of truth for the workbench↔dashboard
-  // links (openDashboard, the dashboard's Back link) rather than hardcoding
-  // `/sql` in several shapes.
-  app.basePath = configBase(loc.pathname);
-  const loadDoc = oauthCfg.memoizeConfig(() => oauthCfg.loadConfigDoc(fetchFn, app.basePath));
-  const resolvedCache = new Map<string, Promise<oauthCfg.ResolvedIdpConfig>>();
-  app.idpId = ss.getItem('oauth_idp') || null;
-  function selectIdp(id: string): void { app.idpId = id; ss.setItem('oauth_idp', id); }
-  async function resolveConfig(): Promise<oauthCfg.ResolvedIdpConfig> {
-    const { idps } = await loadDoc();
-    const chosen = idps.find((i) => i.id === app.idpId) || idps[0];
-    app.idpId = chosen.id;
-    if (!resolvedCache.has(chosen.id)) resolvedCache.set(chosen.id, oauthCfg.resolveIdp(fetchFn, chosen));
-    return resolvedCache.get(chosen.id)!;
-  }
-  app.loadIdps = loadDoc;
-  app.selectIdp = selectIdp;
-
   // --- persistence -------------------------------------------------------
   app.saveJSON = saveJSON;
   app.saveStr = saveStr;
@@ -359,12 +318,9 @@ export function createApp(env: CreateAppEnv = {}): App {
   // libraryName/libraryDirty effect, so callers just mutate those signals.
   app.downloadFile = downloadFile;
 
-  // --- identity ----------------------------------------------------------
-  // The host queries actually go to. chCtx.origin already resolves to the basic
-  // target, the picked OAuth cluster (oauth_origin), or the serving origin — so a
-  // cross-origin OAuth connection shows the cluster, not localhost. (URL.host drops
-  // a default :443, so a 443 cluster shows a bare hostname; an 8443 one shows :8443.)
-  app.host = () => originHost(chCtx.origin) || 'clickhouse';
+  // --- identity ------------------------------------------------------------
+  // app.host is a Phase-2 delegate (conn.host) — assigned below, alongside the
+  // rest of the ConnectionSession delegates, once `conn` is constructed.
   app.activeTab = () => activeTab(app.state);
 
   // --- independent SQL + Spec editor seams (#143/#212) ---------------------
@@ -455,50 +411,6 @@ export function createApp(env: CreateAppEnv = {}): App {
     app.revalidateSpecDrafts();
     return () => { unregister(); app.revalidateSpecDrafts(); };
   };
-  // A `?host=` query param pre-fills the credential server address on the login
-  // screen (and disables SSO, which only targets the serving host).
-  app.hostHint = new URLSearchParams(loc.search || '').get('host') || '';
-  app.isSignedIn = () => (app.authMode === 'basic'
-    ? !!basicCreds()
-    : !!app.token && !isTokenExpired(app.token, 0));
-  // The CH-facing identity for the current token — what currentUser() will be:
-  // for ch_auth=basic it's the Basic username (honouring basicUserClaim); for
-  // bearer it's the email the token-processor keys on. Shared by authHeader and
-  // the header display so the UI never shows a different claim than CH sees.
-  function chUsername(p: Record<string, unknown>): string {
-    return String((app.chAuth === 'basic' && app.basicUserClaim && p[app.basicUserClaim])
-      || p.email || p.preferred_username || p.sub || '');
-  }
-  app.chUsername = chUsername;
-  app.email = () => (app.authMode === 'basic'
-    ? basicUser()
-    : chUsername(decodeJwtPayload(app.token)));
-
-  function setTokens(id: string, refresh?: string): void {
-    app.token = id;
-    ss.setItem('oauth_id_token', id);
-    if (refresh) {
-      app.refreshToken = refresh;
-      ss.setItem('oauth_refresh_token', refresh);
-    }
-    // The PKCE verifier + CSRF state are one-shot — done with them once we hold
-    // tokens. (The refresh path also lands here; they're already gone → no-op.)
-    ss.removeItem('oauth_verifier');
-    ss.removeItem('oauth_state');
-  }
-  function clearTokens(): void {
-    app.token = null;
-    app.refreshToken = null;
-    app.idpId = null;
-    app.authMode = 'oauth';
-    chCtx.origin = loc.origin;
-    chCtx.authConfirmed = false; // a fresh sign-in starts unconfirmed again
-    ['oauth_id_token', 'oauth_refresh_token', 'oauth_verifier', 'oauth_state', 'oauth_idp', 'oauth_origin',
-      'ch_basic_auth', 'ch_basic_user', 'ch_basic_origin'].forEach((k) => ss.removeItem(k));
-  }
-  app.setTokens = setTokens;
-  app.loadConfig = resolveConfig;
-
   // login.ts's `LoginApp.root` is narrowed to a non-null `Element` (vs.
   // `App.root`'s `Element | null`) — deliberate there (that module always
   // writes through it unconditionally); every real renderLogin() call below
@@ -507,132 +419,46 @@ export function createApp(env: CreateAppEnv = {}): App {
   // root would already throw inside login.ts's own `app.root.replaceChildren`
   // either way).
   const renderLoginApp = (msg?: string): void => renderLogin(app as App & { root: Element }, msg);
-  app.signOut = () => { clearTokens(); renderLoginApp(); };
-  app.showLogin = (msg) => renderLoginApp(msg);
-
-  // --- OAuth -------------------------------------------------------------
-  async function login(idpId?: string, targetOrigin?: string): Promise<void> {
-    if (idpId) selectIdp(idpId);
-    // A picked saved-connection can target another cluster: stash its origin so
-    // the rebuilt chCtx (after the redirect reload) POSTs the bearer there.
-    // Survives the redirect like oauth_state/oauth_idp; cleared for serving-host SSO.
-    if (targetOrigin) ss.setItem('oauth_origin', targetOrigin);
-    else ss.removeItem('oauth_origin');
-    const cfg = await resolveConfig();
-    const { verifier, challenge } = await generatePKCE(cryptoObj);
-    const state = randomState(cryptoObj);
-    ss.setItem('oauth_verifier', verifier);
-    ss.setItem('oauth_state', state);
-    loc.href = oauth.buildAuthorizeUrl(cfg, {
-      redirectUri: loc.origin + loc.pathname,
-      challenge,
-      state,
-    });
-  }
-
-  async function refresh(): Promise<boolean> {
-    // Basic credentials don't expire and can't be refreshed; a surviving 401
-    // means the password is wrong → authedFetch falls through to onSignedOut.
-    if (app.authMode === 'basic') return false;
-    const cfg = await resolveConfig();
-    const tokens = await oauth.refreshTokens(fetchFn, cfg, app.refreshToken);
-    const bearer = oauth.bearerFromTokens(tokens, cfg.bearer);
-    if (!bearer) return false;
-    // `bearer` is only ever truthy when `tokens` (its own source) is non-null.
-    setTokens(bearer, tokens?.refresh_token);
-    return true;
-  }
-
-  async function getToken(): Promise<string | null> {
-    // In basic mode the stored credential is the "token" authedFetch carries.
-    if (app.authMode === 'basic') return basicCreds();
-    if (!app.token) return null;
-    if (!isTokenExpired(app.token)) return app.token;
-    if (await refresh()) return app.token;
-    clearTokens();
-    return null;
-  }
-
-  // --- ClickHouse context ------------------------------------------------
-  // How the token is presented to CH. 'bearer' (token_processor) or 'basic'
-  // (OSS + a verifier like ch-jwt-verify, where the JWT is the Basic password
-  // and the username is the token's email). Resolved from config by ensureConfig.
-  app.chAuth = 'bearer';
-  // Which claim becomes the Basic username (per-IdP, from config). Empty → the
-  // default chain. Lets one IdP map to a CH username distinct from another's.
-  app.basicUserClaim = '';
-  function authHeader(token: string): string {
-    // Basic mode: `token` is already base64(user:pass) — send it verbatim.
-    if (app.authMode === 'basic') return 'Basic ' + token;
-    if (app.chAuth !== 'basic') return 'Bearer ' + token;
-    const user = chUsername(decodeJwtPayload(token));
-    return 'Basic ' + btoa(unescape(encodeURIComponent(user + ':' + token)));
-  }
-  const chCtx: AppChCtx = {
-    fetch: fetchFn,
-    // Where queries POST: the serving origin for OAuth, or the (possibly
-    // cross-origin) target chosen at credential sign-in for basic mode.
-    origin: app.authMode === 'basic'
-      ? (ss.getItem('ch_basic_origin') || loc.origin)
-      : (ss.getItem('oauth_origin') || loc.origin),
-    // Flips true after the first 2xx; gates whether a later 401/403 is treated
-    // as a sign-in failure (only before auth is confirmed) or a query error.
-    authConfirmed: false,
-    getToken,
-    refresh,
-    authHeader,
-    // detail is set when CH rejects a *valid* login (authorization denial); the
-    // no-arg calls (no token / expired + refresh failed) fall back to expiry.
-    onSignedOut: (detail?: string) => {
-      clearTokens();
-      renderLoginApp(detail || 'Your session expired — please sign in again.');
-    },
-  };
+  // The auth + config + ClickHouse connection lifecycle (#276 Phase 2) — OAuth
+  // PKCE login/refresh, Basic probing, IdP config resolution, and cross-tab
+  // auth handoff all now live in `application/connection-session.ts`,
+  // constructible without App/AppState/DOM; this module wires it to the real
+  // browser env and to `renderLoginApp` (the one piece that IS this shell's
+  // job — the session only ever calls `onAuthLost`, never renders). The two
+  // handoff windows (how long the child waits for a grant vs. how long the
+  // opener keeps listening) are env-injectable seams whose defaults are
+  // documented in full on `ConnectionSessionDeps` itself.
+  const conn = createConnectionSession({
+    fetch: fetchFn, storage: ss, location: loc, crypto: cryptoObj, win,
+    queryJson: ch.queryJson,
+    handoffMs: env.handoffMs != null ? env.handoffMs : 4000,
+    handoffListenMs: env.handoffListenMs != null ? env.handoffListenMs : 30000,
+    onAuthLost: (detail) => renderLoginApp(detail),
+  });
+  app.conn = conn;
+  // THE single live ClickHouse context — owned by the session, aliased locally
+  // so every existing ch.* call site below keeps referencing the same mutated
+  // object (chCtx.origin/authConfirmed are mutated in place, never replaced).
+  const chCtx = conn.chCtx;
+  const getToken = conn.getToken;
+  const ensureConfig = conn.ensureConfig;
+
+  // Phase-2 delegates — shells/bootstrap consume these; Phase 5 re-points them
+  // to app.conn directly.
+  app.basePath = conn.basePath;
+  app.hostHint = conn.hostHint;
+  app.host = conn.host;
+  app.isSignedIn = conn.isSignedIn;
+  app.email = conn.email;
+  app.setTokens = conn.setTokens;
+  app.loadConfig = conn.resolveConfig;
+  app.loadIdps = conn.loadIdps;
+  app.ensureConfig = conn.ensureConfig;
+  app.ensureFreshToken = conn.ensureFreshToken;
   app.chCtx = chCtx;
-
-  // Load config (once) and apply the CH auth mode before any query runs.
-  // Fail-soft: if config can't be loaded we keep the current mode (bearer)
-  // rather than blocking the query.
-  async function ensureConfig(): Promise<oauthCfg.ResolvedIdpConfig | null> {
-    // Basic mode needs no OAuth config — the auth scheme is fixed.
-    if (app.authMode === 'basic') return null;
-    try {
-      const cfg = await resolveConfig();
-      app.chAuth = cfg.chAuth;
-      app.basicUserClaim = cfg.basicUserClaim || '';
-      return cfg;
-    } catch {
-      return null;
-    }
-  }
-  app.ensureConfig = ensureConfig;
-
-  // --- credentials (HTTP Basic) sign-in ----------------------------------
-  // Validate a ClickHouse username/password against `host` (blank → the serving
-  // host) with a probe query, then commit the session and enter the workbench.
-  // The probe uses a throwaway ctx so a bad password surfaces CH's own reason
-  // here (rejected as a thrown Error) instead of auto-rendering the login.
-  async function connect({ username, password, host }: { username: string; password: string; host?: string }): Promise<void> {
-    const user = String(username || '').trim();
-    const target = resolveTarget(host, loc.origin);
-    const creds = btoa(unescape(encodeURIComponent(user + ':' + (password || ''))));
-    const probeCtx: ch.ChCtx = {
-      fetch: fetchFn,
-      origin: target,
-      getToken: async () => creds,
-      authHeader: () => 'Basic ' + creds,
-      refresh: async () => false,
-      onSignedOut: (detail?: string) => { throw new Error(detail || 'Authentication failed'); },
-    };
-    await ch.queryJson(probeCtx, 'SELECT 1');
-    // Probe passed → commit the session and switch the live ctx to the target.
-    app.authMode = 'basic';
-    ss.setItem('ch_basic_auth', creds);
-    ss.setItem('ch_basic_user', user);
-    ss.setItem('ch_basic_origin', target);
-    chCtx.origin = target;
-    app.renderApp();
-  }
+  app.signOut = () => { conn.signOut(); renderLoginApp(); };
+  app.showLogin = (msg) => renderLoginApp(msg);
+  app.receiveAuthHandoff = (handoffEnv) => conn.receiveAuthHandoff(handoffEnv);
 
   // --- data loaders ------------------------------------------------------
   app.loadVersion = async () => {
@@ -2431,18 +2257,6 @@ export function createApp(env: CreateAppEnv = {}): App {
   const toEditorOnMobile = (): void => { if (app.state.isMobile.value) app.state.mobileView.value = 'editor'; };
 
   // --- dashboard (#149 D1) ----------------------------------------------
-  // ensureConfig + getToken, resolving (and refreshing) the auth token ONCE.
-  // The dashboard calls this before fanning tiles out, so the tiles never each
-  // race an expired-token refresh (a rotating refresh token used N-ways at once
-  // would invalidate itself), and a single sign-out is handled by the caller
-  // instead of N tiles each firing onSignedOut. Also used by bootstrap to
-  // refresh a handed-off-but-expired token before falling back to login.
-  async function ensureFreshToken(): Promise<boolean> {
-    await ensureConfig();
-    return !!(await getToken());
-  }
-  app.ensureFreshToken = ensureFreshToken;
-
   // Dashboard tiles stream their read-only SQL through the shared
   // `app.exec.executeRead` seam directly (#193/#276 — see src/ui/dashboard.js
   // `runSlotTile`), the same path run() and the detached Data view use; the
@@ -2450,83 +2264,16 @@ export function createApp(env: CreateAppEnv = {}): App {
   // was retired so cap/settings fixes can't apply to only one path.
   app.renderDashboard = () => renderDashboard(app);
 
-  // One-time cross-tab auth handoff. The dashboard opens in a new same-origin
-  // tab whose sessionStorage starts empty; rather than force a second sign-in,
-  // this (opener) tab grants its live credentials once when the child asks.
-  // Both sides pin the target origin AND the peer window; a timeout stops the
-  // opener listening if the child never asks. Message contract: core/auth-handoff.
-  // Two windows: the child waits HANDOFF_MS for a grant once it *asks* (a
-  // same-origin reply is near-instant, so this is short); the opener listens far
-  // longer (HANDOFF_LISTEN_MS) because it must survive the child's cold JS load
-  // before the child can ask — a short opener window would drop a slow tab's
-  // request and force a needless re-login.
-  const HANDOFF_MS = env.handoffMs != null ? env.handoffMs : 4000;
-  const HANDOFF_LISTEN_MS = env.handoffListenMs != null ? env.handoffListenMs : 30000;
-  function sendAuthHandoff(child: Window): void {
-    const onMsg = (e: MessageEvent): void => {
-      if (!isAuthRequest(e, loc.origin, child)) return;
-      const creds = snapshotAuth(ss);
-      // Only grant when we actually hold credentials — never hand over an empty
-      // snapshot (which the child would have to reject anyway).
-      if (hasAuth(creds)) child.postMessage({ type: AUTH_GRANT, creds }, loc.origin);
-      win.removeEventListener('message', onMsg);
-    };
-    win.addEventListener('message', onMsg);
-    win.setTimeout(() => win.removeEventListener('message', onMsg), HANDOFF_LISTEN_MS);
-  }
-  // Open the dashboard in a new tab and stand ready to hand it our credentials.
+  // Open the dashboard in a new tab and stand ready to hand it our credentials
+  // — the cross-tab auth-handoff GRANT side itself is the session's job now
+  // (`conn.grantHandoffTo`, #276 Phase 2); this stays app-side only because
+  // opening the tab (window.open) is a DOM/browser concern.
   function openDashboard(): void {
-    const child = app.openWindow(loc.origin + app.basePath + '/dashboard');
-    if (child) sendAuthHandoff(child);
+    const child = app.openWindow(loc.origin + conn.basePath + '/dashboard');
+    if (child) conn.grantHandoffTo(child);
   }
   app.openDashboard = openDashboard;
 
-  // Restore a handed-off credential snapshot into BOTH this tab's sessionStorage
-  // and the already-constructed in-memory auth fields — token/authMode/idp/origin
-  // were snapshotted from an empty ss at construction, so writing keys back alone
-  // wouldn't take effect until a reload.
-  function applyAuthSnapshot(creds: AuthSnapshot): void {
-    restoreAuth(ss, creds);
-    if (creds.ch_basic_auth) {
-      app.authMode = 'basic';
-      chCtx.origin = creds.ch_basic_origin || loc.origin;
-    } else {
-      if (creds.oauth_id_token) setTokens(creds.oauth_id_token, creds.oauth_refresh_token);
-      if (creds.oauth_idp) app.idpId = creds.oauth_idp;
-      chCtx.origin = creds.oauth_origin || loc.origin;
-    }
-  }
-  // Child side: ask the opener for credentials once. Resolves true once a valid
-  // grant is applied; false when there's no opener or the request times out (a
-  // cold/bookmarked visit → the caller falls through to the normal login flow).
-  app.receiveAuthHandoff = (handoffEnv) => new Promise((resolve) => {
-    const opener = handoffEnv.opener;
-    if (!opener) { resolve(false); return; }
-    let done = false;
-    const finish = (ok: boolean): void => {
-      if (done) return;
-      done = true;
-      win.removeEventListener('message', onMsg);
-      resolve(ok);
-    };
-    const onMsg = (e: MessageEvent): void => {
-      if (!isAuthGrant(e, loc.origin, opener)) return;
-      // `e.data` is a real handoff grant `{type, creds}` once isAuthGrant has
-      // confirmed `type` — `AuthMessageEvent`'s own contract type only pins
-      // `type` (the shared predicate's whole point); `creds` rides alongside.
-      const data = e.data as { type?: string; creds?: AuthSnapshot } | null;
-      // Ignore an empty grant (opener signed out / mid-sign-in) — keep waiting so
-      // the request times out into the normal login rather than falsely
-      // reporting success with no credentials applied.
-      if (!hasAuth(data?.creds)) return;
-      applyAuthSnapshot(data!.creds!);
-      finish(true);
-    };
-    win.addEventListener('message', onMsg);
-    opener.postMessage({ type: AUTH_REQUEST }, loc.origin);
-    win.setTimeout(() => finish(false), HANDOFF_MS);
-  });
-
   // --- actions registry --------------------------------------------------
   app.actions = {
     run: runEntry,
@@ -2535,8 +2282,8 @@ export function createApp(env: CreateAppEnv = {}): App {
     selectTab: (id) => selectTab(app, id),
     closeTab: (id) => closeTab(app, id),
     loadIntoNewTab: (queryOrName, sql) => { loadIntoNewTab(app, queryOrName, sql); toEditorOnMobile(); },
-    login: (idpId, targetOrigin) => login(idpId, targetOrigin),
-    connect,
+    login: (idpId, targetOrigin) => conn.beginOAuth(idpId, targetOrigin),
+    connect: async (input) => { await conn.connectBasic(input); app.renderApp(); },
     share,
     copyResult,
     // `ActionsRegistry.copySnapshot`'s public `result: Json | null` is looser
diff --git a/src/ui/app.types.ts b/src/ui/app.types.ts
index 4ae3e15..b94f8ef 100644
--- a/src/ui/app.types.ts
+++ b/src/ui/app.types.ts
@@ -15,6 +15,7 @@ import type { CodeViewerFactory } from '../editor/code-viewer.types.js';
 import type { QueryTab as Tab, AppState as State, SpecValidationService } from '../state.js';
 import type { ConfigDoc, ResolvedIdpConfig } from '../net/oauth-config.js';
 import type { QueryExecutionService } from '../application/query-execution-service.js';
+import type { ConnectionSession, SessionChCtx } from '../application/connection-session.js';
 import type { SpecValidatorFn } from '../core/spec-draft.js';
 import type { SavedQueryV2 } from '../generated/json-schema.types.js';
 import type { DynamicSources } from '../core/spec-completion.js';
@@ -100,15 +101,14 @@ export interface AppDom {
   varStripDeferHooked?: boolean;
 }
 
-export interface ChCtx {
-  fetch: typeof fetch;
-  origin: string;
-  authConfirmed: boolean;
-  getToken(): Promise<string | null>;
-  refresh(): Promise<boolean>;
-  authHeader(token: string): string;
-  onSignedOut(detail?: string): void;
-}
+/** The live ClickHouse auth context every query call site reads/mutates —
+ * a structural alias of `application/connection-session.ts`'s own
+ * `SessionChCtx` (the session is the one place that constructs and mutates
+ * it now, #276 Phase 2) rather than a second, independently-maintained
+ * copy of the same shape. `src/ui/**` may depend on `src/application/**`,
+ * never the reverse — connection-session.ts redeclares this shape itself
+ * rather than importing it from here. */
+export type ChCtx = SessionChCtx;
 
 export interface ActionsRegistry {
   run(opts?: Json): void | Promise<void>;
@@ -167,8 +167,15 @@ export interface App {
   hardenedVars: Set<string>;
   root: Element | null;
   document: Document;
-  token: string | null;
-  refreshToken: string | null;
+
+  /** The auth + config + ClickHouse connection lifecycle (#276 Phase 2) —
+   *  OAuth PKCE login/refresh, Basic probing, IdP config resolution, and
+   *  cross-tab auth handoff, constructible without App/AppState/DOM
+   *  (`src/application/connection-session.ts`). The identity/auth members
+   *  below (`isSignedIn`/`email`/`host`/…) are Phase-2 delegates onto this —
+   *  shells/bootstrap consume those; a future phase re-points them to
+   *  `app.conn` directly. */
+  conn: ConnectionSession;
 
   // Editor ports (injected seams — #143/#212).
   sqlEditor: EditorPort;
@@ -196,16 +203,16 @@ export interface App {
   /** Ad-hoc, consumer-attached (chart-render.js), not initialized by createApp. */
   chart?: { destroy(): void };
 
-  // Identity / auth.
+  // Identity / auth — Phase-2 delegates onto `conn` (see its doc comment
+  // above). `authMode`/`chAuth`/`basicUserClaim`/`idpId`/`selectIdp`/
+  // `chUsername` moved onto `app.conn` itself (`conn.authMode()`/
+  // `conn.chAuth()`/`conn.basicUserClaim()`/`conn.idpId()`/`conn.selectIdp()`)
+  // — no other module read them off `App` directly (verified #276 Phase 2),
+  // so they aren't re-delegated here.
   host(): string;
   activeTab(): Tab;
   isSignedIn(): boolean;
   email(): string;
-  chUsername(jwtPayload: Json): string;
-  authMode: 'oauth' | 'basic';
-  chAuth: 'bearer' | 'basic';
-  basicUserClaim: string;
-  idpId: string | null;
   hostHint: string;
   basePath: string;
   setTokens(id: string, refresh?: string): void;
@@ -219,7 +226,6 @@ export interface App {
    * not just `{id}`); login.ts read the real shape all along behind its own
    * `LoginIdpsResult` widening, now redundant (dropped there). */
   loadIdps(): Promise<ConfigDoc>;
-  selectIdp(id: string): void;
   /** Same real shape as `loadConfig` (`null` when config couldn't be loaded —
    * fail-soft, see app.ts's own `ensureConfig`). */
   ensureConfig(): Promise<ResolvedIdpConfig | null>;
diff --git a/tests/helpers/auth-fixtures.ts b/tests/helpers/auth-fixtures.ts
new file mode 100644
index 0000000..2d027e8
--- /dev/null
+++ b/tests/helpers/auth-fixtures.ts
@@ -0,0 +1,33 @@
+// Shared auth test fixtures (#276 Phase 2). `jwt()` and `memStorage()` were
+// being hand-copied per spec file (app.test.ts / dashboard.test.ts still carry
+// their own older embedded variants — consolidate them here opportunistically
+// when those files are next touched); new specs import from here instead of
+// adding another copy.
+
+/** A valid-looking JWT (base64url header.payload.sig). `decodeJwtPayload`
+ *  only ever reads segment [1]; the signature is never verified client-side. */
+export function jwt(payload: Record<string, unknown>): string {
+  const b = (o: unknown): string => btoa(JSON.stringify(o)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  return `${b({ alg: 'RS256' })}.${b(payload)}.sig`;
+}
+
+/** A Map-backed sessionStorage fake — the three methods the auth code uses,
+ *  plus the backing `_map` for direct assertions. Structurally satisfies
+ *  `connection-session.ts`'s `SessionStorageLike` (and the narrower
+ *  `core/auth-handoff.js` `StorageLike`). */
+export interface MemStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  _map: Map<string, string>;
+}
+
+export function memStorage(initial: Record<string, string> = {}): MemStorage {
+  const m = new Map(Object.entries(initial));
+  return {
+    getItem: (k) => (m.has(k) ? (m.get(k) as string) : null),
+    setItem: (k, v) => { m.set(k, v); },
+    removeItem: (k) => { m.delete(k); },
+    _map: m,
+  };
+}
diff --git a/tests/helpers/fake-app.ts b/tests/helpers/fake-app.ts
index 5062cbe..75fb6f9 100644
--- a/tests/helpers/fake-app.ts
+++ b/tests/helpers/fake-app.ts
@@ -30,6 +30,48 @@ import type { StreamResult } from '../../src/core/stream.js';
 import type { ChartJsConfigResult } from '../../src/core/chart-data.js';
 import type { ChartInstance } from '../../src/ui/chart-render.js';
 import type { QueryExecutionService } from '../../src/application/query-execution-service.js';
+import type { ConnectionSession } from '../../src/application/connection-session.js';
+
+// Production invariant (#276 Phase 2): `app.chCtx` and `app.conn.chCtx` are
+// THE SAME live object (app.ts aliases `conn.chCtx`) — the defaults + the
+// makeApp merge below preserve that identity so a fixture mutation through
+// either alias observes shared state, exactly like the real app.
+const chCtxDefaults: ChCtx = {
+  fetch, origin: '', authConfirmed: true,
+  getToken: async () => null, refresh: async () => false, authHeader: () => '', onSignedOut: () => {},
+};
+
+// A minimal `ConnectionSession` stub (#276 Phase 2) — every render-module test
+// exercises `app.conn` only incidentally (through the `App`-level auth
+// delegates it backs, e.g. `isSignedIn`/`email`/`ensureConfig`), never
+// directly; this is inert, never-called-by-default plumbing so `appDefaults`
+// still satisfies the full `App` contract.
+const connDefaults: ConnectionSession = {
+  basePath: '',
+  hostHint: '',
+  chCtx: chCtxDefaults,
+  token: () => null,
+  refreshToken: () => null,
+  authMode: () => 'basic',
+  idpId: () => null,
+  chAuth: () => 'basic',
+  basicUserClaim: () => 'sub',
+  isSignedIn: () => true,
+  email: () => '',
+  host: () => '',
+  loadIdps: async () => ({ idps: [], basicLogin: true, hosts: [] }) as ConfigDoc,
+  selectIdp: () => {},
+  resolveConfig: async () => ({}) as ResolvedIdpConfig,
+  ensureConfig: async () => null,
+  setTokens: () => {},
+  getToken: async () => null,
+  beginOAuth: async () => {},
+  connectBasic: async () => {},
+  signOut: () => {},
+  ensureFreshToken: async () => true,
+  grantHandoffTo: () => {},
+  receiveAuthHandoff: async () => false,
+};
 
 // A stand-in for the Chart.js constructor: records its canvas + config and
 // exposes a destroy() spy, so the chart glue is testable without a real
@@ -68,8 +110,7 @@ const appDefaults: App = {
   build: 'v0.0.0-test',
   root: null,
   document,
-  token: null,
-  refreshToken: null,
+  conn: connDefaults,
   sqlEditor: {} as App['sqlEditor'],
   specEditor: {} as App['specEditor'],
   CodeViewer: () => ({ setText: () => {}, setLanguage: () => {}, setWrap: () => {}, focus: () => {}, destroy: () => {} }),
@@ -87,23 +128,14 @@ const appDefaults: App = {
   activeTab: () => ({}) as App['activeTab'] extends () => infer T ? T : never,
   isSignedIn: () => true,
   email: () => '',
-  chUsername: () => '',
-  authMode: 'basic',
-  chAuth: 'basic',
-  basicUserClaim: 'sub',
-  idpId: null,
   hostHint: '',
   basePath: '',
   setTokens: () => {},
   loadConfig: async () => ({}) as ResolvedIdpConfig,
   loadIdps: async () => ({ idps: [], basicLogin: true, hosts: [] }) as ConfigDoc,
-  selectIdp: () => {},
   ensureConfig: async () => null,
   ensureFreshToken: async () => true,
-  chCtx: {
-    fetch, origin: '', authConfirmed: true,
-    getToken: async () => null, refresh: async () => false, authHeader: () => '', onSignedOut: () => {},
-  },
+  chCtx: chCtxDefaults,
   showLogin: () => {},
   signOut: () => {},
   receiveAuthHandoff: async () => false,
@@ -169,7 +201,7 @@ const appDefaults: App = {
  * onSignedOut }` (a caller overriding one ChCtx member, not the whole
  * service) would otherwise fail the constraint even though the nested merge
  * below happily accepts a partial sub-object. */
-type AppOverrides = Partial<Omit<App, 'dom' | 'chCtx' | 'actions' | 'exec'>> & {
+type AppOverrides = Partial<Omit<App, 'dom' | 'chCtx' | 'actions' | 'exec' | 'conn'>> & {
   dom?: Partial<AppDom>;
   chCtx?: Partial<ChCtx>;
   actions?: Partial<ActionsRegistry>;
@@ -177,6 +209,11 @@ type AppOverrides = Partial<Omit<App, 'dom' | 'chCtx' | 'actions' | 'exec'>> & {
    *  about overriding `executeRead` (the #185 detached-read seam / dashboard
    *  tile transport); `executeScript`/`kill` fall back to the base stubs. */
   exec?: Partial<QueryExecutionService>;
+  /** Partial like the rest. `conn.chCtx` cannot be overridden here — the
+   *  merge below always re-points it at the shared merged `chCtx` object
+   *  (the production identity invariant); override `chCtx` at the top level
+   *  and both aliases see it. */
+  conn?: Partial<Omit<ConnectionSession, 'chCtx'>>;
 };
 
 // `overrides` is generic so its properties keep their OWN precise call-site
@@ -297,14 +334,18 @@ export function makeApp<O extends AppOverrides = Record<string, never>>(override
       updateSaveBtn: vi.fn(),
     },
   };
+  // One merged chCtx object shared by BOTH aliases (app.chCtx and
+  // app.conn.chCtx) — the production identity invariant (#276 Phase 2).
+  const chCtx = { ...appDefaults.chCtx, ...base.chCtx, ...(overrides.chCtx ?? {}) };
   const merged = {
     ...appDefaults,
     ...base,
     ...overrides,
     dom: { ...appDefaults.dom, ...base.dom, ...(overrides.dom ?? {}) },
-    chCtx: { ...appDefaults.chCtx, ...base.chCtx, ...(overrides.chCtx ?? {}) },
+    chCtx,
     actions: { ...appDefaults.actions, ...base.actions, ...(overrides.actions ?? {}) },
     exec: { ...appDefaults.exec, ...base.exec, ...(overrides.exec ?? {}) },
+    conn: { ...connDefaults, ...(overrides.conn ?? {}), chCtx },
   };
   // Assignability check only (a variable reference, not a fresh literal, so
   // this never trips an excess-property error) — `merged`'s own inferred type
diff --git a/tests/unit/app.test.ts b/tests/unit/app.test.ts
index 911960a..cdaa578 100644
--- a/tests/unit/app.test.ts
+++ b/tests/unit/app.test.ts
@@ -362,7 +362,7 @@ describe('createApp basics', () => {
   });
   it('reads the stored token and derives identity', () => {
     const app = createApp(env());
-    expect(app.token).toBe(validToken);
+    expect(app.conn.token()).toBe(validToken);
     expect(app.isSignedIn()).toBe(true);
     expect(app.email()).toBe('me@example.com');
     expect(app.host()).toBe('ch.example');
@@ -493,7 +493,7 @@ describe('renderApp shell', () => {
     expect(qs(menu, '.um-id').textContent).toBe('me@example.com');
     expect(qs(menu, '.um-build').textContent).toBe(app.build); // build stamp ('dev' here)
     qs(menu, '.um-item.danger').dispatchEvent(new Event('click', { bubbles: true }));
-    expect(app.token).toBeNull();
+    expect(app.conn.token()).toBeNull();
     expect(e.sessionStorage!.getItem('oauth_id_token')).toBeNull();
     expect(qs(app.root, '.login-screen')).not.toBeNull();
     expect(qs(document, '.user-menu')).toBeNull(); // closed
@@ -525,7 +525,7 @@ describe('renderApp shell', () => {
     const e = env({ sessionStorage: memSession({ oauth_verifier: 'v', oauth_state: 's' }) });
     const app = createApp(e);
     app.setTokens('tok');
-    expect(app.token).toBe('tok');
+    expect(app.conn.token()).toBe('tok');
     expect(e.sessionStorage!.getItem('oauth_id_token')).toBe('tok');
     expect(e.sessionStorage!.getItem('oauth_verifier')).toBeNull();
     expect(e.sessionStorage!.getItem('oauth_state')).toBeNull();
@@ -2626,7 +2626,7 @@ describe('auth flows', () => {
     const app = createApp(e);
     const ok = await app.chCtx.refresh();
     expect(ok).toBe(true);
-    expect(app.token).toBe(validToken);
+    expect(app.conn.token()).toBe(validToken);
   });
   it('getToken returns null + clears when refresh fails', async () => {
     const e = env({
@@ -2683,7 +2683,7 @@ describe('credentials (basic) sign-in', () => {
 
   it('restores a basic session from sessionStorage', () => {
     const app = createApp(env({ sessionStorage: memSession(basicSession) }));
-    expect(app.authMode).toBe('basic');
+    expect(app.conn.authMode()).toBe('basic');
     expect(app.isSignedIn()).toBe(true);
     expect(app.email()).toBe('demo');
     expect(app.host()).toBe('gh.example:8443');
@@ -2721,9 +2721,9 @@ describe('credentials (basic) sign-in', () => {
       fetch: makeFetch([[(u, sql) => /SELECT 1/.test(sql), resp({ json: { data: [{ '1': 1 }] } })]]),
     });
     const app = createApp(e);
-    expect(app.authMode).toBe('oauth');
+    expect(app.conn.authMode()).toBe('oauth');
     await app.actions.connect({ username: 'demo', password: 'demo', host: '' });
-    expect(app.authMode).toBe('basic');
+    expect(app.conn.authMode()).toBe('basic');
     expect(e.sessionStorage!.getItem('ch_basic_auth')).toBe(creds);
     expect(e.sessionStorage!.getItem('ch_basic_user')).toBe('demo');
     expect(e.sessionStorage!.getItem('ch_basic_origin')).toBe('https://ch.example');
@@ -2749,7 +2749,7 @@ describe('credentials (basic) sign-in', () => {
     });
     const app = createApp(e);
     await expect(app.actions.connect({ username: 'demo', password: 'wrong', host: '' })).rejects.toThrow();
-    expect(app.authMode).toBe('oauth');
+    expect(app.conn.authMode()).toBe('oauth');
     expect(e.sessionStorage!.getItem('ch_basic_auth')).toBeNull();
   });
   it('signing out of a basic session resets mode, origin, and stored creds', () => {
@@ -2757,7 +2757,7 @@ describe('credentials (basic) sign-in', () => {
     const app = createApp(e);
     app.renderApp();
     app.signOut();
-    expect(app.authMode).toBe('oauth');
+    expect(app.conn.authMode()).toBe('oauth');
     expect(app.chCtx.origin).toBe('https://ch.example');
     expect(e.sessionStorage!.getItem('ch_basic_auth')).toBeNull();
     expect(qs(app.root, '.login-screen')).not.toBeNull();
@@ -3098,7 +3098,7 @@ describe('exhaustive controller coverage', () => {
     });
     const app = createApp(e);
     await app.chCtx.refresh();
-    expect(app.refreshToken).toBe('rt2');
+    expect(app.conn.refreshToken()).toBe('rt2');
     expect(e.sessionStorage!.getItem('oauth_refresh_token')).toBe('rt2');
   });
 
@@ -3319,7 +3319,7 @@ describe('exhaustive controller coverage', () => {
     const app = createApp(e);
     app.renderApp();
     await app.ensureConfig();
-    expect(app.chAuth).toBe('basic');
+    expect(app.conn.chAuth()).toBe('basic');
     app.activeTab().sqlDraft = 'SELECT 1';
     await app.actions.run();
     const q = asMock(e.fetch!).mock.calls.find((c) => c[1] && c[1].body === 'SELECT 1')!;
@@ -3342,7 +3342,7 @@ describe('exhaustive controller coverage', () => {
     const app = createApp(e);
     app.renderApp();
     await app.ensureConfig();
-    expect(app.basicUserClaim).toBe('nickname');
+    expect(app.conn.basicUserClaim()).toBe('nickname');
     app.activeTab().sqlDraft = 'SELECT 1';
     await app.actions.run();
     const q = asMock(e.fetch!).mock.calls.find((c) => c[1] && c[1].body === 'SELECT 1')!;
diff --git a/tests/unit/connection-session.test.ts b/tests/unit/connection-session.test.ts
new file mode 100644
index 0000000..9a10447
--- /dev/null
+++ b/tests/unit/connection-session.test.ts
@@ -0,0 +1,660 @@
+import { describe, it, expect, vi } from 'vitest';
+import { webcrypto } from 'node:crypto';
+import { createConnectionSession } from '../../src/application/connection-session.js';
+import type { ConnectionSessionDeps, SessionStorageLike } from '../../src/application/connection-session.js';
+import type { ChCtx, queryJson } from '../../src/net/ch-client.js';
+import { jwt, memStorage } from '../helpers/auth-fixtures.js';
+
+// ── Fakes / helpers ──────────────────────────────────────────────────────────
+
+const nowSec = (): number => Math.floor(Date.now() / 1000);
+const validToken = jwt({ email: 'me@example.com', exp: nowSec() + 3600 });
+// Expires within getToken's default 60s skew but NOT within isSignedIn's zero
+// skew — the one token that tells the two checks apart.
+const expiringSoonToken = jwt({ email: 'soon@example.com', exp: nowSec() + 30 });
+const expiredToken = jwt({ email: 'gone@example.com', exp: nowSec() - 10 });
+
+// `memStorage` comes from tests/helpers/auth-fixtures.ts — its MemStorage
+// shape structurally satisfies the session's SessionStorageLike.
+const _storageTypeCheck: SessionStorageLike = memStorage();
+void _storageTypeCheck;
+
+/** A test-only `MessageEvent`-shaped object — the session only ever reads
+ * `data`/`origin`/`source` off a dispatched message (matches
+ * `core/auth-handoff.ts`'s own `AuthMessageEvent` contract). */
+interface FakeMessageEvent { data: unknown; origin: string; source: unknown }
+
+/** A fake `win` seam: captures `message` listeners (so tests can dispatch
+ * synthetic events at them) and queued `setTimeout` callbacks (so tests can
+ * fire the handoff timeout deterministically instead of sleeping). Cast to
+ * the narrow `Pick<Window, ...>` the session declares — the same "widen the
+ * fake, single cast" idiom `tests/unit/dashboard.test.ts`'s own `asWindow`
+ * helper uses for the same reason (a plain object only ever needs the few
+ * members real code reads, not the whole `Window` interface). */
+function makeWin() {
+  const listeners = new Set<(e: MessageEvent) => void>();
+  const timeouts: (() => void)[] = [];
+  const raw = {
+    addEventListener: (_type: string, fn: (e: MessageEvent) => void) => { listeners.add(fn); },
+    removeEventListener: (_type: string, fn: (e: MessageEvent) => void) => { listeners.delete(fn); },
+    setTimeout: (fn: () => void, _ms?: number): number => { timeouts.push(fn); return timeouts.length; },
+  };
+  return {
+    win: raw as unknown as Pick<Window, 'addEventListener' | 'removeEventListener' | 'setTimeout'>,
+    dispatch: (e: FakeMessageEvent): void => { for (const fn of [...listeners]) fn(e as unknown as MessageEvent); },
+    listenerCount: (): number => listeners.size,
+    fireTimeouts: (): void => { const t = timeouts.splice(0); for (const fn of t) fn(); },
+  };
+}
+
+interface FakeResponse { ok: boolean; status: number; json(): Promise<unknown>; text(): Promise<string> }
+function jsonResponse(status: number, body: unknown): FakeResponse {
+  return { ok: status >= 200 && status < 300, status, json: async () => body, text: async () => JSON.stringify(body) };
+}
+type RouteFn = (url: string, init?: RequestInit) => FakeResponse | null;
+
+// One shared config.json doc: 'g' is a default (bearer) IdP; 'basicidp' maps
+// ch_auth=basic with a custom basic_user_claim, for the chUsername/authHeader
+// basic-mode tests.
+const CONFIG_DOC_RAW = {
+  idps: [
+    { id: 'g', issuer: 'https://issuer.example', client_id: 'cid-g' },
+    { id: 'basicidp', issuer: 'https://issuer2.example', client_id: 'cid-b', ch_auth: 'basic', basic_user_claim: 'nickname' },
+  ],
+  basic_login: true,
+};
+
+/** Routes config.json + OIDC discovery generically; extra `routes` (e.g. a
+ * scripted token endpoint) are checked first so a test can override/extend
+ * the defaults. */
+function makeFetch(routes: RouteFn[] = []): { fn: typeof fetch; calls: string[] } {
+  const calls: string[] = [];
+  const fn = vi.fn(async (url: string, init?: RequestInit): Promise<FakeResponse> => {
+    calls.push(url);
+    for (const r of routes) {
+      const resp = r(url, init);
+      if (resp) return resp;
+    }
+    if (url.endsWith('/config.json')) return jsonResponse(200, CONFIG_DOC_RAW);
+    if (url.includes('/.well-known/openid-configuration')) {
+      const issuer = url.replace(/\/\.well-known.*/, '');
+      return jsonResponse(200, { authorization_endpoint: issuer + '/authorize', token_endpoint: issuer + '/token' });
+    }
+    return jsonResponse(404, {});
+  });
+  return { fn: fn as unknown as typeof fetch, calls };
+}
+
+type QueryJsonFn = typeof queryJson;
+/** A queued `queryJson` fake for the Basic-auth probe — `connectBasic` only
+ * ever calls it with `(ctx, 'SELECT 1')`. */
+function fakeQueryJson(impl: (ctx: ChCtx, sql: string) => Promise<unknown>): QueryJsonFn {
+  return (async (ctx: ChCtx, sql: string) => impl(ctx, sql)) as unknown as QueryJsonFn;
+}
+
+interface SetupOpts {
+  storage?: SessionStorageLike;
+  location?: { origin: string; pathname: string; search: string; href: string };
+  routes?: RouteFn[];
+  queryJson?: QueryJsonFn;
+  handoffMs?: number;
+  handoffListenMs?: number;
+  onAuthLost?: (detail?: string) => void;
+}
+function setup(opts: SetupOpts = {}) {
+  const win = makeWin();
+  const fetchMock = makeFetch(opts.routes || []);
+  const storage = opts.storage || memStorage();
+  const onAuthLost = opts.onAuthLost || vi.fn();
+  const location = opts.location || { origin: 'https://ch.example', pathname: '/sql', search: '', href: 'https://ch.example/sql' };
+  const deps: ConnectionSessionDeps = {
+    fetch: fetchMock.fn,
+    storage,
+    location,
+    // Explicit `node:crypto` webcrypto, NOT ambient `globalThis.crypto` — a
+    // sibling spec stubbing the global (or a differently-ordered aggregation
+    // where it's undefined at setup() time) must not break PKCE here.
+    crypto: webcrypto,
+    win: win.win,
+    queryJson: opts.queryJson || fakeQueryJson(async () => ({ data: [{ 1: 1 }] })),
+    handoffMs: opts.handoffMs ?? 50,
+    handoffListenMs: opts.handoffListenMs ?? 200,
+    onAuthLost,
+  };
+  return { deps, storage, location, win, fetchMock, onAuthLost, session: createConnectionSession(deps) };
+}
+
+// ── construction seeding ─────────────────────────────────────────────────────
+
+describe('construction seeding', () => {
+  it('restores an OAuth session from sessionStorage', () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: validToken, oauth_refresh_token: 'r0' }) });
+    expect(session.authMode()).toBe('oauth');
+    expect(session.token()).toBe(validToken);
+    expect(session.refreshToken()).toBe('r0');
+  });
+
+  it('restores a basic session (authMode + chCtx.origin) from sessionStorage', () => {
+    const { session } = setup({
+      storage: memStorage({ ch_basic_auth: 'YWJj', ch_basic_user: 'bob', ch_basic_origin: 'https://other.example' }),
+    });
+    expect(session.authMode()).toBe('basic');
+    expect(session.chCtx.origin).toBe('https://other.example');
+  });
+
+  it('falls back to the serving origin when a basic session has no ch_basic_origin', () => {
+    const { session, location } = setup({ storage: memStorage({ ch_basic_auth: 'YWJj' }) });
+    expect(session.chCtx.origin).toBe(location.origin);
+  });
+
+  it('falls back to the serving origin for oauth when no oauth_origin is stashed', () => {
+    const { session, location } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    expect(session.chCtx.origin).toBe(location.origin);
+  });
+
+  it('restores a stashed cross-cluster oauth_origin', () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: validToken, oauth_origin: 'https://cluster.example' }) });
+    expect(session.chCtx.origin).toBe('https://cluster.example');
+  });
+
+  it('restores the persisted idpId', () => {
+    const { session } = setup({ storage: memStorage({ oauth_idp: 'g' }) });
+    expect(session.idpId()).toBe('g');
+  });
+
+  it('resolves basePath from /sql/dashboard via configBase', () => {
+    const { session } = setup({ location: { origin: 'https://ch.example', pathname: '/sql/dashboard', search: '', href: '' } });
+    expect(session.basePath).toBe('/sql');
+  });
+
+  it('reads hostHint from ?host=', () => {
+    const { session } = setup({ location: { origin: 'https://ch.example', pathname: '/sql', search: '?host=myhost%3A9000', href: '' } });
+    expect(session.hostHint).toBe('myhost:9000');
+  });
+
+  it('defaults chAuth to bearer and basicUserClaim to empty before any config load', () => {
+    const { session } = setup();
+    expect(session.chAuth()).toBe('bearer');
+    expect(session.basicUserClaim()).toBe('');
+  });
+});
+
+// ── isSignedIn (zero skew) vs getToken (default skew) ───────────────────────
+
+describe('isSignedIn vs getToken skew', () => {
+  it('isSignedIn is true and getToken refreshes for a token expiring within 60s but not yet', async () => {
+    const { session, storage, fetchMock } = setup({
+      storage: memStorage({ oauth_id_token: expiringSoonToken, oauth_refresh_token: 'r0' }),
+      routes: [(url) => (url.endsWith('/token') ? jsonResponse(200, { id_token: 'refreshed-token', refresh_token: 'r1' }) : null)],
+    });
+    expect(session.isSignedIn()).toBe(true);
+    const tok = await session.getToken();
+    expect(tok).toBe('refreshed-token');
+    expect(storage.getItem('oauth_id_token')).toBe('refreshed-token');
+    expect(fetchMock.calls.some((u) => u.endsWith('/token'))).toBe(true);
+  });
+
+  it('isSignedIn is false with no token, and false once a token is fully expired', () => {
+    const { session: noToken } = setup();
+    expect(noToken.isSignedIn()).toBe(false);
+    const { session: expired } = setup({ storage: memStorage({ oauth_id_token: expiredToken }) });
+    expect(expired.isSignedIn()).toBe(false);
+  });
+
+  it('isSignedIn reads basic creds directly', () => {
+    const { session } = setup({ storage: memStorage({ ch_basic_auth: 'YWJj' }) });
+    expect(session.isSignedIn()).toBe(true);
+  });
+
+  it('getToken returns a still-valid token directly, without refreshing', async () => {
+    const { session, fetchMock } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    await expect(session.getToken()).resolves.toBe(validToken);
+    expect(fetchMock.calls.some((u) => u.endsWith('/token'))).toBe(false);
+  });
+
+  it('getToken returns null with no token', async () => {
+    const { session } = setup();
+    await expect(session.getToken()).resolves.toBeNull();
+  });
+
+  it('getToken reads basic creds directly, in basic mode', async () => {
+    const { session } = setup({ storage: memStorage({ ch_basic_auth: 'YWJj' }) });
+    await expect(session.getToken()).resolves.toBe('YWJj');
+  });
+});
+
+// ── email()/chUsername chain + authHeader ───────────────────────────────────
+
+describe('email() / chUsername chain', () => {
+  it('prefers email', () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: jwt({ email: 'e@x.com', preferred_username: 'pu', sub: 's', exp: nowSec() + 60 }) }) });
+    expect(session.email()).toBe('e@x.com');
+  });
+  it('falls back to preferred_username when email is absent', () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: jwt({ preferred_username: 'pu', sub: 's', exp: nowSec() + 60 }) }) });
+    expect(session.email()).toBe('pu');
+  });
+  it('falls back to sub when email and preferred_username are absent', () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: jwt({ sub: 's', exp: nowSec() + 60 }) }) });
+    expect(session.email()).toBe('s');
+  });
+  it('falls back to empty string when no claim is present', () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: jwt({ exp: nowSec() + 60 }) }) });
+    expect(session.email()).toBe('');
+  });
+  it('reads ch_basic_user in basic mode', () => {
+    const { session } = setup({ storage: memStorage({ ch_basic_auth: 'YWJj', ch_basic_user: 'bob' }) });
+    expect(session.email()).toBe('bob');
+  });
+});
+
+describe('chCtx.authHeader', () => {
+  it('basic mode sends the stored credential verbatim', () => {
+    const { session } = setup({ storage: memStorage({ ch_basic_auth: 'YWJj' }) });
+    expect(session.chCtx.authHeader('YWJj')).toBe('Basic YWJj');
+  });
+  it('bearer (default chAuth) sends Bearer <token>', () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    expect(session.chCtx.authHeader(validToken)).toBe('Bearer ' + validToken);
+  });
+  it('chAuth=basic sends Basic base64(chUsername:token), honouring basicUserClaim', async () => {
+    const tok = jwt({ nickname: 'nicky', email: 'e@x.com', exp: nowSec() + 3600 });
+    const { session } = setup({ storage: memStorage({ oauth_id_token: tok, oauth_idp: 'basicidp' }) });
+    await session.ensureConfig();
+    expect(session.chAuth()).toBe('basic');
+    expect(session.basicUserClaim()).toBe('nickname');
+    expect(session.chCtx.authHeader(tok)).toBe('Basic ' + btoa(unescape(encodeURIComponent('nicky:' + tok))));
+  });
+});
+
+// ── setTokens / refresh ──────────────────────────────────────────────────────
+
+describe('setTokens', () => {
+  it('stores the id token and removes the one-shot verifier/state, without touching refresh', () => {
+    const { session, storage } = setup({ storage: memStorage({ oauth_verifier: 'v', oauth_state: 's' }) });
+    session.setTokens('idtok');
+    expect(storage.getItem('oauth_id_token')).toBe('idtok');
+    expect(storage.getItem('oauth_verifier')).toBeNull();
+    expect(storage.getItem('oauth_state')).toBeNull();
+    expect(session.refreshToken()).toBeNull();
+  });
+  it('stores the refresh token when given', () => {
+    const { session, storage } = setup();
+    session.setTokens('idtok2', 'reftok2');
+    expect(storage.getItem('oauth_refresh_token')).toBe('reftok2');
+    expect(session.refreshToken()).toBe('reftok2');
+  });
+});
+
+describe('refresh (via getToken)', () => {
+  it('fails without touching tokens when authMode is basic', async () => {
+    const { session } = setup({ storage: memStorage({ ch_basic_auth: 'YWJj' }) });
+    // basic mode short-circuits refresh() to false, but getToken itself never
+    // reaches refresh() for basic mode — assert the direct behavior instead.
+    await expect(session.getToken()).resolves.toBe('YWJj');
+  });
+
+  it('clears everything when the token endpoint rejects the refresh', async () => {
+    const { session, storage } = setup({
+      storage: memStorage({ oauth_id_token: expiredToken, oauth_refresh_token: 'r0', oauth_idp: 'g' }),
+      routes: [(url) => (url.endsWith('/token') ? jsonResponse(401, {}) : null)],
+    });
+    session.chCtx.authConfirmed = true;
+    const tok = await session.getToken();
+    expect(tok).toBeNull();
+    expect(session.token()).toBeNull();
+    expect(session.refreshToken()).toBeNull();
+    expect(session.idpId()).toBeNull();
+    expect(session.authMode()).toBe('oauth');
+    expect(session.chCtx.authConfirmed).toBe(false);
+    for (const k of [
+      'oauth_id_token', 'oauth_refresh_token', 'oauth_verifier', 'oauth_state', 'oauth_idp', 'oauth_origin',
+      'ch_basic_auth', 'ch_basic_user', 'ch_basic_origin',
+    ]) expect(storage.getItem(k)).toBeNull();
+  });
+
+  it('returns false when the token endpoint yields no usable bearer', async () => {
+    const { session } = setup({
+      storage: memStorage({ oauth_id_token: expiredToken, oauth_refresh_token: 'r0' }),
+      routes: [(url) => (url.endsWith('/token') ? jsonResponse(200, {}) : null)],
+    });
+    await expect(session.getToken()).resolves.toBeNull();
+  });
+});
+
+// ── beginOAuth ───────────────────────────────────────────────────────────────
+
+describe('beginOAuth', () => {
+  it('builds the authorize URL, stashes PKCE + state, selects the idp, redirects', async () => {
+    const { session, storage, location } = setup();
+    await session.beginOAuth('g', 'https://cluster.example');
+    expect(session.idpId()).toBe('g');
+    expect(storage.getItem('oauth_idp')).toBe('g');
+    expect(storage.getItem('oauth_origin')).toBe('https://cluster.example');
+    expect(storage.getItem('oauth_verifier')).toBeTruthy();
+    expect(storage.getItem('oauth_state')).toBeTruthy();
+    expect(location.href).not.toBe('');
+    const url = new URL(location.href);
+    expect(url.origin + url.pathname).toBe('https://issuer.example/authorize');
+    expect(url.searchParams.get('client_id')).toBe('cid-g');
+    expect(url.searchParams.get('redirect_uri')).toBe(location.origin + location.pathname);
+    expect(url.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(url.searchParams.get('state')).toBe(storage.getItem('oauth_state'));
+  });
+
+  it('clears oauth_origin when no targetOrigin is given, and keeps the current idp selection', async () => {
+    const { session, storage } = setup({ storage: memStorage({ oauth_origin: 'https://stale.example', oauth_idp: 'g' }) });
+    await session.beginOAuth();
+    expect(storage.getItem('oauth_origin')).toBeNull();
+    expect(session.idpId()).toBe('g');
+  });
+});
+
+// ── config ───────────────────────────────────────────────────────────────────
+
+describe('config', () => {
+  it('loadIdps resolves the normalized config doc', async () => {
+    const { session } = setup();
+    const doc = await session.loadIdps();
+    expect(doc.idps.map((i) => i.id)).toEqual(['g', 'basicidp']);
+  });
+
+  it('selectIdp persists the choice', () => {
+    const { session, storage } = setup();
+    session.selectIdp('basicidp');
+    expect(session.idpId()).toBe('basicidp');
+    expect(storage.getItem('oauth_idp')).toBe('basicidp');
+  });
+
+  it('resolveConfig finds the selected idp and memoizes discovery per idp', async () => {
+    const { session, fetchMock } = setup();
+    session.selectIdp('g');
+    const a = await session.resolveConfig();
+    const b = await session.resolveConfig();
+    expect(a.id).toBe('g');
+    expect(b).toBe(a);
+    expect(fetchMock.calls.filter((u) => u.includes('/.well-known/')).length).toBe(1);
+  });
+
+  it('resolveConfig falls back to the first idp when none is selected', async () => {
+    const { session } = setup();
+    const cfg = await session.resolveConfig();
+    expect(cfg.id).toBe('g');
+  });
+});
+
+describe('ensureConfig', () => {
+  it('applies chAuth/basicUserClaim from the resolved config', async () => {
+    const { session } = setup({ storage: memStorage({ oauth_idp: 'basicidp' }) });
+    const cfg = await session.ensureConfig();
+    expect(cfg && cfg.id).toBe('basicidp');
+    expect(session.chAuth()).toBe('basic');
+    expect(session.basicUserClaim()).toBe('nickname');
+  });
+
+  it('is a fail-soft null when config.json cannot be loaded', async () => {
+    const { session } = setup({ routes: [(url) => (url.endsWith('/config.json') ? jsonResponse(500, {}) : null)] });
+    await expect(session.ensureConfig()).resolves.toBeNull();
+    expect(session.chAuth()).toBe('bearer');
+  });
+
+  it('short-circuits to null (no fetch) in basic mode', async () => {
+    const { session, fetchMock } = setup({ storage: memStorage({ ch_basic_auth: 'YWJj' }) });
+    await expect(session.ensureConfig()).resolves.toBeNull();
+    expect(fetchMock.calls.length).toBe(0);
+  });
+});
+
+// ── connectBasic ─────────────────────────────────────────────────────────────
+
+describe('connectBasic', () => {
+  it('probes with a Basic header, then commits session + chCtx.origin to the default host', async () => {
+    const probes: { origin: string; header: string; token: string | null; refreshed: boolean }[] = [];
+    const { session, storage, location } = setup({
+      queryJson: fakeQueryJson(async (ctx) => {
+        // Exercise the probe ctx's own getToken/refresh — the real authedFetch
+        // (net/ch-client.ts) would call these; this fake queryJson stands in
+        // for it, so it drives them itself to prove the throwaway ctx is
+        // fully wired (getToken resolves the probe creds verbatim; refresh is
+        // hardwired false — Basic credentials can't be refreshed).
+        const t = await ctx.getToken();
+        const r = await ctx.refresh();
+        probes.push({ origin: ctx.origin, header: ctx.authHeader!(''), token: t, refreshed: r });
+        return { data: [{ 1: 1 }] };
+      }),
+    });
+    await session.connectBasic({ username: 'bob', password: 'pw' });
+    expect(probes[0].origin).toBe(location.origin);
+    expect(probes[0].header).toBe('Basic ' + btoa(unescape(encodeURIComponent('bob:pw'))));
+    expect(probes[0].token).toBe(btoa(unescape(encodeURIComponent('bob:pw'))));
+    expect(probes[0].refreshed).toBe(false);
+    expect(session.authMode()).toBe('basic');
+    expect(storage.getItem('ch_basic_auth')).toBe(btoa(unescape(encodeURIComponent('bob:pw'))));
+    expect(storage.getItem('ch_basic_user')).toBe('bob');
+    expect(storage.getItem('ch_basic_origin')).toBe(location.origin);
+    expect(session.chCtx.origin).toBe(location.origin);
+  });
+
+  it('targets a custom host when given', async () => {
+    const { session, storage } = setup();
+    await session.connectBasic({ username: 'bob', password: 'pw', host: 'myhost:8443' });
+    expect(storage.getItem('ch_basic_origin')).toBe('https://myhost:8443');
+    expect(session.chCtx.origin).toBe('https://myhost:8443');
+  });
+
+  it('trims the username and tolerates an empty one', async () => {
+    const { session, storage } = setup();
+    await session.connectBasic({ username: '  bob  ', password: 'pw' });
+    expect(storage.getItem('ch_basic_user')).toBe('bob');
+    const { session: s2, storage: storage2 } = setup();
+    await s2.connectBasic({ username: '', password: 'pw' });
+    expect(storage2.getItem('ch_basic_user')).toBe('');
+  });
+
+  it('propagates a probe rejection and commits nothing', async () => {
+    const { session, storage } = setup({ queryJson: fakeQueryJson(async () => { throw new Error('wrong password'); }) });
+    await expect(session.connectBasic({ username: 'bob', password: 'bad' })).rejects.toThrow('wrong password');
+    expect(storage.getItem('ch_basic_auth')).toBeNull();
+    expect(session.authMode()).toBe('oauth');
+  });
+
+  it('the probe ctx.onSignedOut throws, with the given detail or a default', async () => {
+    const { session } = setup({ queryJson: fakeQueryJson(async (ctx) => { ctx.onSignedOut('denied: bad creds'); return {}; }) });
+    await expect(session.connectBasic({ username: 'bob', password: 'bad' })).rejects.toThrow('denied: bad creds');
+    const { session: s2 } = setup({ queryJson: fakeQueryJson(async (ctx) => { ctx.onSignedOut(); return {}; }) });
+    await expect(s2.connectBasic({ username: 'bob', password: 'bad' })).rejects.toThrow('Authentication failed');
+  });
+});
+
+// ── signOut / onSignedOut ────────────────────────────────────────────────────
+
+describe('signOut', () => {
+  it('clears every auth key and resets mode/origin/authConfirmed, without calling onAuthLost', () => {
+    const { session, storage, location, onAuthLost } = setup({
+      storage: memStorage({
+        oauth_id_token: validToken, oauth_refresh_token: 'r', oauth_verifier: 'v', oauth_state: 's',
+        oauth_idp: 'g', oauth_origin: 'https://cluster.example',
+        ch_basic_auth: 'YWJj', ch_basic_user: 'bob', ch_basic_origin: 'https://other.example',
+      }),
+    });
+    session.chCtx.authConfirmed = true;
+    session.signOut();
+    for (const k of [
+      'oauth_id_token', 'oauth_refresh_token', 'oauth_verifier', 'oauth_state', 'oauth_idp', 'oauth_origin',
+      'ch_basic_auth', 'ch_basic_user', 'ch_basic_origin',
+    ]) expect(storage.getItem(k)).toBeNull();
+    expect(session.token()).toBeNull();
+    expect(session.authMode()).toBe('oauth');
+    expect(session.chCtx.origin).toBe(location.origin);
+    expect(session.chCtx.authConfirmed).toBe(false);
+    expect(onAuthLost).not.toHaveBeenCalled();
+  });
+});
+
+describe('chCtx.onSignedOut', () => {
+  it('clears tokens and reports the given detail', () => {
+    const { session, onAuthLost } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    session.chCtx.onSignedOut('you are not welcome');
+    expect(session.token()).toBeNull();
+    expect(onAuthLost).toHaveBeenCalledWith('you are not welcome');
+  });
+  it('falls back to the default expired-session message', () => {
+    const { session, onAuthLost } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    session.chCtx.onSignedOut();
+    expect(onAuthLost).toHaveBeenCalledWith('Your session expired — please sign in again.');
+  });
+});
+
+// ── ensureFreshToken ─────────────────────────────────────────────────────────
+
+describe('ensureFreshToken', () => {
+  it('resolves true when a valid token is available', async () => {
+    const { session } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    await expect(session.ensureFreshToken()).resolves.toBe(true);
+  });
+  it('resolves false with no token', async () => {
+    const { session } = setup();
+    await expect(session.ensureFreshToken()).resolves.toBe(false);
+  });
+});
+
+// ── cross-tab auth handoff ───────────────────────────────────────────────────
+
+describe('grantHandoffTo', () => {
+  it('answers a pinned request with a snapshot, only when it holds credentials, then stops listening', () => {
+    const { session, win, location } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    const child = { postMessage: vi.fn() };
+    session.grantHandoffTo(child as unknown as Window);
+    win.dispatch({ data: { type: 'asb-auth-request' }, origin: location.origin, source: child });
+    expect(child.postMessage).toHaveBeenCalledTimes(1);
+    const [payload, origin] = child.postMessage.mock.calls[0];
+    expect(payload.type).toBe('asb-auth-grant');
+    expect(payload.creds.oauth_id_token).toBe(validToken);
+    expect(origin).toBe(location.origin);
+    expect(win.listenerCount()).toBe(0);
+  });
+
+  it('ignores a request from the wrong origin or the wrong source window', () => {
+    const { session, win, location } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    const child = { postMessage: vi.fn() };
+    const stranger = { postMessage: vi.fn() };
+    session.grantHandoffTo(child as unknown as Window);
+    win.dispatch({ data: { type: 'asb-auth-request' }, origin: 'https://evil.example', source: child });
+    win.dispatch({ data: { type: 'asb-auth-request' }, origin: location.origin, source: stranger });
+    expect(child.postMessage).not.toHaveBeenCalled();
+    expect(win.listenerCount()).toBe(1);
+  });
+
+  it('grants nothing (but still stops listening) when it holds no credentials', () => {
+    const { session, win, location } = setup();
+    const child = { postMessage: vi.fn() };
+    session.grantHandoffTo(child as unknown as Window);
+    win.dispatch({ data: { type: 'asb-auth-request' }, origin: location.origin, source: child });
+    expect(child.postMessage).not.toHaveBeenCalled();
+    expect(win.listenerCount()).toBe(0);
+  });
+
+  it('stops listening after handoffListenMs even if the child never asks', () => {
+    const { session, win, location } = setup({ storage: memStorage({ oauth_id_token: validToken }) });
+    const child = { postMessage: vi.fn() };
+    session.grantHandoffTo(child as unknown as Window);
+    win.fireTimeouts();
+    win.dispatch({ data: { type: 'asb-auth-request' }, origin: location.origin, source: child });
+    expect(child.postMessage).not.toHaveBeenCalled();
+  });
+});
+
+describe('receiveAuthHandoff', () => {
+  it('resolves false immediately with no opener', async () => {
+    const { session } = setup();
+    await expect(session.receiveAuthHandoff({})).resolves.toBe(false);
+  });
+
+  it('requests, then applies a full OAuth grant (token/refresh/idp/origin all updated)', async () => {
+    const { session, win, storage, location } = setup();
+    const opener = { postMessage: vi.fn() };
+    const newTok = jwt({ email: 'x@y.com', exp: nowSec() + 3600 });
+    const p = session.receiveAuthHandoff({ opener: opener as unknown as Window });
+    expect(opener.postMessage).toHaveBeenCalledWith({ type: 'asb-auth-request' }, location.origin);
+    win.dispatch({ data: { type: 'other' }, origin: location.origin, source: opener }); // ignored: wrong type
+    win.dispatch({
+      data: { type: 'asb-auth-grant', creds: { oauth_id_token: newTok, oauth_refresh_token: 'r9', oauth_idp: 'zz', oauth_origin: 'https://cluster.example' } },
+      origin: location.origin, source: opener,
+    });
+    await expect(p).resolves.toBe(true);
+    expect(session.token()).toBe(newTok);
+    expect(session.refreshToken()).toBe('r9');
+    expect(session.idpId()).toBe('zz');
+    expect(session.chCtx.origin).toBe('https://cluster.example');
+    expect(storage.getItem('oauth_id_token')).toBe(newTok);
+  });
+
+  it('applies a partial OAuth grant, falling back to the serving origin with no idp change', async () => {
+    const { session, win, location } = setup();
+    const opener = { postMessage: vi.fn() };
+    const newTok = jwt({ email: 'x@y.com', exp: nowSec() + 3600 });
+    const p = session.receiveAuthHandoff({ opener: opener as unknown as Window });
+    win.dispatch({ data: { type: 'asb-auth-grant', creds: { oauth_id_token: newTok } }, origin: location.origin, source: opener });
+    await expect(p).resolves.toBe(true);
+    expect(session.token()).toBe(newTok);
+    expect(session.idpId()).toBeNull();
+    expect(session.chCtx.origin).toBe(location.origin);
+  });
+
+  it('applies a basic grant', async () => {
+    const { session, win, location } = setup();
+    const opener = { postMessage: vi.fn() };
+    const p = session.receiveAuthHandoff({ opener: opener as unknown as Window });
+    win.dispatch({ data: { type: 'asb-auth-grant', creds: { ch_basic_auth: 'YWJj', ch_basic_origin: 'https://other.example' } }, origin: location.origin, source: opener });
+    await expect(p).resolves.toBe(true);
+    expect(session.authMode()).toBe('basic');
+    expect(session.chCtx.origin).toBe('https://other.example');
+  });
+
+  it('ignores an empty grant and times out into false', async () => {
+    const { session, win, location } = setup();
+    const opener = { postMessage: vi.fn() };
+    const p = session.receiveAuthHandoff({ opener: opener as unknown as Window });
+    win.dispatch({ data: { type: 'asb-auth-grant', creds: {} }, origin: location.origin, source: opener });
+    win.fireTimeouts();
+    await expect(p).resolves.toBe(false);
+  });
+
+  it('ignores a grant from the wrong source window', async () => {
+    const { session, win, location } = setup();
+    const opener = { postMessage: vi.fn() };
+    const stranger = { postMessage: vi.fn() };
+    const newTok = jwt({ email: 'x@y.com', exp: nowSec() + 3600 });
+    const p = session.receiveAuthHandoff({ opener: opener as unknown as Window });
+    win.dispatch({ data: { type: 'asb-auth-grant', creds: { oauth_id_token: 'from-stranger' } }, origin: location.origin, source: stranger });
+    win.dispatch({ data: { type: 'asb-auth-grant', creds: { oauth_id_token: newTok } }, origin: location.origin, source: opener });
+    await expect(p).resolves.toBe(true);
+    expect(session.token()).toBe(newTok);
+  });
+
+  it('resolves once — a second grant after the first is ignored', async () => {
+    const { session, win, location } = setup();
+    const opener = { postMessage: vi.fn() };
+    const tokA = jwt({ email: 'a@x.com', exp: nowSec() + 3600 });
+    const tokB = jwt({ email: 'b@x.com', exp: nowSec() + 3600 });
+    const p = session.receiveAuthHandoff({ opener: opener as unknown as Window });
+    win.dispatch({ data: { type: 'asb-auth-grant', creds: { oauth_id_token: tokA } }, origin: location.origin, source: opener });
+    await expect(p).resolves.toBe(true);
+    win.dispatch({ data: { type: 'asb-auth-grant', creds: { oauth_id_token: tokB } }, origin: location.origin, source: opener });
+    expect(session.token()).toBe(tokA);
+  });
+});
+
+// ── host() ───────────────────────────────────────────────────────────────────
+
+describe('host()', () => {
+  it('derives the host from chCtx.origin', () => {
+    const { session } = setup({ location: { origin: 'https://ch.example:8443', pathname: '/sql', search: '', href: '' } });
+    expect(session.host()).toBe('ch.example:8443');
+  });
+  it('falls back to "clickhouse" when chCtx.origin is not a parseable URL', () => {
+    const { session } = setup();
+    session.chCtx.origin = 'not a url';
+    expect(session.host()).toBe('clickhouse');
+  });
+});
diff --git a/tests/unit/dashboard.test.ts b/tests/unit/dashboard.test.ts
index 5c55034..21078a8 100644
--- a/tests/unit/dashboard.test.ts
+++ b/tests/unit/dashboard.test.ts
@@ -2012,11 +2012,13 @@ const msg = (data: unknown, source: unknown, origin = 'https://ch.example'): Fak
  * ensureConfig, chCtx, renderApp, receiveAuthHandoff, …) are attached via
  * later property assignment inside that same untyped function, invisible to
  * declaration inference, but genuinely present on the one real object at
- * runtime. Several of those methods are closures over THAT object (`app.token
- * = …` inside receiveAuthHandoff, not `this.token`), so returning a spread
- * COPY here (as `makeApp()` does for its stateless stub) would silently
- * detach every such mutation from what the test reads back — `asApp` only
- * reinterprets the type, preserving the one real reference. */
+ * runtime. Several of those methods are closures over `app.conn` — the real
+ * `ConnectionSession` (#276 Phase 2) createApp constructs and wires in place,
+ * whose own internal `token`/`authMode`/… locals mutate on
+ * `receiveAuthHandoff`/`setTokens`/etc. — so returning a spread COPY here (as
+ * `makeApp()` does for its stateless stub) would silently detach every such
+ * mutation from what the test reads back — `asApp` only reinterprets the
+ * type, preserving the one real reference. */
 const asApp = (v: object): App => v as App;
 function realApp(env: CreateAppEnv): App {
   return asApp(createApp(env));
@@ -2105,8 +2107,8 @@ describe('app auth handoff', () => {
     window.dispatchEvent(msg({ type: 'other' }, opener)); // ignored
     window.dispatchEvent(msg({ type: AUTH_GRANT, creds: { oauth_id_token: newTok, oauth_refresh_token: 'r', oauth_idp: 'g', oauth_origin: 'https://cluster' } }, opener));
     await expect(p).resolves.toBe(true);
-    expect(app.token).toBe(newTok);
-    expect(app.idpId).toBe('g');
+    expect(app.conn.token()).toBe(newTok);
+    expect(app.conn.idpId()).toBe('g');
     expect(app.chCtx.origin).toBe('https://cluster');
     expect(ss.getItem('oauth_id_token')).toBe(newTok);
   });
@@ -2117,7 +2119,7 @@ describe('app auth handoff', () => {
     const p = app.receiveAuthHandoff({ opener: asWindow(opener) });
     window.dispatchEvent(msg({ type: AUTH_GRANT, creds: { ch_basic_auth: 'YmFzZQ==', ch_basic_user: 'u', ch_basic_origin: 'https://c2' } }, opener));
     await expect(p).resolves.toBe(true);
-    expect(app.authMode).toBe('basic');
+    expect(app.conn.authMode()).toBe('basic');
     expect(app.chCtx.origin).toBe('https://c2');
     expect(ss.getItem('ch_basic_auth')).toBe('YmFzZQ==');
   });
@@ -2130,7 +2132,7 @@ describe('app auth handoff', () => {
     const newTok = jwt({ email: 'z@z.com', exp: Math.floor(Date.now() / 1000) + 3600 });
     window.dispatchEvent(msg({ type: AUTH_GRANT, creds: { oauth_id_token: newTok } }, opener));
     await expect(p).resolves.toBe(true);
-    expect(app.token).toBe(newTok);
+    expect(app.conn.token()).toBe(newTok);
   });
   it('resolves false when the request times out', async () => {
     const app = realApp(appEnv({ handoffMs: 5 }));