@wickedevolutions/abilities-mcp 1.3.1 → 1.5.1

package/lib/auth/discovery-client.js

@@ -0,0 +1,273 @@
+'use strict';
+
+const https = require('node:https');
+const http = require('node:http');
+const { URL } = require('node:url');
+
+const { DiscoveryError, CapabilityPinningError } = require('./errors');
+
+/**
+ * Discovery client for OAuth 2.1 .well-known endpoints.
+ *
+ * Per design doc:
+ *   - L1 (Appendix D.2): MCP TypeScript SDK probes three well-known paths.
+ *     We try them in this order until one returns 200 with valid metadata:
+ *       1. {origin}/.well-known/oauth-authorization-server{path}
+ *       2. {origin}/.well-known/openid-configuration{path}
+ *       3. {origin}{path}/.well-known/openid-configuration
+ *     The protected-resource metadata lives at {origin}/.well-known/oauth-protected-resource.
+ *   - HTTPS-only on .well-known paths (Appendix H.2.3). The discovery client
+ *     refuses HTTP URLs unless the caller passes `allowInsecure: true` for
+ *     localhost development.
+ *   - No redirect-following. A 3xx on a .well-known path is treated as a
+ *     non-discovery (move to next candidate). This mitigates Location-header
+ *     injection attacks (H.2.3).
+ *   - HTTP timeout: 30s read/write (H.2.1 mandate is for token-manager but
+ *     we apply the same ceiling here for parity).
+ *
+ * Capability pinning (Appendix H.2.3):
+ *   - On first successful discovery, callers should write
+ *     `oauth_capability_pinned.first_seen_at` to site config.
+ *   - On every subsequent connection, refresh `last_confirmed_at`.
+ *   - If pinned AND discovery returns 404, throw CapabilityPinningError —
+ *     do NOT silently downgrade to App Password.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Build the L1 probe order for a given site URL.
+ *
+ * @param {string} siteUrl  e.g. "https://example.com" or "https://example.com/site2"
+ * @returns {{authorizationServer: string[], protectedResource: string}}
+ */
+function buildProbeOrder(siteUrl) {
+  const u = new URL(siteUrl);
+  const origin = u.origin;
+  const pathPart = u.pathname.replace(/\/+$/g, '');
+
+  const authorizationServer = [
+    `${origin}/.well-known/oauth-authorization-server${pathPart}`,
+    `${origin}/.well-known/openid-configuration${pathPart}`,
+    `${origin}${pathPart}/.well-known/openid-configuration`,
+  ];
+
+  // De-dupe (when pathPart is empty the three collapse to two distinct URLs).
+  const seen = new Set();
+  const dedupedAuth = [];
+  for (const url of authorizationServer) {
+    if (!seen.has(url)) { seen.add(url); dedupedAuth.push(url); }
+  }
+
+  const protectedResource = `${origin}/.well-known/oauth-protected-resource`;
+  return { authorizationServer: dedupedAuth, protectedResource };
+}
+
+/**
+ * GET a .well-known URL with explicit security constraints.
+ *
+ * Returns either { ok: true, json, status, url } or { ok: false, status, url }.
+ * Network errors raise.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs]
+ * @param {boolean} [opts.allowInsecure]   Localhost-only escape hatch
+ * @param {object} [opts.httpsAgent]       Test injection
+ */
+function getWellKnown(url, opts = {}) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try { parsed = new URL(url); }
+    catch (err) { reject(new DiscoveryError(`Invalid URL: ${url}`, { cause: err })); return; }
+
+    const isHttps = parsed.protocol === 'https:';
+    const isHttp = parsed.protocol === 'http:';
+    if (!isHttps && !isHttp) {
+      reject(new DiscoveryError(`Discovery URL must be http(s): ${url}`));
+      return;
+    }
+    const isLocal = parsed.hostname === 'localhost'
+      || parsed.hostname === '127.0.0.1'
+      || parsed.hostname === '::1';
+    if (isHttp && !(isLocal && opts.allowInsecure)) {
+      reject(new DiscoveryError(
+        `Discovery refused: HTTPS required for ${url}. ` +
+        `Per Appendix H.2.3 the bridge does not perform OAuth discovery over plain HTTP.`
+      ));
+      return;
+    }
+
+    const mod = isHttps ? https : http;
+    const requestOpts = {
+      method: 'GET',
+      hostname: parsed.hostname,
+      port: parsed.port || (isHttps ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      headers: { 'Accept': 'application/json' },
+      timeout: opts.timeoutMs || DEFAULT_TIMEOUT_MS,
+    };
+    if (opts.httpsAgent && isHttps) requestOpts.agent = opts.httpsAgent;
+
+    const req = mod.request(requestOpts, (res) => {
+      // Per H.2.3: do NOT follow redirects on .well-known paths.
+      if (res.statusCode >= 300 && res.statusCode < 400) {
+        res.resume();
+        resolve({ ok: false, status: res.statusCode, url, redirected: true });
+        return;
+      }
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (res.statusCode !== 200) {
+          resolve({ ok: false, status: res.statusCode, url, body });
+          return;
+        }
+        let json;
+        try { json = JSON.parse(body); }
+        catch (err) {
+          resolve({ ok: false, status: res.statusCode, url, parseError: err.message });
+          return;
+        }
+        resolve({ ok: true, status: res.statusCode, url, json });
+      });
+      res.on('error', (err) => reject(new DiscoveryError(`Response error from ${url}: ${err.message}`, { cause: err })));
+    });
+
+    req.on('error', (err) => reject(new DiscoveryError(`Request failed for ${url}: ${err.message}`, { cause: err })));
+    req.on('timeout', () => req.destroy(new DiscoveryError(`Discovery timed out at ${requestOpts.timeout}ms: ${url}`)));
+    req.end();
+  });
+}
+
+/**
+ * Validate the shape of an authorization-server metadata document.
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+function validateAsMetadata(json) {
+  if (!json || typeof json !== 'object') return { ok: false, reason: 'metadata is not an object' };
+  for (const required of ['issuer', 'authorization_endpoint', 'token_endpoint']) {
+    if (typeof json[required] !== 'string') {
+      return { ok: false, reason: `missing field: ${required}` };
+    }
+  }
+  if (Array.isArray(json.code_challenge_methods_supported)
+      && !json.code_challenge_methods_supported.includes('S256')) {
+    return { ok: false, reason: 'server does not advertise S256 PKCE support' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Validate the shape of a protected-resource metadata document.
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+function validatePrMetadata(json) {
+  if (!json || typeof json !== 'object') return { ok: false, reason: 'metadata is not an object' };
+  if (typeof json.resource !== 'string') return { ok: false, reason: 'missing field: resource' };
+  if (!Array.isArray(json.authorization_servers) || json.authorization_servers.length === 0) {
+    return { ok: false, reason: 'missing field: authorization_servers' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Run the full discovery flow against a site.
+ *
+ * @param {string} siteUrl
+ * @param {object} [opts]
+ * @param {boolean} [opts.pinned]            true if site is already OAuth-pinned (H.2.3)
+ * @param {string}  [opts.pinnedFirstSeenAt] for the failure message
+ * @param {boolean} [opts.allowInsecure]
+ * @param {number}  [opts.timeoutMs]
+ * @param {object}  [opts.httpsAgent]        test injection
+ * @returns {Promise<{
+ *   asMetadata: object,
+ *   asMetadataUrl: string,
+ *   prMetadata: object|null,
+ *   prMetadataUrl: string|null,
+ *   probeResults: Array<object>,
+ * }>}
+ */
+async function discover(siteUrl, opts = {}) {
+  const probes = buildProbeOrder(siteUrl);
+  const probeResults = [];
+
+  let asMetadata = null;
+  let asMetadataUrl = null;
+
+  for (const url of probes.authorizationServer) {
+    let res;
+    try {
+      res = await getWellKnown(url, opts);
+    } catch (err) {
+      probeResults.push({ url, ok: false, error: err.message });
+      // HTTPS-required is a configuration error, not a probe miss — surface
+      // it immediately so the caller sees the real reason. Per Appendix
+      // H.2.3 the bridge does not perform OAuth discovery over plain HTTP.
+      if (/HTTPS required/i.test(err.message)) throw err;
+      // Other hard errors (network, TLS) — record and continue to next
+      // candidate path.
+      continue;
+    }
+    probeResults.push({ url, ok: res.ok, status: res.status, redirected: res.redirected });
+    if (res.ok) {
+      const validation = validateAsMetadata(res.json);
+      if (!validation.ok) {
+        probeResults[probeResults.length - 1].invalid = validation.reason;
+        continue;
+      }
+      asMetadata = res.json;
+      asMetadataUrl = url;
+      break;
+    }
+  }
+
+  if (!asMetadata) {
+    const all404 = probeResults.length > 0 && probeResults.every((p) => p.status === 404);
+    if (all404 && opts.pinned) {
+      throw new CapabilityPinningError(
+        `Site ${siteUrl} previously supported OAuth (first seen ${opts.pinnedFirstSeenAt || 'unknown'}) ` +
+        `but now reports no OAuth. This may indicate a network attack. ` +
+        `Refusing to silently downgrade to App Password.`,
+        { state: 'discovering' }
+      );
+    }
+    throw new DiscoveryError(
+      `OAuth discovery failed for ${siteUrl} — none of ${probes.authorizationServer.length} probe URLs returned valid metadata.`,
+      { state: 'discovering', cause: { probeResults } }
+    );
+  }
+
+  // Protected-resource metadata is informative but not strictly required to
+  // proceed. We try once at the canonical path.
+  let prMetadata = null;
+  let prMetadataUrl = null;
+  try {
+    const res = await getWellKnown(probes.protectedResource, opts);
+    if (res.ok) {
+      const validation = validatePrMetadata(res.json);
+      if (validation.ok) {
+        prMetadata = res.json;
+        prMetadataUrl = probes.protectedResource;
+      }
+    }
+  } catch {
+    // Non-fatal — proceed without protected-resource metadata.
+  }
+
+  return { asMetadata, asMetadataUrl, prMetadata, prMetadataUrl, probeResults };
+}
+
+module.exports = {
+  buildProbeOrder,
+  getWellKnown,
+  validateAsMetadata,
+  validatePrMetadata,
+  discover,
+  DEFAULT_TIMEOUT_MS,
+};

