swaggerizer 1.0.0 → 1.1.0

package/dist/cli.js

@@ -11,6 +11,9 @@ var os = require('node:os');
 var SwaggerParser = require('@apidevtools/swagger-parser');
 var http = require('node:http');
 var node_url = require('node:url');
+var Ajv = require('ajv');
+var Ajv2020 = require('ajv/dist/2020');
+var addFormats = require('ajv-formats');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /*
@@ -1857,6 +1860,23 @@ function sendJson(res, status, payload) {
 function blank(value) {
     return value === undefined || value === null || value === "";
 }
+/** MSW reports request summaries to the live log; keep only the fields the page renders. */
+function toValidation(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const text = (value, max = 200) => typeof value === "string" && value !== "" ? value.slice(0, max) : undefined;
+    const request = (Array.isArray(raw.request) ? raw.request : [])
+        .slice(0, 20)
+        .map((issue) => ({
+        location: text(issue?.location, 120) ?? "request",
+        message: text(issue?.message) ?? "is invalid",
+        ...(text(issue?.keyword, 40) ? { keyword: text(issue?.keyword, 40) } : {})
+    }));
+    const skipped = text(raw.skipped, 60);
+    if (request.length === 0 && !skipped)
+        return undefined;
+    return { request, ...(skipped ? { skipped } : {}) };
+}
 /**
  * Turns a flat record (query string, form post or JSON) into a selection. Accepts the ramlizer
  * names (`nextResponseCode`, `nextExampleName`) and flat custom fields (`status`, `body`, `contentType`).
@@ -1951,6 +1971,10 @@ function registerAdmin(ctx) {
                 sendJson(res, 200, { changes: ctx.getState().changes });
                 return true;
             }
+            if (method === "GET" && path === "/api/validation") {
+                sendJson(res, 200, ctx.getValidation());
+                return true;
+            }
             if (path === "/api/log") {
                 if (method === "GET") {
                     const since = Number(query.get("since") || 0);
@@ -1960,16 +1984,20 @@ function registerAdmin(ctx) {
                 if (method === "POST") {
                     // Lets the MSW runtime report requests it answered in the browser or in tests.
                     const items = Array.isArray(req.body) ? req.body : [req.body];
-                    const entries = items.slice(0, 50).map(item => ctx.recordRequest({
-                        method: String(item?.method || "GET").toUpperCase(),
-                        path: String(item?.path || ""),
-                        ...(item?.route ? { route: String(item.route) } : {}),
-                        status: Number(item?.status) || 0,
-                        example: String(item?.example || ""),
-                        ...(item?.specId ? { specId: String(item.specId) } : {}),
-                        ...(item?.ms !== undefined ? { ms: Number(item.ms) } : {}),
-                        source: "msw"
-                    }));
+                    const entries = items.slice(0, 50).map(item => {
+                        const validation = toValidation(item?.validation);
+                        return ctx.recordRequest({
+                            method: String(item?.method || "GET").toUpperCase(),
+                            path: String(item?.path || ""),
+                            ...(item?.route ? { route: String(item.route) } : {}),
+                            status: Number(item?.status) || 0,
+                            example: String(item?.example || ""),
+                            ...(item?.specId ? { specId: String(item.specId) } : {}),
+                            ...(item?.ms !== undefined ? { ms: Number(item.ms) } : {}),
+                            ...(validation ? { validation } : {}),
+                            source: "msw"
+                        });
+                    });
                     sendJson(res, 200, { recorded: entries.length });
                     return true;
                 }
@@ -2003,6 +2031,490 @@ function registerAdmin(ctx) {
     return { handle, uiAvailable: ctx.ui && assets.available };
 }
 
+/*
+ * Request validation: checks a matched request against the operation's declared parameters and
+ * request body, so a mock cannot answer `200` to a request the contract forbids.
+ *
+ * Node only. Ajv must never reach the browser entry points (`msw`, `debug-menu`, `config`), which is
+ * why the shared types live in `./types` and this module is not re-exported from them.
+ *
+ * Specs are bundled but not dereferenced: every operation schema is compiled on its own, with its
+ * internal `#/...` refs pointed at the registered document. That keeps recursive schemas valid.
+ */
+const VALIDATION_HEADER = "x-swaggerizer-validation";
+const MAX_ISSUES = 20;
+const IGNORED_HEADER_PARAMS = new Set(["accept", "content-type", "authorization"]);
+const PARAM_LOCATIONS = new Set(["path", "query", "header", "cookie"]);
+const SKIP = Symbol("swaggerizer-skip");
+/* ------------------------------------------------------------------ schema preparation */
+/** OpenAPI 3.0 spells nullability as `nullable: true`; JSON Schema wants a `null` type. */
+function withoutNullable(node) {
+    if (Array.isArray(node))
+        return node.map(withoutNullable);
+    if (!node || typeof node !== "object")
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node))
+        out[key] = withoutNullable(value);
+    if (out.nullable !== true)
+        return out;
+    delete out.nullable;
+    if (typeof out.type === "string")
+        out.type = [out.type, "null"];
+    else if (Array.isArray(out.type)) {
+        if (!out.type.includes("null"))
+            out.type = [...out.type, "null"];
+    }
+    else if (out.$ref || out.allOf || out.oneOf || out.anyOf || out.not) {
+        return { anyOf: [out, { type: "null" }] };
+    }
+    return out;
+}
+/** Points a schema's internal refs at the registered document so it can be compiled standalone. */
+function withBaseRefs(value, base) {
+    if (Array.isArray(value))
+        return value.map(entry => withBaseRefs(entry, base));
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        out[key] = key === "$ref" && typeof entry === "string" && entry.startsWith("#") ? `${base}${entry}` : withBaseRefs(entry, base);
+    }
+    return out;
+}
+function createAjv(specVersion) {
+    // OAS 3.1 is JSON Schema 2020-12, where `exclusiveMinimum` is a number; draft-07 would reject it.
+    const Ctor = typeof specVersion === "string" && /^3\.[1-9]/.test(specVersion) ? Ajv2020 : Ajv;
+    const ajv = new Ctor({
+        strict: false,
+        allErrors: true,
+        coerceTypes: false,
+        useDefaults: false,
+        allowUnionTypes: true,
+        validateFormats: true
+    });
+    addFormats(ajv);
+    return ajv;
+}
+function typeOf(schema) {
+    const type = schema?.type;
+    if (Array.isArray(type))
+        return type.find((entry) => entry !== "null") ?? type[0];
+    if (typeof type === "string")
+        return type;
+    if (schema?.properties || schema?.additionalProperties)
+        return "object";
+    if (schema?.items)
+        return "array";
+    return undefined;
+}
+function headerValue(headers, name) {
+    const value = headers[name.toLowerCase()];
+    if (Array.isArray(value))
+        return value.join(", ");
+    return value === undefined ? undefined : String(value);
+}
+/* ------------------------------------------------------------------ parameters */
+/** Delimiter of a non-exploded array: `form` is comma-separated, the others say so in their name. */
+function arrayDelimiter(style) {
+    if (style === "spaceDelimited")
+        return " ";
+    if (style === "pipeDelimited")
+        return "|";
+    return ",";
+}
+/**
+ * Exploded `form` objects arrive as their own top-level keys (`?a=1&b=2`) and `deepObject` as
+ * `name[key]=…`. Neither is rebuilt here, so such parameters are reported as skipped, not failed.
+ */
+function isSpreadObject(param, type) {
+    return (!param.json &&
+        type === "object" &&
+        (param.in === "query" || param.in === "cookie") &&
+        ((param.style === "form" && param.explode) || param.style === "deepObject"));
+}
+function hasDeepObjectKeys(query, name) {
+    for (const key of query.keys())
+        if (key.startsWith(`${name}[`))
+            return true;
+    return false;
+}
+/** The value a parameter arrived as: repeated query keys for arrays, the last cookie for scalars. */
+function rawParam(param, input, type) {
+    if (param.in === "path")
+        return input.params[param.name];
+    if (param.in === "query") {
+        if (type === "array" && !param.json)
+            return input.query.getAll(param.name);
+        return input.query.get(param.name) ?? undefined;
+    }
+    if (param.in === "header")
+        return headerValue(input.headers, param.name);
+    const cookie = headerValue(input.headers, "cookie");
+    if (!cookie)
+        return undefined;
+    const found = [];
+    for (const part of cookie.split(";")) {
+        const at = part.indexOf("=");
+        if (at < 0)
+            continue;
+        if (part.slice(0, at).trim() === param.name)
+            found.push(part.slice(at + 1).trim());
+    }
+    if (found.length === 0)
+        return undefined;
+    return type === "array" ? found : found[found.length - 1];
+}
+function coerceScalar(doc, value, schemaIn) {
+    const { node: schema } = deref(doc, schemaIn);
+    const type = typeOf(schema);
+    if (type === "integer" || type === "number") {
+        return /^[+-]?(\d+(\.\d+)?|\.\d+)([eE][+-]?\d+)?$/.test(value) ? Number(value) : value;
+    }
+    if (type === "boolean")
+        return value === "true" ? true : value === "false" ? false : value;
+    return value;
+}
+/**
+ * HTTP hands us strings; the spec talks in types. Validation runs against a coerced copy, so
+ * handlers keep receiving exactly what they always did.
+ */
+function coerceParam(doc, param, raw, summary) {
+    const { node: schema } = deref(doc, param.schema);
+    const type = typeOf(schema);
+    if (type === "array") {
+        // Repeated keys (`ids=1&ids=2`) are already separate; a non-exploded value (`ids=1,2`) is split.
+        const split = (value, delimiter) => value.split(delimiter).map(part => part.trim()).filter(part => part !== "");
+        const values = Array.isArray(raw)
+            ? param.explode
+                ? raw
+                : raw.flatMap(value => split(value, arrayDelimiter(param.style)))
+            : split(String(raw), ",");
+        return values.map(value => coerceScalar(doc, value, schema?.items));
+    }
+    if (type === "object") {
+        if (Array.isArray(raw))
+            return raw;
+        if (isSpreadObject(param, type)) {
+            summary.skipped ??= "object-style";
+            return SKIP;
+        }
+        const out = {};
+        for (const pair of String(raw).split(",")) {
+            if (pair === "")
+                continue;
+            const at = pair.indexOf(":");
+            if (at < 0) {
+                out[pair.trim()] = true;
+            }
+            else {
+                const key = pair.slice(0, at).trim();
+                out[key] = coerceScalar(doc, pair.slice(at + 1).trim(), schema?.properties?.[key] ?? schema?.additionalProperties);
+            }
+        }
+        return out;
+    }
+    return Array.isArray(raw) ? raw[raw.length - 1] : coerceScalar(doc, String(raw), schema);
+}
+function coerceForm(doc, body, schemaIn, summary) {
+    const { node: schema } = deref(doc, schemaIn);
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return body;
+    const properties = schema?.properties || {};
+    const out = {};
+    for (const [key, value] of Object.entries(body)) {
+        const property = properties[key];
+        const propertyType = typeOf(deref(doc, property).node);
+        if (propertyType === "object") {
+            // Deep form bodies need a parser this tool does not ship; report the gap instead of a false pass.
+            summary.skipped ??= "form-nesting";
+            out[key] = value;
+            continue;
+        }
+        if (propertyType === "array" && typeof value === "string") {
+            out[key] = value.split(",").map(entry => coerceScalar(doc, entry.trim(), deref(doc, property).node?.items));
+            continue;
+        }
+        out[key] = typeof value === "string" ? coerceScalar(doc, value, property) : value;
+    }
+    return out;
+}
+/* ------------------------------------------------------------------ bodies */
+function normaliseContentType(value) {
+    if (!value)
+        return undefined;
+    const type = String(value).split(";")[0].trim().toLowerCase();
+    if (!type)
+        return undefined;
+    return type === "*/*" || type === "*" || type === "application/*" ? "application/json" : type;
+}
+/** The declared media type this request should be checked against, if any. */
+function matchMediaType(declared, actual) {
+    if (declared.length === 0)
+        return undefined;
+    const types = declared.map(key => ({ key, type: key.split(";")[0].trim().toLowerCase() }));
+    const wanted = actual ?? "application/json";
+    const exact = types.find(entry => entry.type === wanted);
+    if (exact)
+        return exact.key;
+    if (wanted.endsWith("+json")) {
+        const json = types.find(entry => entry.type === "application/json");
+        if (json)
+            return json.key;
+    }
+    const wildcard = types.find(entry => entry.type === "*/*" || entry.type === "application/*");
+    return wildcard?.key;
+}
+const FORM_TYPE = "application/x-www-form-urlencoded";
+/**
+ * Bodies the server can parse: JSON (`+json` included) and urlencoded forms. No `Content-Type` means
+ * JSON, as it always has. Multipart, octet-stream, text… are skipped rather than failed to parse.
+ */
+function readableMediaType(actual) {
+    if (!actual)
+        return true;
+    return actual === "application/json" || actual.endsWith("+json") || actual === FORM_TYPE;
+}
+/** True when the operation (or its path item) declares any parameter or a request body. */
+function hasRequestSchema(doc, op) {
+    const item = doc?.paths?.[op.route];
+    const node = item?.[op.method];
+    return Boolean((Array.isArray(item?.parameters) && item.parameters.length > 0) ||
+        (Array.isArray(node?.parameters) && node.parameters.length > 0) ||
+        node?.requestBody);
+}
+/* ------------------------------------------------------------------ issues */
+function pointerPath(pointer) {
+    if (typeof pointer !== "string" || pointer === "")
+        return "";
+    return pointer.split("/").filter(Boolean).map(decodePointerSegment).join(".");
+}
+function issueFromError(error, prefix) {
+    const path = pointerPath(error?.instancePath);
+    const missing = error?.keyword === "required" ? error?.params?.missingProperty : undefined;
+    const location = [prefix, path, missing].filter(Boolean).join(".");
+    return {
+        location,
+        message: String(error?.message ?? "is invalid"),
+        ...(error?.keyword ? { keyword: String(error.keyword) } : {})
+    };
+}
+function add(summary, issue) {
+    if (summary.request.length < MAX_ISSUES)
+        summary.request.push(issue);
+}
+function runCheck(validate, value) {
+    if (!validate)
+        return [];
+    return validate(value) ? [] : validate.errors ?? [];
+}
+/* ------------------------------------------------------------------ matching helpers */
+/** `X-Swaggerizer-Validation: off | warn | enforce`; unknown values fall back to the configured mode. */
+function parseValidationMode(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const mode = value.trim().toLowerCase();
+    return mode === "off" || mode === "warn" || mode === "enforce" ? mode : undefined;
+}
+/** True when one of `validateIgnore`'s operationIds or `"METHOD /route"` entries covers `op`. */
+function matchesIgnore(ignore, op) {
+    if (!ignore || ignore.length === 0)
+        return false;
+    return ignore.some(entry => {
+        const value = String(entry).trim();
+        return value === op.operationId || value === `${op.method.toUpperCase()} ${op.route}` || value === op.key;
+    });
+}
+/** `validateIgnore` entries that match no operation, reported as a spec warning. */
+function unmatchedIgnore(ignore, operations) {
+    if (!ignore || ignore.length === 0)
+        return [];
+    return ignore.filter(entry => !operations.some(op => entry === op.operationId ||
+        entry === `${op.method.toUpperCase()} ${op.route}` ||
+        entry === op.key));
+}
+/* ------------------------------------------------------------------ the validator */
+function createValidator(doc, specId, specVersion) {
+    const base = `urn:swaggerizer:${encodeURIComponent(specId)}`;
+    const ajv = createAjv(specVersion);
+    try {
+        ajv.addSchema(withoutNullable(structuredClone(doc)), base);
+    }
+    catch {
+        // A document Ajv refuses to register simply leaves every check skipped, never the mock broken.
+    }
+    const plans = new Map();
+    const bodyChecks = new Map();
+    function compile(schema) {
+        try {
+            // Inline operation schemas get the same `nullable` rewrite as the registered document.
+            return ajv.compile(withBaseRefs(withoutNullable(schema), base));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function buildPlan(op) {
+        const item = doc?.paths?.[op.route];
+        const node = item?.[op.method];
+        const plan = { params: [] };
+        // An operation-level parameter replaces a path-level one with the same name and location.
+        const declared = new Map();
+        for (const entry of [
+            ...(Array.isArray(item?.parameters) ? item.parameters : []),
+            ...(Array.isArray(node?.parameters) ? node.parameters : [])
+        ]) {
+            const { node: param } = deref(doc, entry);
+            if (!param || typeof param !== "object" || !param.name || typeof param.in !== "string")
+                continue;
+            const name = param.in === "header" ? String(param.name).toLowerCase() : String(param.name);
+            declared.set(`${param.in}\u0000${name}`, param);
+        }
+        for (const param of declared.values()) {
+            if (!PARAM_LOCATIONS.has(param.in))
+                continue;
+            const where = param.in;
+            if (where === "header" && IGNORED_HEADER_PARAMS.has(String(param.name).toLowerCase()))
+                continue;
+            let schema = param.schema;
+            let json = false;
+            if (!schema && param.content && typeof param.content === "object") {
+                // Only a JSON `content` parameter can be read; any other media type is left unchecked.
+                const key = Object.keys(param.content).find(entry => /^application\/(.+\+)?json\b/i.test(entry.trim()));
+                if (key) {
+                    schema = param.content[key]?.schema;
+                    json = true;
+                }
+            }
+            if (!schema)
+                continue;
+            const style = typeof param.style === "string" ? param.style : where === "query" || where === "cookie" ? "form" : "simple";
+            const compiled = compile(schema);
+            plan.params.push({
+                name: String(param.name),
+                in: where,
+                required: where === "path" || param.required === true,
+                style,
+                explode: typeof param.explode === "boolean" ? param.explode : style === "form",
+                schema,
+                json,
+                ...(compiled ? { validate: compiled } : { problem: "invalid-schema" })
+            });
+        }
+        const requestBody = node?.requestBody ? deref(doc, node.requestBody).node : undefined;
+        if (requestBody && typeof requestBody === "object" && requestBody.content && typeof requestBody.content === "object") {
+            plan.body = { required: requestBody.required === true, content: requestBody.content };
+        }
+        return plan;
+    }
+    function planFor(op) {
+        let plan = plans.get(op.key);
+        if (!plan) {
+            plan = buildPlan(op);
+            plans.set(op.key, plan);
+        }
+        return plan;
+    }
+    function bodyCheck(op, mediaKey, schema) {
+        const key = `${op.key}\u0000${mediaKey}`;
+        if (bodyChecks.has(key))
+            return bodyChecks.get(key);
+        const compiled = compile(schema);
+        bodyChecks.set(key, compiled);
+        return compiled;
+    }
+    function validateRequest(op, input) {
+        const plan = planFor(op);
+        const summary = { request: [] };
+        for (const param of plan.params) {
+            const { node: schema } = deref(doc, param.schema);
+            const type = typeOf(schema);
+            if (isSpreadObject(param, type)) {
+                // `deepObject` keys can at least be seen; exploded form objects cannot be told from other keys.
+                const deep = param.style === "deepObject" && param.in === "query";
+                const present = deep && hasDeepObjectKeys(input.query, param.name);
+                if (deep && !present && param.required) {
+                    add(summary, {
+                        location: `${param.in}.${param.name}`,
+                        message: `must have required parameter '${param.name}'`,
+                        keyword: "required"
+                    });
+                }
+                else if (present || param.required) {
+                    summary.skipped ??= "object-style";
+                }
+                continue;
+            }
+            const raw = rawParam(param, input, type);
+            const missing = raw === undefined || (Array.isArray(raw) ? raw.length === 0 : raw === "");
+            if (missing) {
+                if (param.required) {
+                    add(summary, {
+                        location: `${param.in}.${param.name}`,
+                        message: `must have required parameter '${param.name}'`,
+                        keyword: "required"
+                    });
+                }
+                continue;
+            }
+            if (param.problem) {
+                summary.skipped ??= param.problem;
+                continue;
+            }
+            let value;
+            if (param.json) {
+                const text = Array.isArray(raw) ? raw[raw.length - 1] : String(raw);
+                try {
+                    value = JSON.parse(text);
+                }
+                catch {
+                    add(summary, { location: `${param.in}.${param.name}`, message: "must be valid JSON", keyword: "parse" });
+                    continue;
+                }
+            }
+            else {
+                value = coerceParam(doc, param, raw, summary);
+            }
+            if (value === SKIP)
+                continue;
+            for (const error of runCheck(param.validate, value)) {
+                add(summary, issueFromError(error, `${param.in}.${param.name}`));
+            }
+        }
+        if (plan.body) {
+            const actual = normaliseContentType(input.contentType);
+            const mediaKey = matchMediaType(Object.keys(plan.body.content), actual);
+            if (!mediaKey || !readableMediaType(actual)) {
+                summary.skipped ??= "unsupported-media-type";
+            }
+            else if (input.bodyError) {
+                add(summary, { location: "body", message: input.bodyError, keyword: "parse" });
+            }
+            else if (input.body === undefined) {
+                if (plan.body.required) {
+                    add(summary, { location: "body", message: "must have a request body", keyword: "required" });
+                }
+            }
+            else {
+                const schema = plan.body.content[mediaKey]?.schema;
+                const check = schema ? bodyCheck(op, mediaKey, schema) : undefined;
+                if (schema && !check) {
+                    summary.skipped ??= "invalid-schema";
+                }
+                else if (check) {
+                    const form = (actual ?? mediaKey.split(";")[0].trim().toLowerCase()) === FORM_TYPE;
+                    const value = form ? coerceForm(doc, input.body, schema, summary) : input.body;
+                    for (const error of runCheck(check, value)) {
+                        add(summary, issueFromError(error, "body"));
+                    }
+                }
+            }
+        }
+        return summary;
+    }
+    return { validateRequest, hasRequestSchema: op => hasRequestSchema(doc, op) };
+}
+
 /* The Swaggerizer mock server: serves every loaded spec and exposes the admin API + page. */
 const REQUEST_LOG_LIMIT = 300;
 const MAX_BODY_BYTES = 5 * 1024 * 1024;
@@ -2094,6 +2606,41 @@ function createSwaggerizer(options = {}) {
     /* ------------------------------------------------------------------ state */
     const ordered = () => [...specs.values()];
     const states = () => buildOperationStates(ordered(), scenarios, { defaultDelay: options.delay });
+    /* ------------------------------------------------------------------ request validation */
+    const validators = new Map();
+    function validatorFor(spec) {
+        let validator = validators.get(spec.id);
+        if (!validator) {
+            validator = createValidator(spec.doc, spec.id, spec.specVersion);
+            validators.set(spec.id, validator);
+        }
+        return validator;
+    }
+    /** Header override, then `validateIgnore`, then the spec's mode, then the server's. */
+    function validationModeFor(op, header) {
+        const fromHeader = parseValidationMode(Array.isArray(header) ? header[0] : header);
+        if (fromHeader)
+            return fromHeader;
+        const cfg = configFor(op.specId);
+        if (matchesIgnore(cfg.validateIgnore, op))
+            return "off";
+        return cfg.validate ?? options.specValidation?.[op.specId] ?? options.validate ?? "off";
+    }
+    function validationInfo(operations = states()) {
+        const perSpec = { ...(options.specValidation || {}) };
+        for (const [id, cfg] of Object.entries(specConfigs))
+            if (cfg.validate)
+                perSpec[id] = cfg.validate;
+        return {
+            mode: options.validate ?? "off",
+            perSpec,
+            operations: operations.map(op => {
+                const spec = specs.get(op.specId);
+                // Read straight from the document: reporting this must not build an Ajv instance while validation is off.
+                return { specId: op.specId, key: op.key, hasRequestSchema: spec ? hasRequestSchema(spec.doc, op) : false };
+            })
+        };
+    }
     function summarise(spec) {
         return {
             id: spec.id,
@@ -2118,14 +2665,16 @@ function createSwaggerizer(options = {}) {
             ...snapshotReports,
             ...[...previousReports.values()].filter(r => r.changes.length > 0)
         ];
+        const operations = states();
         return {
             endpoint,
             ...(options.delay ? { defaultDelay: options.delay } : {}),
             ...(options.fallback ? { fallback: options.fallback } : {}),
             specs: ordered().map(summarise),
-            operations: states(),
+            operations,
             lastReload,
-            changes
+            changes,
+            validation: validationInfo(operations)
         };
     }
     function servingOperation(method, route) {
@@ -2260,6 +2809,9 @@ function createSwaggerizer(options = {}) {
                 for (const key of unmatchedKeys(cfg.handlers, analysed.operations)) {
                     analysed.warnings.push(`Custom handler '${key}' matches no operation`);
                 }
+                for (const key of unmatchedIgnore(cfg.validateIgnore, analysed.operations)) {
+                    analysed.warnings.push(`validateIgnore entry '${key}' matches no operation`);
+                }
                 const enabled = before ? before.enabled : !disabled.has(id);
                 next.set(id, { ...analysed, enabled, loadedAt: new Date().toISOString() });
                 if (before && !before.error) {
@@ -2291,6 +2843,8 @@ function createSwaggerizer(options = {}) {
             }
         }
         specs.clear();
+        // Compiled validators hold the old documents; rebuild them lazily against the new ones.
+        validators.clear();
         for (const [id, spec] of next)
             specs.set(id, spec);
         for (const id of previousReports.keys())
@@ -2365,18 +2919,18 @@ function createSwaggerizer(options = {}) {
         return reload();
     }
     /* ------------------------------------------------------------------ mock serving */
-    async function proxy(req, res, target, relativePath, search) {
+    async function proxy(req, res, target, relativePath, search, bufferedBody) {
         const upstream = target.replace(/\/+$/, "") + relativePath + search;
         const headers = {};
         for (const [name, value] of Object.entries(req.headers)) {
             if (value === undefined)
                 continue;
-            if (["host", "connection", "content-length", "accept-encoding", SCENARIO_HEADER].includes(name))
+            if (["host", "connection", "content-length", "accept-encoding", SCENARIO_HEADER, VALIDATION_HEADER].includes(name))
                 continue;
             headers[name] = Array.isArray(value) ? value.join(", ") : value;
         }
         const method = (req.method || "GET").toUpperCase();
-        const body = method === "GET" || method === "HEAD" ? undefined : await readBody(req);
+        const body = method === "GET" || method === "HEAD" ? undefined : bufferedBody ?? (await readBody(req));
         const response = await fetch(upstream, { method, headers, body: body && body.length ? new Uint8Array(body) : undefined, redirect: "manual" });
         const out = Buffer.from(await response.arrayBuffer());
         res.statusCode = response.status;
@@ -2403,22 +2957,79 @@ function createSwaggerizer(options = {}) {
         const spec = specs.get(op.specId);
         const cfg = configFor(op.specId);
         const override = parseScenarioHeader(req.headers[SCENARIO_HEADER]);
-        const entry = { method: method.toUpperCase(), path: url.pathname + url.search, route: op.route, specId: op.specId, source: "server" };
+        const mode = validationModeFor(op, req.headers[VALIDATION_HEADER]);
+        const resolved = resolveResponse(op, override);
         const custom = lookupByOperation(cfg.handlers, op);
-        if (custom && !override && !op.modified) {
-            const raw = method === "get" || method === "head" ? undefined : (await readBody(req)).toString("utf8");
-            let body = raw;
-            if (raw !== undefined) {
-                try {
-                    body = raw.trim() ? JSON.parse(raw) : undefined;
-                }
-                catch {
-                    body = raw;
-                }
+        const wantsHandler = Boolean(custom) && !override && !op.modified;
+        const sendsBody = method !== "get" && method !== "head";
+        // The request stream can only be read once: buffer it when validation, a custom handler or the
+        // proxy needs it, then hand the same buffer to each of them.
+        const buffered = sendsBody && (mode !== "off" || wantsHandler || resolved.kind === "proxy")
+            ? await readBody(req)
+            : undefined;
+        const contentType = req.headers["content-type"];
+        // What a custom handler has always received: parsed JSON, or the raw text when it is not JSON.
+        let handlerBody;
+        if (buffered && buffered.length > 0) {
+            const text = buffered.toString("utf8");
+            try {
+                handlerBody = text.trim() ? JSON.parse(text) : undefined;
+            }
+            catch {
+                handlerBody = text;
+            }
+        }
+        let validationBody;
+        let bodyError;
+        // A whitespace-only body is no body, for validation as for the handler.
+        if (mode !== "off" && buffered && buffered.toString("utf8").trim() !== "") {
+            try {
+                validationBody = parseRequestBody(buffered, contentType);
             }
-            const params = candidatePaths(url.pathname, spec.basePaths, cfg.aliases || {})
-                .map(p => extractParams(op.route, p))
-                .find(p => Object.keys(p).length > 0) ?? {};
+            catch (err) {
+                bodyError = err?.message ? String(err.message) : String(err);
+            }
+        }
+        const pathParams = candidatePaths(url.pathname, spec.basePaths, cfg.aliases || {})
+            .map(p => extractParams(op.route, p))
+            .find(p => Object.keys(p).length > 0) ?? {};
+        let summary;
+        if (mode !== "off") {
+            summary = validatorFor(spec).validateRequest(op, {
+                params: pathParams,
+                query: url.searchParams,
+                headers: req.headers,
+                ...(validationBody !== undefined ? { body: validationBody } : {}),
+                ...(bodyError ? { bodyError } : {}),
+                ...(contentType ? { contentType } : {})
+            });
+            if (summary.request.length === 0 && !summary.skipped)
+                summary = undefined;
+        }
+        const entry = {
+            method: method.toUpperCase(),
+            path: url.pathname + url.search,
+            route: op.route,
+            specId: op.specId,
+            source: "server",
+            ...(summary ? { validation: summary } : {})
+        };
+        if (summary && mode === "enforce" && summary.request.length > 0) {
+            res.setHeader("X-Swaggerizer-Validation", "failed");
+            sendJson(res, 400, {
+                error: "Request validation failed",
+                operation: `${op.method.toUpperCase()} ${op.route}`,
+                specId: op.specId,
+                issues: summary.request
+            });
+            recordRequest({ ...entry, status: 400, example: "validation", ms: Date.now() - started });
+            return true;
+        }
+        if (summary)
+            res.setHeader("X-Swaggerizer-Validation", "warning");
+        if (custom && wantsHandler) {
+            const body = handlerBody;
+            const params = pathParams;
             const headers = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : String(v ?? "")]));
             let outcome;
             try {
@@ -2445,7 +3056,6 @@ function createSwaggerizer(options = {}) {
                 return true;
             }
         }
-        const resolved = resolveResponse(op, override);
         if (resolved.delay > 0)
             await sleep(resolved.delay);
         if (resolved.kind === "proxy") {
@@ -2457,7 +3067,7 @@ function createSwaggerizer(options = {}) {
             }
             const relative = relativeToBase(url.pathname, spec.basePaths, cfg.aliases || {});
             try {
-                const status = await proxy(req, res, target, relative, url.search);
+                const status = await proxy(req, res, target, relative, url.search, buffered);
                 recordRequest({ ...entry, status, example: "proxy", ms: Date.now() - started });
             }
             catch (err) {
@@ -2495,14 +3105,15 @@ function createSwaggerizer(options = {}) {
         reload,
         getRequestLog,
         recordRequest,
-        getSpecDocument: id => specs.get(id)?.doc
+        getSpecDocument: id => specs.get(id)?.doc,
+        getValidation: validationInfo
     });
     function handler(req, res, next) {
         if (options.cors !== false) {
             res.setHeader("Access-Control-Allow-Origin", req.headers.origin || "*");
             res.setHeader("Vary", "Origin");
             res.setHeader("Access-Control-Allow-Credentials", "true");
-            res.setHeader("Access-Control-Expose-Headers", "X-Swaggerizer-Scenario, X-Swaggerizer-Proxied");
+            res.setHeader("Access-Control-Expose-Headers", "X-Swaggerizer-Scenario, X-Swaggerizer-Proxied, X-Swaggerizer-Validation");
             if (req.method === "OPTIONS" && req.headers["access-control-request-method"]) {
                 res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS");
                 res.setHeader("Access-Control-Allow-Headers", req.headers["access-control-request-headers"] || "*");
@@ -2596,6 +3207,7 @@ function createSwaggerizer(options = {}) {
         getRequestLog,
         recordRequest,
         getSpecDocument: id => specs.get(id)?.doc,
+        getValidationInfo: validationInfo,
         listen,
         close,
         endpoint,
@@ -2819,6 +3431,7 @@ async function pull(options) {
 }
 
 const FAIL_ON = ["breaking", "warning", "any", "none"];
+const VALIDATE_MODES = ["off", "warn", "enforce"];
 const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
 async function confirm(reports) {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
@@ -2873,6 +3486,10 @@ async function run(argv = process.argv) {
         .option("proxy", { type: "string", describe: "upstream base URL for 'Real API' mode (default: each spec's servers URL)" })
         .option("delay", { type: "number", describe: "default latency for every operation, in ms" })
         .option("fallback", { type: "string", describe: "proxy requests that match no operation to this URL" })
+        .option("validate", {
+        choices: VALIDATE_MODES,
+        describe: "check requests against the spec: off (default), warn or enforce"
+    })
         .option("state-file", { type: "string", describe: "persist scenario choices to this JSON file" })
         .option("generated", { alias: "output", type: "string", describe: "generated code folder: warn when the specs drift from it" })
         .option("watch", { alias: "w", type: "boolean", default: false, describe: "reload specs when files change" })
@@ -2890,6 +3507,7 @@ async function run(argv = process.argv) {
             proxy: args.proxy,
             delay: args.delay ?? config?.delay,
             fallback: args.fallback ?? config?.fallback,
+            validate: args.validate ?? config?.validate,
             stateFile: args["state-file"] ?? config?.stateFile,
             generated: args.generated ?? config?.output,
             watch: args.watch,