@wickedevolutions/abilities-mcp 1.3.1 → 1.5.3

package/lib/auth/token-manager.js

@@ -0,0 +1,378 @@
+'use strict';
+
+const { postForm } = require('./http-json');
+const { resolveRef, parseRef, makeRef } = require('./secret-store');
+const { RefreshError, AuthError } = require('./errors');
+const { AUTH_STATUS } = require('./events');
+
+/**
+ * TokenManager — runs the bridge's pre-call refresh + retry policy and the
+ * OAuth-capability pin bookkeeping.
+ *
+ * Binding rules (Appendix H.2.1):
+ *   - HTTP timeout: 30s read/write.
+ *   - Retry policy: on network error or 5xx, retry up to 2 times with the
+ *     SAME refresh token. The adapter's 30s grace window honors this.
+ *   - NEVER retry on 4xx — the server has decided.
+ *   - Persist intent-to-refresh to keychain BEFORE sending the request. Mark
+ *     refresh complete only after 200 received and new tokens persisted. On
+ *     crash mid-flight, the old refresh token is still in keychain; the next
+ *     call retries with it.
+ *
+ * Refresh window:
+ *   - Refresh when access_token_expires_at is within 300 seconds (Appendix
+ *     "Token refresh" + H.4.5 clock-skew row).
+ *
+ * On auth failure (4xx from /oauth/token):
+ *   - Set auth_status to "expired".
+ *   - Surface a reauth hint via the returned Result object (callers wire
+ *     this into CLI / GUI messaging — no console output here).
+ *   - Other sites are unaffected.
+ *
+ * Capability pinning (Appendix H.2.3):
+ *   - On every successful discovery, callers should refresh
+ *     `oauth_capability_pinned.last_confirmed_at`.
+ *   - On 404 against a pinned site, throw CapabilityPinningError (handled
+ *     by discovery-client); this module exposes helpers to update the pin.
+ *
+ * The TokenManager does not perform discovery — discovery happens during
+ * add-site / reauth (oauth-client.js). The TokenManager only refreshes
+ * tokens against an already-known token endpoint.
+ *
+ * @typedef {object} TokenSet
+ * @property {string} access_token
+ * @property {string} refresh_token
+ * @property {number} expires_in                seconds
+ * @property {string} [token_type]
+ * @property {string} [scope]
+ *
+ * @typedef {object} SiteAuthState
+ * @property {string} siteId
+ * @property {string} tokenEndpoint
+ * @property {string} clientId
+ * @property {string} accessTokenRef            keychain://...
+ * @property {string} refreshTokenRef           keychain://...
+ * @property {string} accessTokenExpiresAt      ISO 8601
+ * @property {string} refreshTokenExpiresAt     ISO 8601
+ * @property {string} authStatus                'active' | 'expired' | 'revoked' | 'pending-reauth'
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const REFRESH_WINDOW_SECONDS = 300;
+const HTTP_TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 2;
+const SECRET_SERVICE = 'abilities-mcp';
+
+class TokenManager {
+  /**
+   * @param {object} args
+   * @param {object} args.secretStore                 SecretStore instance
+   * @param {object} [args.deps]
+   * @param {Function} [args.deps.postForm]
+   * @param {(ms:number)=>Promise<void>} [args.deps.sleep]
+   * @param {()=>number} [args.deps.now]              Defaults to Date.now
+   */
+  constructor(args) {
+    if (!args || !args.secretStore) {
+      throw new Error('TokenManager requires secretStore');
+    }
+    this._store = args.secretStore;
+    this._allowInsecure = !!args.allowInsecure;
+    const deps = args.deps || {};
+    this._postForm = deps.postForm || postForm;
+    this._sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this._now = deps.now || (() => Date.now());
+  }
+
+  // ---------------------------------------------------------------------
+  // Bearer token resolution
+  // ---------------------------------------------------------------------
+
+  /**
+   * Returns a usable access token for `siteAuth`, refreshing if within the
+   * refresh window or if explicitly forced.
+   *
+   * @param {SiteAuthState} siteAuth
+   * @param {object} [opts]
+   * @param {boolean} [opts.forceRefresh]
+   * @returns {Promise<{accessToken:string, refreshed:boolean, updatedAuth?:SiteAuthState, tokens?:TokenSet}>}
+   */
+  async getAccessToken(siteAuth, opts = {}) {
+    const needsRefresh = opts.forceRefresh || this._isWithinRefreshWindow(siteAuth);
+    if (!needsRefresh) {
+      const accessToken = await resolveRef(this._store, siteAuth.accessTokenRef);
+      return { accessToken, refreshed: false };
+    }
+    const refreshed = await this.refresh(siteAuth);
+    return {
+      accessToken: refreshed.tokens.access_token,
+      refreshed: true,
+      updatedAuth: refreshed.updatedAuth,
+      tokens: refreshed.tokens,
+    };
+  }
+
+  /**
+   * Returns true if the access token will expire within REFRESH_WINDOW_SECONDS.
+   * @param {SiteAuthState} siteAuth
+   */
+  _isWithinRefreshWindow(siteAuth) {
+    if (!siteAuth.accessTokenExpiresAt) return true;
+    const expiresAt = Date.parse(siteAuth.accessTokenExpiresAt);
+    if (Number.isNaN(expiresAt)) return true;
+    const msUntilExpiry = expiresAt - this._now();
+    return msUntilExpiry <= REFRESH_WINDOW_SECONDS * 1000;
+  }
+
+  // ---------------------------------------------------------------------
+  // Refresh
+  // ---------------------------------------------------------------------
+
+  /**
+   * Refresh the access token.
+   *
+   * Retry semantics now live entirely on the server (adapter v1.4.2 ships
+   * encrypt-at-rest grace-window retry per Wicked-Evolutions/abilities-mcp-adapter#61).
+   * A retry within 30 seconds of a successful rotation returns the original
+   * plaintext pair from a server-stored encrypted blob — the bridge does not
+   * need a mid-flight crash-recovery marker. We just retry on transport
+   * failures and 5xx; the server is idempotent within the grace window.
+   *
+   * @param {SiteAuthState} siteAuth
+   * @returns {Promise<{tokens: TokenSet, updatedAuth: SiteAuthState}>}
+   */
+  async refresh(siteAuth) {
+    if (siteAuth.authStatus === AUTH_STATUS.EXPIRED) {
+      throw new RefreshError(
+        `Refresh token expired for site "${siteAuth.siteId}". ` +
+        `Run: abilities-mcp reauth ${siteAuth.siteId}`,
+        { code: 'reauth_required', state: 'refreshing' }
+      );
+    }
+    if (siteAuth.authStatus === AUTH_STATUS.REVOKED) {
+      throw new RefreshError(
+        `Refresh token revoked for site "${siteAuth.siteId}".`,
+        { code: 'revoked', state: 'refreshing' }
+      );
+    }
+
+    if (!siteAuth.refreshTokenRef) {
+      throw new RefreshError('No refresh token configured for site', {
+        code: 'no_refresh_token', state: 'refreshing',
+      });
+    }
+    const refreshToken = await resolveRef(this._store, siteAuth.refreshTokenRef);
+
+    let res;
+    let attempt = 0;
+    let lastNetworkError = null;
+    /* eslint-disable no-constant-condition */
+    while (true) {
+      try {
+        res = await this._postForm(siteAuth.tokenEndpoint, {
+          grant_type: 'refresh_token',
+          refresh_token: refreshToken,
+          client_id: siteAuth.clientId,
+        }, { timeoutMs: HTTP_TIMEOUT_MS, allowInsecure: this._allowInsecure });
+      } catch (err) {
+        // Network error path.
+        lastNetworkError = err;
+        if (attempt < MAX_RETRIES) {
+          attempt++;
+          await this._sleep(this._backoffMs(attempt));
+          continue;
+        }
+        throw new RefreshError(
+          `Refresh failed after ${MAX_RETRIES + 1} network-error attempts: ${err.message}`,
+          { code: 'network_error', state: 'refreshing', cause: err }
+        );
+      }
+      // 5xx → retry with same refresh token.
+      if (res.statusCode >= 500 && res.statusCode <= 599) {
+        if (attempt < MAX_RETRIES) {
+          attempt++;
+          await this._sleep(this._backoffMs(attempt));
+          continue;
+        }
+        throw new RefreshError(
+          `Refresh failed after ${MAX_RETRIES + 1} attempts (last status ${res.statusCode})`,
+          { code: 'server_error', state: 'refreshing', cause: { statusCode: res.statusCode, body: res.body } }
+        );
+      }
+      // 4xx → never retry.
+      if (res.statusCode >= 400 && res.statusCode <= 499) {
+        const oauthError = res.json && res.json.error ? res.json.error : 'invalid_grant';
+        const description = res.json && res.json.error_description;
+        // Mark the site as expired so the caller can route the operator to reauth.
+        const updatedAuth = { ...siteAuth, authStatus: AUTH_STATUS.EXPIRED };
+        const err = new RefreshError(
+          `Refresh rejected (${oauthError}${description ? ': ' + description : ''}). ` +
+          `Run: abilities-mcp reauth ${siteAuth.siteId}`,
+          {
+            code: oauthError,
+            state: 'refreshing',
+            cause: { statusCode: res.statusCode, body: res.body },
+          }
+        );
+        err.updatedAuth = updatedAuth;
+        err.reauthHint = { siteId: siteAuth.siteId, command: `abilities-mcp reauth ${siteAuth.siteId}` };
+        throw err;
+      }
+      // 2xx
+      break;
+    }
+
+    if (!res.json || typeof res.json.access_token !== 'string') {
+      throw new RefreshError('Token endpoint returned 2xx without access_token', {
+        code: 'malformed_response', state: 'refreshing',
+        cause: { body: res.body },
+      });
+    }
+
+    // Success — persist new tokens.
+    const tokens = res.json;
+    const accessAccount = parseRef(siteAuth.accessTokenRef).account;
+    await this._store.set(SECRET_SERVICE, accessAccount, tokens.access_token);
+
+    let refreshAccount = parseRef(siteAuth.refreshTokenRef).account;
+    let refreshTokenRef = siteAuth.refreshTokenRef;
+    if (typeof tokens.refresh_token === 'string' && tokens.refresh_token !== refreshToken) {
+      // Rotation — write the new refresh token under the same account.
+      await this._store.set(SECRET_SERVICE, refreshAccount, tokens.refresh_token);
+      refreshTokenRef = makeRef(SECRET_SERVICE, refreshAccount);
+    }
+
+    const expiresInSec = typeof tokens.expires_in === 'number' ? tokens.expires_in : null;
+    const updatedAuth = {
+      ...siteAuth,
+      accessTokenRef: makeRef(SECRET_SERVICE, accessAccount),
+      refreshTokenRef,
+      accessTokenExpiresAt: expiresInSec
+        ? new Date(this._now() + expiresInSec * 1000).toISOString()
+        : siteAuth.accessTokenExpiresAt,
+      authStatus: AUTH_STATUS.ACTIVE,
+    };
+
+    return { tokens, updatedAuth };
+  }
+
+  _backoffMs(attempt) {
+    // Modest backoff so the second retry stays inside the adapter's 30s
+    // grace window (H.2.1). 500ms then 1500ms.
+    return attempt === 1 ? 500 : 1500;
+  }
+
+  // ---------------------------------------------------------------------
+  // Persist new token set (used after add-site / reauth completes)
+  // ---------------------------------------------------------------------
+
+  /**
+   * Store a freshly-issued token set in the secret store and return refs +
+   * computed expiry timestamps suitable for writing into wp-sites.json v2.
+   *
+   * @param {object} args
+   * @param {string} args.siteId
+   * @param {TokenSet} args.tokens
+   * @returns {Promise<{
+   *   accessTokenRef:string, refreshTokenRef:string,
+   *   accessTokenExpiresAt:string, refreshTokenExpiresAt:string,
+   * }>}
+   */
+  async persistTokens(args) {
+    if (!args || !args.siteId || !args.tokens) {
+      throw new Error('persistTokens requires { siteId, tokens }');
+    }
+    const { siteId, tokens } = args;
+    if (typeof tokens.access_token !== 'string') {
+      throw new Error('tokens.access_token is required');
+    }
+
+    const accessAccount = `${siteId}/access`;
+    const refreshAccount = `${siteId}/refresh`;
+    await this._store.set(SECRET_SERVICE, accessAccount, tokens.access_token);
+
+    let refreshTokenRef = null;
+    if (typeof tokens.refresh_token === 'string') {
+      await this._store.set(SECRET_SERVICE, refreshAccount, tokens.refresh_token);
+      refreshTokenRef = makeRef(SECRET_SERVICE, refreshAccount);
+    }
+
+    const nowMs = this._now();
+    const accessSec = typeof tokens.expires_in === 'number' ? tokens.expires_in : 24 * 3600;
+    // Refresh expiry is not part of the standard token response. Fall back to
+    // 90 days (the adapter's default per design doc decision #5).
+    const refreshSec = typeof tokens.refresh_expires_in === 'number'
+      ? tokens.refresh_expires_in
+      : 90 * 24 * 3600;
+
+    return {
+      accessTokenRef: makeRef(SECRET_SERVICE, accessAccount),
+      refreshTokenRef,
+      accessTokenExpiresAt: new Date(nowMs + accessSec * 1000).toISOString(),
+      refreshTokenExpiresAt: new Date(nowMs + refreshSec * 1000).toISOString(),
+    };
+  }
+
+  // ---------------------------------------------------------------------
+  // Capability pinning helpers (H.2.3)
+  // ---------------------------------------------------------------------
+
+  /**
+   * Build the pin object to write under `oauth_capability_pinned`.
+   * @param {object} [existing]                Existing pin (for refresh)
+   * @returns {{firstSeenAt:string, lastConfirmedAt:string}}
+   */
+  buildPin(existing) {
+    const now = new Date(this._now()).toISOString();
+    if (existing && existing.firstSeenAt) {
+      return { firstSeenAt: existing.firstSeenAt, lastConfirmedAt: now };
+    }
+    return { firstSeenAt: now, lastConfirmedAt: now };
+  }
+
+  // ---------------------------------------------------------------------
+  // Revocation
+  // ---------------------------------------------------------------------
+
+  /**
+   * Server-side revocation (RFC 7009) of a token. Network/5xx errors raise.
+   * 4xx other than `unsupported_token_type` are treated as success — the
+   * server has a final say.
+   * @param {object} args
+   * @param {string} args.revocationEndpoint
+   * @param {string} args.token
+   * @param {string} args.clientId
+   * @param {string} [args.tokenTypeHint]
+   */
+  async revoke(args) {
+    if (!args || !args.revocationEndpoint) {
+      throw new AuthError('revoke requires revocationEndpoint', { code: 'missing_endpoint' });
+    }
+    const params = {
+      token: args.token,
+      client_id: args.clientId,
+    };
+    if (args.tokenTypeHint) params.token_type_hint = args.tokenTypeHint;
+    const res = await this._postForm(args.revocationEndpoint, params, {
+      timeoutMs: HTTP_TIMEOUT_MS,
+      allowInsecure: this._allowInsecure,
+    });
+    if (res.statusCode >= 500) {
+      throw new AuthError(`Revocation failed with ${res.statusCode}`, {
+        code: 'revocation_failed',
+        cause: { statusCode: res.statusCode, body: res.body },
+      });
+    }
+    return { statusCode: res.statusCode };
+  }
+}
+
+module.exports = {
+  TokenManager,
+  REFRESH_WINDOW_SECONDS,
+  HTTP_TIMEOUT_MS,
+  MAX_RETRIES,
+  SECRET_SERVICE,
+};

