@wickedevolutions/abilities-mcp 1.3.1 → 1.5.3

package/lib/auth/index.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Public surface for `lib/auth/`.
+ *
+ * Every export here maps 1:1 to a future CLI subcommand or is a building
+ * block consumed by the state machine. The module is callable from any
+ * consumer (CLI today, GUI tomorrow). It contains zero CLI dependencies —
+ * no console.log, no process.exit, no readline.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const events = require('./events');
+const errors = require('./errors');
+const secretStore = require('./secret-store');
+const { MemorySecretStore } = require('./memory-secret-store');
+const { KeychainSecretStore } = require('./keychain-secret-store');
+const bridgeIdentity = require('./bridge-identity-provider');
+const { FreshEachTimeIdentityProvider } = require('./fresh-each-time-identity');
+const pkce = require('./pkce');
+const discoveryClient = require('./discovery-client');
+const dcrClient = require('./dcr-client');
+const { LoopbackServer, PORT_MIN, PORT_MAX } = require('./loopback-server');
+const { openBrowser } = require('./browser-launcher');
+const { OAuthClient, DEFAULT_SCOPE } = require('./oauth-client');
+const { TokenManager, REFRESH_WINDOW_SECONDS, HTTP_TIMEOUT_MS, MAX_RETRIES } = require('./token-manager');
+const schemaV2 = require('./schema-v2');
+const configMigration = require('./config-migration');
+
+module.exports = {
+  // Constants and enums
+  STATES: events.STATES,
+  TERMINAL_STATES: events.TERMINAL_STATES,
+  AUTH_STATUS: events.AUTH_STATUS,
+  EVENTS: events.EVENTS,
+  DEFAULT_SCOPE,
+  REFRESH_WINDOW_SECONDS,
+  HTTP_TIMEOUT_MS,
+  MAX_RETRIES,
+  PORT_MIN,
+  PORT_MAX,
+  IDENTITY_BUNDLE_VERSION: bridgeIdentity.IDENTITY_BUNDLE_VERSION,
+  SCHEMA_VERSION: schemaV2.SCHEMA_VERSION,
+  AUTH_METHODS: schemaV2.AUTH_METHODS,
+  VALID_AUTH_STATUS: schemaV2.VALID_AUTH_STATUS,
+
+  // Errors
+  AuthError: errors.AuthError,
+  DiscoveryError: errors.DiscoveryError,
+  CapabilityPinningError: errors.CapabilityPinningError,
+  RegistrationError: errors.RegistrationError,
+  TokenExchangeError: errors.TokenExchangeError,
+  StateMismatchError: errors.StateMismatchError,
+  UserDeniedError: errors.UserDeniedError,
+  RefreshError: errors.RefreshError,
+  SecretStoreError: errors.SecretStoreError,
+  MigrationError: errors.MigrationError,
+
+  // Secret store
+  SecretStore: {
+    KEYCHAIN_REF_SCHEME: secretStore.KEYCHAIN_REF_SCHEME,
+    makeRef: secretStore.makeRef,
+    parseRef: secretStore.parseRef,
+    resolveRef: secretStore.resolveRef,
+  },
+  MemorySecretStore,
+  KeychainSecretStore,
+
+  // Identity
+  FreshEachTimeIdentityProvider,
+
+  // Primitives
+  pkce,
+  discoveryClient,
+  dcrClient,
+  LoopbackServer,
+  openBrowser,
+
+  // Orchestration
+  OAuthClient,
+  TokenManager,
+
+  // Config schema
+  schemaV2,
+  configMigration,
+};

package/lib/auth/keychain-secret-store.js

