specshield 3.2.1 → 3.2.3

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 };

package/src/core/conformance/runner.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * Execute a set of conformance probes against the running provider.
+ * Pure function-ish: takes probes + an `http(method, url, opts)` adapter
+ * (so tests can inject without spinning a real HTTP client) and returns
+ * a structured result list.
+ *
+ *   ProbeResult = {
+ *     routePath:  '/users/{userId}',
+ *     method:     'GET',
+ *     resolvedPath: '/users/u-7',          // or null if skipped
+ *     status:     'PASS' | 'FAIL' | 'SKIPPED' | 'ERROR',
+ *     httpStatus: 200,                      // if reached
+ *     reason:     human-readable summary,
+ *     mismatches: [{path, message, expected, got}, …],  // only on FAIL
+ *     skipReason: 'unresolved path params: paymentId',  // only on SKIPPED
+ *     error:      'ECONNREFUSED …',                     // only on ERROR
+ *   }
+ *
+ *   RunSummary = { total, pass, fail, skipped, error }
+ */
+
+const { resolveProbePath, collectSpecExamples } = require('./pathResolver');
+const { pickResponseSchema } = require('./probeBuilder');
+const { validateBody }       = require('./responseValidator');
+
+/**
+ * @param spec        dereferenced OAS (used to gather param examples)
+ * @param probes      output of buildProbes(spec)
+ * @param opts.baseUrl       e.g. 'https://staging.payments.acme.com'
+ * @param opts.pathParams    { paymentId: 'pay-123', ... } CLI overrides
+ * @param opts.headers       request headers to send (e.g. auth)
+ * @param opts.http          async (method, url, {headers, timeoutMs}) → {status, body}
+ * @param opts.timeoutMs     default 8000
+ */
+async function runProbes(spec, probes, opts) {
+  const examples = collectSpecExamples(spec);
+  const results = [];
+  const http = opts.http;
+  const baseUrl = String(opts.baseUrl || '').replace(/\/$/, '');
+
+  for (const probe of probes) {
+    const { resolved, missing } = resolveProbePath(
+      probe.routePath, probe.method, examples, opts.pathParams,
+    );
+
+    if (missing.length > 0) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: null, status: 'SKIPPED',
+        reason: `unresolved path params (no --path-params or spec example)`,
+        skipReason: missing.join(', '),
+      });
+      continue;
+    }
+
+    const url = baseUrl + resolved;
+    let httpStatus, body, err;
+    try {
+      const r = await http(probe.method, url, {
+        headers: opts.headers || {},
+        timeoutMs: opts.timeoutMs || 8000,
+      });
+      httpStatus = r.status;
+      body = r.body;
+    } catch (e) {
+      err = e.message || String(e);
+    }
+
+    if (err) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'ERROR',
+        reason: 'HTTP call failed', error: err,
+      });
+      continue;
+    }
+
+    const schema = pickResponseSchema(probe, httpStatus);
+    if (schema === undefined) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'FAIL', httpStatus,
+        reason: `actual status ${httpStatus} is not documented in the spec`,
+        mismatches: [],
+      });
+      continue;
+    }
+    if (schema === null) {
+      // Status documented but no JSON schema — accept any response body.
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'PASS', httpStatus,
+        reason: 'status documented (no JSON schema to validate against)',
+        mismatches: [],
+      });
+      continue;
+    }
+
+    const { ok, errors } = validateBody(body, schema);
+    if (ok) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'PASS', httpStatus,
+        reason: 'response matches spec schema',
+        mismatches: [],
+      });
+    } else {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'FAIL', httpStatus,
+        reason: `response body does not match spec (${errors.length} mismatch${errors.length === 1 ? '' : 'es'})`,
+        mismatches: errors,
+      });
+    }
+  }
+
+  return { results, summary: summarise(results) };
+}
+
+function summarise(results) {
+  const s = { total: results.length, pass: 0, fail: 0, skipped: 0, error: 0 };
+  for (const r of results) {
+    if (r.status === 'PASS') s.pass++;
+    else if (r.status === 'FAIL') s.fail++;
+    else if (r.status === 'SKIPPED') s.skipped++;
+    else if (r.status === 'ERROR') s.error++;
+  }
+  return s;
+}
+
+module.exports = { runProbes, summarise };

