@wickedevolutions/abilities-mcp 1.3.1 → 1.5.1

package/lib/config.js

@@ -1,24 +1,78 @@
 'use strict';
 
-const { execSync } = require('child_process');
+const { exec } = require('child_process');
+const { promisify } = require('util');
 const fs = require('fs');
+const fsp = require('fs').promises;
 const path = require('path');
 const os = require('os');
 
+const execAsync = promisify(exec);
+
 /**
- * Load configuration from wp-sites.json or build from CLI args.
+ * Load configuration from wp-sites.json, environment variables, or CLI args.
  *
- * Search order for wp-sites.json:
+ * Search order:
  *   1. --config=<path> explicit path
  *   2. Same directory as abilities-mcp.js
  *   3. ~/.abilities-mcp/wp-sites.json
+ *   4. ABILITIES_MCP_URL/USERNAME/PASSWORD env vars (single-site, .mcpb path)
+ *   5. --host/--path CLI args (legacy SSH single-site)
  *
- * If no config file and --host/--path provided, builds a single-site legacy config.
+ * Per Issue #5 / Phase E.2 (Stretch to Stable sprint): the startup chain
+ * — `resolveConfigFilePath`, `loadConfig`, `loadConfigFile`,
+ * `validateSiteConfig`, `resolvePassword` — is async so file reads and
+ * `passwordCommand` shell-outs do not block the event loop during boot.
  *
  * Copyright (C) 2026 Influencentricity | Wicked Evolutions
  * @license GPL-2.0-or-later
  */
