@adrata/adrata-mcp 1.0.0

package/access/oauth.js

@@ -0,0 +1,1059 @@
+/**
+ * OAuth 2.0 Authorization Code Flow for Adrata MCP Server.
+ *
+ * Handles:
+ *   - Building the authorization URL and opening the browser
+ *   - Spinning up a local HTTP server to receive the callback
+ *   - Exchanging the auth code for access + refresh tokens
+ *   - Storing tokens securely in ~/.adrata/tokens.json (obfuscated)
+ *   - Auto-refreshing expired access tokens
+ *   - Revoking tokens on disconnect
+ *   - Fetching workspace capabilities after connection
+ */
+
+import { createServer } from 'node:http';
+import { randomBytes, createCipheriv, createDecipheriv, createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { canonicalResource } from './resource-metadata.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const ADRATA_DIR = process.env.ADRATA_MCP_CONFIG_DIR
+  ? resolve(process.env.ADRATA_MCP_CONFIG_DIR)
+  : join(homedir(), '.adrata');
+const TOKEN_FILE = join(ADRATA_DIR, 'tokens.json');
+const CALLBACK_PORT = 19472; // Ephemeral port for OAuth callback
+const CALLBACK_PATH = '/oauth/callback';
+// IPv4 loopback is FIRST and that order is load-bearing, not cosmetic.
+//
+// A CSP source expression cannot express an IPv6 literal host: the `host-source`
+// grammar only admits ALPHA / DIGIT / "-" host characters, so `http://[::1]:19472`
+// is discarded by the browser as an invalid source while the rest of the
+// directive still applies. The Adrata consent page ships
+// `form-action 'self' http://127.0.0.1:19472 http://localhost:19472 http://[::1]:19472`,
+// and the "Connect workspace" POST answers with a 307 to the loopback callback.
+// Browsers that check `form-action` against post-submission redirects therefore
+// allow the IPv4 redirect and silently drop the IPv6 one — the local listener
+// never sees the callback and `connect_workspace` dies at the 2-minute timeout.
+// Verified in Chrome: with both origins named in one directive, `[::1]` is
+// blocked and `127.0.0.1` succeeds; with no CSP at all, both succeed.
+//
+// `::1` stays as a fallback for hosts where the IPv4 loopback cannot be bound
+// (the loop below falls through on EADDRNOTAVAIL / EAFNOSUPPORT), and both forms
+// remain in the default RFC 7591 registration set.
+export const OAUTH_CALLBACK_ENDPOINTS = Object.freeze([
+  { host: '127.0.0.1', url: `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}` },
+  { host: '::1', url: `http://[::1]:${CALLBACK_PORT}${CALLBACK_PATH}` },
+]);
+const OAUTH_BASE_PATH = '/api/v1/enterprise/oauth';
+// Read-only surface + the AI dispatcher. `ai:base` is required for anything
+// routing through POST /api/v1/ai-crm-tools/execute. The additional read:*
+// scopes unblock ~30 tools that scope_guard gates behind their own families
+// (analytics/forecast, buyer-groups + path-to-power, speedrun, agent-tasks,
+// provider catalog).
+//
+// This stays the DEFAULT grant: least privilege, so a leaked MCP token cannot
+// mutate a workspace. Write access is opt-in per connection via
+// connect_workspace({ writeAccess: true }) — see OAUTH_WRITE_SCOPE below.
+export const OAUTH_SCOPE = [
+  'read:companies', 'read:people', 'read:opportunities', 'read:actions',
+  'read:pipeline', 'read:speedrun', 'read:signals', 'read:search',
+  'read:analytics', 'read:buyer-groups', 'read:tasks', 'read:integrations',
+  'read:partnerships', 'read:sequences', 'read:campaigns', 'read:data',
+  'read:email',
+  'ai:base',
+].join(' ');
+
+// Opt-in CRM write surface.
+//
+// A previous comment here claimed write scopes were pointless because "a
+// machine/OAuth principal cannot complete a governed write anyway". That was
+// factually wrong, and it left the MCP silently read-only while the tool
+// catalog advertised "Full CRUD for companies, people, opportunities,
+// activities, buyer groups". The API gates machine clients on scope ALONE —
+// see adrata_middleware::scope_guard::first_party_user_bypass, which bypasses
+// the guard for human roles and falls through to the scope check when
+// role == "machine_client". A machine token holding write:companies does
+// therefore complete DELETE /api/v1/companies/{id}.
+//
+// Deliberately excluded: admin:* (workspace administration),
+// write:enrichment (spends provider credits), and write:email (sends bulk
+// email under the workspace's identity — the highest-blast-radius write in
+// the product, and not consent-elevatable at all: it requires an
+// admin-provisioned OAuth client, so requesting it here would only make
+// every writeAccess consent fail). Those still require a signed-in human
+// session or an admin-created client.
+export const OAUTH_WRITE_SCOPE = [
+  'write:companies', 'write:people', 'write:buyer-groups',
+  'write:opportunities', 'write:actions', 'write:tasks',
+  'write:partnerships', 'write:sequences', 'write:campaigns', 'write:data',
+].join(' ');
+
+/**
+ * Scope string for a connection. Read-only unless write access is requested.
+ *
+ * Requires a strict boolean `true`. A truthy check would let a stray string
+ * (notably the string "false", which is truthy) silently escalate the grant,
+ * so elevation is opt-in on exactly one value.
+ */
+export function oauthScopeFor({ writeAccess = false } = {}) {
+  return writeAccess === true ? `${OAUTH_SCOPE} ${OAUTH_WRITE_SCOPE}` : OAUTH_SCOPE;
+}
+
+/**
+ * Human-readable capability summary derived from an *actually granted*
+ * OAuth scope string. Every place that tells a caller what connecting (or
+ * being connected) unlocks must go through this rather than asserting a
+ * fixed "enterprise tools are available" claim — OAUTH_SCOPE above is
+ * deliberately read-only (no write or admin scopes), and the API's scope_guard
+ * middleware rejects writes from a token that lacks them (403
+ * insufficient_scope) regardless of what any message here claims. Deriving
+ * the summary from the scope string (rather than hardcoding "read-only")
+ * also keeps this honest automatically if OAUTH_SCOPE ever changes.
+ */
+export function describeOAuthScopeCapabilities(scopeString) {
+  const scopes = String(scopeString || '')
+    .split(/\s+/)
+    .filter(Boolean);
+  const canWrite = scopes.some((s) => s.startsWith('write:') || s.startsWith('admin:'));
+  const canAdmin = scopes.some((s) => s.startsWith('admin:'));
+  // Describe ONLY what the granted scopes actually permit. An earlier version
+  // of this string promised "sequences, campaigns, and workspace
+  // administration" for any write grant -- none of which OAUTH_WRITE_SCOPE
+  // contains. Over-claiming here is the same defect this module exists to
+  // avoid: a capability claim the API will refuse.
+  const written = scopes
+    .filter((s) => s.startsWith('write:'))
+    .map((s) => s.slice('write:'.length))
+    .sort();
+  return {
+    scopes,
+    canWrite,
+    canAdmin,
+    summary: canWrite
+      ? `Read access, plus create/update/delete on: ${written.join(', ') || '(none)'}. `
+        + `Anything outside that list -- including email sending`
+        + `${canAdmin ? '' : ' and workspace administration'} -- is NOT granted and the API will reject it `
+        + `with 403 insufficient_scope.`
+      : 'Read-only access: search and read companies, people, opportunities, pipeline, buyer groups, signals, and analytics, plus the governed AI tool dispatcher for read operations. CRM writes, sequences, campaigns, email sending, and admin actions are NOT granted by this connection — request CRM/sequence/campaign writes explicitly with connect_workspace({ writeAccess: true }), which requires interactive human approval. Email sending and admin actions are never granted to MCP connections.',
+  };
+}
+const CALLBACK_SECURITY_HEADERS = Object.freeze({
+  'Cache-Control': 'no-store',
+  'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+  'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
+  'Referrer-Policy': 'no-referrer',
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+});
+const CALLBACK_HTML_HEADERS = Object.freeze({
+  ...CALLBACK_SECURITY_HEADERS,
+  'Content-Type': 'text/html; charset=utf-8',
+});
+const CALLBACK_TEXT_HEADERS = Object.freeze({
+  ...CALLBACK_SECURITY_HEADERS,
+  'Content-Type': 'text/plain; charset=utf-8',
+});
+
+// Encryption uses AES-256-GCM with a machine-derived key.
+// This is not a substitute for OS keychain, but prevents plaintext tokens on disk.
+const ALGORITHM = 'aes-256-gcm';
+
+function openBrowser(url) {
+  if (process.platform === 'darwin') {
+    execFile('open', [url], () => {});
+  } else if (process.platform === 'win32') {
+    execFile('rundll32.exe', ['url.dll,FileProtocolHandler', url], () => {});
+  } else {
+    execFile('xdg-open', [url], () => {});
+  }
+}
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+// The Adrata mark — 8 dashed arc segments forming a ring (Figma node 525:158),
+// the same brand element the desktop app renders on its home and sign-in
+// screens. Inlined so these OAuth pages match the product surface.
+const ADRATA_MARK_SEGMENTS = [
+  'M41.3099 9.12903C37.7723 8.94462 34.2275 8.94462 30.6899 9.12903',
+  'M60.5402 18.7769C59.0102 15.3329 56.6672 12.9899 53.2202 11.4629',
+  'M62.8711 30.6899C63.0611 34.2274 63.0611 37.7725 62.8711 41.3099',
+  'M60.5401 53.2202C59.0101 56.6702 56.6701 59.0102 53.2231 60.5402',
+  'M41.3129 62.8682C37.7745 63.0593 34.2284 63.0603 30.6899 62.8712',
+  'M18.78 60.5371C15.33 59.0131 12.99 56.6671 11.46 53.2231',
+  'M9.12908 30.6899C8.94556 34.2286 8.94656 37.7744 9.13208 41.3129',
+  'M18.78 11.46C15.333 12.99 12.99 15.333 11.46 18.78',
+];
+
+function adrataMarkSvg(size, color) {
+  const paths = ADRATA_MARK_SEGMENTS.map(
+    (d) =>
+      `<path d="${d}" stroke="${color}" stroke-width="5.4" stroke-linecap="round" stroke-linejoin="round"/>`,
+  ).join('');
+  return `<svg width="${size}" height="${size}" viewBox="0 0 72 72" fill="none" aria-label="Adrata" role="img">${paths}</svg>`;
+}
+
+export function oauthCallbackPage({ success, title, message, detail }) {
+  const accent = success ? '#56d48f' : '#ff6b6b';
+  const safeTitle = escapeHtml(title);
+  const safeMessage = escapeHtml(message);
+  const safeDetail = detail ? escapeHtml(detail) : '';
+  const closeText = success
+    ? 'You can close this window and return to your terminal.'
+    : 'You can close this window and return to your workspace.';
+  // Success shows a small check badge tucked onto the ring; error shows nothing
+  // extra — the red ring carries the state. Matches the desktop's restraint.
+  const badge = success
+    ? `<span class="badge" aria-hidden="true"><svg width="15" height="15" viewBox="0 0 24 24" fill="none"><path d="M5 12.5l4.2 4.2L19 7" stroke="#0a0a0b" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/></svg></span>`
+    : '';
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${safeTitle} · Adrata</title><style>
+:root{color-scheme:dark}*{box-sizing:border-box}html,body{height:100%}body{margin:0;display:grid;place-items:center;padding:24px;background:#0a0a0b;color:#f5f5f6;font-family:-apple-system,BlinkMacSystemFont,"SF Pro Text","SF Pro Display",system-ui,sans-serif;-webkit-font-smoothing:antialiased}main{width:min(100%,460px);padding:48px 44px;border:1px solid #1b1b1f;border-radius:22px;background:#0f0f11;box-shadow:0 1px 0 0 rgba(255,255,255,.02) inset,0 30px 80px -20px rgba(0,0,0,.7);text-align:center}.mark{position:relative;width:64px;height:64px;margin:0 auto 26px;color:${accent}}.mark svg{display:block;filter:drop-shadow(0 0 14px ${accent}40)}.badge{position:absolute;right:-2px;bottom:-2px;display:grid;place-items:center;width:24px;height:24px;border-radius:50%;background:${accent};box-shadow:0 0 0 4px #0f0f11}h1{margin:0 0 10px;font-size:25px;font-weight:500;letter-spacing:-.02em;line-height:1.15}p{margin:0 auto;max-width:34ch;color:#9a9aa2;font-size:15px;line-height:1.6}.detail{margin-top:22px;padding:11px 13px;border-radius:11px;border:1px solid #1b1b1f;background:#0a0a0b;color:#6f6f78;font:12px/1.5 ui-monospace,"SF Mono",SFMono-Regular,Menlo,monospace;overflow-wrap:anywhere;text-align:left}.close{margin-top:28px;color:#6f6f78;font-size:12.5px;letter-spacing:.01em}</style></head><body><main><div class="mark">${adrataMarkSvg(
+    64,
+    accent,
+  )}${badge}</div><h1>${safeTitle}</h1><p>${safeMessage}</p>${
+    safeDetail ? `<div class="detail">${safeDetail}</div>` : ''
+  }<div class="close">${closeText}</div></main></body></html>`;
+}
+
+/**
+ * Derive a machine-specific encryption key from hostname + username.
+ * This is intentionally not high-security — it prevents casual plaintext
+ * exposure while remaining portable across sessions without a password.
+ */
+function deriveKey() {
+  const material = `adrata-mcp:${homedir()}:${process.env.USER || process.env.USERNAME || 'default'}`;
+  return createHash('sha256').update(material).digest();
+}
+
+function base64Url(buffer) {
+  return Buffer.from(buffer)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+function createPkcePair() {
+  const verifier = base64Url(randomBytes(32));
+  const challenge = base64Url(createHash('sha256').update(verifier).digest());
+  return { verifier, challenge };
+}
+
+function normalizeTokenResult(result) {
+  return {
+    accessToken: result.accessToken || result.access_token,
+    refreshToken: result.refreshToken || result.refresh_token,
+    expiresIn: result.expiresIn || result.expires_in,
+    scope: result.scope,
+  };
+}
+
+/**
+ * Register a fresh native/public client for this explicit connection attempt.
+ * PKCE protects the code exchange; an npm-embedded client secret would not.
+ */
+export async function registerNativeClient(
+  apiBase,
+  fetchImpl = fetch,
+  redirectUris = OAUTH_CALLBACK_ENDPOINTS.map(({ url: redirectUri }) => redirectUri),
+  scope = OAUTH_SCOPE,
+) {
+  const url = new URL(`${OAUTH_BASE_PATH}/register`, apiBase);
+  const res = await fetchImpl(url.toString(), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client_name: 'Adrata MCP',
+      redirect_uris: redirectUris,
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      // Must match what the authorize step will request. Registering the
+      // read-only scope while asking for write scopes leaves the
+      // authorization server free to narrow the grant back to read.
+      scope,
+      token_endpoint_auth_method: 'none',
+    }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`OAuth client registration failed: ${res.status} ${JSON.stringify(data).slice(0, 200)}`);
+  }
+  if (typeof data.client_id !== 'string' || !data.client_id) {
+    throw new Error('OAuth client registration returned no client_id.');
+  }
+  if (data.token_endpoint_auth_method !== 'none' || data.client_secret) {
+    throw new Error('OAuth server did not register a public PKCE client.');
+  }
+  return {
+    clientId: data.client_id,
+    registrationAccessToken: data.registration_access_token,
+    tokenEndpointAuthMethod: data.token_endpoint_auth_method,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Encryption helpers
+// ---------------------------------------------------------------------------
+
+function encrypt(plaintext) {
+  const key = deriveKey();
+  const iv = randomBytes(12);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(plaintext, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  const tag = cipher.getAuthTag().toString('hex');
+  return `${iv.toString('hex')}:${tag}:${encrypted}`;
+}
+
+function decrypt(ciphertext) {
+  const key = deriveKey();
+  const [ivHex, tagHex, encHex] = ciphertext.split(':');
+  if (!ivHex || !tagHex || !encHex) throw new Error('Malformed encrypted token');
+  const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(ivHex, 'hex'));
+  decipher.setAuthTag(Buffer.from(tagHex, 'hex'));
+  let decrypted = decipher.update(encHex, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+  return decrypted;
+}
+
+// ---------------------------------------------------------------------------
+// Token storage
+// ---------------------------------------------------------------------------
+
+function ensureDir() {
+  if (!existsSync(ADRATA_DIR)) {
+    mkdirSync(ADRATA_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Save tokens to ~/.adrata/tokens.json (encrypted).
+ */
+export function saveTokens(tokenData) {
+  ensureDir();
+  const payload = {
+    v: 1,
+    data: encrypt(JSON.stringify(tokenData)),
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(TOKEN_FILE, JSON.stringify(payload, null, 2), { mode: 0o600 });
+  try { chmodSync(TOKEN_FILE, 0o600); } catch { /* best-effort */ }
+}
+
+/**
+ * Load tokens from ~/.adrata/tokens.json. Returns null if not found or invalid.
+ */
+export function loadTokens() {
+  try {
+    if (!existsSync(TOKEN_FILE)) return null;
+    const raw = JSON.parse(readFileSync(TOKEN_FILE, 'utf8'));
+    if (raw.v !== 1 || !raw.data) return null;
+    return JSON.parse(decrypt(raw.data));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clear stored tokens (for disconnect).
+ */
+export function clearTokens() {
+  try {
+    if (existsSync(TOKEN_FILE)) unlinkSync(TOKEN_FILE);
+  } catch { /* ignore */ }
+}
+
+/**
+ * Check if we have stored tokens.
+ */
+export function hasStoredTokens() {
+  return loadTokens() !== null;
+}
+
+// ---------------------------------------------------------------------------
+// Token refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if the access token is expired or about to expire (within 5 min).
+ */
+function isTokenExpired(tokens) {
+  if (!tokens.expiresAt) return true;
+  const expiresAt = new Date(tokens.expiresAt).getTime();
+  const now = Date.now();
+  const bufferMs = 5 * 60 * 1000; // 5 minutes
+  return now >= expiresAt - bufferMs;
+}
+
+/**
+ * OAuth tokens are audience/environment bound. Never send a stored access or
+ * refresh token to an API origin other than the one that issued the session.
+ */
+export function storedSessionMatchesApiBase(apiBase, tokens = loadTokens()) {
+  if (!tokens?.apiBase) return true;
+  try {
+    return new URL(tokens.apiBase).origin === new URL(apiBase).origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The refresh token is dead — revoked, expired, rotated away, or bound to a
+ * different API/audience. The only recovery is an interactive reconnect, so
+ * callers should surface "run connect_workspace" rather than silently 401.
+ */
+export class ReconnectRequiredError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = 'ReconnectRequiredError';
+    this.code = 'reconnect_required';
+    this.reconnectRequired = true;
+  }
+}
+
+/**
+ * A transient failure refreshing the access token (network error, timeout,
+ * 429, or 5xx). The stored refresh token is probably still valid and the
+ * caller may retry shortly. Kept distinct from ReconnectRequiredError so a
+ * flaky network never masquerades as a revoked session.
+ */
+export class TransientRefreshError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = 'TransientRefreshError';
+    this.code = 'refresh_transient';
+    this.transient = true;
+  }
+}
+
+const REFRESH_MAX_ATTEMPTS = 3;
+const REFRESH_BASE_DELAY_MS = 250;
+
+function refreshBackoffDelay(attempt) {
+  // Exponential backoff with light jitter: ~250ms then ~500ms between attempts.
+  const base = REFRESH_BASE_DELAY_MS * 2 ** (attempt - 1);
+  return base + Math.floor(Math.random() * REFRESH_BASE_DELAY_MS);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * In-flight refresh promises keyed by API base. The authorization server
+ * ROTATES and revokes the previous refresh token on every refresh, so N
+ * concurrent tool calls must NOT each POST /token — the first would win and the
+ * rest would get invalid_grant. We single-flight: concurrent callers for the
+ * same apiBase await one shared refresh.
+ */
+const _inflightRefresh = new Map();
+
+/**
+ * Refresh the access token using the refresh token.
+ *
+ * - Single-flight: concurrent callers for the same apiBase share one refresh.
+ * - Retries transient failures (network / 429 / 5xx) with backoff.
+ * - Throws ReconnectRequiredError when the refresh token is rejected
+ *   (invalid_grant and other 4xx) so the caller can prompt a reconnect instead
+ *   of silently 401ing.
+ * - Preserves the RFC 8707 `resource` audience binding across the refresh.
+ *
+ * Updates stored tokens on success.
+ */
+export async function refreshAccessToken(apiBase, fetchImpl = fetch) {
+  const existing = _inflightRefresh.get(apiBase);
+  if (existing) return existing;
+
+  const inflight = performTokenRefresh(apiBase, fetchImpl).finally(() => {
+    _inflightRefresh.delete(apiBase);
+  });
+  _inflightRefresh.set(apiBase, inflight);
+  return inflight;
+}
+
+async function performTokenRefresh(apiBase, fetchImpl) {
+  const tokens = loadTokens();
+  if (!tokens || !tokens.refreshToken) {
+    throw new ReconnectRequiredError(
+      'No refresh token available. Run connect_workspace to reconnect your workspace.',
+    );
+  }
+  if (!storedSessionMatchesApiBase(apiBase, tokens)) {
+    throw new ReconnectRequiredError(
+      'OAuth session/API mismatch. Run connect_workspace against the target workspace or correct ADRATA_API_URL.',
+    );
+  }
+
+  const url = new URL(`${OAUTH_BASE_PATH}/token`, apiBase);
+  const buildBody = () => new URLSearchParams({
+    grant_type: 'refresh_token',
+    client_id: tokens.clientId,
+    refresh_token: tokens.refreshToken,
+    // RFC 8707: keep the same audience binding the initial grant used so the
+    // refreshed access token stays bound to the /api/v1/mcp resource.
+    resource: tokens.resource || canonicalResource(),
+  });
+
+  let lastError;
+  for (let attempt = 1; attempt <= REFRESH_MAX_ATTEMPTS; attempt += 1) {
+    let res;
+    try {
+      res = await fetchImpl(url.toString(), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: buildBody(),
+      });
+    } catch (err) {
+      // Network-level failure — transient, worth a retry.
+      lastError = new TransientRefreshError(
+        `Token refresh network error: ${err.message}`,
+        { cause: err },
+      );
+      if (attempt < REFRESH_MAX_ATTEMPTS) {
+        await sleep(refreshBackoffDelay(attempt));
+        continue;
+      }
+      throw lastError;
+    }
+
+    const data = await res.json().catch(() => ({}));
+
+    if (res.ok) {
+      const result = normalizeTokenResult(data.data || data);
+      const updatedTokens = {
+        ...tokens,
+        accessToken: result.accessToken,
+        expiresAt: new Date(Date.now() + (result.expiresIn || 3600) * 1000).toISOString(),
+        // Refresh token may rotate — persist the new one so the next refresh works.
+        ...(result.refreshToken ? { refreshToken: result.refreshToken } : {}),
+      };
+      saveTokens(updatedTokens);
+      return updatedTokens;
+    }
+
+    // Transient server-side failure — retry with backoff.
+    if (res.status === 429 || res.status >= 500) {
+      lastError = new TransientRefreshError(
+        `Token refresh failed: ${res.status} ${JSON.stringify(data).slice(0, 200)}`,
+      );
+      if (attempt < REFRESH_MAX_ATTEMPTS) {
+        await sleep(refreshBackoffDelay(attempt));
+        continue;
+      }
+      throw lastError;
+    }
+
+    // 4xx (invalid_grant, invalid_client, invalid_request, …): the refresh
+    // token is dead. Retrying cannot help — surface a reconnect requirement.
+    const errorCode = data.error || data.data?.error;
+    throw new ReconnectRequiredError(
+      `Refresh token rejected (${res.status}${errorCode ? ` ${errorCode}` : ''}). `
+      + 'Run connect_workspace to reconnect your workspace.',
+    );
+  }
+
+  // Unreachable in practice, but keep the type contract honest.
+  throw lastError || new TransientRefreshError('Token refresh failed after retries.');
+}
+
+/**
+ * Get a valid access token, refreshing if expired.
+ *
+ * Returns null only when NO workspace session is stored (not connected). When a
+ * session exists but the refresh fails, this THROWS a typed error
+ * (ReconnectRequiredError or TransientRefreshError) instead of returning null —
+ * a silent null previously let callers proceed unauthenticated and 401 with no
+ * discoverable reason.
+ */
+export async function getValidToken(apiBase, { forceRefresh = false, fetchImpl = fetch } = {}) {
+  const tokens = loadTokens();
+  if (!tokens) return null;
+
+  if (forceRefresh || isTokenExpired(tokens)) {
+    const refreshed = await refreshAccessToken(apiBase, fetchImpl);
+    return refreshed.accessToken;
+  }
+
+  return tokens.accessToken;
+}
+
+// ---------------------------------------------------------------------------
+// OAuth authorization flow
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the OAuth authorization URL.
+ */
+function buildAuthUrl(apiBase, clientId, redirectUri, state, pkce, scope = OAUTH_SCOPE) {
+  // Use the web app's OAuth authorize page (user-facing login + consent screen)
+  const url = new URL(`${OAUTH_BASE_PATH}/authorize`, apiBase);
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('scope', scope);
+  url.searchParams.set('state', state);
+  url.searchParams.set('source', 'mcp');
+  // RFC 8707 Resource Indicator — request a token audience-bound to this MCP
+  // resource so it cannot be replayed against a different service.
+  url.searchParams.set('resource', canonicalResource());
+  url.searchParams.set('code_challenge', pkce.challenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  return { url: url.toString(), state, codeVerifier: pkce.verifier };
+}
+
+/**
+ * Start a temporary local HTTP server to receive the OAuth callback.
+ * Returns a promise that resolves with { code, state } or rejects on timeout/error.
+ */
+export async function startCallbackServer(expectedState, timeoutMs = 120000) {
+  let lastError;
+  for (const endpoint of OAUTH_CALLBACK_ENDPOINTS) {
+    try {
+      return await listenForCallback(endpoint, expectedState, timeoutMs);
+    } catch (err) {
+      lastError = err;
+      if (!['EADDRNOTAVAIL', 'EAFNOSUPPORT'].includes(err.code)) throw err;
+    }
+  }
+  throw new Error(`No supported OAuth loopback address is available: ${lastError?.message || 'unknown error'}`);
+}
+
+function listenForCallback(endpoint, expectedState, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let listening = false;
+    const server = createServer((req, res) => {
+      const reqUrl = new URL(req.url, endpoint.url);
+
+      if (reqUrl.pathname !== CALLBACK_PATH) {
+        res.writeHead(404, CALLBACK_TEXT_HEADERS);
+        res.end('Not found');
+        return;
+      }
+
+      const code = reqUrl.searchParams.get('code');
+      const state = reqUrl.searchParams.get('state');
+      const error = reqUrl.searchParams.get('error');
+
+      if (error) {
+        res.writeHead(200, CALLBACK_HTML_HEADERS);
+        res.end(oauthCallbackPage({ success: false, title: 'Authorization failed', message: 'Adrata could not connect this client. Return to your workspace and try connecting again.', detail: 'oauth_authorization_failed' }));
+        cleanup();
+        const oauthError = new Error(`OAuth error: ${error}`);
+        oauthError.code = error;
+        callbackReject(oauthError);
+        return;
+      }
+
+      if (state !== expectedState) {
+        res.writeHead(400, CALLBACK_HTML_HEADERS);
+        res.end(oauthCallbackPage({ success: false, title: 'Connection could not be verified', message: 'The security state did not match. Start a new connection from Adrata.', detail: 'oauth_state_mismatch' }));
+        cleanup();
+        callbackReject(new Error('OAuth state mismatch (possible CSRF)'));
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400, CALLBACK_HTML_HEADERS);
+        res.end(oauthCallbackPage({ success: false, title: 'Connection incomplete', message: 'No authorization code was returned. Start a new connection from Adrata.', detail: 'missing_authorization_code' }));
+        cleanup();
+        callbackReject(new Error('No authorization code in callback'));
+        return;
+      }
+
+      res.writeHead(200, CALLBACK_HTML_HEADERS);
+      res.end(oauthCallbackPage({ success: true, title: 'Connected to Adrata', message: 'Your workspace connection is ready.' }));
+      cleanup();
+      callbackResolve({ code, state });
+    });
+
+    let callbackResolve;
+    let callbackReject;
+    const callback = new Promise((callbackResolveFn, callbackRejectFn) => {
+      callbackResolve = callbackResolveFn;
+      callbackReject = callbackRejectFn;
+    });
+    const timer = setTimeout(() => {
+      cleanup();
+      callbackReject(new Error('OAuth callback timed out after 2 minutes. Please try again.'));
+    }, timeoutMs);
+
+    function cleanup() {
+      clearTimeout(timer);
+      try { server.close(); } catch { /* ignore */ }
+    }
+
+    const listenOptions = {
+      port: CALLBACK_PORT,
+      host: endpoint.host,
+      ...(endpoint.host === '::1' ? { ipv6Only: true } : {}),
+    };
+    server.listen(listenOptions, () => {
+      listening = true;
+      resolve({ redirectUri: endpoint.url, callback, close: cleanup });
+    });
+
+    server.on('error', (err) => {
+      cleanup();
+      err.message = `Failed to start OAuth callback server on ${endpoint.host}: ${err.message}`;
+      if (listening) callbackReject(err);
+      else reject(err);
+    });
+  });
+}
+
+/**
+ * Build the request handler separately from the fixed-port listener so the
+ * complete browser response contract can be tested on an ephemeral port.
+ */
+export function createOAuthCallbackRequestHandler({
+  endpointUrl,
+  expectedState,
+  onComplete,
+  onResolve,
+  onReject,
+}) {
+  return (req, res) => {
+    let reqUrl;
+    try {
+      reqUrl = new URL(req.url, endpointUrl);
+    } catch {
+      res.writeHead(400, CALLBACK_TEXT_HEADERS);
+      res.end('Bad request');
+      return;
+    }
+
+    if (reqUrl.pathname !== CALLBACK_PATH) {
+      res.writeHead(404, CALLBACK_TEXT_HEADERS);
+      res.end('Not found');
+      return;
+    }
+
+    const code = reqUrl.searchParams.get('code');
+    const state = reqUrl.searchParams.get('state');
+    const error = reqUrl.searchParams.get('error');
+
+    if (error) {
+      res.writeHead(200, CALLBACK_HTML_HEADERS);
+      res.end(oauthCallbackPage({ success: false, title: 'Authorization failed', message: 'Adrata could not connect this client. Return to your workspace and try connecting again.', detail: 'oauth_authorization_failed' }));
+      onComplete();
+      const oauthError = new Error(`OAuth error: ${error}`);
+      oauthError.code = error;
+      onReject(oauthError);
+      return;
+    }
+
+    if (state !== expectedState) {
+      res.writeHead(400, CALLBACK_HTML_HEADERS);
+      res.end(oauthCallbackPage({ success: false, title: 'Connection could not be verified', message: 'The security state did not match. Start a new connection from Adrata.', detail: 'oauth_state_mismatch' }));
+      onComplete();
+      onReject(new Error('OAuth state mismatch (possible CSRF)'));
+      return;
+    }
+
+    if (!code) {
+      res.writeHead(400, CALLBACK_HTML_HEADERS);
+      res.end(oauthCallbackPage({ success: false, title: 'Connection incomplete', message: 'No authorization code was returned. Start a new connection from Adrata.', detail: 'missing_authorization_code' }));
+      onComplete();
+      onReject(new Error('No authorization code in callback'));
+      return;
+    }
+
+    res.writeHead(200, CALLBACK_HTML_HEADERS);
+    res.end(oauthCallbackPage({ success: true, title: 'Connected to Adrata', message: 'Your workspace connection is ready.' }));
+    onComplete();
+    onResolve({ code, state });
+  };
+}
+
+/**
+ * Exchange an authorization code for tokens.
+ */
+async function exchangeCode(apiBase, code, clientId, codeVerifier, redirectUri) {
+  const url = new URL(`${OAUTH_BASE_PATH}/token`, apiBase);
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: clientId,
+    code,
+    code_verifier: codeVerifier,
+    redirect_uri: redirectUri,
+    resource: canonicalResource(),
+  });
+
+  const res = await fetch(url.toString(), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`Token exchange failed: ${res.status} ${JSON.stringify(data).slice(0, 200)}`);
+  }
+
+  return normalizeTokenResult(data.data || data);
+}
+
+/**
+ * Revoke tokens on the server.
+ */
+async function revokeToken(apiBase, accessToken) {
+  try {
+    const url = new URL(`${OAUTH_BASE_PATH}/revoke`, apiBase);
+    const body = new URLSearchParams({ token: accessToken });
+    await fetch(url.toString(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Authorization': `Bearer ${accessToken}`,
+      },
+      body,
+    });
+  } catch {
+    // Best-effort revocation — token will expire naturally if server unreachable
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Workspace capabilities
+// ---------------------------------------------------------------------------
+
+/** In-memory capability cache */
+let _workspaceCapabilities = null;
+
+/**
+ * Fetch workspace capabilities from the API.
+ */
+export async function fetchWorkspaceCapabilities(apiBase, accessToken, fetchImpl = fetch) {
+  try {
+    const url = new URL('/api/v1/capabilities/workspace', apiBase);
+    const res = await fetchImpl(url.toString(), {
+      headers: { 'Authorization': `Bearer ${accessToken}` },
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    _workspaceCapabilities = data.data || data;
+    return _workspaceCapabilities;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get cached workspace capabilities.
+ */
+export function getWorkspaceCapabilities() {
+  return _workspaceCapabilities;
+}
+
+/**
+ * Check if a specific capability is enabled.
+ */
+export function hasCapability(name) {
+  if (!_workspaceCapabilities) return false;
+  const caps = _workspaceCapabilities.features || _workspaceCapabilities;
+  if (Array.isArray(caps)) return caps.includes(name);
+  return !!caps[name];
+}
+
+// ---------------------------------------------------------------------------
+// Public API: connect and disconnect workspace
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the full OAuth connect flow:
+ *   1. Open browser to authorization URL
+ *   2. Wait for callback with auth code
+ *   3. Exchange code for tokens
+ *   4. Store tokens securely
+ *   5. Fetch workspace capabilities
+ *
+ * @param {string} apiBase - The Adrata API base URL
+ * @param {object} [options]
+ * @param {boolean} [options.writeAccess=false] - Additionally request the
+ *   opt-in CRM write scopes (OAUTH_WRITE_SCOPE). Off by default so the
+ *   ordinary connection stays least-privilege.
+ * @returns {object} Connection result with workspace info
+ */
+export async function connectWorkspace(apiBase, { writeAccess = false } = {}) {
+  const requestedScope = oauthScopeFor({ writeAccess });
+  const state = randomBytes(16).toString('hex');
+  const pkce = createPkcePair();
+
+  // Bind before registration so the client advertises only the callback URI
+  // this host can actually receive, which narrows the registered redirect
+  // surface to exactly one exact-match URI. See OAUTH_CALLBACK_ENDPOINTS for
+  // why that negotiation prefers the IPv4 loopback.
+  const callbackServer = await startCallbackServer(state);
+
+  // Prefer an explicitly provisioned client when an operator supplies one.
+  // Otherwise use RFC 7591 DCR so every installation gets a real public client
+  // instead of relying on a database seed or a secret embedded in npm.
+  const configuredClientId = process.env.ADRATA_MCP_CLIENT_ID?.trim();
+  let registration;
+  try {
+    registration = configuredClientId
+      ? { clientId: configuredClientId, tokenEndpointAuthMethod: 'none' }
+      : await registerNativeClient(apiBase, fetch, [callbackServer.redirectUri], requestedScope);
+  } catch (error) {
+    callbackServer.close();
+    throw error;
+  }
+  const clientId = registration.clientId;
+  const authUrl = buildAuthUrl(
+    apiBase,
+    clientId,
+    callbackServer.redirectUri,
+    state,
+    pkce,
+    requestedScope,
+  ).url;
+
+  if (process.env.ADRATA_MCP_PRINT_AUTH_URL === '1') {
+    console.error(`[adrata-mcp] Open this URL to authorize the workspace: ${authUrl}`);
+  }
+
+  // Step 2: Open browser
+  openBrowser(authUrl);
+
+  // Step 3: Wait for callback
+  const { code } = await callbackServer.callback;
+
+  // Step 4: Exchange code for tokens
+  const tokenResult = await exchangeCode(
+    apiBase,
+    code,
+    clientId,
+    pkce.verifier,
+    callbackServer.redirectUri,
+  );
+
+  // Step 5: Store tokens
+  const tokenData = {
+    accessToken: tokenResult.accessToken,
+    refreshToken: tokenResult.refreshToken,
+    expiresAt: new Date(Date.now() + (tokenResult.expiresIn || 3600) * 1000).toISOString(),
+    // The SERVER's granted scope wins. If the authorization server narrows the
+    // grant (unregistered client scope, consent declined), the stored scope
+    // must reflect what was actually granted -- never what we asked for.
+    scope: tokenResult.scope || requestedScope,
+    clientId,
+    clientRegistration: configuredClientId ? 'configured' : 'dynamic',
+    tokenEndpointAuthMethod: registration.tokenEndpointAuthMethod,
+    resource: canonicalResource(),
+    apiBase,
+    connectedAt: new Date().toISOString(),
+  };
+  saveTokens(tokenData);
+
+  // Step 6: Fetch workspace capabilities
+  const capabilities = await fetchWorkspaceCapabilities(apiBase, tokenData.accessToken);
+
+  // The message must match what the granted scope actually supports — never
+  // assert "enterprise tools are now available" when the scope this flow
+  // requests (OAUTH_SCOPE) is deliberately read-only. See
+  // describeOAuthScopeCapabilities above.
+  const grantedAccess = describeOAuthScopeCapabilities(tokenData.scope);
+
+  return {
+    connected: true,
+    scope: tokenData.scope,
+    expiresAt: tokenData.expiresAt,
+    capabilities: capabilities || 'Unable to fetch capabilities (may require workspace setup)',
+    grantedAccess: grantedAccess.summary,
+    message: grantedAccess.canWrite
+      ? 'Workspace connected successfully. Enterprise tools are now available.'
+      : 'Workspace connected successfully with read-only access. See grantedAccess for exactly what this unlocks — CRM writes, email sending, sequences, and admin actions still require a signed-in human session, not this OAuth connection.',
+  };
+}
+
+/**
+ * Disconnect the workspace: revoke tokens and clear local storage.
+ *
+ * @param {string} apiBase - The Adrata API base URL
+ * @returns {object} Disconnection result
+ */
+export async function disconnectWorkspace(apiBase) {
+  const tokens = loadTokens();
+
+  if (tokens && tokens.accessToken) {
+    await revokeToken(apiBase, tokens.accessToken);
+  }
+
+  clearTokens();
+  _workspaceCapabilities = null;
+
+  return {
+    disconnected: true,
+    message: 'Workspace disconnected. Tokens revoked and local credentials cleared. Enterprise tools are no longer available.',
+  };
+}
+
+/**
+ * Get the current connection status.
+ */
+export async function getConnectionStatus(apiBase) {
+  const tokens = loadTokens();
+  if (!tokens) {
+    return {
+      connected: false,
+      message: 'No workspace connected. Use connect_workspace to set up OAuth.',
+    };
+  }
+
+  let accessToken;
+  try {
+    accessToken = await getValidToken(apiBase);
+  } catch (err) {
+    const reconnectRequired = err instanceof ReconnectRequiredError;
+    return {
+      connected: false,
+      reconnectRequired,
+      transient: err instanceof TransientRefreshError,
+      storedCredentials: true,
+      scope: tokens.scope,
+      connectedAt: tokens.connectedAt,
+      expiresAt: tokens.expiresAt,
+      hasRefreshToken: !!tokens.refreshToken,
+      message: reconnectRequired
+        ? 'Stored workspace credentials expired or were revoked. Reconnect the workspace before using governed tools.'
+        : 'Could not refresh the workspace session due to a temporary network issue. Try again in a moment; no reconnect needed.',
+    };
+  }
+
+  if (!accessToken) {
+    return {
+      connected: false,
+      reconnectRequired: true,
+      storedCredentials: true,
+      scope: tokens.scope,
+      connectedAt: tokens.connectedAt,
+      expiresAt: tokens.expiresAt,
+      hasRefreshToken: !!tokens.refreshToken,
+      message: 'Stored workspace credentials expired or were revoked. Reconnect the workspace before using governed tools.',
+    };
+  }
+
+  const capabilities = await fetchWorkspaceCapabilities(apiBase, accessToken);
+
+  return {
+    connected: true,
+    scope: tokens.scope,
+    connectedAt: tokens.connectedAt,
+    expiresAt: tokens.expiresAt,
+    hasRefreshToken: !!tokens.refreshToken,
+    capabilities: capabilities || _workspaceCapabilities || 'Workspace session is valid; capabilities are temporarily unavailable.',
+  };
+}