@@ -0,0 +1,265 @@
+'use strict';
+
+const { execFile } = require('node:child_process');
+
+const { SecretStoreError } = require('./errors');
+
+/**
+ * KeychainSecretStore — keytar-backed SecretStore with a darwin-only
+ * `security` CLI fallback for Claude Desktop's hardened-runtime barrier.
+ *
+ * keytar wraps macOS Keychain, Windows Credential Manager, and Linux libsecret
+ * via a native binding (`build/Release/keytar.node`). It is declared as an
+ * `optionalDependency` so a failed native build does not break `npm install`
+ * for env-var-only operators.
+ *
+ * **The darwin fallback (issue #39).** When the bundled keytar binary fails
+ * to dlopen inside Claude Desktop's hardened-runtime process — the macOS
+ * code-signing rejects native binaries with mismatched Team IDs, Anthropic-
+ * signed Claude Desktop refuses to load npm-distribution-signed keytar.node —
+ * we fall back to shelling out to the macOS `security` CLI via
+ * `child_process.execFile`. `security` is always installed on macOS, doesn't
+ * require dynamic native loading, operates against the same macOS Keychain,
+ * and runs as a child process out from under Claude Desktop's hardened-
+ * runtime restrictions. The fallback fires only on darwin; on linux/win32 a
+ * keytar load failure still throws `keytar_unavailable` (current behavior).
+ *
+ * Outside the .mcpb path — system Node, CLI install, npx, source clone —
+ * keytar loads normally and the fallback never engages.
+ *
+ * If keytar is unavailable at runtime AND the darwin fallback also can't run,
+ * every method throws `SecretStoreError` with code `keytar_unavailable` —
+ * callers can detect that and fall back to a different store (e.g.
+ * MemorySecretStore for tests, or surface to the user).
+ *
+ * Implements the SecretStore interface defined in `secret-store.js`.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+class KeychainSecretStore {
+  /**
+   * @param {object} [opts]
+   * @param {object} [opts.keytar]         Inject a keytar module — primarily for tests.
+   *                                       When omitted, keytar is required lazily on
+   *                                       first use.
+   * @param {Function} [opts.requireKeytar] Override the require call used to load
+   *                                       keytar. Test seam: pass a function that
+   *                                       throws to simulate the .mcpb-path dlopen
+   *                                       rejection without breaking the real
+   *                                       require('keytar') in the test runtime.
+   * @param {string} [opts.platform]       Override `process.platform` for the
+   *                                       fallback-eligibility decision. Test seam.
+   * @param {Function} [opts.exec]         Override `child_process.execFile`. Test
+   *                                       seam for the security-CLI fallback path.
+   */
+  constructor(opts = {}) {
+    this._injected = opts.keytar || null;
+    this._keytar = null;
+    this._loadAttempted = false;
+    this._loadError = null;
+    this._fallbackMode = null; // null | 'security-cli'
+
+    this._requireKeytar = opts.requireKeytar || ((id) => require(id));
+    this._platform = opts.platform || process.platform;
+    this._exec = opts.exec || execFile;
+  }
+
+  /**
+   * Lazy load. Sets one of three terminal states:
+   *  - `this._keytar` populated (keytar loaded normally; primary path)
+   *  - `this._fallbackMode === 'security-cli'` (darwin fallback engaged)
+   *  - `this._loadError` set + throws (non-darwin keytar failure)
+   */
+  _load() {
+    if (this._keytar || this._fallbackMode) {
+      return;
+    }
+    if (this._loadAttempted) {
+      // Previously failed and we cached the error.
+      throw new SecretStoreError(
+        `OS keychain unavailable: ${this._loadError.message}`,
+        { code: 'keytar_unavailable', cause: this._loadError }
+      );
+    }
+    this._loadAttempted = true;
+
+    if (this._injected) {
+      this._keytar = this._injected;
+      return;
+    }
+
+    try {
+      this._keytar = this._requireKeytar('keytar');
+      return;
+    } catch (err) {
+      // darwin: Claude Desktop's hardened-runtime rejects bundled keytar.node
+      // with a Team ID mismatch (issue #39). Fall back to the `security` CLI
+      // rather than throwing — the bridge keeps working against the same
+      // macOS Keychain, just via shell-out.
+      if (this._platform === 'darwin') {
+        this._fallbackMode = 'security-cli';
+        return;
+      }
+      this._loadError = err;
+      throw new SecretStoreError(
+        `OS keychain unavailable: ${err.message}`,
+        { code: 'keytar_unavailable', cause: err }
+      );
+    }
+  }
+
+  /**
+   * @returns {Promise<boolean>} true if keytar can be loaded on this host OR
+   *                             the darwin security-CLI fallback is engaged.
+   */
+  async isAvailable() {
+    try {
+      this._load();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async get(service, account) {
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      return this._securityGet(service, account);
+    }
+    return this._keytar.getPassword(service, account);
+  }
+
+  async set(service, account, secret) {
+    if (typeof secret !== 'string') {
+      throw new TypeError('SecretStore.set: secret must be a string');
+    }
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      return this._securitySet(service, account, secret);
+    }
+    await this._keytar.setPassword(service, account, secret);
+  }
+
+  async delete(service, account) {
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      return this._securityDelete(service, account);
+    }
+    return this._keytar.deletePassword(service, account);
+  }
+
+  async findAll(service) {
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      // The macOS `security` CLI has no clean enumerate-by-service mode.
+      // Returning [] here is safe because the bridge runtime path never
+      // calls findAll — only the CLI subcommand `list-sites` does, and that
+      // runs in system Node where keytar loads normally and this branch
+      // is never taken. Documented in the issue body's "findAll" note.
+      return [];
+    }
+    return this._keytar.findCredentials(service);
+  }
+
+  // ---------------------------------------------------------------------
+  // darwin `security` CLI fallback — internal helpers.
+  // ---------------------------------------------------------------------
+
+  /**
+   * Run the `security` CLI with the given args. Returns { stdout, stderr }
+   * on success, rejects with an error carrying `.stderr` / `.stdout` /
+   * `.code` (exit code) on failure. Uses `execFile` (not `exec`) so args
+   * are not shell-interpreted — the password / account / service strings
+   * pass through verbatim, no shell injection surface.
+   */
+  _execSecurity(args) {
+    return new Promise((resolve, reject) => {
+      this._exec('security', args, {}, (err, stdout, stderr) => {
+        const stdoutStr = typeof stdout === 'string'
+          ? stdout
+          : (stdout ? stdout.toString() : '');
+        const stderrStr = typeof stderr === 'string'
+          ? stderr
+          : (stderr ? stderr.toString() : '');
+        if (err) {
+          // Real child_process.execFile populates err.stderr / err.stdout
+          // and ALSO passes them as cb args. Preserve whichever the caller
+          // already attached (some test doubles attach to the err object
+          // and don't pass via cb args); fall back to the cb args otherwise.
+          if (typeof err.stderr !== 'string') err.stderr = stderrStr;
+          if (typeof err.stdout !== 'string') err.stdout = stdoutStr;
+          return reject(err);
+        }
+        resolve({ stdout: stdoutStr, stderr: stderrStr });
+      });
+    });
+  }
+
+  async _securityGet(service, account) {
+    try {
+      const { stdout } = await this._execSecurity([
+        'find-generic-password', '-s', service, '-a', account, '-w',
+      ]);
+      // -w prints just the password to stdout, terminated by a newline.
+      return stdout.replace(/\n$/, '');
+    } catch (err) {
+      if (_isNotFound(err)) return null;
+      throw new SecretStoreError(
+        `security find-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
+        { code: 'security_cli_failed', cause: err }
+      );
+    }
+  }
+
+  async _securitySet(service, account, secret) {
+    // -U updates the existing entry if present, adds it otherwise.
+    // Note: passing the password as the last argv element is the standard
+    // pattern for non-interactive `security` use; the macOS `security` CLI
+    // exposes no stdin-only password input mode for non-interactive callers.
+    // This is the same trade-off keytar's own native binding makes — the
+    // password lives in process memory until the syscall completes.
+    try {
+      await this._execSecurity([
+        'add-generic-password', '-U', '-s', service, '-a', account, '-w', secret,
+      ]);
+    } catch (err) {
+      throw new SecretStoreError(
+        `security add-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
+        { code: 'security_cli_failed', cause: err }
+      );
+    }
+  }
+
+  async _securityDelete(service, account) {
+    try {
+      await this._execSecurity([
+        'delete-generic-password', '-s', service, '-a', account,
+      ]);
+      return true;
+    } catch (err) {
+      if (_isNotFound(err)) return false;
+      throw new SecretStoreError(
+        `security delete-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
+        { code: 'security_cli_failed', cause: err }
+      );
+    }
+  }
+}
+
+/**
+ * Detect the macOS `security` CLI's "entry not found" condition. Stderr from
+ * `find-generic-password` / `delete-generic-password` against a missing entry
+ * looks like:
+ *   security: SecKeychainSearchCopyNext: The specified item could not be
+ *   found in the keychain.
+ * Match on the substring "could not be found" (case-insensitive) to map it
+ * to keytar's null/false return semantics.
+ */
+function _isNotFound(err) {
+  const stderr = (err && err.stderr) || '';
+  return /could not be found/i.test(stderr);
+}
+
+module.exports = { KeychainSecretStore };

package/lib/auth/loopback-server.js

@@ -0,0 +1,249 @@
+'use strict';
+
+const http = require('node:http');
+const { randomInt } = require('node:crypto');
+const { URL } = require('node:url');
+
+const { safeStateEquals } = require('./pkce');
+const { StateMismatchError, UserDeniedError, AuthError } = require('./errors');
+
+/**
+ * Loopback callback server for the OAuth authorization-code flow.
+ *
+ * Per Appendix H.4.5 (binding):
+ *   - Bind on 127.0.0.1, random high port in [49152, 65535].
+ *   - SO_REUSEADDR=false. In Node, that maps to `listen({ exclusive: true })`
+ *     — the server will not be shared with other workers and will fail with
+ *     EADDRINUSE if the port is already bound.
+ *   - State token validates the callback (H.3.5: timingSafeEqual on equal
+ *     length, mismatch → reject without exchanging code).
+ *
+ * Public API:
+ *   const server = new LoopbackServer({ expectedState });
+ *   const { port, redirectUri } = await server.start();
+ *   // → operator browser flow happens
+ *   const callback = await server.waitForCallback({ timeoutMs });
+ *   // callback = { code, state } | throws StateMismatchError | UserDeniedError | AuthError
+ *   await server.stop();
+ *
+ * The server responds to the browser with a small HTML success or error page
+ * depending on the outcome. The callback Promise resolves AFTER the response
+ * is flushed so the operator's browser shows the page even if the caller
+ * stops the server immediately.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const PORT_MIN = 49_152;
+const PORT_MAX = 65_535;
+const DEFAULT_TIMEOUT_MS = 5 * 60_000; // 5 min for operator to complete browser flow
+const DEFAULT_BIND_RETRIES = 5;
+
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Authorization complete</title>
+<style>body{font:16px/1.5 -apple-system,system-ui,sans-serif;max-width:36rem;margin:6rem auto;padding:0 1.5rem;color:#111}h1{margin:0 0 1rem}p{margin:.25rem 0}</style>
+</head><body><h1>Authorization complete</h1>
+<p>You can close this tab and return to your terminal.</p></body></html>`;
+
+const DENIED_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Authorization denied</title>
+<style>body{font:16px/1.5 -apple-system,system-ui,sans-serif;max-width:36rem;margin:6rem auto;padding:0 1.5rem;color:#111}h1{margin:0 0 1rem;color:#a00}p{margin:.25rem 0}</style>
+</head><body><h1>Authorization denied</h1>
+<p>The site reported that authorization was denied. You can close this tab.</p></body></html>`;
+
+const ERROR_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Authorization error</title>
+<style>body{font:16px/1.5 -apple-system,system-ui,sans-serif;max-width:36rem;margin:6rem auto;padding:0 1.5rem;color:#111}h1{margin:0 0 1rem;color:#a00}p{margin:.25rem 0}</style>
+</head><body><h1>Authorization error</h1>
+<p>An unexpected response was received. Check your terminal for details.</p></body></html>`;
+
+class LoopbackServer {
+  /**
+   * @param {object} args
+   * @param {string} args.expectedState           Bridge-generated state token
+   * @param {string} [args.callbackPath]          Defaults to '/callback'
+   * @param {number} [args.bindRetries]
+   * @param {(min:number,max:number)=>number} [args.portFn] Test seam.
+   */
+  constructor(args) {
+    if (!args || typeof args.expectedState !== 'string' || args.expectedState.length === 0) {
+      throw new Error('LoopbackServer requires expectedState');
+    }
+    this._expectedState = args.expectedState;
+    this._callbackPath = args.callbackPath || '/callback';
+    this._bindRetries = args.bindRetries ?? DEFAULT_BIND_RETRIES;
+    this._portFn = args.portFn || (() => randomInt(PORT_MIN, PORT_MAX + 1));
+    this._server = null;
+    this._port = null;
+    this._callbackPromise = null;
+    this._resolveCallback = null;
+    this._rejectCallback = null;
+    this._stopped = false;
+  }
+
+  /** @returns {{port: number, redirectUri: string}} */
+  async start() {
+    let lastErr;
+    for (let attempt = 0; attempt <= this._bindRetries; attempt++) {
+      const port = this._portFn(PORT_MIN, PORT_MAX);
+      try {
+        await this._listen(port);
+        this._port = port;
+        return { port, redirectUri: this.redirectUri };
+      } catch (err) {
+        lastErr = err;
+        if (err && err.code !== 'EADDRINUSE') break;
+      }
+    }
+    throw new AuthError(
+      `Loopback server failed to bind on a free port after ${this._bindRetries + 1} attempts`,
+      { code: 'loopback_bind_failed', cause: lastErr }
+    );
+  }
+
+  get redirectUri() {
+    if (this._port == null) throw new Error('LoopbackServer not started');
+    return `http://127.0.0.1:${this._port}${this._callbackPath}`;
+  }
+
+  /**
+   * Wait for the OAuth provider to redirect the operator's browser to our
+   * callback URL. Resolves with `{ code, state }` once a valid callback
+   * arrives, or rejects with a typed error.
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs]
+   * @returns {Promise<{code: string, state: string}>}
+   */
+  waitForCallback(opts = {}) {
+    if (this._callbackPromise) return this._callbackPromise;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this._callbackPromise = new Promise((resolve, reject) => {
+      let timer = null;
+      const settle = (fn, value) => {
+        if (timer) clearTimeout(timer);
+        timer = null;
+        this._resolveCallback = null;
+        this._rejectCallback = null;
+        fn(value);
+      };
+      this._resolveCallback = (value) => settle(resolve, value);
+      this._rejectCallback = (err) => settle(reject, err);
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          // The settle path clears `timer` to avoid double-clear here.
+          this._reject(new AuthError(
+            `Loopback callback timed out after ${timeoutMs}ms`,
+            { code: 'loopback_timeout', state: 'awaiting_consent' }
+          ));
+        }, timeoutMs);
+        if (timer.unref) timer.unref();
+      }
+    });
+    return this._callbackPromise;
+  }
+
+  async stop() {
+    this._stopped = true;
+    if (!this._server) return;
+    await new Promise((resolve) => this._server.close(() => resolve()));
+    this._server = null;
+  }
+
+  // ---------------------------------------------------------------------
+
+  _listen(port) {
+    return new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => this._onRequest(req, res));
+      server.on('error', (err) => {
+        if (this._port == null) reject(err);
+      });
+      // exclusive: true → SO_REUSEADDR=false in Node's worker model. Per
+      // Appendix H.4.5 we do not share the port with other listeners.
+      server.listen({ host: '127.0.0.1', port, exclusive: true }, () => {
+        this._server = server;
+        resolve();
+      });
+    });
+  }
+
+  _onRequest(req, res) {
+    if (this._stopped) {
+      res.statusCode = 503;
+      res.end();
+      return;
+    }
+    let parsed;
+    try { parsed = new URL(req.url, `http://127.0.0.1:${this._port}`); }
+    catch {
+      this._respond(res, 400, ERROR_HTML);
+      return;
+    }
+    if (parsed.pathname !== this._callbackPath) {
+      this._respond(res, 404, ERROR_HTML);
+      return;
+    }
+
+    const params = parsed.searchParams;
+    const error = params.get('error');
+    const errorDescription = params.get('error_description');
+    const code = params.get('code');
+    const receivedState = params.get('state');
+
+    if (error) {
+      this._respond(res, 200, error === 'access_denied' ? DENIED_HTML : ERROR_HTML);
+      const Cls = error === 'access_denied' ? UserDeniedError : AuthError;
+      this._reject(new Cls(
+        errorDescription || `Authorization server returned error: ${error}`,
+        { code: error, state: 'awaiting_consent' }
+      ));
+      return;
+    }
+
+    if (!code || !receivedState) {
+      this._respond(res, 400, ERROR_HTML);
+      this._reject(new AuthError(
+        'Loopback callback missing code or state',
+        { code: 'invalid_callback', state: 'awaiting_consent' }
+      ));
+      return;
+    }
+
+    if (!safeStateEquals(this._expectedState, receivedState)) {
+      this._respond(res, 400, ERROR_HTML);
+      this._reject(new StateMismatchError(undefined, { state: 'awaiting_consent' }));
+      return;
+    }
+
+    this._respond(res, 200, SUCCESS_HTML);
+    this._resolve({ code, state: receivedState });
+  }
+
+  _respond(res, status, html) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(html);
+  }
+
+  _resolve(value) {
+    if (this._resolveCallback) {
+      const fn = this._resolveCallback;
+      this._resolveCallback = null;
+      this._rejectCallback = null;
+      fn(value);
+    }
+  }
+
+  _reject(err) {
+    if (this._rejectCallback) {
+      const fn = this._rejectCallback;
+      this._resolveCallback = null;
+      this._rejectCallback = null;
+      fn(err);
+    }
+  }
+}
+
+module.exports = { LoopbackServer, PORT_MIN, PORT_MAX, DEFAULT_TIMEOUT_MS };