package/src/core/har/emitOpenapi.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Group normalised HAR records by (method, templated-path) and emit an
+ * OpenAPI 3.0 document. Per-status response schemas are merged across all
+ * samples for that group so the emitted contract describes what the
+ * consumer ACTUALLY read across the captured run — not just one example.
+ */
+
+const { templatePath } = require('./pathTemplate');
+const { inferSchema, mergeSchemas } = require('./schemaInfer');
+
+/**
+ * @param records normalised HAR records (output of normaliseEntries())
+ * @param opts    { title, version, baseUrl, dynamicPatterns }
+ * @returns       OpenAPI 3.0 document (plain JS object)
+ */
+function harToOpenapi(records, opts = {}) {
+  const groups = new Map();   // key: "METHOD /templated/path"
+
+  for (const r of records) {
+    const { templated, paramNames } = templatePath(r.path, {
+      dynamicPatterns: opts.dynamicPatterns,
+    });
+    const key = `${r.method} ${templated}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = {
+        method: r.method.toLowerCase(),
+        path: templated,
+        paramNames,
+        requestSchema: undefined,
+        responses: new Map(),    // status → merged schema (or null = saw status, no JSON body)
+      };
+      groups.set(key, g);
+    }
+
+    if (r.requestBody !== undefined) {
+      const sample = inferSchema(r.requestBody);
+      g.requestSchema = g.requestSchema ? mergeSchemas(g.requestSchema, sample) : sample;
+    }
+
+    if (r.responseStatus) {
+      const status = String(r.responseStatus);
+      const schema = r.responseBody !== undefined ? inferSchema(r.responseBody) : null;
+      if (schema) {
+        const existing = g.responses.get(status);
+        g.responses.set(status, existing ? mergeSchemas(existing, schema) : schema);
+      } else if (!g.responses.has(status)) {
+        g.responses.set(status, null);
+      }
+    }
+  }
+
+  // Build the OpenAPI doc.
+  const paths = {};
+  for (const g of groups.values()) {
+    const pItem = paths[g.path] || (paths[g.path] = {});
+    const op = {};
+
+    if (g.paramNames.length > 0) {
+      op.parameters = g.paramNames.map(name => ({
+        name, in: 'path', required: true, schema: { type: 'string' },
+      }));
+    }
+
+    if (g.requestSchema) {
+      op.requestBody = {
+        required: true,
+        content: { 'application/json': { schema: g.requestSchema } },
+      };
+    }
+
+    const responses = {};
+    if (g.responses.size === 0) {
+      responses['200'] = { description: 'OK' };
+    } else {
+      // Sort numerically for stable output.
+      const statuses = [...g.responses.keys()].sort((a, b) => Number(a) - Number(b));
+      for (const status of statuses) {
+        const schema = g.responses.get(status);
+        const r = { description: defaultDescriptionFor(status) };
+        if (schema) r.content = { 'application/json': { schema } };
+        responses[status] = r;
+      }
+    }
+    op.responses = responses;
+
+    pItem[g.method] = op;
+  }
+
+  const doc = {
+    openapi: '3.0.0',
+    info: {
+      title: opts.title || 'Captured consumer contract',
+      version: opts.version || '0.1.0',
+      description:
+        'Generated by `specshield bdct capture` from recorded HAR traffic. ' +
+        'Reflects only the endpoints/fields the consumer actually called/read.',
+    },
+    paths: sortObject(paths),   // stable, alphabetical output
+  };
+  if (opts.baseUrl) doc.servers = [{ url: String(opts.baseUrl) }];
+  // Re-order top-level so `servers` appears between `info` and `paths` (idiomatic).
+  if (opts.baseUrl) {
+    return { openapi: doc.openapi, info: doc.info, servers: doc.servers, paths: doc.paths };
+  }
+  return doc;
+}
+
+function defaultDescriptionFor(status) {
+  const n = Number(status);
+  if (n >= 200 && n < 300) return 'Successful response';
+  if (n >= 300 && n < 400) return 'Redirection';
+  if (n >= 400 && n < 500) return 'Client error';
+  if (n >= 500)            return 'Server error';
+  return 'Response';
+}
+
+function sortObject(o) {
+  if (!o || typeof o !== 'object') return o;
+  return Object.keys(o).sort().reduce((acc, k) => { acc[k] = o[k]; return acc; }, {});
+}
+
+module.exports = { harToOpenapi };

package/src/core/har/index.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * One-call orchestrator for `specshield bdct capture from-har`. Read a HAR
+ * file → produce an OpenAPI 3.0 document (text + parsed) + a small summary
+ * the CLI can print.
+ *
+ * This is Phase 1 of Fix 2 (the BDCT fidelity-roadmap "capture" feature):
+ * HAR ingest specifically — language-agnostic, no TLS-proxy gymnastics.
+ * Later phases can layer on live capture (Node `--require` interceptor,
+ * full mitm proxy) without changing the downstream pipeline.
+ */
+
+const yaml = require('js-yaml');
+const { readHarFile, normaliseEntries } = require('./parseHar');
+const { harToOpenapi } = require('./emitOpenapi');
+
+/**
+ * @param filepath  path to a HAR file
+ * @param opts      { baseUrl, methods, onlyJson, title, version, format,
+ *                    dynamicPatterns }
+ * @returns         { text, doc, summary }
+ *
+ *   text     — the OpenAPI document serialised (default: YAML)
+ *   doc      — the same document as a JS object
+ *   summary  — { harEntries, recordsKept, endpoints, operations }
+ */
+function captureFromHarFile(filepath, opts = {}) {
+  const har = readHarFile(filepath);
+  const records = normaliseEntries(har, {
+    baseUrl: opts.baseUrl,
+    methods: opts.methods,
+    onlyJson: opts.onlyJson,
+  });
+  const doc = harToOpenapi(records, {
+    title: opts.title,
+    version: opts.version,
+    baseUrl: opts.baseUrl,
+    dynamicPatterns: opts.dynamicPatterns,
+  });
+
+  const fmt = String(opts.format || 'yaml').toLowerCase();
+  const text = fmt === 'json'
+    ? JSON.stringify(doc, null, 2) + '\n'
+    : yaml.dump(doc, { noRefs: true, sortKeys: false, lineWidth: 120 });
+
+  return {
+    text,
+    doc,
+    summary: {
+      harEntries: har.log.entries.length,
+      recordsKept: records.length,
+      endpoints: Object.keys(doc.paths || {}).length,
+      operations: countOperations(doc),
+    },
+  };
+}
+
+function countOperations(doc) {
+  let n = 0;
+  const methods = ['get','post','put','patch','delete','head','options','trace'];
+  for (const item of Object.values(doc.paths || {})) {
+    for (const k of Object.keys(item)) if (methods.includes(k)) n++;
+  }
+  return n;
+}
+
+module.exports = { captureFromHarFile };