@wickedevolutions/abilities-mcp 1.3.1 → 1.5.1

package/lib/auth/browser-launcher.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+
+/**
+ * Cross-platform default-browser opener.
+ *
+ * Picks an OS-appropriate "open this URL in the user's default browser"
+ * command and dispatches it. Returns a Promise that resolves once the launch
+ * command has been spawned (we do not wait for the browser to render).
+ *
+ * Uses platform-native commands only — no third-party dependency.
+ *   - macOS:   /usr/bin/open
+ *   - Windows: cmd /c start "" "<url>"
+ *   - Linux/BSD: xdg-open
+ *
+ * Callers can override the launcher entirely via `opts.launcher` for tests
+ * or unusual environments (e.g. a remote SSH session where there is no
+ * display server — operator pastes the URL by hand).
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+function _commandFor(platform) {
+  if (platform === 'darwin') return { cmd: 'open', args: [] };
+  if (platform === 'win32') return { cmd: 'cmd', args: ['/c', 'start', ''] };
+  return { cmd: 'xdg-open', args: [] };
+}
+
+/**
+ * Open `url` in the operator's default browser.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {(url:string)=>Promise<void>|void} [opts.launcher]   Test/override seam.
+ * @param {string} [opts.platform]                             Defaults to process.platform.
+ * @returns {Promise<{spawned:boolean, platform:string, command?:string}>}
+ */
+async function openBrowser(url, opts = {}) {
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new TypeError('openBrowser: url must be a non-empty string');
+  }
+  if (!/^https?:\/\//i.test(url)) {
+    throw new Error(`openBrowser: refusing to open non-http(s) URL: ${url}`);
+  }
+
+  if (opts.launcher) {
+    await opts.launcher(url);
+    return { spawned: true, platform: 'override' };
+  }
+
+  const platform = opts.platform || process.platform;
+  const { cmd, args } = _commandFor(platform);
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, [...args, url], { stdio: 'ignore', detached: true });
+    child.on('error', (err) => reject(err));
+    // Once spawn-error has had a tick to surface, consider the launch dispatched.
+    setImmediate(() => {
+      child.unref();
+      resolve({ spawned: true, platform, command: cmd });
+    });
+  });
+}
+
+module.exports = { openBrowser, _commandFor };

package/lib/auth/config-migration.js

