specshield 3.2.2 → 3.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating, GitHub PR checks, and a first-run setup wizard.",
   "main": "src/cli.js",
   "bin": {
@@ -54,6 +54,9 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "axios": "^1.6.7",
     "chalk": "^4.1.2",
     "commander": "^12.0.0",

package/src/cli.js

@@ -9,6 +9,7 @@ const logoutCommand = require('./commands/logout');
 const bdctCommand = require('./commands/bdct');
 const historyCommand = require('./commands/history');
 const shareCommand = require('./commands/share');
+const whoamiCommand = require('./commands/whoami');
 
 const program = new Command();
 
@@ -28,6 +29,7 @@ program.addCommand(logoutCommand);
 program.addCommand(bdctCommand);
 program.addCommand(historyCommand);
 program.addCommand(shareCommand);
+program.addCommand(whoamiCommand);
 
 program.parseAsync(process.argv).catch((err) => {
   const logger = require('./utils/logger');

package/src/commands/bdct.js

@@ -689,6 +689,164 @@ const listConsumersCommand = new Command('list-consumers')
     }
   });
 
+// ─── capture (Fix 2 — turn recorded traffic into a consumer contract) ────────
+// Reads a HAR file (any browser/Cypress/Playwright/k6 can export one) and
+// emits an OpenAPI 3.0 consumer-contract subset describing only the
+// endpoints/fields the consumer actually called/read. Pure local CLI work —
+// no API token required.
+
+const captureFromHarCommand = new Command('from-har')
+  .description('Generate a consumer OpenAPI contract from a recorded HAR file')
+  .requiredOption('--in <path>',          'Input HAR file (HTTP Archive 1.2)')
+  .option('--out <path>',                 'Output file (default: write to stdout)')
+  .option('--base-url <url>',             'Keep only entries matching this URL prefix (e.g. https://api.acme.com or https://api.acme.com/v1)')
+  .option('--method <verbs>',             'Comma-separated methods to include (e.g. GET,POST). Default: all')
+  .option('--title <title>',              'OpenAPI info.title', 'Captured consumer contract')
+  .option('--version <ver>',              'OpenAPI info.version', '0.1.0')
+  .option('--format <fmt>',               'Output format: yaml | json', 'yaml')
+  .option('--include-non-json',           'Keep entries with non-JSON bodies (default: drop them)')
+  .action(async (opts) => {
+    const { captureFromHarFile } = require('../core/har');
+    const inputPath = path.resolve(opts.in);
+    if (!fsExtra.existsSync(inputPath)) {
+      logger.error(`HAR file not found: ${inputPath}`);
+      process.exit(2);
+    }
+    const methods = opts.method
+      ? opts.method.split(',').map(s => s.trim()).filter(Boolean)
+      : undefined;
+
+    let result;
+    try {
+      result = captureFromHarFile(inputPath, {
+        baseUrl: opts.baseUrl,
+        methods,
+        onlyJson: !opts.includeNonJson,
+        title: opts.title,
+        version: opts.version,
+        format: opts.format,
+      });
+    } catch (err) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+
+    if (opts.out) {
+      const outPath = path.resolve(opts.out);
+      fsExtra.outputFileSync(outPath, result.text);
+      process.stderr.write(chalk.green('✔ ') +
+        `Wrote ${chalk.cyan(opts.out)}  ` +
+        chalk.gray(`(${result.summary.endpoints} endpoints, ${result.summary.operations} ops from ${result.summary.recordsKept}/${result.summary.harEntries} entries)`) + '\n');
+    } else {
+      process.stdout.write(result.text);
+      process.stderr.write(chalk.gray(
+        `# ${result.summary.endpoints} endpoints, ${result.summary.operations} ops from ${result.summary.recordsKept}/${result.summary.harEntries} HAR entries\n`
+      ));
+    }
+  });
+
+const captureCommand = new Command('capture')
+  .description('Capture a consumer OpenAPI contract from observed traffic (currently: HAR ingest)');
+captureCommand.addCommand(captureFromHarCommand);
+
+// ─── verify-provider (Fix 3 — spec-vs-production conformance) ─────────────────
+// Fires probes derived from the OpenAPI spec at the running provider and
+// validates that every response body actually matches its documented schema.
+// Pure local CLI work (calls the customer's service directly); no API token.
+// Safe-by-default: only GET/HEAD/OPTIONS unless --include-mutating.
+
+const verifyProviderCommand = new Command('verify-provider')
+  .description('Check that a running provider service matches its OpenAPI spec')
+  .requiredOption('--spec <path>',         'Path to the provider OpenAPI spec (YAML or JSON)')
+  .requiredOption('--base-url <url>',      'Base URL of the running provider, e.g. https://staging.payments.acme.com')
+  .option('--include-mutating',            'Also probe POST/PUT/PATCH/DELETE (off by default for safety)')
+  .option('--path-params <kvList>',        'Resolve path params: name=val,other=val (overrides spec examples)', collectPathParams, {})
+  .option('--header <header>',             'Extra request header to send, e.g. "Authorization: Bearer X" (repeatable)', collectHeaders, {})
+  .option('--timeout-ms <ms>',             'Per-request timeout in ms', v => parseInt(v, 10), 8000)
+  .option('--json',                        'Output raw JSON instead of the human report')
+  .action(async (opts) => {
+    const { verifyProvider } = require('../core/conformance');
+    const specPath = path.resolve(opts.spec);
+    if (!fsExtra.existsSync(specPath)) {
+      logger.error(`Spec file not found: ${specPath}`);
+      process.exit(2);
+    }
+    const spinner = opts.json ? null : ora('Probing provider…').start();
+    let report;
+    try {
+      report = await verifyProvider({
+        spec: specPath,
+        baseUrl: opts.baseUrl,
+        includeMutating: !!opts.includeMutating,
+        pathParams: opts.pathParams,
+        headers: opts.header,
+        timeoutMs: opts.timeoutMs,
+      });
+    } catch (err) {
+      if (spinner) spinner.fail('Conformance run failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+    if (spinner) spinner.stop();
+
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+      process.exit(report.summary.fail + report.summary.error > 0 ? 1 : 0);
+    }
+
+    // Human report.
+    process.stdout.write('\n' + chalk.bold('  Provider conformance — spec vs ') + chalk.cyan(opts.baseUrl) + '\n');
+    process.stdout.write('  ' + '─'.repeat(60) + '\n');
+    for (const r of report.results) {
+      const label = `${r.method.padEnd(6)} ${r.routePath}`;
+      const tag =
+        r.status === 'PASS'    ? chalk.green('  PASS  ') :
+        r.status === 'FAIL'    ? chalk.red('  FAIL  ')   :
+        r.status === 'ERROR'   ? chalk.red(' ERROR  ')   :
+                                  chalk.yellow(' SKIP   ');
+      process.stdout.write(`  ${tag} ${label}` +
+        (r.httpStatus ? chalk.gray(`  (${r.httpStatus})`) : '') + '\n');
+      if (r.status === 'FAIL' && r.mismatches && r.mismatches.length > 0) {
+        for (const m of r.mismatches.slice(0, 5)) {
+          process.stdout.write(chalk.gray(`           ${m.path || '(root)'}: ${m.message}\n`));
+        }
+        if (r.mismatches.length > 5) {
+          process.stdout.write(chalk.gray(`           …and ${r.mismatches.length - 5} more\n`));
+        }
+      } else if (r.status === 'FAIL' && r.reason) {
+        process.stdout.write(chalk.gray(`           ${r.reason}\n`));
+      } else if (r.status === 'ERROR') {
+        process.stdout.write(chalk.gray(`           ${r.error}\n`));
+      } else if (r.status === 'SKIPPED') {
+        process.stdout.write(chalk.gray(`           ${r.reason}: ${r.skipReason}\n`));
+      }
+    }
+    const s = report.summary;
+    process.stdout.write('  ' + '─'.repeat(60) + '\n');
+    process.stdout.write(`  ${s.pass} pass · ${s.fail} fail · ${s.error} error · ${s.skipped} skip   (${s.total} probes)\n\n`);
+    process.exit(s.fail + s.error > 0 ? 1 : 0);
+  });
+
+// Repeatable --header parser: collects into a map.
+function collectHeaders(val, acc) {
+  const idx = val.indexOf(':');
+  if (idx < 0) return acc;
+  const k = val.slice(0, idx).trim();
+  const v = val.slice(idx + 1).trim();
+  if (k) acc[k] = v;
+  return acc;
+}
+
+// --path-params name=val,name=val parser: merges into the accumulator so the
+// flag can be passed multiple times.
+function collectPathParams(val, acc) {
+  for (const pair of String(val).split(',')) {
+    const [k, ...rest] = pair.split('=');
+    if (k && k.trim()) acc[k.trim()] = rest.join('=').trim();
+  }
+  return acc;
+}
+
 // ─── Parent bdct command ──────────────────────────────────────────────────────
 
 const bdct = new Command('bdct')
@@ -702,5 +860,7 @@ bdct.addCommand(listCommand);
 bdct.addCommand(matrixCommand);
 bdct.addCommand(listProvidersCommand);
 bdct.addCommand(listConsumersCommand);
+bdct.addCommand(captureCommand);
+bdct.addCommand(verifyProviderCommand);
 
 module.exports = bdct;

package/src/commands/whoami.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * `specshield whoami` — print the active customer's identity and the list of
+ * organizations they can use as `--org` values. Reuses /auth/validate-api-key
+ * (for the customer summary) and /me/orgs (for the org list) — the same two
+ * endpoints the init wizard hits.
+ *
+ * Why it exists: the dashboard now surfaces orgKey, but terminal-native users
+ * and CI engineers shouldn't have to open a browser to discover what their
+ * org_key is. This command makes it a one-line lookup.
+ *
+ * Resolves the API token the same way every other command does:
+ *   --api-token flag  >  $SPECSHIELD_API_KEY  >  stored ~/.specshield/config.json
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const axios = require('axios');
+const logger = require('../utils/logger');
+const { getStoredApiKey } = require('../config/localConfig');
+
+const DEFAULT_SERVER = 'https://specshield.io';
+
+const whoami = new Command('whoami');
+
+whoami
+  .description('Show the signed-in customer and the orgKeys you can use as --org')
+  .option('--api-token <key>', 'Override stored / env API token for this call')
+  .option('--server <url>',    'Override the SpecShield server URL', DEFAULT_SERVER)
+  .option('--json',            'Output machine-readable JSON instead of a table')
+  .action(async (opts) => {
+    const token = opts.apiToken
+      || process.env.SPECSHIELD_API_KEY
+      || (await getStoredApiKey());
+    if (!token) {
+      logger.error('Not logged in. Run: specshield login --api-key <KEY>');
+      process.exit(2);
+    }
+
+    const server = (opts.server || DEFAULT_SERVER).replace(/\/$/, '');
+    const headers = { 'X-Api-Key': token, 'X-SpecShield-Client': 'cli' };
+
+    let me, orgs;
+    try {
+      const meRes = await axios.post(`${server}/auth/validate-api-key`, {}, { headers, timeout: 8000 });
+      if (!meRes.data || !meRes.data.valid) {
+        logger.error('API key did not validate against ' + server);
+        process.exit(2);
+      }
+      me = meRes.data;
+    } catch (err) {
+      logger.error(err.response
+        ? `Failed to validate token: ${err.response.status} ${JSON.stringify(err.response.data)}`
+        : `Could not reach ${server}: ${err.message}`);
+      process.exit(2);
+    }
+
+    try {
+      const orgsRes = await axios.get(`${server}/me/orgs`, { headers, timeout: 8000 });
+      orgs = Array.isArray(orgsRes.data) ? orgsRes.data : (orgsRes.data?.orgs || []);
+    } catch (err) {
+      // Org fetch is best-effort; the customer info already printed below
+      // is the more important part.
+      orgs = [];
+    }
+
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({
+        customer: { name: me.name, email: me.email, plan: me.plan, customerId: me.customerId },
+        server,
+        orgs: orgs.map(o => ({ orgKey: o.orgKey, name: o.name, role: o.myRole || o.role || null })),
+      }, null, 2) + '\n');
+      return;
+    }
+
+    // Human-readable output. Two sections — identity, then orgs table.
+    process.stdout.write('\n');
+    process.stdout.write(`  ${chalk.bold('Logged in as:')} ${me.name || '(no name)'} `);
+    if (me.email) process.stdout.write(chalk.gray(`(${me.email})`));
+    process.stdout.write(`   ${chalk.gray('· plan:')} ${chalk.cyan(me.plan || 'FREE')}\n`);
+    process.stdout.write(`  ${chalk.gray('Server:')}       ${server}\n`);
+    process.stdout.write('\n');
+
+    if (orgs.length === 0) {
+      process.stdout.write(chalk.yellow('  You are not a member of any organization yet.\n'));
+      process.stdout.write(chalk.gray(`  Create one at ${server}/account/team to get an org_key.\n\n`));
+      return;
+    }
+
+    process.stdout.write(`  ${chalk.bold('Organizations you can use as --org:')}\n`);
+    process.stdout.write(chalk.gray('  ─────────────────────────────────────────────────────\n'));
+    const widestKey = Math.max(...orgs.map(o => (o.orgKey || '').length), 8);
+    for (const o of orgs) {
+      const key  = (o.orgKey || '').padEnd(widestKey);
+      const role = o.myRole || o.role || '';
+      process.stdout.write(
+        `    ${chalk.cyan(key)}   ${o.name || ''}` +
+        (role ? `   ${chalk.gray('(' + role + ')')}` : '') + '\n');
+    }
+    process.stdout.write('\n');
+    process.stdout.write(chalk.gray(`  Tip: paste an org_key into --org on CLI commands or bdct.org in .specshield.yml\n\n`));
+  });
+
+module.exports = whoami;