-function loadConfig(args) {
+
+/**
+ * Async non-throwing existence check. Returns true iff the path resolves
+ * via fs.access(); any error (ENOENT, EACCES, …) yields false. Used by the
+ * search-order helpers which only care whether a candidate file is readable.
+ */
+async function _exists(p) {
+  try {
+    await fsp.access(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the on-disk wp-sites.json path that `loadConfig` would consume,
+ * without reading or validating it. Returns `null` when no file path applies
+ * (env-var single-site, legacy --host/--path, or no config at all).
+ *
+ * Used by the v1→v2 migration shim in `abilities-mcp.js` so the migration can
+ * run before `loadConfig` parses + validates a stale v1 file.
+ *
+ * Mirrors steps 1-3 of `loadConfig`'s search order. Steps 4-5 (env / legacy
+ * CLI) intentionally return `null` — there is no on-disk file to migrate.
+ *
+ * @param {object} args
+ * @returns {Promise<string|null>}  Absolute path of the resolved wp-sites.json, or null.
+ */
+async function resolveConfigFilePath(args) {
+  if (args && args.config) {
+    return path.resolve(args.config);
+  }
+  const scriptDir = path.resolve(__dirname, '..');
+  const scriptConfig = path.join(scriptDir, 'wp-sites.json');
+  if (await _exists(scriptConfig)) {
+    return scriptConfig;
+  }
+  const homeConfig = path.join(os.homedir(), '.abilities-mcp', 'wp-sites.json');
+  if (await _exists(homeConfig)) {
+    return homeConfig;
+  }
+  return null;
+}
+
+async function loadConfig(args) {
   // Explicit config path
   if (args.config) {
     return loadConfigFile(args.config);
@@ -27,33 +81,111 @@ function loadConfig(args) {
   // Check alongside script (lib/ → package root)
   const scriptDir = path.resolve(__dirname, '..');
   const scriptConfig = path.join(scriptDir, 'wp-sites.json');
-  if (fs.existsSync(scriptConfig)) {
+  if (await _exists(scriptConfig)) {
     return loadConfigFile(scriptConfig);
   }
 
   // Check home directory
   const homeConfig = path.join(os.homedir(), '.abilities-mcp', 'wp-sites.json');
-  if (fs.existsSync(homeConfig)) {
+  if (await _exists(homeConfig)) {
     return loadConfigFile(homeConfig);
   }
 
+  // Env-var single-site config — covers the .mcpb install path and any
+  // env-var-based MCP client configuration (claude mcp add, Docker, etc.)
+  if (process.env.ABILITIES_MCP_URL) {
+    return buildEnvConfig(process.env);
+  }
+
   // Legacy CLI mode — single site from --host/--path
   if (args.host && args.path) {
     return buildLegacyConfig(args);
   }
 
   throw new Error(
-    'No wp-sites.json found and no --host/--path provided.\n' +
-    'Create wp-sites.json or use: --host=<ssh-host> --path=<wp-path>'
+    'No configuration found.\n' +
+    'Provide one of: wp-sites.json, ABILITIES_MCP_URL+USERNAME+PASSWORD env vars, or --host/--path.'
   );
 }
 
-function loadConfigFile(filePath) {
-  const raw = fs.readFileSync(filePath, 'utf8');
+/**
+ * Build single-site config from env vars (ABILITIES_MCP_URL/USERNAME/PASSWORD).
+ *
+ * Auto-derives the MCP adapter endpoint from the site URL:
+ *   https://example.com  →  https://example.com/wp-json/mcp/mcp-adapter-default-server
+ *
+ * This is the path used by .mcpb bundles installed in Claude Desktop and any
+ * other env-var-based MCP client configuration.
+ */
+function buildEnvConfig(env) {
+  const rawUrl = env.ABILITIES_MCP_URL;
+  const username = env.ABILITIES_MCP_USERNAME;
+  const password = env.ABILITIES_MCP_PASSWORD;
+
+  if (!username) {
+    throw new Error('ABILITIES_MCP_URL is set but ABILITIES_MCP_USERNAME is missing');
+  }
+  if (!password) {
+    throw new Error('ABILITIES_MCP_URL is set but ABILITIES_MCP_PASSWORD is missing');
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(rawUrl);
+  } catch (e) {
+    throw new Error(`ABILITIES_MCP_URL is not a valid URL: ${rawUrl}`);
+  }
+
+  const isHttps = parsedUrl.protocol === 'https:';
+  const isHttp = parsedUrl.protocol === 'http:';
+  if (!isHttps && !isHttp) {
+    throw new Error(`ABILITIES_MCP_URL must be http or https: ${rawUrl}`);
+  }
+
+  // Strip trailing slash from origin+path, then append the adapter route.
+  const base = (parsedUrl.origin + parsedUrl.pathname).replace(/\/+$/, '');
+  const endpoint = `${base}/wp-json/mcp/mcp-adapter-default-server`;
+
+  const siteConfig = {
+    label: parsedUrl.hostname,
+    url: parsedUrl.origin,
+    transport: 'http',
+    http: {
+      endpoint,
+      username,
+      password,
+    },
+  };
+
+  // Allow plain HTTP only when the operator explicitly opts in. The .mcpb path
+  // expects HTTPS by default; localhost dev gets a narrow exception.
+  if (isHttp) {
+    const isLocal = parsedUrl.hostname === 'localhost' || parsedUrl.hostname === '127.0.0.1';
+    if (!isLocal && env.ABILITIES_MCP_ALLOW_INSECURE !== 'true') {
+      throw new Error(
+        `ABILITIES_MCP_URL is HTTP (not HTTPS): ${rawUrl}\n` +
+        `Set ABILITIES_MCP_ALLOW_INSECURE=true to allow plain HTTP.`
+      );
+    }
+    siteConfig.allowInsecure = true;
+  }
+
+  return {
+    defaultSite: 'default',
+    _isMultiSite: false,
+    _configSource: 'env',
+    sites: {
+      default: siteConfig,
+    },
+  };
+}
+
+async function loadConfigFile(filePath) {
+  const raw = await fsp.readFile(filePath, 'utf8');
 
   // Warn if config file is readable by group or world
   try {
-    const stat = fs.statSync(filePath);
+    const stat = await fsp.stat(filePath);
     if (stat.mode & 0o077) {
       process.stderr.write(
         `WARNING: ${filePath} is readable by group/world (mode ${(stat.mode & 0o777).toString(8)}). ` +
@@ -78,7 +210,7 @@ function loadConfigFile(filePath) {
 
   // Validate each site
   for (const [key, site] of Object.entries(config.sites)) {
-    validateSiteConfig(key, site);
+    await validateSiteConfig(key, site);
   }
 
   config._isMultiSite = Object.keys(config.sites).length > 1 ||
@@ -88,7 +220,57 @@ function loadConfigFile(filePath) {
   return config;
 }
 
-function validateSiteConfig(key, site) {
+async function validateSiteConfig(key, site) {
+  // v2 OAuth sites carry no transport block (Appendix F.5 + add-site flow).
+  // The runtime treats them as HTTP — endpoint comes from auth.mcp_resource
+  // or site.mcp_resource (resolved by the OAuth-aware transport).
+  if (site.auth && site.auth.method === 'oauth') {
+    if (!site.url) {
+      throw new Error(`Site "${key}" (oauth): requires "url"`);
+    }
+    if (!site.auth.access_token_ref || !site.auth.refresh_token_ref) {
+      throw new Error(`Site "${key}" (oauth): requires auth.access_token_ref and auth.refresh_token_ref`);
+    }
+    if (!site.mcp_resource) {
+      throw new Error(`Site "${key}" (oauth): requires mcp_resource (set during add-site / reauth)`);
+    }
+    if (!site.mcp_resource.startsWith('https://') && !site.allowInsecure) {
+      throw new Error(`Site "${key}" (oauth): mcp_resource is not HTTPS. Set "allowInsecure": true on the site to allow HTTP`);
+    }
+    return;
+  }
+
+  // v2 App-Password sites — produced by config-migration from v1 transport-style
+  // configs. Secret lives in keychain (auth.password_ref); the legacy http.password*
+  // fields are stripped during migration so the keychain is the sole source of
+  // truth. Carrier transport (http or ssh) is preserved for the runtime.
+  if (site.auth && site.auth.method === 'apppassword') {
+    if (!site.auth.username) {
+      throw new Error(`Site "${key}" (apppassword): requires auth.username`);
+    }
+    if (!site.auth.password_ref) {
+      throw new Error(`Site "${key}" (apppassword): requires auth.password_ref`);
+    }
+    if (!site.transport) {
+      throw new Error(`Site "${key}" (apppassword): missing "transport" (ssh or http)`);
+    }
+    if (site.transport === 'ssh') {
+      if (!site.ssh || !site.ssh.host || !site.ssh.path) {
+        throw new Error(`Site "${key}" (apppassword/ssh): requires ssh.host and ssh.path`);
+      }
+    } else if (site.transport === 'http') {
+      if (!site.http || !site.http.endpoint) {
+        throw new Error(`Site "${key}" (apppassword/http): requires http.endpoint`);
+      }
+      if (!site.http.endpoint.startsWith('https://') && !site.allowInsecure) {
+        throw new Error(`Site "${key}" (apppassword/http): endpoint is not HTTPS. Set "allowInsecure": true on the site to allow HTTP`);
+      }
+    } else {
+      throw new Error(`Site "${key}" (apppassword): unknown transport "${site.transport}" (use ssh or http)`);
+    }
+    return;
+  }
+
   if (!site.transport) {
     throw new Error(`Site "${key}": missing "transport" (ssh or http)`);
   }
@@ -137,6 +319,7 @@ function buildLegacyConfig(args) {
 
 /**
  * Resolve a composite site key like "wicked.community" into config + subsite URL.
+ * Pure in-memory dispatch — kept synchronous since it has no I/O.
  */
 function resolveSiteKey(config, compositeKey) {
   // Direct match — "helena" or "wicked"
@@ -189,17 +372,23 @@ function buildSiteKeyEnum(config) {
 }
 
 /**
- * Resolve the password for an HTTP transport config, supporting
- * plaintext password, environment variable, or shell command.
+ * Resolve the password for an HTTP transport config, supporting plaintext
+ * password, environment variable, or shell command.
+ *
+ * `passwordCommand` is dispatched through `util.promisify(exec)` so the shell
+ * interprets the command string the same way the previous `execSync` did
+ * (operators rely on pipes, redirects, and command chaining — e.g.
+ * `op read 'op://Vault/foo' | tr -d '\n'` — which `execFile` cannot run).
  */
-function resolvePassword(httpConfig) {
+async function resolvePassword(httpConfig) {
   if (httpConfig.passwordEnv) {
     const val = process.env[httpConfig.passwordEnv];
     if (!val) throw new Error(`Environment variable ${httpConfig.passwordEnv} is not set`);
     return val;
   }
   if (httpConfig.passwordCommand) {
-    return execSync(httpConfig.passwordCommand, { encoding: 'utf8' }).trim();
+    const { stdout } = await execAsync(httpConfig.passwordCommand, { encoding: 'utf8' });
+    return stdout.trim();
   }
   if (httpConfig.password) {
     return httpConfig.password;
@@ -207,4 +396,44 @@ function resolvePassword(httpConfig) {
   throw new Error('No password, passwordEnv, or passwordCommand configured');
 }
 
-module.exports = { loadConfig, resolvePassword, resolveSiteKey, buildSiteKeyEnum };
+/**
+ * Resolve a site's HTTP password, dispatching on schema shape.
+ *
+ * v2 App-Password sites (auth.method === 'apppassword' + auth.password_ref)
+ * read the secret from the keychain via the SecretStore. v1 carriers without
+ * a ref fall back to the `resolvePassword(http)` resolver.
+ *
+ * @param {object} site
+ * @param {object} [secretStore]  SecretStore instance. Lazily defaults to
+ *                                KeychainSecretStore when an apppassword path
+ *                                runs and no store was supplied — preserves
+ *                                the "no keytar for SSH-only / v1-only setups"
+ *                                property by deferring the require to the
+ *                                point of need.
+ * @returns {Promise<string>}
+ */
+async function resolveSitePassword(site, secretStore) {
+  if (site && site.auth && site.auth.method === 'apppassword' && site.auth.password_ref) {
+    let store = secretStore;
+    if (!store) {
+      const { KeychainSecretStore } = require('./auth/keychain-secret-store');
+      store = new KeychainSecretStore();
+    }
+    const { resolveRef } = require('./auth/secret-store');
+    return resolveRef(store, site.auth.password_ref);
+  }
+  if (site && site.http) {
+    return resolvePassword(site.http);
+  }
+  throw new Error('No password source configured for site');
+}
+
+module.exports = {
+  loadConfig,
+  resolveConfigFilePath,
+  resolvePassword,
+  resolveSitePassword,
+  resolveSiteKey,
+  buildSiteKeyEnum,
+  buildEnvConfig,
+};

package/lib/connection-pool.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { SshTransport } = require('./transports/ssh-transport');
-const { resolveSiteKey, resolvePassword } = require('./config');
+const { resolveSiteKey, resolveSitePassword } = require('./config');
 
 // Incrementing counter for synthetic handshake IDs.
 // Avoids integer overflow from Date.now() (13-digit ms timestamps exceed
@@ -9,6 +9,23 @@ const { resolveSiteKey, resolvePassword } = require('./config');
 // Starting at 1000 to avoid collision with real request IDs (typically 1+).
 let _synthIdCounter = 1000;
 
+/**
+ * Build a TokenManager-shaped siteAuth object from a v2 OAuth site block.
+ * The OAuthHttpTransport and TokenManager use this shape.
+ */
+function _siteAuthFromConfig(siteId, siteConfig, asMetadata) {
+  return {
+    siteId,
+    tokenEndpoint: asMetadata && asMetadata.token_endpoint,
+    clientId: siteConfig.auth.client_id,
+    accessTokenRef: siteConfig.auth.access_token_ref,
+    refreshTokenRef: siteConfig.auth.refresh_token_ref,
+    accessTokenExpiresAt: siteConfig.auth.access_token_expires_at,
+    refreshTokenExpiresAt: siteConfig.auth.refresh_token_expires_at,
+    authStatus: siteConfig.auth_status || 'active',
+  };
+}
+
 /**
  * Connection Pool — manages one transport per site, lazily instantiated.
  *
@@ -21,12 +38,38 @@ let _synthIdCounter = 1000;
  */
 class ConnectionPool {
 
-  constructor(config, logger) {
+  /**
+   * @param {object} config
+   * @param {function} logger
+   * @param {object} [deps]                   Optional injection seam for tests
+   * @param {object} [deps.secretStore]       Defaults to KeychainSecretStore
+   * @param {object} [deps.tokenManager]      Defaults to a TokenManager built from secretStore
+   * @param {function} [deps.discover]        Defaults to lib/auth/discovery-client.discover
+   * @param {function} [deps.persistAuthStatus] (siteId, newStatus) => void
+   *                                          Persists to wp-sites.json. Defaults to
+   *                                          atomic write via config-migration._atomicWrite
+   *                                          when config._configPath is set.
+   * @param {boolean} [deps.allowInsecure]    For local-dev OAuth over HTTP
+   */
+  constructor(config, logger, deps = {}) {
     this.config = config;
     this.log = logger;
     this.transports = new Map();      // compositeKey -> Transport
     this.connecting = new Map();      // compositeKey -> Promise<Transport>
 
+    // OAuth-runtime deps. Built lazily so SSH-only / App-Password-only setups
+    // never load keytar or the auth modules at all.
+    this._deps = deps;
+    this._secretStore = deps.secretStore || null;
+    this._tokenManager = deps.tokenManager || null;
+    this._discover = deps.discover || null;
+    this._allowInsecure = !!deps.allowInsecure;
+    this._persistAuthStatus = deps.persistAuthStatus || null;
+
+    // Cache of OAuth AS metadata per site URL — avoids re-probing .well-known
+    // on every transport rebuild. Refreshed when the transport is recreated.
+    this._asMetadataCache = new Map();   // siteUrl -> { asMetadata, prMetadata }
+
     // Handshake cache — set after the default site completes init
     this.cachedInitRequest = null;
     this.cachedInitNotification = null;
@@ -98,7 +141,7 @@ class ConnectionPool {
    */
   async connectDefault(onMessage) {
     const key = this.config.defaultSite;
-    const transport = this._createTransport(key, null);
+    const transport = await this._createTransport(key, null);
     transport.onMessage = onMessage;
     await transport.connect();
     this.transports.set(key, transport);
@@ -145,6 +188,28 @@ class ConnectionPool {
     try {
       const { siteConfig } = resolveSiteKey(this.config, compositeKey);
 
+      // v2 OAuth site — probe the resource URL with HEAD. We do NOT mint a
+      // token here; this is just a reachability check, the real auth happens
+      // on first MCP request via OAuthHttpTransport.
+      if (siteConfig.auth && siteConfig.auth.method === 'oauth') {
+        const target = siteConfig.mcp_resource;
+        if (!target) {
+          return { status: 'unreachable', latencyMs: Date.now() - start, error: 'no mcp_resource configured' };
+        }
+        const mod = target.startsWith('https://') ? require('https') : require('http');
+        const url = new URL(target);
+        await new Promise((resolve, reject) => {
+          const req = mod.request({
+            hostname: url.hostname, port: url.port,
+            path: url.pathname, method: 'HEAD', timeout: 10000,
+          }, (res) => resolve(res.statusCode));
+          req.on('error', reject);
+          req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+          req.end();
+        });
+        return { status: 'reachable', latencyMs: Date.now() - start };
+      }
+
       if (siteConfig.transport === 'ssh') {
         const { execFileSync } = require('child_process');
         execFileSync('ssh', [
@@ -199,7 +264,7 @@ class ConnectionPool {
 
     this.log(`Lazy-connecting to site: ${compositeKey}`);
 
-    const transport = this._createTransport(compositeKey, subsiteUrl);
+    const transport = await this._createTransport(compositeKey, subsiteUrl);
 
     // Set up message callback — route responses back to main
     // The main entry will set this after getting the transport
@@ -220,10 +285,18 @@ class ConnectionPool {
     return transport;
   }
 
-  _createTransport(compositeKey, subsiteUrl) {
+  async _createTransport(compositeKey, subsiteUrl) {
     const { siteConfig, subsiteUrl: resolvedSubsiteUrl, resolvedEndpoint } = resolveSiteKey(this.config, compositeKey);
     const finalSubsiteUrl = subsiteUrl || resolvedSubsiteUrl;
 
+    // v2 OAuth dispatch — single branch per Issue #17 acceptance criteria.
+    // Sites with auth.method === 'oauth' use the OAuth-aware HTTP transport;
+    // every other site (App Password, SSH carrier-only) keeps the existing
+    // legacy code paths untouched.
+    if (siteConfig.auth && siteConfig.auth.method === 'oauth') {
+      return this._createOAuthHttpTransport(compositeKey, siteConfig);
+    }
+
     if (siteConfig.transport === 'ssh') {
       return new SshTransport({
         host: siteConfig.ssh.host,
@@ -236,13 +309,25 @@ class ConnectionPool {
     }
 
     if (siteConfig.transport === 'http') {
-      // HTTP transport — loaded lazily to avoid requiring it when only SSH is used
+      // HTTP transport — loaded lazily to avoid requiring it when only SSH is used.
+      // v2 apppassword sites resolve the secret from keychain via auth.password_ref;
+      // v1 sites fall through to the legacy synchronous resolver. KeychainSecretStore
+      // is only constructed when an apppassword path actually runs, preserving the
+      // "no keytar for SSH-only / v1-only setups" property.
       const { HttpTransport } = require('./transports/http-transport');
-      const password = resolvePassword(siteConfig.http);
+      const isV2AppPassword = siteConfig.auth
+        && siteConfig.auth.method === 'apppassword'
+        && siteConfig.auth.password_ref;
+      if (isV2AppPassword && !this._secretStore) {
+        const { KeychainSecretStore } = require('./auth/keychain-secret-store');
+        this._secretStore = new KeychainSecretStore();
+      }
+      const password = await resolveSitePassword(siteConfig, this._secretStore);
+      const username = (siteConfig.auth && siteConfig.auth.username) || siteConfig.http.username;
       return new HttpTransport({
         endpoint: resolvedEndpoint || siteConfig.http.endpoint,
-        username: siteConfig.http.username,
-        password: password,
+        username,
+        password,
         logger: this.log,
       });
     }
@@ -250,15 +335,133 @@ class ConnectionPool {
     throw new Error(`Unknown transport: ${siteConfig.transport}`);
   }
 
+  /**
+   * Build an OAuthHttpTransport for a v2 OAuth site. Lazily resolves AS
+   * metadata via the discovery client (passing capability-pin state per
+   * Appendix H.2.3 — pinned-then-404 throws CapabilityPinningError, which
+   * we let propagate so the bridge fails loud rather than silently
+   * downgrading to App Password).
+   */
+  async _createOAuthHttpTransport(compositeKey, siteConfig) {
+    const { OAuthHttpTransport } = require('./transports/oauth-http-transport');
+    const { TokenManager } = require('./auth/token-manager');
+    const { discover } = require('./auth/discovery-client');
+
+    if (!siteConfig.mcp_resource) {
+      throw new Error(
+        `Site "${compositeKey}" (oauth): no mcp_resource configured — ` +
+        `re-run \`abilities-mcp reauth ${compositeKey}\` to repopulate it`
+      );
+    }
+    if (!siteConfig.url) {
+      throw new Error(`Site "${compositeKey}" (oauth): no url configured`);
+    }
+
+    if (!this._secretStore) {
+      const { KeychainSecretStore } = require('./auth/keychain-secret-store');
+      this._secretStore = new KeychainSecretStore();
+    }
+    if (!this._tokenManager) {
+      this._tokenManager = new TokenManager({
+        secretStore: this._secretStore,
+        allowInsecure: this._allowInsecure,
+      });
+    }
+    const discoverFn = this._discover || discover;
+
+    let asMetadata = (this._asMetadataCache.get(siteConfig.url) || {}).asMetadata;
+    if (!asMetadata) {
+      const result = await discoverFn(siteConfig.url, {
+        pinned: !!siteConfig.oauth_capability_pinned,
+        pinnedFirstSeenAt: siteConfig.oauth_capability_pinned
+          && siteConfig.oauth_capability_pinned.first_seen_at,
+        allowInsecure: this._allowInsecure,
+      });
+      asMetadata = result.asMetadata;
+      this._asMetadataCache.set(siteConfig.url, {
+        asMetadata: result.asMetadata,
+        prMetadata: result.prMetadata,
+      });
+    }
+
+    if (!asMetadata || !asMetadata.token_endpoint) {
+      throw new Error(
+        `Site "${compositeKey}" (oauth): discovery did not yield a token_endpoint`
+      );
+    }
+
+    const siteAuth = _siteAuthFromConfig(compositeKey, siteConfig, asMetadata);
+
+    return new OAuthHttpTransport({
+      endpoint: siteConfig.mcp_resource,
+      tokenManager: this._tokenManager,
+      siteAuth,
+      onAuthStatusChange: (newStatus, info) => {
+        // In-memory update first so subsequent transport rebuilds see it.
+        try {
+          siteConfig.auth_status = newStatus;
+        } catch { /* siteConfig may be frozen in tests — ignore */ }
+        this.log(
+          `OAuth auth_status change: ${compositeKey} → ${newStatus} (${info && info.reason || 'unknown'})`
+        );
+        // Persist to wp-sites.json best-effort. A failure to write should
+        // not break the request path that triggered this change.
+        if (this._persistAuthStatus) {
+          Promise.resolve()
+            .then(() => this._persistAuthStatus(compositeKey, newStatus, info))
+            .catch((err) => this.log(`OAuth auth_status persist failed: ${err.message}`));
+        } else if (this.config && this.config._configPath) {
+          this._defaultPersistAuthStatus(compositeKey, newStatus)
+            .catch((err) => this.log(`OAuth auth_status persist failed: ${err.message}`));
+        }
+      },
+      logger: this.log,
+    });
+  }
+
+  /**
+   * Default auth_status persistor — atomic rewrite of wp-sites.json. Used
+   * when the pool was constructed without a custom persistAuthStatus.
+   */
+  async _defaultPersistAuthStatus(siteId, newStatus) {
+    const { _atomicWrite } = require('./auth/config-migration');
+    const fs = require('node:fs');
+    const filePath = this.config._configPath;
+    if (!filePath) return;
+    let raw;
+    try {
+      raw = await fs.promises.readFile(filePath, 'utf8');
+    } catch (err) {
+      throw new Error(`read ${filePath}: ${err.message}`);
+    }
+    let parsed;
+    try { parsed = JSON.parse(raw); }
+    catch (err) {
+      throw new Error(`parse ${filePath}: ${err.message}`);
+    }
+    if (parsed && parsed.sites && parsed.sites[siteId]) {
+      parsed.sites[siteId].auth_status = newStatus;
+      await _atomicWrite(filePath, parsed);
+    }
+  }
+
   /**
    * Check if a composite key resolves to the same HTTP endpoint as an
    * already-connected transport. Returns { key, transport } or null.
+   *
+   * Covers both v1 App-Password HTTP sites and v2 OAuth sites — the dedup
+   * target is whichever URL the eventual transport will POST to.
    */
   _findExistingHttpTransport(compositeKey) {
     const { siteConfig, resolvedEndpoint } = resolveSiteKey(this.config, compositeKey);
-    if (siteConfig.transport !== 'http') return null;
 
-    const targetEndpoint = resolvedEndpoint || siteConfig.http.endpoint;
+    let targetEndpoint = null;
+    if (siteConfig.auth && siteConfig.auth.method === 'oauth') {
+      targetEndpoint = siteConfig.mcp_resource;
+    } else if (siteConfig.transport === 'http') {
+      targetEndpoint = resolvedEndpoint || (siteConfig.http && siteConfig.http.endpoint);
+    }
+    if (!targetEndpoint) return null;
 
     for (const [key, transport] of this.transports) {
       if (transport.endpoint === targetEndpoint) {