@wickedevolutions/abilities-mcp 1.3.1 → 1.5.1

package/lib/cli/commands/upgrade-auth.js

@@ -0,0 +1,259 @@
+'use strict';
+
+const {
+  OAuthClient,
+  TokenManager,
+  AUTH_STATUS,
+  DEFAULT_SCOPE,
+} = require('../../auth');
+const { discover } = require('../../auth/discovery-client');
+const { makeRef, parseRef } = require('../../auth/secret-store');
+const { CliError, EXIT_USAGE, fromAuthError, withProgress } = require('../errors');
+const { subscribeProgress } = require('../output');
+const { readConfig, writeConfig } = require('../config-store');
+const testCmd = require('./test');
+
+/**
+ * `upgrade-auth <site_id> [--confirm]` — migrate an App Password site to
+ * OAuth without disturbing the App Password fallback.
+ *
+ * Implements the four-step sequence locked in Appendix F.5:
+ *
+ *   Step 1 — Pre-flight discovery. 404 → "Site does not have OAuth. Install
+ *            abilities-mcp-adapter v1.5.0+ first."
+ *   Step 2 — Dual-write: copy current apppassword credentials to
+ *            apppassword_fallback, then run the OAuth flow. On success the
+ *            site uses OAuth; the fallback remains.
+ *   Step 3 — Validation: run `test <site_id>`. On success, "✓ OAuth working.
+ *            App Password kept as fallback for now." On failure, revert.
+ *   Step 4 — `--confirm`: remove apppassword_fallback and delete the legacy
+ *            keychain entry.
+ *
+ * `upgrade-auth` without `--confirm` is idempotent (per F.5 prose) — running
+ * it twice on the same site is safe.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const SECRET_SERVICE = 'abilities-mcp';
+
+async function run(args, ctx) {
+  const siteId = args._ && args._[0];
+  if (!siteId) {
+    throw new CliError('upgrade-auth requires a site_id argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp upgrade-auth <site_id> [--confirm]',
+    });
+  }
+  const config = readConfig(ctx.configPath);
+  const site = config.sites[siteId];
+  if (!site) {
+    throw new CliError(`upgrade-auth: unknown site_id "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp list-sites to see configured sites',
+    });
+  }
+
+  // ---- Step 4: --confirm cleans up the fallback. -----------------------
+  if (args.confirm) {
+    return _confirm(siteId, site, config, ctx);
+  }
+
+  if (site.auth.method === 'oauth' && !site.auth.apppassword_fallback) {
+    return {
+      exitCode: 0,
+      lines: [`Site "${siteId}" already uses OAuth with no App Password fallback.`,
+              `(Idempotent — nothing to do.)`],
+    };
+  }
+
+  if (site.auth.method !== 'apppassword') {
+    // OAuth-with-fallback case is allowed (Step 2 may have already run).
+    if (!(site.auth.method === 'oauth' && site.auth.apppassword_fallback)) {
+      throw new CliError(
+        `upgrade-auth: site "${siteId}" is not in a state we can upgrade (method=${site.auth.method})`,
+        {
+          exitCode: EXIT_USAGE,
+          nextAction: `Run: abilities-mcp list-sites and inspect the site state`,
+        }
+      );
+    }
+  }
+
+  const out = [];
+
+  // ---- Step 1: pre-flight discovery. -----------------------------------
+  out.push(`Step 1: pre-flight OAuth discovery for "${siteId}" (${site.url})…`);
+  const discoverFn = (ctx.deps && ctx.deps.discover) || discover;
+  try {
+    await discoverFn(site.url, {
+      pinned: !!site.oauth_capability_pinned,
+      pinnedFirstSeenAt: site.oauth_capability_pinned && site.oauth_capability_pinned.first_seen_at,
+      allowInsecure: ctx.allowInsecure,
+    });
+    out.push('  ✓ OAuth discovery succeeded.');
+  } catch (err) {
+    if (err && err.name === 'DiscoveryError') {
+      throw new CliError(
+        `Site ${siteId} does not have OAuth. Install abilities-mcp-adapter v1.5.0+ first.`,
+        {
+          exitCode: 4,
+          nextAction: 'Install / upgrade abilities-mcp-adapter on the site to v1.5.0 or later',
+          cause: err,
+        }
+      );
+    }
+    throw fromAuthError(err, { siteId });
+  }
+
+  // ---- Step 2: dual-write. ---------------------------------------------
+  out.push(`Step 2: running OAuth flow while keeping App Password as fallback…`);
+
+  // Stash the current apppassword credentials before the OAuth flow runs.
+  // If the operator has already done step 2 (resuming after a partial run),
+  // the fallback already exists and we leave it untouched.
+  let pendingFallback = site.auth.apppassword_fallback || null;
+  if (!pendingFallback && site.auth.method === 'apppassword') {
+    pendingFallback = {
+      username: site.auth.username,
+      password_ref: site.auth.password_ref,
+    };
+    // Move the keychain entry from <siteId>/apppassword to
+    // <siteId>/apppassword-legacy per the F.5 example. We do this before
+    // the OAuth flow so a mid-flow crash leaves us with a recoverable
+    // state (operator can re-run upgrade-auth).
+    const legacyAccount = `${siteId}/apppassword-legacy`;
+    try {
+      const oldAccount = parseRef(site.auth.password_ref).account;
+      const value = await ctx.secretStore.get(SECRET_SERVICE, oldAccount);
+      if (typeof value === 'string') {
+        await ctx.secretStore.set(SECRET_SERVICE, legacyAccount, value);
+      }
+    } catch {
+      // Non-fatal — operator may have already deleted the original entry.
+    }
+    pendingFallback = {
+      username: site.auth.username,
+      password_ref: makeRef(SECRET_SERVICE, legacyAccount),
+    };
+  }
+
+  const clientName = `${ctx.userLabel}'s Operator (${ctx.hostnameLabel})`;
+  const OAuthClientCls = (ctx.deps && ctx.deps.OAuthClient) || OAuthClient;
+  const oauth = new OAuthClientCls({
+    siteUrl: site.url,
+    clientName,
+    softwareVersion: ctx.softwareVersion,
+    scope: args.scope || DEFAULT_SCOPE,
+    identityProvider: ctx.identityProvider,
+    allowInsecure: ctx.allowInsecure,
+    capabilityPin: site.oauth_capability_pinned ? {
+      firstSeenAt: site.oauth_capability_pinned.first_seen_at,
+    } : null,
+    deps: ctx.deps && ctx.deps.oauthClientDeps,
+  });
+  subscribeProgress(oauth, out);
+
+  let result;
+  try { result = await oauth.run(); }
+  catch (err) {
+    out.push('✗ OAuth flow failed — config left unchanged. App Password remains primary.');
+    throw fromAuthError(err, { siteId });
+  }
+
+  const tm = new TokenManager({ secretStore: ctx.secretStore, allowInsecure: ctx.allowInsecure });
+  const persisted = await tm.persistTokens({ siteId, tokens: result.tokens });
+
+  site.auth = {
+    method: 'oauth',
+    client_id: result.clientId,
+    user_login: pendingFallback ? pendingFallback.username : (ctx.userLabel || 'operator'),
+    scopes: result.scopes,
+    access_token_expires_at: persisted.accessTokenExpiresAt,
+    refresh_token_expires_at: persisted.refreshTokenExpiresAt,
+    access_token_ref: persisted.accessTokenRef,
+    refresh_token_ref: persisted.refreshTokenRef,
+    apppassword_fallback: pendingFallback,
+  };
+  site.auth_status = AUTH_STATUS.ACTIVE;
+  site.oauth_capability_pinned = {
+    first_seen_at: result.capabilityPin.firstSeenAt,
+    last_confirmed_at: result.capabilityPin.lastConfirmedAt,
+  };
+  if (result.prMetadata && result.prMetadata.resource) {
+    site.mcp_resource = result.prMetadata.resource;
+  }
+  await writeConfig(ctx.configPath, config);
+
+  // ---- Step 3: validation via `test`. ----------------------------------
+  out.push(`Step 3: validating OAuth bearer with a ping…`);
+  let pingFailed = false;
+  let pingError;
+  try {
+    const testResult = await testCmd.run({ _: [siteId] }, ctx);
+    for (const line of testResult.lines) out.push(`  ${line}`);
+  } catch (err) {
+    pingFailed = true;
+    pingError = err;
+  }
+
+  if (pingFailed) {
+    // Spec wording (binding): "✗ OAuth test failed — reverting."
+    out.push('✗ OAuth test failed — reverting.');
+    if (pendingFallback) {
+      site.auth = {
+        method: 'apppassword',
+        username: pendingFallback.username,
+        password_ref: pendingFallback.password_ref,
+      };
+      site.auth_status = AUTH_STATUS.ACTIVE;
+      delete site.mcp_resource;
+      await writeConfig(ctx.configPath, config);
+    }
+    // Attach progress lines so the router prints "✗ OAuth test failed —
+    // reverting." on stdout alongside the stderr error from the ping.
+    throw withProgress(fromAuthError(pingError, { siteId }), out);
+  }
+
+  // Spec wording (binding):
+  //   "✓ OAuth working. App Password kept as fallback for now."
+  out.push('✓ OAuth working. App Password kept as fallback for now.');
+  out.push(`  Run: abilities-mcp upgrade-auth ${siteId} --confirm  (when ready to remove the fallback)`);
+  return { exitCode: 0, lines: out };
+}
+
+async function _confirm(siteId, site, config, ctx) {
+  if (site.auth.method !== 'oauth') {
+    throw new CliError(
+      `upgrade-auth --confirm: site "${siteId}" is not OAuth (method=${site.auth.method})`,
+      {
+        exitCode: EXIT_USAGE,
+        nextAction: `Run: abilities-mcp upgrade-auth ${siteId}  (without --confirm) first`,
+      }
+    );
+  }
+  if (!site.auth.apppassword_fallback) {
+    return {
+      exitCode: 0,
+      lines: [`Site "${siteId}" has no App Password fallback to remove. (Idempotent — nothing to do.)`],
+    };
+  }
+  // Delete the legacy keychain entry, then strip the fallback from config.
+  let legacyAccount;
+  try { legacyAccount = parseRef(site.auth.apppassword_fallback.password_ref).account; }
+  catch { legacyAccount = null; }
+  if (legacyAccount) {
+    await ctx.secretStore.delete(SECRET_SERVICE, legacyAccount).catch(() => {});
+  }
+  delete site.auth.apppassword_fallback;
+  await writeConfig(ctx.configPath, config);
+  return {
+    exitCode: 0,
+    // Spec wording (binding):
+    //   "✓ Migration complete. App Password removed. Site siteX now uses OAuth only."
+    lines: [`✓ Migration complete. App Password removed. Site ${siteId} now uses OAuth only.`],
+  };
+}
+
+module.exports = { run };

package/lib/cli/config-store.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { SCHEMA_VERSION, validate, emptyConfig } = require('../auth/schema-v2');
+const { _atomicWrite } = require('../auth/config-migration');
+const { CliError, EXIT_CONFIG } = require('./errors');
+
+/**
+ * Read / write the v2 wp-sites.json file from a CLI command.
+ *
+ * This is the only place CLI commands touch the on-disk config — keeping it
+ * here means atomic-write, validation, and pathing rules live in one spot.
+ *
+ * Search order (matches lib/config.js so the MCP server and CLI agree on
+ * which file is "the" config):
+ *   1. --config=<path> explicit
+ *   2. <repo root>/wp-sites.json (alongside the bridge bin)
+ *   3. ~/.abilities-mcp/wp-sites.json
+ *
+ * If no file exists, `resolveConfigPath` returns the canonical home-dir path
+ * so commands like `add-site` write a fresh config there.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const HOME_DIR_REL = path.join('.abilities-mcp', 'wp-sites.json');
+
+function _scriptRootConfig() {
+  // lib/cli/ → repo root
+  return path.resolve(__dirname, '..', '..', 'wp-sites.json');
+}
+
+function _homeConfig() {
+  return path.join(os.homedir(), HOME_DIR_REL);
+}
+
+/**
+ * Resolve the on-disk wp-sites.json path. Returns the first match in the
+ * search order, or the home-dir path if none exists yet.
+ *
+ * @param {object} [args]
+ * @param {string} [args.config]
+ * @returns {{ path: string, exists: boolean, source: 'explicit'|'script-root'|'home'|'home-default' }}
+ */
+function resolveConfigPath(args = {}) {
+  if (args.config) {
+    return {
+      path: path.resolve(args.config),
+      exists: fs.existsSync(args.config),
+      source: 'explicit',
+    };
+  }
+  const scriptCfg = _scriptRootConfig();
+  if (fs.existsSync(scriptCfg)) {
+    return { path: scriptCfg, exists: true, source: 'script-root' };
+  }
+  const homeCfg = _homeConfig();
+  if (fs.existsSync(homeCfg)) {
+    return { path: homeCfg, exists: true, source: 'home' };
+  }
+  return { path: homeCfg, exists: false, source: 'home-default' };
+}
+
+/**
+ * Read a v2 config file. Throws CliError on parse / validation failure.
+ *
+ * @param {string} filePath
+ * @returns {object}
+ */
+function readConfig(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new CliError(`Config not found: ${filePath}`, {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'Run: abilities-mcp add-site <url> to create your first site',
+        cause: err,
+      });
+    }
+    throw new CliError(`Cannot read ${filePath}: ${err.message}`, {
+      exitCode: EXIT_CONFIG,
+      nextAction: 'Verify file permissions on the config path',
+      cause: err,
+    });
+  }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) {
+    throw new CliError(`Cannot parse ${filePath}: ${err.message}`, {
+      exitCode: EXIT_CONFIG,
+      nextAction: 'Inspect the JSON syntax of the config file',
+      cause: err,
+    });
+  }
+  if (parsed.schema_version !== SCHEMA_VERSION) {
+    throw new CliError(
+      `Config schema is v${parsed.schema_version || '<unknown>'} but CLI expects v${SCHEMA_VERSION}`,
+      {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'Run the bridge once to trigger v1→v2 migration, or update the config manually',
+      }
+    );
+  }
+  const v = validate(parsed);
+  if (!v.ok) {
+    throw new CliError(
+      `Config failed v2 validation:\n  - ${v.errors.join('\n  - ')}`,
+      {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'Fix the listed validation errors in the config file',
+      }
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Atomically write a v2 config file. Validates before writing.
+ *
+ * @param {string} filePath
+ * @param {object} config
+ */
+async function writeConfig(filePath, config) {
+  const v = validate(config);
+  if (!v.ok) {
+    throw new CliError(
+      `Refusing to write invalid v2 config:\n  - ${v.errors.join('\n  - ')}`,
+      {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'This is a CLI bug — please report it. The on-disk config was not modified.',
+      }
+    );
+  }
+  // Ensure parent dir exists (e.g. ~/.abilities-mcp/ on first add-site).
+  const dir = path.dirname(filePath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  await _atomicWrite(filePath, config);
+}
+
+/**
+ * Build an empty v2 config skeleton. Used the first time `add-site` runs and
+ * no config exists yet.
+ * @returns {object}
+ */
+function freshConfig() {
+  return emptyConfig();
+}
+
+module.exports = {
+  resolveConfigPath,
+  readConfig,
+  writeConfig,
+  freshConfig,
+  HOME_DIR_REL,
+};

package/lib/cli/context.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const os = require('node:os');
+
+const {
+  KeychainSecretStore,
+  MemorySecretStore,
+  FreshEachTimeIdentityProvider,
+} = require('../auth');
+const { resolveConfigPath } = require('./config-store');
+
+/**
+ * CliContext — DI container the subcommands use to reach the outside world.
+ *
+ * The router builds one CliContext per invocation and hands it to the chosen
+ * command. Tests build their own context with `MemorySecretStore` and
+ * dependency-injected helpers (clock, fetch, identity provider) so they never
+ * touch real keychain or network.
+ *
+ * The context owns:
+ *   - secretStore           SecretStore instance (KeychainSecretStore by default)
+ *   - identityProvider      BridgeIdentityProvider (FreshEachTime in v1.0)
+ *   - configPath            absolute path to wp-sites.json
+ *   - debug                 boolean — when true, command errors include cause
+ *   - softwareVersion       bridge version (read from package.json)
+ *   - hostnameLabel         OS hostname, used in DCR client_name
+ *   - userLabel             username, used in DCR client_name
+ *   - now                   () => number (Date.now), test seam
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+function _readPackageVersion() {
+  try {
+    // eslint-disable-next-line global-require
+    return require('../../package.json').version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Build a real context for production CLI invocations.
+ *
+ * @param {object} args                Parsed CLI args (minimum: { config?, debug? })
+ * @returns {object} ctx
+ */
+function createContext(args = {}) {
+  const { path: configPath } = resolveConfigPath(args);
+  const secretStore = new KeychainSecretStore();
+  const identityProvider = new FreshEachTimeIdentityProvider({ store: secretStore });
+  return {
+    secretStore,
+    identityProvider,
+    configPath,
+    debug: !!args.debug,
+    allowInsecure: !!args.allowInsecure,
+    softwareVersion: _readPackageVersion(),
+    hostnameLabel: _safeHostname(),
+    userLabel: _safeUserLogin(),
+    now: () => Date.now(),
+  };
+}
+
+/**
+ * Build a test context. Uses MemorySecretStore unless caller overrides.
+ *
+ * @param {object} [overrides]
+ * @returns {object}
+ */
+function createTestContext(overrides = {}) {
+  const secretStore = overrides.secretStore || new MemorySecretStore();
+  const identityProvider = overrides.identityProvider
+    || new FreshEachTimeIdentityProvider({ store: secretStore });
+  return Object.assign({
+    secretStore,
+    identityProvider,
+    configPath: overrides.configPath || null,
+    debug: !!overrides.debug,
+    allowInsecure: overrides.allowInsecure !== false,   // tests default to true
+    softwareVersion: overrides.softwareVersion || '1.4.0-test',
+    hostnameLabel: overrides.hostnameLabel || 'host.local',
+    userLabel: overrides.userLabel || 'tester',
+    now: overrides.now || (() => Date.now()),
+  }, overrides);
+}
+
+function _safeHostname() {
+  try { return os.hostname(); } catch { return 'host.local'; }
+}
+
+function _safeUserLogin() {
+  try {
+    const u = os.userInfo();
+    return u.username || 'operator';
+  } catch {
+    return 'operator';
+  }
+}
+
+module.exports = { createContext, createTestContext };