package/src/core/conformance/index.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * One-call orchestrator for `specshield bdct verify-provider` — the
+ * "spec-vs-production conformance" check (Fix 3 of the BDCT fidelity
+ * roadmap).
+ *
+ * Loads + dereferences an OpenAPI spec, derives a probe list (safe methods
+ * only by default), fires the probes at the running provider, validates
+ * each response body against the spec's schema for that status, and
+ * returns a structured result + summary.
+ *
+ * Defaults are deliberately conservative — this tool is pointed at REAL
+ * customer services (typically staging, sometimes prod), so:
+ *
+ *   - Only GET / HEAD / OPTIONS unless `includeMutating: true`.
+ *   - Probes whose path params can't be resolved are SKIPPED, not guessed.
+ *   - Network errors are reported as ERROR results — never thrown — so a
+ *     single flaky endpoint doesn't kill the whole run.
+ */
+
+const axios = require('axios');
+const SwaggerParser = require('@apidevtools/swagger-parser');
+const { buildProbes } = require('./probeBuilder');
+const { runProbes }   = require('./runner');
+
+async function verifyProvider(opts) {
+  const spec = await SwaggerParser.dereference(opts.spec);
+  const probes = buildProbes(spec, { includeMutating: !!opts.includeMutating });
+  const http = opts.http || defaultHttpAdapter;
+  return runProbes(spec, probes, {
+    baseUrl: opts.baseUrl,
+    pathParams: opts.pathParams,
+    headers: opts.headers,
+    timeoutMs: opts.timeoutMs,
+    http,
+  });
+}
+
+/** Default HTTP adapter (axios). Returns { status, body } and rejects only
+ *  on connection-level failures — HTTP error statuses come back as data. */
+async function defaultHttpAdapter(method, url, { headers, timeoutMs }) {
+  const res = await axios.request({
+    method, url, headers, timeout: timeoutMs,
+    validateStatus: () => true,    // never throw on 4xx/5xx; the validator decides
+    responseType: 'json',
+    transitional: { silentJSONParsing: true, forcedJSONParsing: true },
+  });
+  return { status: res.status, body: res.data };
+}
+
+module.exports = { verifyProvider, defaultHttpAdapter };

