@wickedevolutions/abilities-mcp 1.3.1 → 1.5.1

package/lib/auth/oauth-client.js

@@ -0,0 +1,357 @@
+'use strict';
+
+const { EventEmitter } = require('node:events');
+
+const { STATES, TERMINAL_STATES, EVENTS } = require('./events');
+const { discover } = require('./discovery-client');
+const { register } = require('./dcr-client');
+const { LoopbackServer } = require('./loopback-server');
+const { openBrowser } = require('./browser-launcher');
+const { generatePkce, generateState } = require('./pkce');
+const { postForm } = require('./http-json');
+const {
+  AuthError,
+  TokenExchangeError,
+} = require('./errors');
+
+/**
+ * OAuthClient — event-emitting state machine for the authorization-code +
+ * PKCE flow. Defined in the design doc's "Architectural constraint: ship
+ * CLI, architect for console" section as binding for v1.0.
+ *
+ * States (binding):
+ *   idle → discovering → registering → awaiting_consent → exchanging
+ *        → complete | failed
+ *
+ * Events emitted (see lib/auth/events.js):
+ *   'state'       every transition, payload `{ from, to, data }`
+ *   'progress'    sub-step info (e.g. discovery probe results)
+ *   'complete'    terminal success
+ *   'failed'      terminal failure
+ *   plus one event per state name for observers that prefer named handlers.
+ *
+ * Public API:
+ *   const client = new OAuthClient({ siteUrl, identityProvider, scope, ... });
+ *   client.on('state', ({ from, to, data }) => { ... });
+ *   const result = await client.run();
+ *   // result = { tokens, scopes, clientId, asMetadata, prMetadata, capabilityPin }
+ *
+ * Constraints (from issue #12 and the sprint plan):
+ *   - No console.* / process.* writes anywhere in this module.
+ *   - Public methods map 1:1 to future CLI subcommands.
+ *   - The state machine is the entire flow — no one-shot helpers that bypass
+ *     it for "convenience."
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const DEFAULT_SCOPE = 'abilities:read abilities:write';
+const DEFAULT_LOOPBACK_TIMEOUT_MS = 5 * 60_000;
+
+class OAuthClient extends EventEmitter {
+  /**
+   * @param {object} args
+   * @param {string} args.siteUrl                                   Canonical site URL
+   * @param {string} args.clientName                                e.g. "<user>'s Operator (host.local)"
+   * @param {string} args.softwareVersion                           Bridge package version
+   * @param {string|string[]} [args.scope]                          Default 'abilities:read abilities:write'
+   * @param {string} [args.resource]                                RFC 8707 resource indicator. If omitted, derived from prMetadata.
+   * @param {object} args.identityProvider                          BridgeIdentityProvider
+   * @param {object} [args.capabilityPin]                           { firstSeenAt: ISO } — pass when site is OAuth-pinned
+   * @param {boolean} [args.allowInsecure]
+   * @param {object} [args.loopback]                                LoopbackServer override (DI for tests)
+   * @param {object} [args.deps]                                    DI of low-level helpers (tests)
+   * @param {number} [args.loopbackTimeoutMs]
+   * @param {number} [args.timeoutMs]                               HTTP timeout for non-loopback calls
+   */
+  constructor(args) {
+    super();
+    if (!args || typeof args.siteUrl !== 'string') {
+      throw new Error('OAuthClient requires siteUrl');
+    }
+    if (typeof args.clientName !== 'string' || !args.clientName) {
+      throw new Error('OAuthClient requires clientName');
+    }
+    if (typeof args.softwareVersion !== 'string' || !args.softwareVersion) {
+      throw new Error('OAuthClient requires softwareVersion');
+    }
+    if (!args.identityProvider || typeof args.identityProvider.getClientId !== 'function') {
+      throw new Error('OAuthClient requires identityProvider with BridgeIdentityProvider shape');
+    }
+
+    this.siteUrl = args.siteUrl;
+    this.clientName = args.clientName;
+    this.softwareVersion = args.softwareVersion;
+    this.scope = args.scope || DEFAULT_SCOPE;
+    this.resource = args.resource || null;
+    this.identityProvider = args.identityProvider;
+    this.capabilityPin = args.capabilityPin || null;
+    this.allowInsecure = !!args.allowInsecure;
+    this.loopbackTimeoutMs = args.loopbackTimeoutMs || DEFAULT_LOOPBACK_TIMEOUT_MS;
+    this.timeoutMs = args.timeoutMs;
+
+    // Dependency injection seams — production callers don't pass these.
+    const deps = args.deps || {};
+    this._discover = deps.discover || discover;
+    this._register = deps.register || register;
+    this._postForm = deps.postForm || postForm;
+    this._openBrowser = deps.openBrowser || openBrowser;
+    this._LoopbackServer = deps.LoopbackServer || LoopbackServer;
+    this._loopbackOverride = args.loopback || null;
+
+    this.state = STATES.IDLE;
+    this._lastError = null;
+  }
+
+  // ---------------------------------------------------------------------
+  // State helpers
+  // ---------------------------------------------------------------------
+
+  _transition(to, data) {
+    const from = this.state;
+    this.state = to;
+    const payload = { from, to, data: data || null };
+    this.emit(EVENTS.STATE, payload);
+    this.emit(to, payload);
+  }
+
+  _progress(message, data) {
+    this.emit(EVENTS.PROGRESS, { state: this.state, message, data: data || null });
+  }
+
+  _fail(err) {
+    this._lastError = err;
+    this._transition(STATES.FAILED, { error: err });
+    this.emit(EVENTS.FAILED, { error: err, state: STATES.FAILED });
+  }
+
+  // ---------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------
+
+  /**
+   * Run the full state machine. Resolves with the result on success, throws
+   * on failure (the 'failed' event is emitted first so subscribers see the
+   * terminal state before the rejection propagates).
+   *
+   * @returns {Promise<{
+   *   tokens: object,
+   *   scopes: string[],
+   *   clientId: string,
+   *   asMetadata: object,
+   *   prMetadata: object|null,
+   *   capabilityPin: {firstSeenAt: string, lastConfirmedAt: string},
+   *   resource: string|null,
+   * }>}
+   */
+  async run() {
+    if (TERMINAL_STATES.has(this.state)) {
+      throw new Error(`OAuthClient.run() called on terminal state: ${this.state}`);
+    }
+    try {
+      const discovered = await this._runDiscover();
+      const registered = await this._runRegister(discovered);
+      const consent = await this._runAwaitConsent(discovered, registered);
+      const exchanged = await this._runExchange(discovered, registered, consent);
+      const result = this._buildResult(discovered, registered, exchanged);
+      this._transition(STATES.COMPLETE, result);
+      this.emit(EVENTS.COMPLETE, result);
+      return result;
+    } catch (err) {
+      const wrapped = err instanceof AuthError ? err : new AuthError(err.message, { cause: err, state: this.state });
+      this._fail(wrapped);
+      throw wrapped;
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // State implementations
+  // ---------------------------------------------------------------------
+
+  async _runDiscover() {
+    this._transition(STATES.DISCOVERING, { siteUrl: this.siteUrl });
+    const pinnedFirstSeenAt = this.capabilityPin && this.capabilityPin.firstSeenAt
+      ? this.capabilityPin.firstSeenAt
+      : null;
+    const discovered = await this._discover(this.siteUrl, {
+      pinned: !!this.capabilityPin,
+      pinnedFirstSeenAt,
+      allowInsecure: this.allowInsecure,
+      timeoutMs: this.timeoutMs,
+    });
+    this._progress('discovery_succeeded', {
+      asMetadataUrl: discovered.asMetadataUrl,
+      probeResults: discovered.probeResults,
+    });
+    return discovered;
+  }
+
+  async _runRegister(discovered) {
+    this._transition(STATES.REGISTERING, {
+      registrationEndpoint: discovered.asMetadata.registration_endpoint,
+    });
+
+    // H-8: never reuse a persisted client_id from this code path.
+    //
+    // The previous early-return looked up identityProvider.getClientId() and
+    // returned the persisted client_id without checking whether the registered
+    // loopback redirect_uri's port matched the live loopback port. v1.0 was
+    // safe by accident because FreshEachTimeIdentityProvider.getClientId()
+    // always returns null. v1.1 (Option C, persistent client_id per Appendix
+    // H.3.2) would have surfaced the bug: a stale persisted client_id whose
+    // server-side registered redirect_uri pinned a port no longer in use
+    // would cause the next /oauth/authorize to fail redirect_uri_valid().
+    //
+    // Defensive guard: clear any persisted client_id before DCR. v1.0
+    // FreshEachTime is a no-op; v1.1+ implementations of clearClientId() get
+    // a chance to remove a stale entry before we mint a new one. Reuse paths
+    // that *already know* their loopback port matches the registration must
+    // not flow through _runRegister — they need their own short-circuit at
+    // the OAuthClient.run() level.
+    await this.identityProvider.clearClientId(this.siteUrl);
+
+    if (!discovered.asMetadata.registration_endpoint) {
+      throw new AuthError('Authorization server metadata missing registration_endpoint', {
+        code: 'no_registration_endpoint', state: STATES.REGISTERING,
+      });
+    }
+
+    // We need a redirect_uri to register. Spin up the loopback server now
+    // so its port is known to DCR (even though we don't await callbacks
+    // until later).
+    const expectedState = generateState();
+    const loopback = this._loopbackOverride || new this._LoopbackServer({ expectedState });
+    await loopback.start();
+    this._loopback = loopback;
+    this._expectedState = expectedState;
+
+    let registration;
+    try {
+      registration = await this._register({
+        registrationEndpoint: discovered.asMetadata.registration_endpoint,
+        clientName: this.clientName,
+        redirectUri: loopback.redirectUri,
+        scope: this.scope,
+        softwareVersion: this.softwareVersion,
+        allowInsecure: this.allowInsecure,
+        timeoutMs: this.timeoutMs,
+      });
+    } catch (err) {
+      await loopback.stop().catch(() => {});
+      throw err;
+    }
+
+    await this.identityProvider.persistClientId(this.siteUrl, registration.clientId);
+    this._progress('registered', { clientId: registration.clientId });
+    return registration;
+  }
+
+  async _runAwaitConsent(discovered, registered) {
+    if (!this._loopback) {
+      throw new AuthError('Internal error: loopback server not started', { code: 'internal_error' });
+    }
+    const pkce = generatePkce();
+    this._pkce = pkce;
+
+    const resource = this.resource
+      || (discovered.prMetadata && discovered.prMetadata.resource)
+      || null;
+
+    const authorizeUrl = new URL(discovered.asMetadata.authorization_endpoint);
+    authorizeUrl.searchParams.set('response_type', 'code');
+    authorizeUrl.searchParams.set('client_id', registered.clientId);
+    authorizeUrl.searchParams.set('redirect_uri', this._loopback.redirectUri);
+    authorizeUrl.searchParams.set('scope', Array.isArray(this.scope) ? this.scope.join(' ') : this.scope);
+    authorizeUrl.searchParams.set('state', this._expectedState);
+    authorizeUrl.searchParams.set('code_challenge', pkce.challenge);
+    authorizeUrl.searchParams.set('code_challenge_method', pkce.method);
+    if (resource) authorizeUrl.searchParams.set('resource', resource);
+
+    this._transition(STATES.AWAITING_CONSENT, {
+      authorizeUrl: authorizeUrl.toString(),
+      redirectUri: this._loopback.redirectUri,
+    });
+
+    // Launch browser as a side-effect and wait for the loopback callback.
+    // We swallow browser-launch errors because the caller may already have
+    // displayed the URL for manual paste (e.g. headless SSH session).
+    this._openBrowser(authorizeUrl.toString()).catch((err) => {
+      this._progress('browser_launch_failed', { error: err.message });
+    });
+
+    let callback;
+    try {
+      callback = await this._loopback.waitForCallback({ timeoutMs: this.loopbackTimeoutMs });
+    } finally {
+      await this._loopback.stop().catch(() => {});
+    }
+    this._progress('callback_received', { codePresent: !!callback.code });
+    return { ...callback, resource };
+  }
+
+  async _runExchange(discovered, registered, consent) {
+    this._transition(STATES.EXCHANGING, { tokenEndpoint: discovered.asMetadata.token_endpoint });
+
+    const params = {
+      grant_type: 'authorization_code',
+      code: consent.code,
+      redirect_uri: this._loopback ? this._loopback.redirectUri : undefined,
+      client_id: registered.clientId,
+      code_verifier: this._pkce.verifier,
+    };
+    if (consent.resource) params.resource = consent.resource;
+    // Strip undefined.
+    for (const k of Object.keys(params)) if (params[k] === undefined) delete params[k];
+
+    let res;
+    try {
+      res = await this._postForm(discovered.asMetadata.token_endpoint, params, {
+        allowInsecure: this.allowInsecure,
+        timeoutMs: this.timeoutMs,
+      });
+    } catch (err) {
+      throw new TokenExchangeError(`Token exchange request failed: ${err.message}`, {
+        cause: err, state: STATES.EXCHANGING,
+      });
+    }
+    if (res.statusCode < 200 || res.statusCode >= 300 || !res.json) {
+      throw new TokenExchangeError(`Token endpoint returned ${res.statusCode}`, {
+        cause: { statusCode: res.statusCode, body: res.body, json: res.json },
+        state: STATES.EXCHANGING,
+      });
+    }
+    if (typeof res.json.access_token !== 'string') {
+      throw new TokenExchangeError('Token response missing access_token', {
+        cause: res.json, state: STATES.EXCHANGING,
+      });
+    }
+    return res.json;
+  }
+
+  _buildResult(discovered, registered, tokens) {
+    const now = new Date().toISOString();
+    const grantedScope = typeof tokens.scope === 'string'
+      ? tokens.scope.split(/\s+/).filter(Boolean)
+      : (Array.isArray(this.scope) ? this.scope : String(this.scope).split(/\s+/).filter(Boolean));
+
+    return {
+      tokens,
+      scopes: grantedScope,
+      clientId: registered.clientId,
+      asMetadata: discovered.asMetadata,
+      asMetadataUrl: discovered.asMetadataUrl,
+      prMetadata: discovered.prMetadata,
+      prMetadataUrl: discovered.prMetadataUrl,
+      capabilityPin: {
+        firstSeenAt: this.capabilityPin && this.capabilityPin.firstSeenAt
+          ? this.capabilityPin.firstSeenAt
+          : now,
+        lastConfirmedAt: now,
+      },
+      resource: this.resource || (discovered.prMetadata && discovered.prMetadata.resource) || null,
+    };
+  }
+}
+
+module.exports = { OAuthClient, DEFAULT_SCOPE };

package/lib/auth/pkce.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { randomBytes, createHash, timingSafeEqual: cryptoTimingSafeEqual } = require('node:crypto');
+
+/**
+ * PKCE (RFC 7636) and CSRF state primitives.
+ *
+ * Per design doc:
+ *   - PKCE method MUST be S256 (Appendix D.1, H.3.6, discovery metadata).
+ *   - state = bin2hex(random_bytes(16)) → 128 bits of entropy (Appendix H.3.5).
+ *   - State comparison on loopback callback uses timingSafeEqual (H.3.5, H.4.5).
+ *
+ * The verifier byte length is implementer's choice within RFC 7636 (43–128
+ * chars after base64url). We use 32 bytes → 43-char base64url string, the
+ * common choice.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const VERIFIER_BYTES = 32;       // → 43-char base64url verifier (RFC 7636 §4.1)
+const STATE_BYTES = 16;          // → 32-char hex state (128 bits, per H.3.5)
+const STATE_MAX_LENGTH = 256;    // server enforces; mirrored here for safety
+
+function base64url(buf) {
+  return Buffer.from(buf).toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+/**
+ * Generate a fresh PKCE pair.
+ * @returns {{verifier: string, challenge: string, method: 'S256'}}
+ */
+function generatePkce() {
+  const verifierBytes = randomBytes(VERIFIER_BYTES);
+  const verifier = base64url(verifierBytes);
+  const challenge = base64url(createHash('sha256').update(verifier).digest());
+  return { verifier, challenge, method: 'S256' };
+}
+
+/**
+ * Compute the S256 challenge for a given verifier — useful for tests.
+ * @param {string} verifier
+ * @returns {string}
+ */
+function challengeFromVerifier(verifier) {
+  return base64url(createHash('sha256').update(verifier).digest());
+}
+
+/**
+ * Generate a fresh CSRF state token. 128 bits of entropy, hex-encoded.
+ * @returns {string}
+ */
+function generateState() {
+  return randomBytes(STATE_BYTES).toString('hex');
+}
+
+/**
+ * Constant-time equality check on two strings. Used to compare the loopback
+ * callback's `state` query param against the bridge-generated value (H.3.5,
+ * H.4.5). Returns false on any error including length mismatch.
+ *
+ * @param {string} expected
+ * @param {string} received
+ * @returns {boolean}
+ */
+function safeStateEquals(expected, received) {
+  if (typeof expected !== 'string' || typeof received !== 'string') return false;
+  if (expected.length === 0 || received.length === 0) return false;
+  if (expected.length > STATE_MAX_LENGTH || received.length > STATE_MAX_LENGTH) return false;
+  if (expected.length !== received.length) {
+    // Avoid throwing in timingSafeEqual on length mismatch — but burn a few
+    // CPU cycles so timing doesn't trivially leak the length difference.
+    const filler = Buffer.alloc(expected.length, 0);
+    try { cryptoTimingSafeEqual(filler, filler); } catch { /* ignore */ }
+    return false;
+  }
+  const a = Buffer.from(expected, 'utf8');
+  const b = Buffer.from(received, 'utf8');
+  return cryptoTimingSafeEqual(a, b);
+}
+
+module.exports = {
+  generatePkce,
+  challengeFromVerifier,
+  generateState,
+  safeStateEquals,
+  VERIFIER_BYTES,
+  STATE_BYTES,
+  STATE_MAX_LENGTH,
+};

package/lib/auth/schema-v2.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const { AUTH_STATUS } = require('./events');
+
+/**
+ * wp-sites.json schema v2 — defined in design doc Appendix F.5 with
+ * amendments from H.2.3 (oauth_capability_pinned).
+ *
+ * The bridge supports both `oauth` and `apppassword` per site. OAuth always
+ * takes precedence; `apppassword_fallback` fires only when OAuth discovery
+ * returns 404 (no pin) — silent fallback for reverse compatibility. A pinned
+ * site that loses OAuth fails loud (H.2.3 — handled in discovery-client).
+ *
+ * This module ships a minimal validator. The bridge's existing config.js
+ * does richer transport-specific validation; v2 adds:
+ *   - schema_version === 2 sentinel
+ *   - auth.method ∈ {'oauth','apppassword'} per site
+ *   - auth_status ∈ {'active','expired','revoked','pending-reauth'}
+ *   - oauth_capability_pinned shape (when present)
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const SCHEMA_VERSION = 2;
+const AUTH_METHODS = Object.freeze(['oauth', 'apppassword']);
+const VALID_AUTH_STATUS = Object.freeze(Object.values(AUTH_STATUS));
+
+/**
+ * @param {object} config  Parsed wp-sites.json
+ * @returns {{ok: true} | {ok: false, errors: string[]}}
+ */
+function validate(config) {
+  const errors = [];
+  if (!config || typeof config !== 'object') {
+    return { ok: false, errors: ['config is not an object'] };
+  }
+  if (config.schema_version !== SCHEMA_VERSION) {
+    errors.push(`schema_version must be ${SCHEMA_VERSION}, got ${JSON.stringify(config.schema_version)}`);
+  }
+  if (!config.sites || typeof config.sites !== 'object') {
+    return { ok: false, errors: errors.concat(['sites object is missing']) };
+  }
+  for (const [siteId, site] of Object.entries(config.sites)) {
+    const prefix = `sites.${siteId}`;
+    if (!site || typeof site !== 'object') {
+      errors.push(`${prefix} is not an object`);
+      continue;
+    }
+    if (typeof site.url !== 'string' || site.url.length === 0) {
+      errors.push(`${prefix}.url is missing`);
+    }
+    if (!site.auth || typeof site.auth !== 'object') {
+      errors.push(`${prefix}.auth is missing`);
+      continue;
+    }
+    if (!AUTH_METHODS.includes(site.auth.method)) {
+      errors.push(`${prefix}.auth.method must be one of ${AUTH_METHODS.join(', ')}`);
+    }
+    if (site.auth_status && !VALID_AUTH_STATUS.includes(site.auth_status)) {
+      errors.push(`${prefix}.auth_status must be one of ${VALID_AUTH_STATUS.join(', ')}`);
+    }
+    if (site.auth.method === 'oauth') {
+      for (const k of ['client_id', 'access_token_ref', 'refresh_token_ref']) {
+        if (typeof site.auth[k] !== 'string') {
+          errors.push(`${prefix}.auth.${k} is required for OAuth sites`);
+        }
+      }
+    } else if (site.auth.method === 'apppassword') {
+      if (typeof site.auth.username !== 'string') {
+        errors.push(`${prefix}.auth.username is required for App Password sites`);
+      }
+      if (typeof site.auth.password_ref !== 'string') {
+        errors.push(`${prefix}.auth.password_ref is required for App Password sites`);
+      }
+    }
+    if (site.oauth_capability_pinned) {
+      const pin = site.oauth_capability_pinned;
+      if (typeof pin !== 'object'
+          || typeof pin.first_seen_at !== 'string'
+          || typeof pin.last_confirmed_at !== 'string') {
+        errors.push(`${prefix}.oauth_capability_pinned must be { first_seen_at, last_confirmed_at }`);
+      }
+    }
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+/**
+ * Build a minimal v2 config skeleton.
+ * @param {object} [opts]
+ * @param {string} [opts.defaultSite]
+ * @returns {object}
+ */
+function emptyConfig(opts = {}) {
+  return {
+    $schema: 'https://wickedevolutions.com/schemas/abilities-mcp/wp-sites/v2.json',
+    schema_version: SCHEMA_VERSION,
+    defaultSite: opts.defaultSite,
+    sites: {},
+  };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  AUTH_METHODS,
+  VALID_AUTH_STATUS,
+  validate,
+  emptyConfig,
+};

package/lib/auth/secret-store.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * SecretStore — interface for persisting tokens, refresh tokens, App Passwords,
+ * and (future, see Appendix H.3.2) bridge identity material.
+ *
+ * The interface is a JSDoc typedef — there is no abstract base class. Any
+ * object implementing the four methods below counts as a SecretStore.
+ *
+ * @typedef {object} SecretStore
+ * @property {(service: string, account: string) => Promise<string|null>} get
+ * @property {(service: string, account: string, secret: string) => Promise<void>} set
+ * @property {(service: string, account: string) => Promise<boolean>} delete
+ * @property {(service: string) => Promise<Array<{account: string, password: string}>>} findAll
+ *
+ * Service / account naming convention:
+ *   service = 'abilities-mcp'
+ *   account = '<siteId>/<kind>' where kind is 'access' | 'refresh' | 'apppassword' | 'apppassword-legacy' | 'client_id'
+ *
+ * Keychain references in wp-sites.json take the form:
+ *   keychain://<service>/<account>
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const KEYCHAIN_REF_SCHEME = 'keychain://';
+
+/**
+ * Build a `keychain://service/account` reference for storage in wp-sites.json.
+ * @param {string} service
+ * @param {string} account
+ * @returns {string}
+ */
+function makeRef(service, account) {
+  if (!service || !account) {
+    throw new Error('makeRef requires both service and account');
+  }
+  return `${KEYCHAIN_REF_SCHEME}${service}/${account}`;
+}
+
+/**
+ * Parse a keychain reference back into service + account.
+ * @param {string} ref
+ * @returns {{service: string, account: string}}
+ */
+function parseRef(ref) {
+  if (typeof ref !== 'string' || !ref.startsWith(KEYCHAIN_REF_SCHEME)) {
+    throw new Error(`Not a keychain reference: ${ref}`);
+  }
+  const remainder = ref.slice(KEYCHAIN_REF_SCHEME.length);
+  const slashIdx = remainder.indexOf('/');
+  if (slashIdx <= 0) {
+    throw new Error(`Malformed keychain reference (expected service/account): ${ref}`);
+  }
+  return {
+    service: remainder.slice(0, slashIdx),
+    account: remainder.slice(slashIdx + 1),
+  };
+}
+
+/**
+ * Resolve a keychain reference through a SecretStore. Returns the secret value
+ * or throws if not found.
+ * @param {SecretStore} store
+ * @param {string} ref
+ * @returns {Promise<string>}
+ */
+async function resolveRef(store, ref) {
+  const { service, account } = parseRef(ref);
+  const value = await store.get(service, account);
+  if (value === null || value === undefined) {
+    throw new Error(`Keychain reference not found: ${ref}`);
+  }
+  return value;
+}
+
+module.exports = { KEYCHAIN_REF_SCHEME, makeRef, parseRef, resolveRef };