@@ -0,0 +1,322 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const { SCHEMA_VERSION } = require('./schema-v2');
+const { AUTH_STATUS } = require('./events');
+const { makeRef } = require('./secret-store');
+const { MigrationError } = require('./errors');
+
+/**
+ * One-shot migration of wp-sites.json from the existing v1 (transport-style)
+ * schema to v2 (oauth + apppassword per site, secrets in keychain).
+ *
+ * Per Appendix F.5 (binding):
+ *   - Triggered on first bridge launch after upgrade.
+ *   - One-shot, non-destructive: idempotent — calling again on a v2 file
+ *     returns `{ migrated: false, alreadyV2: true }`.
+ *   - Atomic write: temp file → rename.
+ *   - Backup the original to `<file>.v1.bak`.
+ *
+ * The "v1" the spec describes assumes plaintext `auth.password`. The actual
+ * existing bridge schema (lib/config.js) is transport-based with
+ * `http.password` / `http.passwordEnv` / `http.passwordCommand` and a
+ * separate `ssh` transport. This migration handles the real schema:
+ *
+ *   transport: http  + http.password           → method: apppassword, secret to keychain
+ *   transport: http  + http.passwordEnv        → method: apppassword, env var resolved at migration time
+ *   transport: http  + http.passwordCommand    → method: apppassword, command run at migration time
+ *   transport: ssh                             → method: apppassword (carrier-only); ssh block preserved
+ *                                                so existing SSH transport continues to work; OAuth
+ *                                                add-site flow does not apply to SSH sites.
+ *
+ * SSH-only sites are tagged `auth.method = "apppassword"` with a synthetic
+ * placeholder so v2 validation passes; the bridge's runtime still consults
+ * the original `transport`, `ssh`, `http` blocks (preserved on each site)
+ * for the actual connection. v2 adds OAuth fields but does NOT remove the
+ * transport-level fields needed by existing transports.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const SECRET_SERVICE = 'abilities-mcp';
+
+/**
+ * Determine whether a parsed config is already at v2.
+ * @param {object} config
+ * @returns {boolean}
+ */
+function isV2(config) {
+  return Boolean(config && config.schema_version === SCHEMA_VERSION);
+}
+
+/**
+ * Resolve an http password from the legacy schema. Mirrors the resolver in
+ * lib/config.js so migration sees the actual value to lift into keychain.
+ *
+ * @param {object} httpBlock
+ * @param {object} env
+ * @returns {string}
+ */
+function _resolveLegacyHttpPassword(httpBlock, env) {
+  if (httpBlock.password) return httpBlock.password;
+  if (httpBlock.passwordEnv) {
+    const v = env[httpBlock.passwordEnv];
+    if (typeof v !== 'string' || v.length === 0) {
+      throw new MigrationError(
+        `Cannot migrate site: passwordEnv "${httpBlock.passwordEnv}" is not set`,
+        { code: 'env_var_missing' }
+      );
+    }
+    return v;
+  }
+  if (httpBlock.passwordCommand) {
+    try {
+      return execSync(httpBlock.passwordCommand, { encoding: 'utf8' }).trim();
+    } catch (err) {
+      throw new MigrationError(
+        `Cannot migrate site: passwordCommand failed: ${err.message}`,
+        { code: 'password_command_failed', cause: err }
+      );
+    }
+  }
+  throw new MigrationError(
+    `Cannot migrate site: no password, passwordEnv, or passwordCommand`,
+    { code: 'no_password_source' }
+  );
+}
+
+/**
+ * Convert a single legacy site block to v2 shape. Stores any plaintext
+ * secret to the SecretStore and replaces it with a keychain reference.
+ *
+ * @param {string} siteId
+ * @param {object} legacy
+ * @param {object} args
+ * @param {object} args.secretStore
+ * @param {object} [args.env]
+ * @returns {Promise<{site: object, lifted: Array<{account:string}>}>}
+ */
+async function _convertSite(siteId, legacy, args) {
+  const env = args.env || process.env;
+  const lifted = [];
+  // Carry forward fields the runtime still uses (transport, ssh, http,
+  // multisite, label, url, allowInsecure, mcpServer).
+  const v2 = {};
+  for (const k of Object.keys(legacy)) {
+    if (k === 'auth') continue;     // legacy didn't have one; preserve any existing
+    v2[k] = legacy[k];
+  }
+  if (typeof v2.url !== 'string') {
+    if (legacy.transport === 'ssh' && legacy.ssh && legacy.ssh.host) {
+      v2.url = `ssh://${legacy.ssh.host}`;
+    } else if (legacy.http && legacy.http.endpoint) {
+      const u = new URL(legacy.http.endpoint);
+      v2.url = u.origin;
+    } else {
+      v2.url = '';
+    }
+  }
+  if (typeof v2.label !== 'string') v2.label = legacy.label || siteId;
+
+  if (legacy.transport === 'http' && legacy.http) {
+    const account = `${siteId}/apppassword`;
+    const password = _resolveLegacyHttpPassword(legacy.http, env);
+    await args.secretStore.set(SECRET_SERVICE, account, password);
+    lifted.push({ account });
+    v2.auth = {
+      method: 'apppassword',
+      username: legacy.http.username,
+      password_ref: makeRef(SECRET_SERVICE, account),
+    };
+    // Sanitize the http block — drop password/passwordEnv/passwordCommand
+    // so the keychain becomes the sole source of truth.
+    if (v2.http) {
+      v2.http = { ...v2.http };
+      delete v2.http.password;
+      delete v2.http.passwordEnv;
+      delete v2.http.passwordCommand;
+      v2.http.password_ref = makeRef(SECRET_SERVICE, account);
+    }
+  } else if (legacy.transport === 'ssh') {
+    // SSH sites have no app-password to migrate. We still tag them
+    // method: 'apppassword' so v2 validation passes; the synthetic
+    // password_ref points at an empty entry callers can ignore.
+    const account = `${siteId}/apppassword`;
+    await args.secretStore.set(SECRET_SERVICE, account, '');
+    lifted.push({ account });
+    v2.auth = {
+      method: 'apppassword',
+      username: (legacy.ssh && legacy.ssh.user) || 'ssh',
+      password_ref: makeRef(SECRET_SERVICE, account),
+    };
+  } else {
+    // Already-shaped v2 sites pass through unchanged.
+    if (legacy.auth && legacy.auth.method) {
+      v2.auth = legacy.auth;
+    } else {
+      throw new MigrationError(
+        `Cannot migrate site "${siteId}": no transport and no v2 auth block`,
+        { code: 'unrecognized_site' }
+      );
+    }
+  }
+
+  v2.auth_status = legacy.auth_status || AUTH_STATUS.ACTIVE;
+  return { site: v2, lifted };
+}
+
+/**
+ * Migrate a parsed config object in memory. Side-effect: writes secrets to
+ * the supplied secret store. Caller is responsible for the file I/O.
+ *
+ * @param {object} legacyConfig
+ * @param {object} args
+ * @param {object} args.secretStore
+ * @param {object} [args.env]
+ * @returns {Promise<{config: object, lifted: Array}>}
+ */
+async function migrateConfig(legacyConfig, args) {
+  if (!args || !args.secretStore) {
+    throw new MigrationError('migrateConfig requires secretStore', { code: 'no_store' });
+  }
+  if (!legacyConfig || typeof legacyConfig !== 'object') {
+    throw new MigrationError('Legacy config is not an object', { code: 'invalid_input' });
+  }
+  if (!legacyConfig.sites || typeof legacyConfig.sites !== 'object') {
+    throw new MigrationError('Legacy config has no sites', { code: 'invalid_input' });
+  }
+
+  const v2 = {
+    $schema: 'https://wickedevolutions.com/schemas/abilities-mcp/wp-sites/v2.json',
+    schema_version: SCHEMA_VERSION,
+    sites: {},
+  };
+  if (legacyConfig.defaultSite) v2.defaultSite = legacyConfig.defaultSite;
+
+  const allLifted = [];
+  for (const [siteId, legacy] of Object.entries(legacyConfig.sites)) {
+    const { site, lifted } = await _convertSite(siteId, legacy, args);
+    v2.sites[siteId] = site;
+    allLifted.push(...lifted.map((l) => ({ siteId, ...l })));
+  }
+  return { config: v2, lifted: allLifted };
+}
+
+/**
+ * Atomic write of `config` to `filePath`. Writes to a temp file in the same
+ * directory and renames. Restrictive permissions (0600) on the new file.
+ * @param {string} filePath
+ * @param {object} config
+ */
+async function _atomicWrite(filePath, config) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.wp-sites.json.tmp.${process.pid}.${Date.now()}`);
+  const payload = JSON.stringify(config, null, 2) + '\n';
+  await fs.promises.writeFile(tmp, payload, { mode: 0o600 });
+  // On POSIX, fs.rename is atomic if source and destination are on the same
+  // filesystem (we ensured that by writing tmp into the same dir).
+  await fs.promises.rename(tmp, filePath);
+}
+
+/**
+ * One-shot migration of the on-disk wp-sites.json file. Idempotent.
+ *
+ * @param {object} args
+ * @param {string} args.filePath
+ * @param {object} args.secretStore
+ * @param {object} [args.env]
+ * @param {boolean} [args.dryRun]            Skip the write and the .v1.bak
+ * @returns {Promise<{
+ *   migrated: boolean,
+ *   alreadyV2?: boolean,
+ *   filePath: string,
+ *   backupPath?: string,
+ *   liftedCount?: number,
+ * }>}
+ */
+async function migrateFile(args) {
+  if (!args || !args.filePath) {
+    throw new MigrationError('migrateFile requires filePath', { code: 'no_path' });
+  }
+  if (!args.secretStore) {
+    throw new MigrationError('migrateFile requires secretStore', { code: 'no_store' });
+  }
+
+  let raw;
+  try {
+    raw = await fs.promises.readFile(args.filePath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // Nothing to migrate — caller is starting clean.
+      return { migrated: false, alreadyV2: false, filePath: args.filePath, missing: true };
+    }
+    throw new MigrationError(`Cannot read ${args.filePath}: ${err.message}`, {
+      code: 'read_failed', cause: err,
+    });
+  }
+
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) {
+    throw new MigrationError(`Cannot parse ${args.filePath}: ${err.message}`, {
+      code: 'parse_failed', cause: err,
+    });
+  }
+
+  if (isV2(parsed)) {
+    return { migrated: false, alreadyV2: true, filePath: args.filePath };
+  }
+
+  const { config: v2Config, lifted } = await migrateConfig(parsed, {
+    secretStore: args.secretStore,
+    env: args.env,
+  });
+
+  if (args.dryRun) {
+    return {
+      migrated: false,
+      alreadyV2: false,
+      filePath: args.filePath,
+      previewConfig: v2Config,
+      liftedCount: lifted.length,
+    };
+  }
+
+  // Backup BEFORE writing — if backup fails, we have not yet damaged anything.
+  const backupPath = `${args.filePath}.v1.bak`;
+  try {
+    await fs.promises.copyFile(args.filePath, backupPath);
+  } catch (err) {
+    throw new MigrationError(
+      `Failed to back up ${args.filePath} → ${backupPath}: ${err.message}`,
+      { code: 'backup_failed', cause: err }
+    );
+  }
+
+  try {
+    await _atomicWrite(args.filePath, v2Config);
+  } catch (err) {
+    throw new MigrationError(
+      `Failed to write v2 config to ${args.filePath}: ${err.message}`,
+      { code: 'write_failed', cause: err }
+    );
+  }
+
+  return {
+    migrated: true,
+    filePath: args.filePath,
+    backupPath,
+    liftedCount: lifted.length,
+  };
+}
+
+module.exports = {
+  isV2,
+  migrateConfig,
+  migrateFile,
+  _atomicWrite,
+};

package/lib/auth/dcr-client.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const { postJson, getJson } = require('./http-json');
+const { RegistrationError } = require('./errors');
+
+/**
+ * Dynamic Client Registration (RFC 7591) client.
+ *
+ * Per Appendix F.4 (DCR registration metadata) and H.4.2 (software_id is a
+ * self-reported hint), v1.0 sends:
+ *
+ *   software_id      = "com.wickedevolutions.abilities-mcp"
+ *   software_version = read from package.json (currently "1.4.0"; the
+ *                      design doc example used "1.0.0", but the spec wording
+ *                      defines software_version as "the bridge's current
+ *                      version" — we report what we ship as)
+ *
+ * Per Appendix D.2 L2: "GET probes before POST." We do a courtesy GET on the
+ * registration endpoint before POSTing — adapter Phase 1 wires both.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const SOFTWARE_ID = 'com.wickedevolutions.abilities-mcp';
+const CLIENT_URI = 'https://wickedevolutions.com/docs/abilities-mcp';
+const DEFAULT_GRANT_TYPES = Object.freeze(['authorization_code', 'refresh_token']);
+const DEFAULT_RESPONSE_TYPES = Object.freeze(['code']);
+const DEFAULT_AUTH_METHOD = 'none'; // public client — PKCE proof-of-possession
+
+/**
+ * Build the DCR request body.
+ * @param {object} args
+ * @param {string} args.clientName
+ * @param {string} args.redirectUri
+ * @param {string|string[]} args.scope            space-separated scope string OR array
+ * @param {string} args.softwareVersion
+ * @param {string[]} [args.grantTypes]
+ * @param {string[]} [args.responseTypes]
+ * @returns {object}
+ */
+function buildRegistrationBody(args) {
+  const scope = Array.isArray(args.scope) ? args.scope.join(' ') : args.scope;
+  return {
+    client_name: args.clientName,
+    redirect_uris: [args.redirectUri],
+    token_endpoint_auth_method: DEFAULT_AUTH_METHOD,
+    grant_types: args.grantTypes || DEFAULT_GRANT_TYPES,
+    response_types: args.responseTypes || DEFAULT_RESPONSE_TYPES,
+    scope,
+    software_id: SOFTWARE_ID,
+    software_version: args.softwareVersion,
+    client_uri: CLIENT_URI,
+  };
+}
+
+/**
+ * Register a new OAuth client with the adapter.
+ *
+ * @param {object} args
+ * @param {string} args.registrationEndpoint
+ * @param {string} args.clientName
+ * @param {string} args.redirectUri
+ * @param {string|string[]} args.scope
+ * @param {string} args.softwareVersion
+ * @param {boolean} [args.skipGetProbe]    Tests can disable.
+ * @param {boolean} [args.allowInsecure]
+ * @param {number}  [args.timeoutMs]
+ * @param {object}  [args.httpsAgent]      test injection
+ * @returns {Promise<{clientId: string, raw: object}>}
+ */
+async function register(args) {
+  // L2 GET probe — best-effort, never raises.
+  if (!args.skipGetProbe) {
+    try {
+      await getJson(args.registrationEndpoint, {
+        allowInsecure: args.allowInsecure,
+        timeoutMs: args.timeoutMs,
+        httpsAgent: args.httpsAgent,
+      });
+    } catch {
+      // Ignore — the probe is informational. Real failures show up on POST.
+    }
+  }
+
+  const body = buildRegistrationBody({
+    clientName: args.clientName,
+    redirectUri: args.redirectUri,
+    scope: args.scope,
+    softwareVersion: args.softwareVersion,
+  });
+
+  let res;
+  try {
+    res = await postJson(args.registrationEndpoint, body, {
+      allowInsecure: args.allowInsecure,
+      timeoutMs: args.timeoutMs,
+      httpsAgent: args.httpsAgent,
+    });
+  } catch (err) {
+    throw new RegistrationError(
+      `DCR request failed: ${err.message}`,
+      { state: 'registering', cause: err }
+    );
+  }
+
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    throw new RegistrationError(
+      `DCR returned ${res.statusCode} from ${args.registrationEndpoint}`,
+      { state: 'registering', cause: { statusCode: res.statusCode, body: res.body } }
+    );
+  }
+  if (!res.json || typeof res.json.client_id !== 'string') {
+    throw new RegistrationError(
+      `DCR response missing client_id`,
+      { state: 'registering', cause: { body: res.body } }
+    );
+  }
+
+  return { clientId: res.json.client_id, raw: res.json };
+}
+
+module.exports = { register, buildRegistrationBody, SOFTWARE_ID, CLIENT_URI };