package/src/core/conformance/pathResolver.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * Resolve OpenAPI path-template parameters into concrete URL paths.
+ * Sources, in priority order:
+ *   1. caller-supplied overrides (e.g. CLI `--path-params paymentId=pay-123`)
+ *   2. the operation's `parameters[].example` for each path-param
+ *   3. the path-item-level `parameters[].example`
+ *   4. the parameter schema's `example`
+ *
+ * If a required path param can't be resolved, the probe is skipped (with a
+ * `missing` list so the runner can report it).
+ */
+
+/**
+ * @param template     '/users/{userId}/orders/{orderId}'
+ * @param resolvedMap  { userId: 'u-1', orderId: 'o-7' }   (already-resolved)
+ * @returns            { resolved: string, missing: string[] }
+ */
+function substitute(template, resolvedMap) {
+  const missing = [];
+  const resolved = template.replace(/\{([^}]+)\}/g, (_full, name) => {
+    const v = resolvedMap && Object.prototype.hasOwnProperty.call(resolvedMap, name)
+      ? resolvedMap[name]
+      : undefined;
+    if (v === undefined || v === null || v === '') { missing.push(name); return `{${name}}`; }
+    return encodeURIComponent(String(v));
+  });
+  return { resolved, missing };
+}
+
+/**
+ * Walk the spec to gather examples for path params. Returns a map per-route:
+ *   { '/users/{userId}': { GET: { userId: 'u-1' }, … }, … }
+ *
+ * Operation-level params override path-item-level params (standard OAS rule).
+ */
+function collectSpecExamples(spec) {
+  const out = {};
+  const paths = (spec && spec.paths) || {};
+  const METHODS = ['get','put','post','delete','options','head','patch','trace'];
+
+  for (const [routePath, item] of Object.entries(paths)) {
+    if (!item || typeof item !== 'object') continue;
+    out[routePath] = {};
+
+    const pathLevelParams = Array.isArray(item.parameters) ? item.parameters : [];
+    for (const method of METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== 'object') continue;
+      const opParams = Array.isArray(op.parameters) ? op.parameters : [];
+
+      const merged = {};
+      for (const p of pathLevelParams) addExample(merged, p);
+      for (const p of opParams)        addExample(merged, p);   // op overrides
+      out[routePath][method.toUpperCase()] = merged;
+    }
+  }
+  return out;
+}
+
+function addExample(target, param) {
+  if (!param || param.in !== 'path' || !param.name) return;
+  const ex = param.example
+         ?? (param.examples && firstExampleValue(param.examples))
+         ?? (param.schema && param.schema.example);
+  if (ex !== undefined) target[param.name] = ex;
+}
+
+function firstExampleValue(examples) {
+  for (const v of Object.values(examples || {})) {
+    if (v && v.value !== undefined) return v.value;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a single probe's path. CLI overrides win over spec examples.
+ *
+ * @param routePath        '/users/{userId}'
+ * @param method           'GET'
+ * @param specExamples     output of collectSpecExamples(spec)
+ * @param cliOverrides     { userId: 'u-7', ... } (global)
+ */
+function resolveProbePath(routePath, method, specExamples, cliOverrides) {
+  const fromSpec = (specExamples[routePath] && specExamples[routePath][method.toUpperCase()]) || {};
+  const merged = { ...fromSpec, ...(cliOverrides || {}) };
+  return substitute(routePath, merged);
+}
+
+/**
+ * Parse a CLI string `paymentId=pay-123,userId=u-7` into a map.
+ * Multiple `--path-params` flags can be joined by the caller before parsing.
+ */
+function parsePathParamsArg(arg) {
+  if (!arg) return {};
+  const map = {};
+  for (const pair of String(arg).split(',')) {
+    const [k, ...rest] = pair.split('=');
+    if (!k) continue;
+    map[k.trim()] = rest.join('=').trim();
+  }
+  return map;
+}
+
+module.exports = {
+  substitute, collectSpecExamples, resolveProbePath, parsePathParamsArg,
+};

package/src/core/conformance/probeBuilder.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Build a flat list of conformance probes from a dereferenced OAS document.
+ *
+ *   Probe = {
+ *     routePath:    '/users/{userId}',
+ *     method:       'GET',
+ *     operationId:  string | undefined,
+ *     expectedResponses: { '200': schema, '404': schema, default?: schema },
+ *     responseHeadersForStatus: { '200': { 'X-RateLimit-Remaining': { schema } } },
+ *   }
+ *
+ * Safety: by default we only probe **safe** methods (GET, HEAD, OPTIONS).
+ * Mutating verbs are opt-in via `includeMutating: true` so we never
+ * accidentally side-effect a customer's staging data.
+ */
+
+const SAFE_METHODS    = new Set(['get', 'head', 'options']);
+const ALL_METHODS     = ['get','put','post','delete','options','head','patch','trace'];
+const JSON_MIME       = /\bjson\b/i;
+
+/**
+ * @param spec               dereferenced OAS document
+ * @param opts.includeMutating   default false
+ * @returns Probe[]
+ */
+function buildProbes(spec, opts = {}) {
+  const includeMutating = opts.includeMutating === true;
+  const allowed = includeMutating ? new Set(ALL_METHODS) : SAFE_METHODS;
+  const out = [];
+
+  const paths = (spec && spec.paths) || {};
+  for (const [routePath, item] of Object.entries(paths)) {
+    if (!item || typeof item !== 'object') continue;
+    for (const method of ALL_METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== 'object') continue;
+      if (!allowed.has(method)) continue;
+
+      out.push({
+        routePath,
+        method: method.toUpperCase(),
+        operationId: op.operationId,
+        expectedResponses: extractResponses(op.responses || {}),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * { '200': { content: { 'application/json': { schema } } }, '4XX': … }
+ * →
+ * { '200': schema | null, '4XX': schema | null, default?: schema | null }
+ *
+ * Pulls the JSON-content schema only (other content types deferred).
+ */
+function extractResponses(responses) {
+  const out = {};
+  for (const [code, body] of Object.entries(responses)) {
+    if (!body) continue;
+    const content = body.content || {};
+    let schema = null;
+    for (const [mime, c] of Object.entries(content)) {
+      if (JSON_MIME.test(mime) && c && c.schema) { schema = c.schema; break; }
+    }
+    out[code] = schema;       // null = "documented status, no JSON schema"
+  }
+  return out;
+}
+
+/**
+ * Match an actual response status (e.g. 200) against the spec's response keys
+ * (which can be exact `"200"`, wildcard `"2XX"`, or `"default"`).
+ * Returns the matching schema (possibly null) or undefined if nothing matches.
+ */
+function pickResponseSchema(probe, actualStatus) {
+  const r = probe.expectedResponses;
+  const code = String(actualStatus);
+  if (Object.prototype.hasOwnProperty.call(r, code)) return r[code];
+  const wildcard = code[0] + 'XX';
+  if (Object.prototype.hasOwnProperty.call(r, wildcard)) return r[wildcard];
+  if (Object.prototype.hasOwnProperty.call(r, wildcard.toLowerCase())) return r[wildcard.toLowerCase()];
+  if (Object.prototype.hasOwnProperty.call(r, 'default')) return r['default'];
+  return undefined;
+}
+
+module.exports = {
+  buildProbes, extractResponses, pickResponseSchema,
+  SAFE_METHODS, ALL_METHODS,
+};

package/src/core/conformance/responseValidator.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Validate an actual HTTP response body against the OAS response schema —
+ * the core of Fix 3 (spec-vs-production conformance).
+ *
+ * OpenAPI 3.0 schemas are a *modified subset* of JSON Schema. ajv validates
+ * standard JSON Schema, so we normalise OAS-isms first:
+ *
+ *   - `nullable: true`     → union with null (`type: [x, 'null']`)
+ *   - `example`, `examples`, `xml`, `discriminator`, `readOnly`, `writeOnly`,
+ *     `deprecated`, `externalDocs`              → stripped (annotations only)
+ *
+ * Anything else (allOf/oneOf/anyOf/not, formats, enums, required, additional-
+ * Properties) passes through to ajv unchanged.
+ *
+ * Format keywords (date-time, uuid, email, …) are handled by ajv-formats.
+ */
+
+const Ajv = require('ajv').default;
+const addFormats = require('ajv-formats');
+
+// One ajv per-validator-call would be slow; cache compiled validators by
+// schema reference. Lifetime is the process — for the CLI that's fine.
+const ajv = new Ajv({
+  strict: false,           // OAS allows non-standard keywords; don't fail compile
+  allErrors: true,         // collect every mismatch, not just the first
+  validateFormats: true,
+  coerceTypes: false,      // a body field that's "1" when spec says integer = mismatch
+});
+addFormats(ajv);
+
+const compiledCache = new WeakMap();
+
+function compile(schema) {
+  if (compiledCache.has(schema)) return compiledCache.get(schema);
+  const normalised = oasToJsonSchema(schema);
+  const fn = ajv.compile(normalised);
+  compiledCache.set(schema, fn);
+  return fn;
+}
+
+/** Recursively rewrite OAS-3.0 quirks into plain JSON Schema. */
+function oasToJsonSchema(node) {
+  if (node === null || typeof node !== 'object') return node;
+  if (Array.isArray(node)) return node.map(oasToJsonSchema);
+
+  // Drop OAS-only annotations that confuse ajv (or are no-ops for validation).
+  const STRIP = new Set([
+    'example', 'examples', 'xml', 'discriminator',
+    'readOnly', 'writeOnly', 'deprecated', 'externalDocs',
+  ]);
+
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (STRIP.has(k)) continue;
+    if (k === 'nullable') continue;            // handled below
+    out[k] = oasToJsonSchema(v);
+  }
+
+  // `nullable: true` → widen type to also permit null. JSON Schema 2020-12 +
+  // ajv accept `type: [...]` arrays.
+  if (node.nullable === true && out.type) {
+    if (Array.isArray(out.type)) {
+      if (!out.type.includes('null')) out.type = [...out.type, 'null'];
+    } else {
+      out.type = [out.type, 'null'];
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Validate one body against one schema.
+ * Returns { ok: true } on pass; otherwise { ok: false, errors: [...] } where
+ * each error is { path, message, expected?, got? } — caller-friendly format.
+ */
+function validateBody(body, schema) {
+  if (!schema) return { ok: true, errors: [] };
+  let validate;
+  try { validate = compile(schema); }
+  catch (e) {
+    return { ok: false, errors: [{
+      path: '', message: `spec schema is invalid: ${e.message}`,
+    }]};
+  }
+  const ok = validate(body);
+  if (ok) return { ok: true, errors: [] };
+  return {
+    ok: false,
+    errors: (validate.errors || []).map(e => ({
+      path: e.instancePath || '(root)',
+      keyword: e.keyword,                       // 'enum' | 'required' | 'type' | 'format' | …
+      message: e.message || 'validation failed',
+      expected: e.params,                       // ajv's params, e.g. { allowedValues, missingProperty, format, type }
+      got: peek(body, e.instancePath),
+    })),
+  };
+}
+
+/** Best-effort: extract the value at a JSON-Pointer-style path for the error. */
+function peek(body, jsonPointer) {
+  if (!jsonPointer || jsonPointer === '') return body;
+  const parts = jsonPointer.split('/').slice(1).map(p => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = body;
+  for (const p of parts) {
+    if (cur === null || cur === undefined) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+module.exports = { validateBody, oasToJsonSchema };