@wickedevolutions/abilities-mcp 1.3.1 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [1.5.1] - 2026-05-02
+
+Stretch-to-stable release. Closes the OAuth 2.1 alpha audit pass and the two integration-seam regressions surfaced during Helena's Phase B operator verification, plus the async-config tech-debt sweep that shares the bridge's startup path. No new features, no surface changes — the v1.5.x line is now stable for broader operator adoption.
+
+Companion releases: [abilities-mcp-adapter v1.4.4](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/releases/tag/v1.4.4) and [abilities-for-ai v1.9.1](https://github.com/Wicked-Evolutions/abilities-for-ai/releases/tag/v1.9.1) — coordinated multi-repo release per the Stretch to Stable sprint plan.
+
+### Fixed
+
+- **Schema v1→v2 auto-migration is now actually wired into boot** (PR #25, closes #23). `migrateFile()` shipped in v1.5.0 but the Phase 4/5 OAuth handoff missed the call sites — the migration code existed but never ran. Now invoked at two points before any consumer touches the config: (a) in `abilities-mcp.js` startup before the MCP server reads `wp-sites.json`, and (b) in `lib/cli/index.js`'s `runCommand()` before any subcommand parses the file. Both call sites share a single `KeychainSecretStore` instance. CLI subcommands no longer error with `v<unknown> but CLI expects v2` against legacy v1 configs; the OAuth `add-site` / `upgrade-auth` flows can reach the auth code path on a fresh install. Idempotent — second-run on an already-v2 file is a no-op.
+- **Post-migration v2 apppassword sites validate and connect** (PR #27, closes #26). Helena's Phase B run surfaced a regression: when PR #25's wired migration converted a multi-site v1 config to v2, every non-OAuth site moved to `auth.method: 'apppassword'` with `auth.password_ref`, and the legacy `http.password` / `http.passwordEnv` / `http.passwordCommand` fields were stripped per Appendix F.5 — keychain becomes the sole source of truth. The runtime side still spoke v1 only: `validateSiteConfig()` had no apppassword branch, so v2 sites fell through to the legacy http validator which rejected them with `requires one of http.password, http.passwordEnv, or http.passwordCommand`, and `ConnectionPool._createTransport` had no resolver for `auth.password_ref`. Two parallel branches added (validator + async `resolveSitePassword(site, secretStore)` helper that reads keychain via the SecretStore), pool dispatches on `auth.method === 'apppassword'`, and `KeychainSecretStore` is constructed lazily so SSH-only / v1-only setups still avoid loading keytar. Multi-site acceptance test (1 oauth + 2 apppassword + 1 ssh-carrier) pins the routing.
+
+### Changed
+
+- **Async config loading** (PR #28, closes #5). The boot chain — `resolveConfigFilePath`, `loadConfig`, `loadConfigFile`, `validateSiteConfig`, `resolvePassword` — is async. File reads use `fs.promises`; the `passwordCommand` shell-out goes through `util.promisify(exec)` rather than `execFile` so existing operator configs that rely on shell features (pipes, redirects, `$()` substitution — e.g. `op read 'op://Vault/foo' | tr -d '\n'`) keep working unchanged. `loadConfig` now returns a `Promise`; `abilities-mcp.js`'s bootstrap awaits it (the IIFE was already async per the migration wiring above). Pure-dispatch helpers (`resolveSiteKey`, `buildSiteKeyEnum`, `buildEnvConfig`, `buildLegacyConfig`) stayed synchronous — they have no I/O and converting them would touch every call site for no runtime benefit.
+
+### Internal
+
+- Test count: 237 (+27 since 1.5.0). Node CI matrix: 18, 20, 22.
+- Validator coverage extended: 8 acceptance/reject cases for v2 apppassword (http and ssh carriers, hand-edited reject paths), 9 cases for the async surface (`loadConfig` Promise return, `resolveConfigFilePath` async, `resolvePassword` env / command / shell-feature regression).
+
+## [1.5.0] - 2026-04-28
+
+OAuth 2.1 release. The bridge is now a full OAuth client: it discovers the authorization server via RFC 9728, performs Dynamic Client Registration (RFC 7591), drives the authorization-code grant with PKCE S256 (RFC 7636) through a loopback browser flow (RFC 8252), persists tokens in the OS keychain, refreshes them automatically, and sends Bearer tokens through the runtime MCP transport.
+
+Companion release: [abilities-mcp-adapter v1.4.3](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/releases/tag/v1.4.3) — the OAuth resource server + authorization server.
+
+### Added — OAuth 2.1 client core (#15)
+
+- **`lib/auth/` module** — full OAuth 2.1 client: `oauth-client.js` (state machine), `discovery-client.js` (RFC 9728 + RFC 8414, refuses HTTP, refuses redirects on `.well-known/*`, throws `CapabilityPinningError` on pinned 404), `dcr-client.js` (RFC 7591), `pkce.js` (32-byte verifier, S256, 16-byte hex state, `crypto.timingSafeEqual` with length-mismatch CPU-burn defense), `loopback-server.js` (RFC 8252 loopback callback), `browser-launcher.js` (cross-platform `open`), `token-manager.js` (refresh window, retry semantics, expired/revoked state machine).
+- **`SecretStore` interface** — three implementations: `keychain-secret-store.js` (libsecret on Linux, Keychain on macOS, Credential Manager on Windows), `memory-secret-store.js` (testing), `secret-store.js` (interface). All token persistence flows through this interface.
+- **`BridgeIdentityProvider` interface** + **`FreshEachTimeIdentityProvider`** (v1.0 implementation per Appendix H.3.2 binding amendment): `getClientId()` always returns null → fresh DCR on every flow. `persistClientId()` is a documented no-op pending v1.1's persistent-identity upgrade contract.
+- **`schema-v2.js`** — keychain references replace inline secrets in `wp-sites.json`. `schema_version: 2` with `auth.method`, `access_token_ref`, `refresh_token_ref`, `oauth_capability_pinned`, `apppassword_fallback`. `config-migration.js` upgrades v1 configs in place.
+- **`OAuthHttpTransport`** (#18) — runtime transport that uses `TokenManager.getAccessToken()` before each request, builds `Authorization: Bearer ...`, handles 401 → `forceRefresh` → retry-once, surfaces terminal auth failure via `onAuthStatusChange('expired')`. `ConnectionPool._create()` dispatches to this when `siteConfig.auth.method === 'oauth'`.
+
+### Added — OAuth CLI subcommands (#16)
+
+- **`abilities-mcp <subcommand>`** dispatches to eight new subcommands wrapping `lib/auth/`: the six in the sprint plan — `add-site`, `reauth`, `revoke`, `list-sites`, `test`, `upgrade-auth` — plus two design-doc extensions: `force-downgrade` (J.1, escape hatch for the H.2.3 capability-pin failure) and `self-check` (J.2, the H.2.6 Authorization-header probe). Each subcommand subscribes to the OAuth state machine and prints operator-facing progress lines. Error messages name the exact next action. Bare `node abilities-mcp.js` (no subcommand) still starts the MCP STDIO server unchanged.
+- Exit-code table (`0`/`1`/`2`/`3`/`4`/`5`) mapping success / generic / usage / config / auth / capability-pinning failures, documented in `abilities-mcp --help`.
+- `--debug` flag includes the `cause` stack on errors for troubleshooting.
+- `force-downgrade` audit lives on the site config (`force_downgrade.{at, expires_at, reason}`) and is surfaced in `list-sites` for 30 days.
+
+### Security
+
+- **H-7: removed dead refresh-intent keychain code** (#21). `TokenManager.refresh()` previously wrote a `${siteId}/refresh-intent` keychain entry before sending the refresh request and deleted it on every exit path. The marker had no reader — the original H.2.1 mid-flight crash-recovery semantics were never implemented. With the adapter's C-2 fix shipping encrypt-at-rest grace-window retry on the server (adapter PR #61), the bridge no longer needs an in-flight intent marker. Pure deletion of dead code that paid a keychain write per refresh.
+- **H-8: client_id port guard in `_runRegister`** (#22). `OAuthClient._runRegister` previously returned a persisted `client_id` from `identityProvider.getClientId()` without verifying that the registered loopback redirect_uri's port matched the live loopback port. v1.0 was safe by accident because `FreshEachTimeIdentityProvider.getClientId()` always returns null. v1.1's persistent-identity upgrade (per Appendix H.3.2) would have surfaced the bug: a stale persisted client_id whose registered port no longer matched would fail server-side `redirect_uri_valid()`. Defensive fix: `_runRegister` now always calls `identityProvider.clearClientId()` before DCR. v1.1+ designs that want to short-circuit DCR on persisted client_id must do so at the `OAuthClient.run()` level after verifying the loopback port matches the registration. See follow-up [abilities-mcp-adapter#73](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/issues/73) for the spec amendment.
+
+### Internal
+
+- Test count: 210 (+34 since 1.4.0). Node CI matrix: 18, 20, 22.
+- `infra: retarget project automation` (#14) for the OAuth sprint workflow.
+
+## [1.4.0] - 2026-04-26
+
+### Added
+- `.mcpb` distribution bundle for one-click install in Claude Desktop (#8). `manifest.json` against MCPB spec v0.3, `.mcpbignore`, and `npm run pack:mcpb` script. Application Password is stored encrypted in the OS keychain via `sensitive: true`. Published as a GitHub Release asset.
+- `ABILITIES_MCP_URL` / `ABILITIES_MCP_USERNAME` / `ABILITIES_MCP_PASSWORD` environment-variable config fallback in `lib/config.js`. When no `wp-sites.json` exists, the bridge builds a single-site config from the env vars and auto-derives the MCP adapter endpoint as `<URL>/wp-json/mcp/mcp-adapter-default-server`. Covers the `.mcpb` install path and any env-var-based MCP client (`claude mcp add`, Docker, etc.).
+- `npm run validate:mcpb` — validates `manifest.json` against the MCPB schema.
+
+### Changed
+- README restructured around three install paths: `.mcpb` bundle (recommended for Claude Desktop), env-vars + npm install (Claude Code / Cursor / Docker), and `wp-sites.json` (multi-site / power users). Existing `wp-sites.json` users are unaffected.
+
 ## [1.3.1] - 2026-03-19
 
 ### Fixed

package/README.md

@@ -16,22 +16,26 @@ Open-source MCP bridge that connects any AI client to your WordPress sites throu
 
 ## What You Can Do
 
-The abilities available to your AI agent depend on which ability plugins you install. With [Abilities for AI](https://wickedevolutions.com/abilities-for-ai) installed, your agent gets access to:
+The abilities available to your AI agent depend on which ability plugins you install. With [Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/) installed, your agent gets access to:
 
 **Content & Publishing** — content, blocks, patterns, media, menus, taxonomies, comments, revisions
 **Site Management** — plugins, themes, settings, users, site health, cache, cron, rewrite rules
 **Infrastructure** — filesystem, meta, REST discovery, knowledge layer
 **Third-party integrations** — auto-detected modules for supported plugins (Astra, Spectra, SureCart, Presto Player, and more)
 
-Additional ability plugins extend coverage further. For example, [Abilities for Fluent Plugins](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins) adds modules for FluentCRM, Fluent Community, Fluent Forms, FluentBooking, Fluent Support, Fluent Boards, FluentSMTP, FluentAuth, Fluent Snippets, Fluent Messaging, FluentCart, and FluentAffiliate.
+**[Abilities for Fluent Plugins](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins)** is our continuously-enhanced third-party translator — bringing AI control to FluentCRM, FluentCommunity, FluentForms, FluentBooking, FluentSupport, FluentBoards, FluentSMTP, FluentAuth, FluentSnippets, FluentMessaging, FluentCart, and FluentAffiliate. We build and maintain it because we use Fluent's plugins ourselves and wanted them AI-native.
+
+Beyond Fluent, the bridge is plugin-agnostic by design. Any plugin that registers abilities through the WordPress Abilities API becomes available automatically — no configuration in this bridge required. We urge every WordPress plugin developer to prioritize native Abilities API support over anything else.
 
 Every ability enforces `current_user_can()` at execution time — your WordPress role is the security boundary.
 
-> **Sign up for the Abilities for AI alpha release:** https://wickedevolutions.com/abilities-for-ai
+> **Sign up for the Abilities for AI alpha release:** https://community.wickedevolutions.com/item/abilities-for-ai/
+
+## Install
 
-## Quick Start
+There are three install paths. Pick the one that matches how you use AI clients.
 
-### 1. Set up WordPress
+### Set up WordPress (required for all paths)
 
 Create a dedicated WordPress user for AI access and generate an Application Password.
 
@@ -59,24 +63,77 @@ Go to **Users → Edit (your mcp-agent user) → Application Passwords**, enter
 
 Install both on your WordPress site:
 
-1. **[Abilities for AI](https://wickedevolutions.com/abilities-for-ai)** — registers WordPress abilities across content, site management, infrastructure, and third-party integration modules
-2. **[Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter)** — exposes abilities as MCP tools via REST API
+1. **[Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/)** — registers WordPress abilities across content, site management, infrastructure, and third-party integration modules
+2. **[Abilities MCP Adapter](https://community.wickedevolutions.com/item/abilities-mcp-adapter/)** — exposes abilities as MCP tools via REST API
+
+Both are available as free downloads from our store, or install from GitHub: [abilities-for-ai](https://github.com/Wicked-Evolutions/abilities-for-ai) and [abilities-mcp-adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter).
+
+---
+
+### Path 1 — `.mcpb` bundle for Claude Desktop (recommended)
+
+Single-click install for Claude Desktop on macOS and Windows. The Application Password is stored encrypted in your OS keychain (macOS Keychain / Windows Credential Manager).
+
+1. Download `abilities-mcp.mcpb` from the [latest GitHub Release](https://github.com/Wicked-Evolutions/abilities-mcp/releases/latest).
+2. Double-click the file. Claude Desktop opens an "Install Extension" dialog.
+3. Type three things:
+   - **WordPress Site URL** — `https://example.com`
+   - **WordPress Username** — `mcp-agent`
+   - **Application Password** — paste the password from the previous step
+4. Click **Install**. The connection is live.
+
+The bundle covers the single-site case. For multi-site (one bridge connected to several WordPress sites at once), use Path 3.
+
+---
 
-### 2. Configure your sites
+### Path 2 — Env vars (Claude Code, Cursor, Docker, any MCP client)
 
-Copy the example config and edit:
+Install the bridge from npm, then point your client at it with three environment variables:
 
 ```bash
-cp wp-sites.example.json wp-sites.json
+npm install -g @wickedevolutions/abilities-mcp
+```
+
+In your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "abilities-mcp",
+      "env": {
+        "ABILITIES_MCP_URL": "https://example.com",
+        "ABILITIES_MCP_USERNAME": "mcp-agent",
+        "ABILITIES_MCP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    }
+  }
+}
 ```
 
-Edit `wp-sites.json` with your site details.
+The endpoint is auto-derived as `<URL>/wp-json/mcp/mcp-adapter-default-server`. Single-site only — for multi-site, use Path 3.
+
+For `claude mcp add` users:
+
+```bash
+claude mcp add wordpress \
+  --env ABILITIES_MCP_URL=https://example.com \
+  --env ABILITIES_MCP_USERNAME=mcp-agent \
+  --env ABILITIES_MCP_PASSWORD='xxxx xxxx xxxx xxxx xxxx xxxx' \
+  -- abilities-mcp
+```
+
+---
+
+### Path 3 — `wp-sites.json` (multi-site, power users)
 
-### 3. Add to your MCP client
+Use this when you connect one bridge to multiple WordPress sites, when you want passwords sourced from a keychain or shell command, or when you're targeting WordPress multisite networks via dot-notation routing.
 
-Works with any MCP-compatible client — Claude Code, Claude Desktop, Gemini CLI, Cursor, Windsurf, VS Code, and any other IDE or AI tool that supports the Model Context Protocol.
+```bash
+cp wp-sites.example.json wp-sites.json
+```
 
-Add the server to your client's MCP config (usually `.mcp.json`, `settings.json`, or equivalent):
+Edit `wp-sites.json` with your sites, then add the server to your client's MCP config:
 
 ```json
 {
@@ -126,11 +183,15 @@ node abilities-mcp.js --register
 }
 ```
 
-### Config file search order
+### Config search order
 
 1. `--config=/path/to/wp-sites.json` (explicit)
-2. Same directory as `abilities-mcp.js`
+2. `wp-sites.json` in the same directory as `abilities-mcp.js`
 3. `~/.abilities-mcp/wp-sites.json`
+4. `ABILITIES_MCP_URL` / `ABILITIES_MCP_USERNAME` / `ABILITIES_MCP_PASSWORD` env vars (single-site, used by the `.mcpb` bundle)
+5. `--host=<ssh-host> --path=<wp-path>` (legacy SSH single-site)
+
+The first one found wins. If a `wp-sites.json` exists, env vars are ignored.
 
 ### WordPress Multisite
 
@@ -313,9 +374,19 @@ See [docs/architecture.md](docs/architecture.md) for the full technical deep div
 ## Requirements
 
 - Node.js >= 18
-- WordPress 6.9+ with [Abilities for AI](https://wickedevolutions.com/abilities-for-ai) and [Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter) installed
+- WordPress 6.9+ with [Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/) and [Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter) installed
 - Application Passwords enabled (default in WordPress 5.6+)
 
+## Evolving Knowledge
+
+We continuously add knowledge docs, skills, and agent patterns to [knowledge.wickedevolutions.com](https://knowledge.wickedevolutions.com).
+
+## Disclaimer
+
+Humans make mistakes — as we know from the present day and history. Humans trained AI. AI acts accordingly. AI predicts probability based on the context window it holds. It is trained to sound certain, as if everything is truth, and to "fix" everything so the human becomes satisfied.
+
+Learn how to communicate with AI. You are fully responsible for using AI in your life, business, and projects. Using these products is your personal responsibility to learn and own.
+
 ## License
 
 GPL-2.0-or-later

package/abilities-mcp.js

@@ -23,147 +23,216 @@
 'use strict';
 
 const { createLogger } = require('./lib/logger');
-const { loadConfig, buildSiteKeyEnum } = require('./lib/config');
+const { loadConfig, buildSiteKeyEnum, resolveConfigFilePath } = require('./lib/config');
 const { ConnectionPool } = require('./lib/connection-pool');
 const { ToolCatalog } = require('./lib/tool-catalog');
 const { McpRouter } = require('./lib/router');
 const { SshTransport } = require('./lib/transports/ssh-transport');
+const { migrateFile } = require('./lib/auth/config-migration');
+const { KeychainSecretStore } = require('./lib/auth/keychain-secret-store');
 
 // ---------------------------------------------------------------------------
-// CLI argument parsing
+// Subcommand routing (Phase 5 OAuth CLI)
 // ---------------------------------------------------------------------------
+// `abilities-mcp <subcommand>` (e.g. add-site, list-sites) dispatches to the
+// OAuth CLI in lib/cli/. With no subcommand the bridge starts the MCP server
+// as before — this preserves backwards compatibility for every existing
+// invocation path (Claude Desktop, .mcpb bundle, bare `node abilities-mcp.js`).
+const { isKnownSubcommand, runCommand, HELP_TEXT, isHelpToken } = require('./lib/cli');
 
-const args = {};
-process.argv.slice(2).forEach(arg => {
-  if (arg.startsWith('--')) {
-    const [key, ...rest] = arg.slice(2).split('=');
-    args[key] = rest.length ? rest.join('=') : true;
-  }
-});
-
-const debug    = !!args.debug;
-const register = !!args.register;
-
-// ---------------------------------------------------------------------------
-// Registration mode (--register)
-// ---------------------------------------------------------------------------
+const rawArgs = process.argv.slice(2);
+const firstToken = rawArgs[0];
 
-if (register) {
-  const { registerClaudeDesktop } = require('./lib/register');
-  registerClaudeDesktop({ name: args.name || 'wordpress', configPath: args.config });
+if (firstToken && isHelpToken(firstToken)) {
+  process.stdout.write(HELP_TEXT.join('\n') + '\n');
   process.exit(0);
 }
 
+const isSubcommandInvocation = firstToken && isKnownSubcommand(firstToken);
+
+if (isSubcommandInvocation) {
+  (async () => {
+    try {
+      const { exitCode, lines, errLines } = await runCommand({
+        subcommand: firstToken,
+        argv: rawArgs.slice(1),
+      });
+      if (lines.length) process.stdout.write(lines.join('\n') + '\n');
+      if (errLines.length) process.stderr.write(errLines.join('\n') + '\n');
+      process.exit(exitCode);
+    } catch (err) {
+      // Last-resort safety net — runCommand normally catches everything.
+      process.stderr.write(`abilities-mcp: ${err.message}\n`);
+      process.exit(1);
+    }
+  })();
+}
+
 // ---------------------------------------------------------------------------
-// Initialize
+// MCP server mode — the original CLI argument parsing (no subcommand).
+// Skipped when a subcommand was dispatched above; otherwise we'd race the
+// IIFE's process.exit() against the bootstrap that awaits loadConfig() and
+// connectDefault().
 // ---------------------------------------------------------------------------
 
-const log = createLogger(debug);
-log('abilities-mcp v1.0.0 starting');
-
-// Ensure SSH agent is available (macOS launchd discovery)
-SshTransport.ensureSshAuthSock();
+if (!isSubcommandInvocation) {
+  const args = {};
+  rawArgs.forEach(arg => {
+    if (arg.startsWith('--')) {
+      const [key, ...rest] = arg.slice(2).split('=');
+      args[key] = rest.length ? rest.join('=') : true;
+    }
+  });
 
-let config;
-try {
-  config = loadConfig(args);
-} catch (err) {
-  process.stderr.write(`abilities-mcp: ${err.message}\n`);
-  process.exit(1);
-}
+  const debug    = !!args.debug;
+  const register = !!args.register;
 
-const isMultiSite = config._isMultiSite;
-const siteKeys = buildSiteKeyEnum(config);
-log(`Config loaded: ${siteKeys.length} site(s): ${siteKeys.join(', ')} (default: ${config.defaultSite})`);
-log(`Multi-site mode: ${isMultiSite}`);
+  if (register) {
+    const { registerClaudeDesktop } = require('./lib/register');
+    registerClaudeDesktop({ name: args.name || 'wordpress', configPath: args.config });
+    process.exit(0);
+  }
 
-const pool = new ConnectionPool(config, log);
-const catalog = new ToolCatalog(config, log);
+  const log = createLogger(debug);
+  log('abilities-mcp v1.0.0 starting');
+
+  // Ensure SSH agent is available (macOS launchd discovery)
+  SshTransport.ensureSshAuthSock();
+
+  // -------------------------------------------------------------------------
+  // Async startup — schema v1→v2 migration must complete BEFORE loadConfig.
+  // -------------------------------------------------------------------------
+  // Per Appendix F.5 (binding): the migration is "Triggered on first bridge
+  // launch after upgrade. One-shot, non-destructive." `migrateFile` is
+  // idempotent — second-run on a v2 file is a no-op. Called before
+  // `loadConfig` so that when v1 is on disk, `loadConfig` reads the freshly
+  // rewritten v2 file (with secrets lifted into the keychain).
+  //
+  // The MCP server uses a fresh `KeychainSecretStore` instance here. The
+  // store is a stateless wrapper over keytar — entry identity is determined
+  // entirely by (service, account), so a freshly constructed instance writes
+  // to the same keychain entries the runtime/CLI later read.
+  //
+  // Env-var single-site mode (.mcpb path) and legacy --host/--path mode have
+  // no on-disk wp-sites.json; `resolveConfigFilePath` returns null and we
+  // skip migration entirely.
+  (async function bootstrap() {
+    const filePath = await resolveConfigFilePath(args);
+    if (filePath) {
+      try {
+        const result = await migrateFile({
+          filePath,
+          secretStore: new KeychainSecretStore(),
+        });
+        if (result.migrated) {
+          log(`Migrated wp-sites.json v1 → v2 (${result.liftedCount} secret(s) lifted; backup: ${result.backupPath})`);
+        }
+      } catch (err) {
+        process.stderr.write(`abilities-mcp: schema migration failed: ${err.message}\n`);
+        process.exit(1);
+      }
+    }
 
-if (catalog.isEnabled()) {
-  log('Tool filtering enabled');
-} else {
-  log('Tool filtering disabled (no toolFilter in config or enabled: false)');
-}
+    let config;
+    try {
+      config = await loadConfig(args);
+    } catch (err) {
+      process.stderr.write(`abilities-mcp: ${err.message}\n`);
+      process.exit(1);
+    }
 
-function sendToClient(data) {
-  process.stdout.write(data + '\n');
-}
+    const isMultiSite = config._isMultiSite;
+    const siteKeys = buildSiteKeyEnum(config);
+    log(`Config loaded: ${siteKeys.length} site(s): ${siteKeys.join(', ')} (default: ${config.defaultSite})`);
+    log(`Multi-site mode: ${isMultiSite}`);
 
-const router = new McpRouter({
-  config,
-  siteKeys,
-  isMultiSite,
-  pool,
-  catalog,
-  sendToClient,
-  log,
-});
+    const pool = new ConnectionPool(config, log);
+    const catalog = new ToolCatalog(config, log);
 
-// ---------------------------------------------------------------------------
-// Client STDIO processing
-// ---------------------------------------------------------------------------
-
-let inputBuffer = '';
-
-process.stdin.on('data', (chunk) => {
-  inputBuffer += chunk.toString();
+    if (catalog.isEnabled()) {
+      log('Tool filtering enabled');
+    } else {
+      log('Tool filtering disabled (no toolFilter in config or enabled: false)');
+    }
 
-  let newlineIdx;
-  while ((newlineIdx = inputBuffer.indexOf('\n')) !== -1) {
-    const line = inputBuffer.slice(0, newlineIdx);
-    inputBuffer = inputBuffer.slice(newlineIdx + 1);
-    if (line.trim()) {
-      let msg;
-      try {
-        msg = JSON.parse(line.trim());
-      } catch (e) {
-        log(`Non-JSON from client (dropped): ${line.substring(0, 200)}`);
-        continue;
-      }
-      router.handleClientMessage(msg, line.trim());
+    function sendToClient(data) {
+      process.stdout.write(data + '\n');
     }
-  }
-});
 
-process.stdin.on('end', () => {
-  log('Client stdin closed — shutting down');
-  shutdown();
-});
+    const router = new McpRouter({
+      config,
+      siteKeys,
+      isMultiSite,
+      pool,
+      catalog,
+      sendToClient,
+      log,
+    });
 
-// ---------------------------------------------------------------------------
-// Startup — connect to default site
-// ---------------------------------------------------------------------------
+    // -----------------------------------------------------------------------
+    // Client STDIO processing
+    // -----------------------------------------------------------------------
+
+    let inputBuffer = '';
+
+    process.stdin.on('data', (chunk) => {
+      inputBuffer += chunk.toString();
+
+      let newlineIdx;
+      while ((newlineIdx = inputBuffer.indexOf('\n')) !== -1) {
+        const line = inputBuffer.slice(0, newlineIdx);
+        inputBuffer = inputBuffer.slice(newlineIdx + 1);
+        if (line.trim()) {
+          let msg;
+          try {
+            msg = JSON.parse(line.trim());
+          } catch (e) {
+            log(`Non-JSON from client (dropped): ${line.substring(0, 200)}`);
+            continue;
+          }
+          router.handleClientMessage(msg, line.trim());
+        }
+      }
+    });
 
-(async function main() {
-  try {
-    const transport = await pool.connectDefault((parsedMsg, rawLine) => {
-      router.handleTransportMessage(parsedMsg, rawLine);
+    process.stdin.on('end', () => {
+      log('Client stdin closed — shutting down');
+      shutdown();
     });
-    router.setDefaultTransport(transport);
-    log(`Default transport connected: ${config.defaultSite}`);
-    router.drainEarlyQueue();
-  } catch (err) {
-    process.stderr.write(`abilities-mcp: Failed to connect to default site: ${err.message}\n`);
-    process.exit(1);
-  }
-})();
 
-// ---------------------------------------------------------------------------
-// Signal handling
-// ---------------------------------------------------------------------------
+    // -----------------------------------------------------------------------
+    // Startup — connect to default site
+    // -----------------------------------------------------------------------
+
+    try {
+      const transport = await pool.connectDefault((parsedMsg, rawLine) => {
+        router.handleTransportMessage(parsedMsg, rawLine);
+      });
+      router.setDefaultTransport(transport);
+      log(`Default transport connected: ${config.defaultSite}`);
+      router.drainEarlyQueue();
+    } catch (err) {
+      process.stderr.write(`abilities-mcp: Failed to connect to default site: ${err.message}\n`);
+      process.exit(1);
+    }
 
-function shutdown() {
-  log('Shutting down');
-  pool.shutdownAll().then(() => {
-    process.exit(0);
-  }).catch(() => {
-    process.exit(1);
-  });
-}
+    // -----------------------------------------------------------------------
+    // Signal handling
+    // -----------------------------------------------------------------------
+
+    function shutdown() {
+      log('Shutting down');
+      pool.shutdownAll().then(() => {
+        process.exit(0);
+      }).catch(() => {
+        process.exit(1);
+      });
+    }
 
-process.on('SIGTERM', shutdown);
-process.on('SIGINT', shutdown);
-process.on('unhandledRejection', (reason) => {
-  log(`Unhandled rejection: ${reason}`);
-});
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    process.on('unhandledRejection', (reason) => {
+      log(`Unhandled rejection: ${reason}`);
+    });
+  })();
+}

package/lib/auth/bridge-identity-provider.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * BridgeIdentityProvider — interface contract.
+ *
+ * Specified in design doc Appendix F.4 (interface) and Appendix H.3.2 (the
+ * v1.0 binding amendment that REPLACES the v1.0 implementation shown in F.4).
+ *
+ * The provider decides whether the bridge presents a stable identity to the
+ * adapter across sessions / installs / machines. v1.0 ships the
+ * fresh-each-time implementation (force fresh DCR on every flow); v1.1+ may
+ * persist client_id same-machine, v1.2+ may export/import across machines.
+ *
+ * @typedef {object} IdentityBundle
+ * @property {1} version
+ * @property {string} siteId
+ * @property {string} clientId
+ * @property {string} exportedAt    ISO 8601
+ * @property {string} [signature]   future: HMAC for tamper-detection
+ *
+ * @typedef {object} BridgeIdentityProvider
+ * @property {(siteId: string) => Promise<string|null>}            getClientId
+ * @property {(siteId: string, clientId: string) => Promise<void>} persistClientId
+ * @property {(siteId: string) => Promise<void>}                   clearClientId
+ * @property {(siteId: string) => Promise<IdentityBundle|null>}    exportIdentity
+ * @property {(siteId: string, bundle: IdentityBundle) => Promise<void>} importIdentity
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const IDENTITY_BUNDLE_VERSION = 1;
+
+module.exports = { IDENTITY_BUNDLE_VERSION };