package/lib/cli/commands/add-site.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const { URL } = require('node:url');
+
+const {
+  OAuthClient,
+  TokenManager,
+  AUTH_STATUS,
+  DEFAULT_SCOPE,
+} = require('../../auth');
+const { makeRef } = require('../../auth/secret-store');
+const { CliError, EXIT_USAGE, EXIT_CONFIG, fromAuthError } = require('../errors');
+const { subscribeProgress } = require('../output');
+const { readConfig, writeConfig, freshConfig } = require('../config-store');
+
+/**
+ * `add-site <url>` — register a new site with the bridge using OAuth (default)
+ * or App Password (`--apppassword`).
+ *
+ * 1:1 mapping:
+ *   - OAuth path  → new OAuthClient(...).run() → TokenManager.persistTokens(...)
+ *   - apppassword → ctx.secretStore.set(<service>, <siteId>/apppassword, <pw>)
+ *
+ * Spec references:
+ *   - "CLI surface" main spec section
+ *   - I.5 (default scope, --scope override)
+ *   - I.6 (config schema v1 source — handled in migration, not here)
+ *   - F.5 (v2 site shape)
+ *
+ * Site-id derivation (CLI gap-fill — not in spec): hostname with the leading
+ * www. stripped and the TLD removed. Operators can override with --site-id=ID.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const SECRET_SERVICE = 'abilities-mcp';
+
+function deriveSiteId(siteUrl) {
+  let host;
+  try { host = new URL(siteUrl).hostname; }
+  catch { return null; }
+  const trimmed = host.replace(/^www\./, '');
+  const dot = trimmed.indexOf('.');
+  return dot > 0 ? trimmed.slice(0, dot) : trimmed;
+}
+
+/**
+ * @param {object} args
+ * @param {string[]} args._                positional args (first should be URL)
+ * @param {boolean} [args.apppassword]
+ * @param {string}  [args.username]        for --apppassword
+ * @param {string}  [args.password]        for --apppassword
+ * @param {string}  [args.scope]
+ * @param {string}  [args['site-id']]
+ * @param {boolean} [args.force]           overwrite existing site of same id
+ * @param {object} ctx
+ * @returns {Promise<{exitCode:number, lines:string[]}>}
+ */
+async function run(args, ctx) {
+  const url = args._ && args._[0];
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new CliError('add-site requires a site URL argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp add-site <url> [--apppassword]',
+    });
+  }
+  let parsedUrl;
+  try { parsedUrl = new URL(url); }
+  catch (err) {
+    throw new CliError(`add-site: invalid URL: ${url}`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Provide a full https://... URL',
+      cause: err,
+    });
+  }
+  if (parsedUrl.protocol !== 'https:' && !ctx.allowInsecure) {
+    throw new CliError(`add-site: HTTPS required (got ${parsedUrl.protocol})`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Provide an https:// URL or pass --allow-insecure for localhost dev',
+    });
+  }
+
+  const explicitId = args['site-id'];
+  const siteId = explicitId || deriveSiteId(url);
+  if (!siteId) {
+    throw new CliError('add-site: cannot derive a site_id from the URL', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Pass --site-id=<id> explicitly',
+    });
+  }
+
+  // Load (or create) the config and check for collisions.
+  let config;
+  try { config = readConfig(ctx.configPath); }
+  catch (err) {
+    if (err instanceof CliError && err.exitCode === EXIT_CONFIG && /not found/i.test(err.message)) {
+      config = freshConfig();
+    } else {
+      throw err;
+    }
+  }
+  if (config.sites[siteId] && !args.force) {
+    throw new CliError(`add-site: site_id "${siteId}" already exists in ${ctx.configPath}`, {
+      exitCode: EXIT_USAGE,
+      nextAction: `Run: abilities-mcp reauth ${siteId} (or pass --force / --site-id=<other> to overwrite)`,
+    });
+  }
+
+  const out = [];
+  let exitCode = 0;
+
+  if (args.apppassword) {
+    if (!args.username) {
+      throw new CliError('add-site --apppassword requires --username=<wp_user>', {
+        exitCode: EXIT_USAGE,
+        nextAction: 'Run: abilities-mcp add-site <url> --apppassword --username=<u> --password=<p>',
+      });
+    }
+    if (!args.password) {
+      throw new CliError('add-site --apppassword requires --password=<application_password>', {
+        exitCode: EXIT_USAGE,
+        nextAction: 'Generate an Application Password in WP admin → Users → Profile and pass it via --password',
+      });
+    }
+    const account = `${siteId}/apppassword`;
+    await ctx.secretStore.set(SECRET_SERVICE, account, args.password);
+    config.sites[siteId] = {
+      url: parsedUrl.origin,
+      label: args.label || parsedUrl.hostname,
+      auth: {
+        method: 'apppassword',
+        username: args.username,
+        password_ref: makeRef(SECRET_SERVICE, account),
+      },
+      auth_status: AUTH_STATUS.ACTIVE,
+    };
+    if (!config.defaultSite) config.defaultSite = siteId;
+    await writeConfig(ctx.configPath, config);
+    out.push(`✓ Site "${siteId}" configured with App Password authentication.`);
+    out.push(`  Config: ${ctx.configPath}`);
+    return { exitCode, lines: out };
+  }
+
+  // OAuth path — full authorization-code + PKCE flow via OAuthClient.
+  const clientName = `${ctx.userLabel}'s Operator (${ctx.hostnameLabel})`;
+  const oauth = (ctx.deps && ctx.deps.OAuthClient)
+    ? new ctx.deps.OAuthClient({
+        siteUrl: parsedUrl.origin,
+        clientName,
+        softwareVersion: ctx.softwareVersion,
+        scope: args.scope || DEFAULT_SCOPE,
+        identityProvider: ctx.identityProvider,
+        allowInsecure: ctx.allowInsecure,
+        deps: ctx.deps && ctx.deps.oauthClientDeps,
+      })
+    : new OAuthClient({
+        siteUrl: parsedUrl.origin,
+        clientName,
+        softwareVersion: ctx.softwareVersion,
+        scope: args.scope || DEFAULT_SCOPE,
+        identityProvider: ctx.identityProvider,
+        allowInsecure: ctx.allowInsecure,
+        deps: ctx.deps && ctx.deps.oauthClientDeps,
+      });
+
+  out.push(`Adding site "${siteId}" (${parsedUrl.origin}) via OAuth…`);
+  subscribeProgress(oauth, out);
+
+  let result;
+  try { result = await oauth.run(); }
+  catch (err) { throw fromAuthError(err, { siteId }); }
+
+  // Persist tokens to keychain via TokenManager, then write the v2 site.
+  const tm = new TokenManager({ secretStore: ctx.secretStore, allowInsecure: ctx.allowInsecure });
+  const persisted = await tm.persistTokens({ siteId, tokens: result.tokens });
+
+  config.sites[siteId] = {
+    url: parsedUrl.origin,
+    label: args.label || parsedUrl.hostname,
+    auth: {
+      method: 'oauth',
+      client_id: result.clientId,
+      user_login: _userLoginFromTokens(result, ctx),
+      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,
+    },
+    auth_status: AUTH_STATUS.ACTIVE,
+    oauth_capability_pinned: {
+      first_seen_at: result.capabilityPin.firstSeenAt,
+      last_confirmed_at: result.capabilityPin.lastConfirmedAt,
+    },
+  };
+  // Adapter-derived MCP endpoint for runtime HTTP calls. Stored alongside
+  // OAuth state so the existing transport layer keeps working.
+  if (result.prMetadata && result.prMetadata.resource) {
+    config.sites[siteId].mcp_resource = result.prMetadata.resource;
+  }
+  if (!config.defaultSite) config.defaultSite = siteId;
+  await writeConfig(ctx.configPath, config);
+
+  out.push(`✓ Site "${siteId}" configured. Granted scopes: ${result.scopes.join(', ')}.`);
+  out.push(`  Config: ${ctx.configPath}`);
+  return { exitCode, lines: out };
+}
+
+/**
+ * Best-effort user_login extraction. The token endpoint may include the
+ * username in a non-standard claim; if absent we fall back to the OS user as
+ * a placeholder operators can edit. The runtime does not depend on this
+ * value — it is display-only per F.5.
+ */
+function _userLoginFromTokens(result, ctx) {
+  if (result.tokens && typeof result.tokens.user_login === 'string') {
+    return result.tokens.user_login;
+  }
+  if (result.tokens && typeof result.tokens.username === 'string') {
+    return result.tokens.username;
+  }
+  return ctx.userLabel || 'operator';
+}
+
+module.exports = { run, deriveSiteId };