package/lib/auth/errors.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Typed error classes for the OAuth flow.
+ *
+ * Code paths in lib/auth/ MUST throw or emit these instead of writing to
+ * stderr. Callers (CLI today, GUI tomorrow) decide how to surface them.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+class AuthError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code]    machine-readable error code
+   * @param {string} [opts.state]   state machine state at the time of failure
+   * @param {object} [opts.cause]   underlying cause
+   */
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = 'AuthError';
+    this.code = opts.code || 'auth_error';
+    if (opts.state) this.state = opts.state;
+    if (opts.cause) this.cause = opts.cause;
+  }
+}
+
+class DiscoveryError extends AuthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'discovery_failed', ...opts });
+    this.name = 'DiscoveryError';
+  }
+}
+
+class CapabilityPinningError extends AuthError {
+  /**
+   * Raised when a previously-pinned OAuth-capable site returns 404 on
+   * discovery — per Appendix H.2.3 we fail loud rather than silently
+   * downgrading to App Password.
+   */
+  constructor(message, opts = {}) {
+    super(message, { code: 'oauth_capability_lost', ...opts });
+    this.name = 'CapabilityPinningError';
+  }
+}
+
+class RegistrationError extends AuthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'registration_failed', ...opts });
+    this.name = 'RegistrationError';
+  }
+}
+
+class TokenExchangeError extends AuthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'token_exchange_failed', ...opts });
+    this.name = 'TokenExchangeError';
+  }
+}
+
+class StateMismatchError extends AuthError {
+  /** CSRF protection — Appendix H.3.5. Loopback callback `state` did not
+   *  match the value the bridge generated for this flow. */
+  constructor(message = 'OAuth state parameter mismatch — CSRF protection rejected callback', opts = {}) {
+    super(message, { code: 'state_mismatch', ...opts });
+    this.name = 'StateMismatchError';
+  }
+}
+
+class UserDeniedError extends AuthError {
+  /** Operator clicked "Deny" on the consent screen. */
+  constructor(message = 'Operator denied authorization', opts = {}) {
+    super(message, { code: 'access_denied', ...opts });
+    this.name = 'UserDeniedError';
+  }
+}
+
+class RefreshError extends AuthError {
+  /** A refresh-token exchange failed with a 4xx — token is unusable.
+   *  Caller should mark `auth_status: "expired"` and prompt reauth. */
+  constructor(message, opts = {}) {
+    super(message, { code: 'refresh_failed', ...opts });
+    this.name = 'RefreshError';
+  }
+}
+
+class SecretStoreError extends AuthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'secret_store_error', ...opts });
+    this.name = 'SecretStoreError';
+  }
+}
+
+class MigrationError extends AuthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'migration_failed', ...opts });
+    this.name = 'MigrationError';
+  }
+}
+
+module.exports = {
+  AuthError,
+  DiscoveryError,
+  CapabilityPinningError,
+  RegistrationError,
+  TokenExchangeError,
+  StateMismatchError,
+  UserDeniedError,
+  RefreshError,
+  SecretStoreError,
+  MigrationError,
+};

