@wickedevolutions/abilities-mcp 1.5.4 → 1.6.1

package/lib/cli/scope-mutation.js

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * Scope-mutation helpers for `reauth` (Issue #50).
+ *
+ * The `reauth` CLI used to accept a single `--scope` flag that REPLACED the
+ * persisted scope array — a UX trap, since an operator (or AI assistant)
+ * adding new scopes via `--scope='<new only>'` would silently drop every
+ * existing scope. The locked design adds `--add-scope` and `--remove-scope`
+ * for the merge / remove cases and keeps `--scope` as the explicit-replace
+ * escape hatch with a stderr warning when the supplied set is a strict
+ * subset of the existing scopes (i.e., the replace would drop scopes).
+ *
+ * All three flags are mutually exclusive — combining any two is a typed
+ * error. Mirrors `git remote add` / `git remote remove` conventions: each
+ * flag has one job.
+ *
+ * This module is pure — no I/O, no logging. The reauth command imports it
+ * and threads warnings through the run-contract's `errLines`.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+/**
+ * Parse a CLI scope-list value into a deduped array, preserving order of
+ * first occurrence. Accepts:
+ *   - already-parsed string array (passes through with dedupe)
+ *   - comma- or whitespace-delimited string ('a,b c d' → ['a','b','c','d'])
+ *   - empty / nullish input → []
+ */
+function parseScopeList(input) {
+  if (input == null || input === '') return [];
+  const tokens = Array.isArray(input)
+    ? input
+    : String(input).split(/[,\s]+/);
+  const out = [];
+  const seen = new Set();
+  for (const t of tokens) {
+    const tok = String(t).trim();
+    if (!tok || seen.has(tok)) continue;
+    seen.add(tok);
+    out.push(tok);
+  }
+  return out;
+}
+
+/**
+ * Return existing ∪ additions, deduped, preserving the order
+ * "existing first, new additions appended in input order."
+ */
+function mergeScopes(existing, additions) {
+  const e = parseScopeList(existing);
+  const a = parseScopeList(additions);
+  const seen = new Set(e);
+  const out = e.slice();
+  for (const tok of a) {
+    if (!seen.has(tok)) {
+      seen.add(tok);
+      out.push(tok);
+    }
+  }
+  return out;
+}
+
+/**
+ * Return { result, missing } where:
+ *   result  = existing minus removals (preserves order of existing)
+ *   missing = removals that weren't in existing (no-op, warn-not-error)
+ */
+function removeScopes(existing, removals) {
+  const e = parseScopeList(existing);
+  const r = parseScopeList(removals);
+  const removeSet = new Set(r);
+  const existingSet = new Set(e);
+  const result = e.filter((tok) => !removeSet.has(tok));
+  const missing = r.filter((tok) => !existingSet.has(tok));
+  return { result, missing };
+}
+
+/**
+ * True iff replacement ⊊ existing (every replacement element is in existing
+ * AND existing has at least one element not in replacement). Used to detect
+ * the --scope replace footgun: supplied set is missing scopes the operator
+ * almost certainly didn't mean to drop.
+ *
+ * Equal sets return false (no warning needed — replace is a no-op).
+ * Replacement that adds new scopes (not subset) returns false — operator
+ * is intentionally swapping the set.
+ */
+function isStrictSubset(replacement, existing) {
+  const r = parseScopeList(replacement);
+  const e = parseScopeList(existing);
+  if (r.length >= e.length) return false; // strict subset must be smaller
+  const existingSet = new Set(e);
+  for (const tok of r) if (!existingSet.has(tok)) return false;
+  return true;
+}
+
+/**
+ * Resolve the final scope list for an OAuthClient invocation given the
+ * three mutually-exclusive CLI flags + the persisted scope array.
+ *
+ * @param {object} args
+ * @param {string|string[]|undefined} args.scope         --scope: replace existing
+ * @param {string|string[]|undefined} args.addScope      --add-scope: merge into existing
+ * @param {string|string[]|undefined} args.removeScope   --remove-scope: remove from existing
+ * @param {string[]|undefined}        args.existing      Persisted scope array (or DEFAULT_SCOPE fallback)
+ *
+ * @returns {{ scopes: string[], warnings: string[], errorCode?: string, errorMessage?: string }}
+ *   scopes        — the array to pass into OAuthClient
+ *   warnings      — stderr advisories (subset replace, no-op removals, etc.)
+ *   errorCode     — set when mutual-exclusion violated; caller should throw CliError
+ *   errorMessage  — human-readable message for the typed error
+ */
+function computeScopeMutation(args) {
+  const { scope, addScope, removeScope, existing } = args;
+  const set = (v) => v != null && v !== '' && !(Array.isArray(v) && v.length === 0);
+  const flags = [
+    set(scope) ? '--scope' : null,
+    set(addScope) ? '--add-scope' : null,
+    set(removeScope) ? '--remove-scope' : null,
+  ].filter(Boolean);
+
+  if (flags.length > 1) {
+    return {
+      scopes: parseScopeList(existing),
+      warnings: [],
+      errorCode: 'reauth_scope_flag_conflict',
+      errorMessage:
+        `reauth: ${flags.join(', ')} are mutually exclusive — each flag does one job. ` +
+        `Use --add-scope to merge new scopes into the existing set, --remove-scope to ` +
+        `drop scopes by exact match, or --scope to replace the entire set.`,
+    };
+  }
+
+  const existingArr = parseScopeList(existing);
+
+  if (set(addScope)) {
+    return { scopes: mergeScopes(existingArr, addScope), warnings: [] };
+  }
+
+  if (set(removeScope)) {
+    const { result, missing } = removeScopes(existingArr, removeScope);
+    const warnings = [];
+    for (const m of missing) {
+      warnings.push(`reauth: --remove-scope: "${m}" was not in the existing scope set (no-op).`);
+    }
+    return { scopes: result, warnings };
+  }
+
+  if (set(scope)) {
+    const replacement = parseScopeList(scope);
+    const warnings = [];
+    if (existingArr.length > 0 && isStrictSubset(replacement, existingArr)) {
+      const dropped = existingArr.filter((s) => !replacement.includes(s));
+      warnings.push(
+        `reauth: --scope replaces ${existingArr.length} existing scopes with ${replacement.length} new ones — ` +
+        `this drops ${dropped.length} scope${dropped.length === 1 ? '' : 's'} (${dropped.slice(0, 3).join(', ')}${dropped.length > 3 ? ', ...' : ''}). ` +
+        `Use --add-scope to merge instead.`
+      );
+    }
+    return { scopes: replacement, warnings };
+  }
+
+  // No scope flag — fall back to existing (caller defaults to DEFAULT_SCOPE
+  // when existing is empty / not present).
+  return { scopes: existingArr, warnings: [] };
+}
+
+module.exports = {
+  parseScopeList,
+  mergeScopes,
+  removeScopes,
+  isStrictSubset,
+  computeScopeMutation,
+};

package/lib/config.js

@@ -356,12 +356,22 @@ function resolveSiteKey(config, compositeKey) {
       const subsiteUrl = site.multisite[subsiteKey];
       let resolvedEndpoint = null;
 
-      // For HTTP transport: build subsite endpoint from subsite URL + parent endpoint path.
-      // This makes WordPress boot natively into the correct blog context —
-      // community.wickedevolutions.com/wp-json/mcp/... boots into blog 2,
-      // not wickedevolutions.com/wp-json/mcp/... which boots into blog 1.
-      if (site.transport === 'http' && site.http && site.http.endpoint) {
-        const parentUrl = new URL(site.http.endpoint);
+      // Build subsite endpoint from subsite URL + parent endpoint path.
+      // WordPress multisite (subdomain-style) routes by URL host, so posting
+      // to community.wickedevolutions.com/wp-json/mcp/... boots into the
+      // community blog, not the network root. Without this substitution the
+      // request lands on blog 1 regardless of which subsite was targeted.
+      //
+      // Source endpoint differs by auth method:
+      //   - HTTP / App Password sites carry it on `http.endpoint`.
+      //   - OAuth sites carry it on `mcp_resource` (set during OAuth
+      //     discovery; there's no `http.endpoint` for OAuth sites).
+      const parentEndpoint =
+        (site.http && site.http.endpoint)
+        || (site.auth && site.auth.method === 'oauth' && site.mcp_resource)
+        || null;
+      if (parentEndpoint) {
+        const parentUrl = new URL(parentEndpoint);
         const subsiteOrigin = new URL(subsiteUrl).origin;
         resolvedEndpoint = subsiteOrigin + parentUrl.pathname;
       }

package/lib/connection-pool.js

@@ -293,8 +293,16 @@ class ConnectionPool {
     // 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.
+    //
+    // Pass the resolved subsite endpoint and URL through. For multisite OAuth
+    // (Issue #48) the OAuth branch must POST to the subsite host, not the
+    // network root — mirroring the HTTP branch's `resolvedEndpoint || ...`
+    // pattern below.
     if (siteConfig.auth && siteConfig.auth.method === 'oauth') {
-      return this._createOAuthHttpTransport(compositeKey, siteConfig);
+      return this._createOAuthHttpTransport(compositeKey, siteConfig, {
+        resolvedEndpoint,
+        subsiteUrl: finalSubsiteUrl,
+      });
     }
 
     if (siteConfig.transport === 'ssh') {
@@ -342,7 +350,7 @@ class ConnectionPool {
    * we let propagate so the bridge fails loud rather than silently
    * downgrading to App Password).
    */
-  async _createOAuthHttpTransport(compositeKey, siteConfig) {
+  async _createOAuthHttpTransport(compositeKey, siteConfig, { resolvedEndpoint, subsiteUrl } = {}) {
     const { OAuthHttpTransport } = require('./transports/oauth-http-transport');
     const { TokenManager } = require('./auth/token-manager');
     const { discover } = require('./auth/discovery-client');
@@ -393,7 +401,8 @@ class ConnectionPool {
     const siteAuth = _siteAuthFromConfig(compositeKey, siteConfig, asMetadata);
 
     return new OAuthHttpTransport({
-      endpoint: siteConfig.mcp_resource,
+      endpoint: resolvedEndpoint || siteConfig.mcp_resource,
+      subsiteUrl: subsiteUrl || null,
       tokenManager: this._tokenManager,
       siteAuth,
       onAuthStatusChange: (newStatus, info) => {
@@ -455,9 +464,16 @@ class ConnectionPool {
   _findExistingHttpTransport(compositeKey) {
     const { siteConfig, resolvedEndpoint } = resolveSiteKey(this.config, compositeKey);
 
+    // The dedupe target must be the *subsite* endpoint when one is resolved,
+    // otherwise different subsite keys collapse onto whichever transport
+    // happens to be cached first — which was the v1.5.4 multisite-OAuth
+    // failure mode (Issue #48): every wickedevolutions.<subsite> reused the
+    // network-root transport built for `wickedevolutions`. Single-site keys
+    // (resolvedEndpoint=null) still fall back to siteConfig.mcp_resource /
+    // http.endpoint, which is what dedupes parent + same-host subsites.
     let targetEndpoint = null;
     if (siteConfig.auth && siteConfig.auth.method === 'oauth') {
-      targetEndpoint = siteConfig.mcp_resource;
+      targetEndpoint = resolvedEndpoint || siteConfig.mcp_resource;
     } else if (siteConfig.transport === 'http') {
       targetEndpoint = resolvedEndpoint || (siteConfig.http && siteConfig.http.endpoint);
     }

package/lib/transports/oauth-http-transport.js

@@ -44,7 +44,28 @@ const MAX_QUEUE = 100;
  *     it is NOT a runtime "if OAuth fails, try Basic" branch.
  *
  * @param {object} opts
- * @param {string} opts.endpoint              MCP resource URL (https)
+ * @param {string} opts.endpoint              MCP resource URL (https). For
+ *                                            multisite OAuth (Issue #48) the
+ *                                            caller derives the subsite-host
+ *                                            endpoint via resolveSiteKey and
+ *                                            passes it here; the transport
+ *                                            posts to whatever it's given.
+ * @param {string} [opts.subsiteUrl]          Optional. When the resolved
+ *                                            site key targets a multisite
+ *                                            subsite, the subsite home URL
+ *                                            is forwarded on every request
+ *                                            via X-Abilities-MCP-Subsite-URL
+ *                                            so server-side adapters that
+ *                                            honour it (Phase B / future)
+ *                                            can route per-request without
+ *                                            re-parsing the endpoint URL.
+ *                                            Subdomain-style multisite does
+ *                                            not need this header — the host
+ *                                            in the endpoint URL is
+ *                                            sufficient — but the header is
+ *                                            unconditional so path-style
+ *                                            multisite works once the
+ *                                            adapter consumes it.
  * @param {object} opts.tokenManager          TokenManager instance
  * @param {object} opts.siteAuth              SiteAuthState (see TokenManager)
  * @param {function} opts.onAuthStatusChange  Optional. Called with
@@ -70,6 +91,7 @@ class OAuthHttpTransport {
     }
 
     this.endpoint = opts.endpoint;
+    this.subsiteUrl = opts.subsiteUrl || null;
     this._tokenManager = opts.tokenManager;
     this._siteAuth = opts.siteAuth;
     this._onAuthStatusChange = opts.onAuthStatusChange || null;
@@ -496,6 +518,12 @@ class OAuthHttpTransport {
 
       if (this.sessionId) headers['Mcp-Session-Id'] = this.sessionId;
       if (this.sessionToken) headers['Mcp-Session-Token'] = this.sessionToken;
+      // Forward subsite context for multisite OAuth (Issue #48). Subdomain-
+      // style multisite already routes by host in the endpoint URL; the
+      // header is forward-looking infrastructure for path-style multisite
+      // (Phase B), so the server can switch_to_blog() without re-parsing
+      // the request URL.
+      if (this.subsiteUrl) headers['X-Abilities-MCP-Subsite-URL'] = this.subsiteUrl;
 
       const hostCookies = this._cookies.get(this.parsedUrl.hostname);
       if (hostCookies && hostCookies.size > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wickedevolutions/abilities-mcp",
-  "version": "1.5.4",
+  "version": "1.6.1",
   "description": "Open-source MCP bridge connecting AI clients to WordPress through the Abilities API — multi-site routing, zero dependencies",
   "main": "abilities-mcp.js",
   "bin": {