package/lib/cli/commands/force-downgrade.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { CliError, EXIT_USAGE } = require('../errors');
+const { readConfig, writeConfig } = require('../config-store');
+
+/**
+ * `force-downgrade <site_id> --i-understand-the-risk` — override OAuth
+ * capability pinning (Appendix H.2.3).
+ *
+ * H.2.3 states force-downgrade is "a deliberate, audit-logged action" and that
+ * the action is "surfaced in `list-sites` output for the next 30 days." The
+ * spec leaves the audit-log schema to the implementer.
+ *
+ * Phase 5 design choice: store the audit record on the site itself rather
+ * than in a separate log file. The record has three fields:
+ *   force_downgrade.at           ISO 8601, when the operator ran the command
+ *   force_downgrade.expires_at   at + 30 days (ISO)
+ *   force_downgrade.reason       free-form string from --reason=<...>
+ *
+ * `list-sites` reads `force_downgrade.expires_at` and surfaces an annotation
+ * line under the affected site row until expiry. A separate log file would
+ * be redundant — the site config already lives in version-control-friendly
+ * JSON, which is the most accessible audit surface on a developer's laptop.
+ *
+ * Effect on runtime: clears `oauth_capability_pinned` so subsequent discovery
+ * misses no longer raise `CapabilityPinningError`. The site config keeps its
+ * OAuth `auth.method` so the operator can return to OAuth simply by running
+ * `add-site` or `reauth` (which re-pin on success).
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const AUDIT_RETENTION_DAYS = 30;
+
+async function run(args, ctx) {
+  const siteId = args._ && args._[0];
+  if (!siteId) {
+    throw new CliError('force-downgrade requires a site_id argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp force-downgrade <site_id> --i-understand-the-risk',
+    });
+  }
+  if (!args['i-understand-the-risk']) {
+    throw new CliError(
+      'force-downgrade requires --i-understand-the-risk (Appendix H.2.3 — deliberate override)',
+      {
+        exitCode: EXIT_USAGE,
+        nextAction: 'Re-run with --i-understand-the-risk if you have verified the site genuinely no longer supports OAuth',
+      }
+    );
+  }
+  const config = readConfig(ctx.configPath);
+  const site = config.sites[siteId];
+  if (!site) {
+    throw new CliError(`force-downgrade: unknown site_id "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp list-sites to see configured sites',
+    });
+  }
+  if (!site.oauth_capability_pinned) {
+    return {
+      exitCode: 0,
+      lines: [
+        `Site "${siteId}" is not OAuth-pinned — nothing to override.`,
+        `(Idempotent — no audit record written.)`,
+      ],
+    };
+  }
+
+  const nowMs = ctx.now ? ctx.now() : Date.now();
+  const at = new Date(nowMs).toISOString();
+  const expiresAt = new Date(nowMs + AUDIT_RETENTION_DAYS * 24 * 3600 * 1000).toISOString();
+  const reason = typeof args.reason === 'string' && args.reason.length > 0
+    ? args.reason
+    : 'no reason given';
+
+  delete site.oauth_capability_pinned;
+  site.force_downgrade = { at, expires_at: expiresAt, reason };
+  await writeConfig(ctx.configPath, config);
+
+  return {
+    exitCode: 0,
+    lines: [
+      `⚠ force-downgrade recorded for site "${siteId}".`,
+      `  Reason: ${reason}`,
+      `  Audit record expires: ${expiresAt} (visible in list-sites for ${AUDIT_RETENTION_DAYS} days).`,
+      `  OAuth capability pin cleared — silent App Password fallback is now allowed for this site.`,
+    ],
+  };
+}
+
+module.exports = { run, AUDIT_RETENTION_DAYS };