package/lib/auth/events.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * State machine constants and event names for the OAuth flow.
+ *
+ * Per design doc (architectural-constraint section): the bridge OAuth flow is
+ * an event-emitting state machine, not a one-shot function. The CLI subscribes
+ * and prints progress lines. A future GUI subscribes and renders progress UI.
+ * Same machine, different observers.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const STATES = Object.freeze({
+  IDLE: 'idle',
+  DISCOVERING: 'discovering',
+  REGISTERING: 'registering',
+  AWAITING_CONSENT: 'awaiting_consent',
+  EXCHANGING: 'exchanging',
+  COMPLETE: 'complete',
+  FAILED: 'failed',
+});
+
+const TERMINAL_STATES = new Set([STATES.COMPLETE, STATES.FAILED]);
+
+/**
+ * Auth-status enum used in wp-sites.json v2 (Appendix F.5).
+ */
+const AUTH_STATUS = Object.freeze({
+  ACTIVE: 'active',
+  EXPIRED: 'expired',
+  REVOKED: 'revoked',
+  PENDING_REAUTH: 'pending-reauth',
+});
+
+/**
+ * Events emitted on the OAuth state machine. Consumers can listen to:
+ *   - 'state'    : every transition, payload `{ from, to, data }`
+ *   - 'progress' : sub-step info inside a state (e.g. discovery probe results)
+ *   - 'error'    : non-fatal warnings during the flow
+ *   - 'complete' : terminal success, payload `{ tokens, scopes, ... }`
+ *   - 'failed'   : terminal failure, payload `{ error, state }`
+ *   - one event per state name (e.g. 'discovering', 'registering', ...)
+ *     with the same data payload as the 'state' event.
+ */
+const EVENTS = Object.freeze({
+  STATE: 'state',
+  PROGRESS: 'progress',
+  ERROR: 'error',
+  COMPLETE: 'complete',
+  FAILED: 'failed',
+});
+
+module.exports = { STATES, TERMINAL_STATES, AUTH_STATUS, EVENTS };

package/lib/auth/fresh-each-time-identity.js

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * FreshEachTimeIdentityProvider — v1.0 BridgeIdentityProvider.
+ *
+ * Per Appendix H.3.2 (binding amendment to F.4):
+ *
+ *   - getClientId() always returns null → triggers a fresh DCR on every
+ *     add-site / reauth call.
+ *   - persistClientId() is intentionally a NO-OP. It does NOT write the
+ *     client_id to the keychain. v1.1 (Option C) will switch this on, but
+ *     turning it on safely requires:
+ *       * a `keychain_schema_version: 2` companion key
+ *       * defensive clearClientId() before DCR in add-site
+ *       * orphan-client-id detection UX
+ *     None of which exist in v1.0.
+ *   - clearClientId() is also a NO-OP at the keychain layer (there is
+ *     nothing persisted to clear). It accepts the call so callers can be
+ *     written symmetrically against the future v1.1 implementation.
+ *   - exportIdentity() returns null.
+ *   - importIdentity() throws.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+class FreshEachTimeIdentityProvider {
+  /**
+   * @param {object} [opts]
+   * @param {import('./secret-store').SecretStore} [opts.store]
+   *   Held for symmetry with v1.1+ implementations. v1.0 does not use it.
+   */
+  constructor(opts = {}) {
+    this._store = opts.store || null;
+  }
+
+  /**
+   * v1.0: always null. Force fresh DCR every flow.
+   * @param {string} _siteId
+   * @returns {Promise<string|null>}
+   */
+  async getClientId(_siteId) {
+    // v1.0: intentionally never reads from storage.
+    // Uncomment in v1.1 (Option C) — and ONLY after implementing the upgrade
+    // contract documented in Appendix H.3.2.
+    return null;
+  }
+
+  /**
+   * v1.0: intentionally does nothing.
+   *
+   * Forward-compat note: v1.1 (Option C) WILL persist client_id to the
+   * keychain. It is NOT safe to enable that here without also implementing:
+   *   - keychain_schema_version key alongside client_id (v1.1+ only)
+   *   - clearClientId() called automatically on add-site (defensive cleanup)
+   *   - operator UX for orphaned-client-id detection
+   *
+   * See Appendix H.3.2 in DESIGN — OAuth 2.1 in the Adapter for the upgrade
+   * contract. Do NOT uncomment a write here without reading that section
+   * first.
+   *
+   * @param {string} _siteId
+   * @param {string} _clientId
+   * @returns {Promise<void>}
+   */
+  async persistClientId(_siteId, _clientId) {
+    // NO-OP — see contract above.
+  }
+
+  /**
+   * v1.0: NO-OP (nothing was persisted).
+   * @param {string} _siteId
+   * @returns {Promise<void>}
+   */
+  async clearClientId(_siteId) {
+    // NO-OP — symmetry with v1.1+ contract.
+  }
+
+  /**
+   * v1.0: not supported. Returns null per F.4.
+   * @param {string} _siteId
+   * @returns {Promise<null>}
+   */
+  async exportIdentity(_siteId) {
+    return null;
+  }
+
+  /**
+   * v1.0: not supported. Throws per F.4.
+   * @param {string} _siteId
+   * @param {object} _bundle
+   * @returns {Promise<never>}
+   */
+  async importIdentity(_siteId, _bundle) {
+    const err = new Error('Identity import not supported in v1.0. Upgrade to v1.1+.');
+    err.code = 'not_implemented';
+    throw err;
+  }
+}
+
+module.exports = { FreshEachTimeIdentityProvider };

package/lib/auth/http-json.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const https = require('node:https');
+const http = require('node:http');
+const { URL } = require('node:url');
+
+/**
+ * Minimal HTTP/JSON helper for OAuth endpoint calls.
+ *
+ * Behavior:
+ *   - HTTPS-required for non-localhost hosts; HTTP allowed only when
+ *     `allowInsecure: true` and the host is loopback.
+ *   - Default 30s timeout (Appendix H.2.1 mandate for token-manager; we mirror
+ *     it here for parity).
+ *   - Does NOT follow redirects on token / register / revoke / discovery
+ *     endpoints (mirrors H.2.3 posture).
+ *   - Returns `{ statusCode, headers, body, json }` where `json` is parsed
+ *     when content-type indicates JSON, else null.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function _buildOptions(parsed, method, headers, isHttps) {
+  return {
+    method,
+    hostname: parsed.hostname,
+    port: parsed.port || (isHttps ? 443 : 80),
+    path: parsed.pathname + parsed.search,
+    headers,
+  };
+}
+
+/**
+ * Send an HTTP(S) request and return the parsed response.
+ * @param {object} args
+ * @param {string} args.url
+ * @param {string} args.method                  GET | POST
+ * @param {object} [args.headers]
+ * @param {string|Buffer|null} [args.body]
+ * @param {boolean} [args.allowInsecure]
+ * @param {number}  [args.timeoutMs]
+ * @param {object}  [args.httpsAgent]           test injection
+ * @returns {Promise<{statusCode:number, headers:object, body:string, json:object|null}>}
+ */
+function request(args) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try { parsed = new URL(args.url); }
+    catch (err) { reject(new Error(`Invalid URL: ${args.url}`)); return; }
+
+    const isHttps = parsed.protocol === 'https:';
+    const isHttp = parsed.protocol === 'http:';
+    if (!isHttps && !isHttp) {
+      reject(new Error(`URL must be http(s): ${args.url}`));
+      return;
+    }
+    const isLocal = parsed.hostname === 'localhost'
+      || parsed.hostname === '127.0.0.1'
+      || parsed.hostname === '::1';
+    if (isHttp && !(isLocal && args.allowInsecure)) {
+      reject(new Error(`HTTPS required for ${args.url}`));
+      return;
+    }
+
+    const headers = Object.assign({ 'Accept': 'application/json' }, args.headers || {});
+    if (args.body && !headers['Content-Length']) {
+      headers['Content-Length'] = Buffer.byteLength(args.body);
+    }
+
+    const mod = isHttps ? https : http;
+    const reqOpts = _buildOptions(parsed, args.method || 'GET', headers, isHttps);
+    reqOpts.timeout = args.timeoutMs || DEFAULT_TIMEOUT_MS;
+    if (args.httpsAgent && isHttps) reqOpts.agent = args.httpsAgent;
+
+    const req = mod.request(reqOpts, (res) => {
+      // Do not auto-follow redirects on auth endpoints.
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        let json = null;
+        const ctype = (res.headers['content-type'] || '').toLowerCase();
+        if (ctype.includes('json') && body.length > 0) {
+          try { json = JSON.parse(body); } catch { /* leave null */ }
+        }
+        resolve({ statusCode: res.statusCode, headers: res.headers, body, json });
+      });
+      res.on('error', (err) => reject(err));
+    });
+
+    req.on('error', (err) => reject(err));
+    req.on('timeout', () => req.destroy(new Error(`Request timed out at ${reqOpts.timeout}ms: ${args.url}`)));
+    if (args.body) req.write(args.body);
+    req.end();
+  });
+}
+
+/**
+ * POST application/x-www-form-urlencoded — used by /oauth/token (RFC 6749).
+ */
+async function postForm(url, params, opts = {}) {
+  const body = new URLSearchParams(params).toString();
+  return request({
+    url,
+    method: 'POST',
+    headers: Object.assign(
+      { 'Content-Type': 'application/x-www-form-urlencoded' },
+      opts.headers || {}
+    ),
+    body,
+    allowInsecure: opts.allowInsecure,
+    timeoutMs: opts.timeoutMs,
+    httpsAgent: opts.httpsAgent,
+  });
+}
+
+/**
+ * POST application/json — used by /oauth/register (RFC 7591).
+ */
+async function postJson(url, body, opts = {}) {
+  const payload = typeof body === 'string' ? body : JSON.stringify(body);
+  return request({
+    url,
+    method: 'POST',
+    headers: Object.assign(
+      { 'Content-Type': 'application/json' },
+      opts.headers || {}
+    ),
+    body: payload,
+    allowInsecure: opts.allowInsecure,
+    timeoutMs: opts.timeoutMs,
+    httpsAgent: opts.httpsAgent,
+  });
+}
+
+/** GET — used by L2 GET-before-POST probes. */
+async function getJson(url, opts = {}) {
+  return request({
+    url,
+    method: 'GET',
+    headers: opts.headers,
+    allowInsecure: opts.allowInsecure,
+    timeoutMs: opts.timeoutMs,
+    httpsAgent: opts.httpsAgent,
+  });
+}
+
+module.exports = { request, postForm, postJson, getJson, DEFAULT_TIMEOUT_MS };