@scalar/mock-server 0.10.18 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @scalar/mock-server
 
+## 0.11.0
+
+### Minor Changes
+
+- [#9466](https://github.com/scalar/scalar/pull/9466): Validate incoming requests against the matched operation by default. Path/query parameters and the `application/json` request body are checked against their schema, and contract violations return a `422` with an `application/problem+json` body listing every violation. Set `validateRequest: false` to opt out and always return a mock response.
+
+### Patch Changes
+
+- [#9467](https://github.com/scalar/scalar/pull/9467): Fix security checking: evaluate `security` as OR-of-ANDs, inherit document-level security when an operation defines none, and validate credential shape (well-formed Basic and Bearer)
+- [#9464](https://github.com/scalar/scalar/pull/9464): Add `Prefer` header support to control mock responses: use `code=<status>` to request a specific response status and `example=<name>` to pick a named example from the `examples` map. Also adds support for the OpenAPI `examples` map (previously only the singular `example` was used).
+
+## 0.10.19
+
 ## 0.10.18
 
 ## 0.10.17

package/dist/create-mock-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAgB5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFtF"}
+{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAiB5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2GtF"}

package/dist/create-mock-server.js

@@ -10,6 +10,7 @@ import { isAuthenticationRequired } from './utils/is-authentication-required.js'
 import { logAuthenticationInstructions } from './utils/log-authentication-instructions.js';
 import { processOpenApiDocument } from './utils/process-openapi-document.js';
 import { setUpAuthenticationRoutes } from './utils/set-up-authentication-routes.js';
+import { validateRequest } from './utils/validate-request.js';
 import { store } from './libs/store.js';
 import { mockAnyResponse } from './routes/mock-any-response.js';
 import { mockHandlerResponse } from './routes/mock-handler-response.js';
@@ -62,20 +63,37 @@ export async function createMockServer(configuration) {
         methods.forEach((method) => {
             const route = honoRouteFromPath(path);
             const operation = pathItem?.[method];
+            // Operation-level security overrides the global requirement, so fall back to the
+            // document-wide `security` when the operation does not define its own.
+            const effectiveSecurity = operation.security ?? schema?.security;
             // Check if authentication is required for this operation
-            if (isAuthenticationRequired(operation.security)) {
+            if (isAuthenticationRequired(effectiveSecurity)) {
                 app[method](route, handleAuthentication(schema, operation));
             }
+            // Notify the `onRequest` callback before validation runs, so it fires for every request —
+            // including ones the validation middleware rejects with a `422`.
+            if (configuration.onRequest) {
+                app[method](route, async (c, next) => {
+                    configuration.onRequest?.({ context: c, operation });
+                    await next();
+                });
+            }
+            // Validate the incoming request against the operation contract (on by default;
+            // opt out with `validateRequest: false`). Runs after authentication but before the
+            // mock handler. Validators are compiled once here, so there is no per-request recompilation.
+            if (configuration.validateRequest !== false) {
+                app[method](route, validateRequest(operation, pathItem?.parameters));
+            }
             // Check if operation has x-handler extension
             // Validate that it's a non-empty string (consistent with x-seed validation)
             const handlerCode = operation?.['x-handler'];
             const hasHandler = handlerCode && typeof handlerCode === 'string' && handlerCode.trim().length > 0;
             // Route to appropriate handler
             if (hasHandler) {
-                app[method](route, (c) => mockHandlerResponse(c, operation, configuration));
+                app[method](route, (c) => mockHandlerResponse(c, operation));
             }
             else {
-                app[method](route, (c) => mockAnyResponse(c, operation, configuration));
+                app[method](route, (c) => mockAnyResponse(c, operation));
             }
         });
     });

package/dist/routes/mock-any-response.d.ts

@@ -1,11 +1,10 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 import type { Context } from 'hono';
 import type { StatusCode } from 'hono/utils/http-status';
-import type { MockServerOptions } from '../types.js';
 /**
  * Mock any response
  */
-export declare function mockAnyResponse(c: Context, operation: OpenAPIV3_1.OperationObject, options: MockServerOptions): (Response & import("hono").TypedResponse<{
+export declare function mockAnyResponse(c: Context, operation: OpenAPIV3_1.OperationObject): (Response & import("hono").TypedResponse<{
     error: string;
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<null, StatusCode, "body">) | (Response & import("hono").TypedResponse<any, import("hono/utils/http-status").ContentfulStatusCode, "body">);
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<null, StatusCode, "body">) | (Response & import("hono").TypedResponse<string, import("hono/utils/http-status").ContentfulStatusCode, "body">);
 //# sourceMappingURL=mock-any-response.d.ts.map

package/dist/routes/mock-any-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAGhD;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,EAAE,OAAO,EAAE,iBAAiB;;yPAwF7G"}
+{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAMxD;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe;;4PAiGjF"}

package/dist/routes/mock-any-response.js

@@ -4,29 +4,32 @@ import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved
 import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
 import { accepts } from 'hono/accepts';
 import { findPreferredResponseKey } from '../utils/find-preferred-response-key.js';
+import { parsePreferHeader } from '../utils/parse-prefer-header.js';
+import { selectResponseExample } from '../utils/select-response-example.js';
 /**
  * Mock any response
  */
-export function mockAnyResponse(c, operation, options) {
-    // Call onRequest callback
-    if (options?.onRequest) {
-        options.onRequest({
-            context: c,
-            operation,
-        });
-    }
-    // Response
-    // default, 200, 201 …
+export function mockAnyResponse(c, operation) {
+    // Note: the `onRequest` callback runs as middleware (see `create-mock-server`) so it also fires
+    // for requests rejected before reaching this handler.
+    // Parse the Prefer header (RFC 7240) so clients can request a specific
+    // response status (`code=`) and named example (`example=`).
+    const prefer = parsePreferHeader(c.req.header('Prefer'));
+    // Response selection:
+    // 1. An explicit `Prefer: code=<status>` that matches a defined response
+    // 2. Otherwise the preferred key (default, 200, 201 …)
+    // An unknown `code=` is ignored and falls back to the preferred key.
     const preferredResponseKey = findPreferredResponseKey(Object.keys(operation.responses ?? {}));
-    const preferredResponse = preferredResponseKey ? getResolvedRef(operation.responses?.[preferredResponseKey]) : null;
-    if (!preferredResponse) {
+    const responseKey = prefer.code && operation.responses?.[prefer.code] ? prefer.code : preferredResponseKey;
+    const selectedResponse = responseKey ? getResolvedRef(operation.responses?.[responseKey]) : null;
+    if (!selectedResponse) {
         c.status(500);
         return c.json({ error: 'No response defined for this operation.' });
     }
     // Status code
-    const statusCode = Number.parseInt(preferredResponseKey === 'default' ? '200' : (preferredResponseKey ?? '200'), 10);
+    const statusCode = Number.parseInt(responseKey === 'default' ? '200' : (responseKey ?? '200'), 10);
     // Headers
-    const headers = preferredResponse?.headers ?? {};
+    const headers = selectedResponse?.headers ?? {};
     Object.keys(headers).forEach((header) => {
         const headerObject = getResolvedRef(headers[header]);
         const value = headerObject?.schema
@@ -41,7 +44,7 @@ export function mockAnyResponse(c, operation, options) {
         c.status(statusCode);
         return c.body(null);
     }
-    const supportedContentTypes = Object.keys(preferredResponse?.content ?? {});
+    const supportedContentTypes = Object.keys(selectedResponse?.content ?? {});
     // If no content types are defined, return the status with no body
     if (supportedContentTypes.length === 0) {
         c.status(statusCode);
@@ -56,10 +59,12 @@ export function mockAnyResponse(c, operation, options) {
             : (supportedContentTypes[0] ?? 'text/plain;charset=UTF-8'),
     });
     c.header('Content-Type', acceptedContentType);
-    const acceptedResponse = preferredResponse?.content?.[acceptedContentType];
-    // Body
-    const body = acceptedResponse?.example
-        ? acceptedResponse.example
+    const acceptedResponse = selectedResponse?.content?.[acceptedContentType];
+    // Body: a named/singular/first example if one is defined, otherwise generate
+    // a value from the schema. `Prefer: example=<name>` picks a named example.
+    const selectedExample = selectResponseExample(acceptedResponse, prefer.example);
+    const body = selectedExample
+        ? selectedExample.value
         : acceptedResponse?.schema
             ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
                 emptyString: 'string',
@@ -68,12 +73,19 @@ export function mockAnyResponse(c, operation, options) {
             })
             : null;
     c.status(statusCode);
-    return c.body(typeof body === 'object'
+    return c.body(
+    // `null` is `typeof 'object'` too, but it is not a valid XML/JSON object
+    // root — serialize it (and any non-string primitive) with `JSON.stringify`
+    // so a `null` example does not get fed into `json2xml`.
+    body !== null && typeof body === 'object'
         ? // XML
             acceptedContentType?.includes('xml')
                 ? json2xml(body)
                 : // JSON
                     JSON.stringify(body, null, 2)
-        : // String
-            body);
+        : typeof body === 'string'
+            ? // String
+                body
+            : // null / number / boolean
+                JSON.stringify(body));
 }

package/dist/routes/mock-handler-response.d.ts

@@ -1,10 +1,9 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 import type { Context } from 'hono';
 import type { StatusCode } from 'hono/utils/http-status';
-import type { MockServerOptions } from '../types.js';
 /**
  * Mock response using x-handler code.
  * Executes the handler and returns its result as the response.
  */
-export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject, options: MockServerOptions): Promise<(Response & import("hono").TypedResponse<null, StatusCode, "body">) | (Response & import("hono").TypedResponse<any, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject): Promise<(Response & import("hono").TypedResponse<null, StatusCode, "body">) | (Response & import("hono").TypedResponse<any, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
 //# sourceMappingURL=mock-handler-response.d.ts.map

package/dist/routes/mock-handler-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAoHhD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,WAAW,CAAC,eAAe,EACtC,OAAO,EAAE,iBAAiB,gMAkE3B"}
+{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AA8HxD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,gMA8D3F"}

package/dist/routes/mock-handler-response.js

@@ -4,11 +4,17 @@ import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
 import { accepts } from 'hono/accepts';
 import { buildHandlerContext } from '../utils/build-handler-context.js';
 import { executeHandler } from '../utils/execute-handler.js';
+import { parsePreferHeader } from '../utils/parse-prefer-header.js';
+import { selectResponseExample } from '../utils/select-response-example.js';
 /**
  * Get example response from OpenAPI spec for a given status code.
  * Returns the example value if found, or null if not available.
+ *
+ * Honors `Prefer: example=<name>` to pick a named example from the
+ * `examples` map; otherwise it falls back to the singular `example`, the
+ * first entry of the map, or a value generated from the schema.
  */
-function getExampleFromResponse(c, statusCode, responses) {
+function getExampleFromResponse(c, statusCode, responses, exampleName) {
     if (!responses) {
         return null;
     }
@@ -34,9 +40,10 @@ function getExampleFromResponse(c, statusCode, responses) {
     if (!acceptedResponse) {
         return null;
     }
-    // Extract example from example property or generate from schema
-    return acceptedResponse.example !== undefined
-        ? acceptedResponse.example
+    // Extract example (named, singular, or first) or generate from schema
+    const selectedExample = selectResponseExample(acceptedResponse, exampleName);
+    return selectedExample
+        ? selectedExample.value
         : acceptedResponse.schema
             ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
                 emptyString: 'string',
@@ -98,14 +105,9 @@ function determineStatusCode(tracking) {
  * Mock response using x-handler code.
  * Executes the handler and returns its result as the response.
  */
-export async function mockHandlerResponse(c, operation, options) {
-    // Call onRequest callback
-    if (options?.onRequest) {
-        options.onRequest({
-            context: c,
-            operation,
-        });
-    }
+export async function mockHandlerResponse(c, operation) {
+    // Note: the `onRequest` callback runs as middleware (see `create-mock-server`) so it also fires
+    // for requests rejected before reaching this handler.
     // Get x-handler code from operation
     const handlerCode = operation?.['x-handler'];
     if (!handlerCode) {
@@ -131,7 +133,8 @@ export async function mockHandlerResponse(c, operation, options) {
         // Handle undefined/null results gracefully
         if (result === undefined || result === null) {
             // Try to pick up example response from OpenAPI spec if available
-            const exampleResponse = getExampleFromResponse(c, statusCode, operation.responses);
+            const prefer = parsePreferHeader(c.req.header('Prefer'));
+            const exampleResponse = getExampleFromResponse(c, statusCode, operation.responses, prefer.example);
             if (exampleResponse !== null) {
                 return c.json(exampleResponse);
             }

package/dist/types.d.ts

@@ -30,6 +30,19 @@ type BaseMockServerOptions = {
         context: Context;
         operation: OpenAPIV3_1.OperationObject;
     }) => void;
+    /**
+     * Validate the incoming request against the matched operation's schema. When the request
+     * violates the contract, the server responds with `422` and a `application/problem+json`
+     * body describing the violations, instead of returning a mock response.
+     *
+     * Validates path/query parameters and the `application/json` request body.
+     *
+     * @default true
+     *
+     * Enabled by default for Prism-style contract enforcement. Set to `false` to opt out and
+     * always return a mock response regardless of whether the request matches the contract.
+     */
+    validateRequest?: boolean;
 };
 export type MockServerOptions = RequireAtLeastOne<BaseMockServerOptions, 'specification' | 'document'>;
 export {};

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,WAAW,+DAAgE,CAAA;AAExF,wBAAwB;AACxB,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,GACzF;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAA;AAET,KAAK,qBAAqB,GAAG;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,WAAW,CAAC,eAAe,CAAA;KAAE,KAAK,IAAI,CAAA;CACzF,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,eAAe,GAAG,UAAU,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,WAAW,+DAAgE,CAAA;AAExF,wBAAwB;AACxB,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,GACzF;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAA;AAET,KAAK,qBAAqB,GAAG;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,WAAW,CAAC,eAAe,CAAA;KAAE,KAAK,IAAI,CAAA;IAExF;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,eAAe,GAAG,UAAU,CAAC,CAAA"}

package/dist/utils/build-handler-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAInC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,GAAG,EAAE;QACH,IAAI,EAAE,GAAG,CAAA;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,sBAAsB,CAAA;CACjC,CAAA;AAuDD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CA4C/B"}
+{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAInC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,GAAG,EAAE;QACH,IAAI,EAAE,GAAG,CAAA;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,sBAAsB,CAAA;CACjC,CAAA;AAuDD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CAiD/B"}

package/dist/utils/build-handler-context.js

@@ -51,8 +51,13 @@ function getExampleFromResponse(c, statusCode, responses) {
 export async function buildHandlerContext(c, operation) {
     let body = undefined;
     try {
-        const contentType = c.req.header('content-type') ?? '';
-        if (contentType.includes('application/json')) {
+        // Compare case-insensitively, since media types are case-insensitive and request validation
+        // matches them the same way. Otherwise a body like `Application/JSON` could pass validation yet
+        // never reach the handler as `req.body`.
+        const contentType = (c.req.header('content-type') ?? '').toLowerCase();
+        // An empty/absent Content-Type is treated as JSON to match request validation, so a headerless
+        // JSON body that passes validation is still delivered to the handler as `req.body`.
+        if (contentType === '' || contentType.includes('application/json')) {
             body = await c.req.json().catch(() => undefined);
         }
         else if (contentType.includes('application/x-www-form-urlencoded')) {

package/dist/utils/handle-authentication.d.ts

@@ -2,6 +2,11 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 import type { Context } from 'hono';
 /**
  * Handles authentication for incoming requests based on the OpenAPI document.
+ *
+ * The `security` array is evaluated as OR-of-ANDs: the request is authenticated if
+ * *any* requirement object is fully satisfied, and a requirement object is satisfied
+ * only when *every* scheme it lists is satisfied. An empty requirement object (`{}`)
+ * means authentication is optional and always passes.
  */
 export declare function handleAuthentication(schema?: OpenAPIV3_1.Document, operation?: OpenAPIV3_1.OperationObject): (c: Context, next: () => Promise<void>) => Promise<Response | void>;
 //# sourceMappingURL=handle-authentication.d.ts.map

package/dist/utils/handle-authentication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAGnC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAC3F,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAwH/E"}
+{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAEnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAiInC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAC3F,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA4D/E"}

package/dist/utils/handle-authentication.js

@@ -1,112 +1,164 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getCookie } from 'hono/cookie';
+/** Realm advertised in `WWW-Authenticate` challenges. */
+const REALM = 'Scalar Mock Server';
+/**
+ * Validate the shape of a `Basic` credential.
+ *
+ * Like Prism, we do not verify the credential against a user store (a mock server
+ * has no way to know valid credentials), but we do check that the header is a
+ * well-formed `Basic <base64(user:password)>` value.
+ */
+function isValidBasicAuth(authHeader) {
+    if (!authHeader?.startsWith('Basic ')) {
+        return false;
+    }
+    const encoded = authHeader.slice('Basic '.length).trim();
+    if (!encoded) {
+        return false;
+    }
+    try {
+        // A valid Basic credential decodes to `user:password`, so it must contain a colon.
+        return atob(encoded).includes(':');
+    }
+    catch {
+        // `atob` throws on invalid base64.
+        return false;
+    }
+}
+/**
+ * Validate the shape of a `Bearer` credential.
+ *
+ * We only check that a non-empty token is present after the scheme. Verifying the
+ * token itself (signature, expiry, scopes) is out of scope for a mock server.
+ */
+function isValidBearerAuth(authHeader) {
+    if (!authHeader?.startsWith('Bearer ')) {
+        return false;
+    }
+    return authHeader.slice('Bearer '.length).trim().length > 0;
+}
+/** Check whether a single security scheme is satisfied by the request. */
+function isSchemeSatisfied(scheme, c) {
+    switch (scheme.type) {
+        case 'http': {
+            const authHeader = c.req.header('Authorization');
+            if ('scheme' in scheme && scheme.scheme?.toLowerCase() === 'basic') {
+                return isValidBasicAuth(authHeader);
+            }
+            if ('scheme' in scheme && scheme.scheme?.toLowerCase() === 'bearer') {
+                return isValidBearerAuth(authHeader);
+            }
+            return false;
+        }
+        case 'apiKey': {
+            if (!('name' in scheme) || !scheme.name || !('in' in scheme)) {
+                return false;
+            }
+            const value = scheme.in === 'header'
+                ? c.req.header(scheme.name)
+                : scheme.in === 'query'
+                    ? c.req.query(scheme.name)
+                    : scheme.in === 'cookie'
+                        ? getCookie(c, scheme.name)
+                        : undefined;
+            return Boolean(value);
+        }
+        // OAuth 2.0 and OpenID Connect both carry a bearer token in the `Authorization` header.
+        case 'oauth2':
+        case 'openIdConnect':
+            return isValidBearerAuth(c.req.header('Authorization'));
+        default:
+            return false;
+    }
+}
+/**
+ * Build the `WWW-Authenticate` challenge for a single security scheme.
+ *
+ * Returns `null` for schemes that do not map to an HTTP authentication challenge.
+ */
+function getChallenge(scheme) {
+    switch (scheme.type) {
+        case 'http':
+            if ('scheme' in scheme && scheme.scheme?.toLowerCase() === 'basic') {
+                return `Basic realm="${REALM}", charset="UTF-8"`;
+            }
+            if ('scheme' in scheme && scheme.scheme?.toLowerCase() === 'bearer') {
+                return `Bearer realm="${REALM}", error="invalid_token", error_description="The access token is invalid or has expired"`;
+            }
+            return null;
+        case 'apiKey':
+            if ('name' in scheme && scheme.name) {
+                return `ApiKey realm="${REALM}", error="invalid_token", error_description="Invalid or missing API key", name="${scheme.name}"`;
+            }
+            return null;
+        case 'oauth2':
+        case 'openIdConnect':
+            return `Bearer realm="${REALM}", error="invalid_token", error_description="The access token is invalid or has expired"`;
+        default:
+            return null;
+    }
+}
+/** Resolve all schemes referenced by a single security requirement object. */
+function resolveSchemes(requirement, schema) {
+    return Object.keys(requirement)
+        .map((name) => getResolvedRef(schema?.components?.securitySchemes?.[name]))
+        .filter((scheme) => Boolean(scheme) && 'type' in (scheme ?? {}));
+}
 /**
  * Handles authentication for incoming requests based on the OpenAPI document.
+ *
+ * The `security` array is evaluated as OR-of-ANDs: the request is authenticated if
+ * *any* requirement object is fully satisfied, and a requirement object is satisfied
+ * only when *every* scheme it lists is satisfied. An empty requirement object (`{}`)
+ * means authentication is optional and always passes.
  */
 export function handleAuthentication(schema, operation) {
     return async (c, next) => {
-        const operationSecuritySchemes = operation?.security || schema?.security;
-        if (operationSecuritySchemes && operationSecuritySchemes.length > 0) {
-            let isAuthenticated = false;
-            let authScheme = '';
-            for (const securityRequirement of operationSecuritySchemes) {
-                let securitySchemeAuthenticated = true;
-                for (const [schemeName] of Object.entries(securityRequirement)) {
-                    const scheme = getResolvedRef(schema?.components?.securitySchemes?.[schemeName]);
-                    if (scheme && 'type' in scheme) {
-                        const securityScheme = scheme;
-                        switch (securityScheme.type) {
-                            case 'http':
-                                if ('scheme' in securityScheme && securityScheme.scheme === 'basic') {
-                                    authScheme = 'Basic';
-                                    const authHeader = c.req.header('Authorization');
-                                    if (authHeader?.startsWith('Basic ')) {
-                                        isAuthenticated = true;
-                                    }
-                                }
-                                else if ('scheme' in securityScheme && securityScheme.scheme === 'bearer') {
-                                    authScheme = 'Bearer';
-                                    const authHeader = c.req.header('Authorization');
-                                    if (authHeader?.startsWith('Bearer ')) {
-                                        isAuthenticated = true;
-                                    }
-                                }
-                                break;
-                            case 'apiKey':
-                                if ('name' in securityScheme && 'in' in securityScheme && securityScheme.name) {
-                                    authScheme = `ApiKey ${securityScheme.name}`;
-                                    if (securityScheme.in === 'header') {
-                                        const apiKey = c.req.header(securityScheme.name);
-                                        if (apiKey) {
-                                            isAuthenticated = true;
-                                        }
-                                    }
-                                    else if (securityScheme.in === 'query') {
-                                        const apiKey = c.req.query(securityScheme.name);
-                                        if (apiKey) {
-                                            isAuthenticated = true;
-                                        }
-                                    }
-                                    else if (securityScheme.in === 'cookie') {
-                                        const apiKey = getCookie(c, securityScheme.name);
-                                        if (apiKey) {
-                                            isAuthenticated = true;
-                                        }
-                                    }
-                                }
-                                break;
-                            case 'oauth2':
-                                authScheme = 'Bearer';
-                                // Handle OAuth 2.0 flows, including password grant
-                                if (c.req.header('Authorization')?.startsWith('Bearer ')) {
-                                    isAuthenticated = true;
-                                }
-                                break;
-                            case 'openIdConnect':
-                                authScheme = 'Bearer';
-                                // Handle OpenID Connect similar to OAuth2
-                                if (c.req.header('Authorization')?.startsWith('Bearer ')) {
-                                    isAuthenticated = true;
-                                }
-                                break;
-                        }
-                    }
-                    if (!isAuthenticated) {
-                        securitySchemeAuthenticated = false;
-                        break;
-                    }
-                }
-                if (securitySchemeAuthenticated) {
-                    isAuthenticated = true;
-                    break;
-                }
+        // Operation-level security overrides the global security requirement.
+        const security = operation?.security ?? schema?.security;
+        // Nothing to enforce.
+        if (!security || security.length === 0) {
+            await next();
+            return;
+        }
+        const isAuthenticated = security.some((requirement) => {
+            const schemeNames = Object.keys(requirement);
+            // An empty requirement object makes authentication optional.
+            if (schemeNames.length === 0) {
+                return true;
             }
-            if (!isAuthenticated) {
-                let wwwAuthenticateValue = authScheme;
-                if (authScheme.startsWith('ApiKey')) {
-                    wwwAuthenticateValue += ` realm="Scalar Mock Server", error="invalid_token", error_description="Invalid or missing API key"`;
+            // Every scheme listed in the requirement must resolve and be satisfied (AND).
+            // A name that does not resolve to a valid scheme makes the whole requirement
+            // unsatisfiable, so a missing scheme cannot be silently skipped.
+            return schemeNames.every((name) => {
+                const scheme = getResolvedRef(schema?.components?.securitySchemes?.[name]);
+                if (!scheme || !('type' in scheme)) {
+                    return false;
                 }
-                else {
-                    switch (authScheme) {
-                        case 'Basic':
-                            wwwAuthenticateValue += ' realm="Scalar Mock Server", charset="UTF-8"';
-                            break;
-                        case 'Bearer':
-                            wwwAuthenticateValue +=
-                                ' realm="Scalar Mock Server", error="invalid_token", error_description="The access token is invalid or has expired"';
-                            break;
-                        default:
-                            wwwAuthenticateValue = 'Bearer realm="Scalar Mock Server"';
-                    }
+                return isSchemeSatisfied(scheme, c);
+            });
+        });
+        if (isAuthenticated) {
+            await next();
+            return;
+        }
+        // Advertise a challenge for every scheme that could satisfy the request.
+        const challenges = new Set();
+        for (const requirement of security) {
+            for (const scheme of resolveSchemes(requirement, schema)) {
+                const challenge = getChallenge(scheme);
+                if (challenge) {
+                    challenges.add(challenge);
                 }
-                c.header('WWW-Authenticate', wwwAuthenticateValue);
-                return c.json({
-                    error: 'Unauthorized',
-                    message: 'Authentication is required to access this resource.',
-                }, 401);
             }
         }
-        // If all checks pass, continue to the next middleware
-        await next();
+        for (const challenge of challenges) {
+            c.header('WWW-Authenticate', challenge, { append: true });
+        }
+        return c.json({
+            error: 'Unauthorized',
+            message: 'Authentication is required to access this resource.',
+        }, 401);
     };
 }

package/dist/utils/parse-prefer-header.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Directives parsed from an HTTP `Prefer` header (RFC 7240).
+ *
+ * The mock server understands `code` (pick a response status) and `example`
+ * (pick a named example). The index signature keeps the shape open so future
+ * directives can be read without changing the parser.
+ */
+type PreferDirectives = {
+    /** Requested response status code, e.g. `code=404`. */
+    code?: string;
+    /** Requested named example from the `examples` map, e.g. `example=notFound`. */
+    example?: string;
+    [directive: string]: string | undefined;
+};
+/**
+ * Parse an HTTP `Prefer` header into its directives.
+ *
+ * The header is a comma- and semicolon-separated list of `key=value` tokens
+ * (RFC 7240). We treat every token uniformly, lower-case the keys, and strip
+ * optional surrounding quotes from the values. A missing header or a token
+ * without a value is simply ignored so callers always fall through to their
+ * default behavior instead of erroring.
+ */
+export declare const parsePreferHeader: (header: string | null | undefined) => PreferDirectives;
+export {};
+//# sourceMappingURL=parse-prefer-header.d.ts.map

package/dist/utils/parse-prefer-header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-prefer-header.d.ts","sourceRoot":"","sources":["../../src/utils/parse-prefer-header.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,KAAK,gBAAgB,GAAG;IACtB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CACxC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,gBAqBrE,CAAA"}

package/dist/utils/parse-prefer-header.js

@@ -0,0 +1,26 @@
+/**
+ * Parse an HTTP `Prefer` header into its directives.
+ *
+ * The header is a comma- and semicolon-separated list of `key=value` tokens
+ * (RFC 7240). We treat every token uniformly, lower-case the keys, and strip
+ * optional surrounding quotes from the values. A missing header or a token
+ * without a value is simply ignored so callers always fall through to their
+ * default behavior instead of erroring.
+ */
+export const parsePreferHeader = (header) => {
+    if (!header) {
+        return {};
+    }
+    const directives = {};
+    for (const token of header.split(/[,;]/)) {
+        const [rawKey, ...rest] = token.split('=');
+        const key = rawKey?.trim().toLowerCase();
+        // Skip tokens that have no key or no value (e.g. `respond-async`).
+        if (!key || rest.length === 0) {
+            continue;
+        }
+        // Re-join in case the value itself contained an `=` and drop quotes.
+        directives[key] = rest.join('=').trim().replace(/^"|"$/g, '');
+    }
+    return directives;
+};

package/dist/utils/select-response-example.d.ts

@@ -0,0 +1,22 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+/**
+ * Pick the example body for a response media type.
+ *
+ * Precedence (per the OpenAPI Media Type Object plus the `Prefer: example=`
+ * directive):
+ * 1. A named example explicitly requested via `exampleName`.
+ * 2. The singular `example` keyword.
+ * 3. The first entry of the `examples` map.
+ *
+ * Returns a `{ value }` wrapper when an example is available — so a `null` or
+ * otherwise falsy value is still treated as a real example — or `undefined`
+ * to signal that the caller should fall back to generating a body from the
+ * schema. An example whose resolved `value` is `undefined` (for example, an
+ * Example Object that only carries an `externalValue`) is skipped, so the
+ * caller still gets a schema-generated body. An unknown `exampleName` simply
+ * falls through to the later steps.
+ */
+export declare const selectResponseExample: (mediaType: OpenAPIV3_1.MediaTypeObject | undefined, exampleName?: string) => {
+    value: unknown;
+} | undefined;
+//# sourceMappingURL=select-response-example.d.ts.map

package/dist/utils/select-response-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/select-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,WAAW,CAAC,eAAe,GAAG,SAAS,EAClD,cAAc,MAAM,KACnB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAoCvB,CAAA"}

package/dist/utils/select-response-example.js

@@ -0,0 +1,47 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+/**
+ * Pick the example body for a response media type.
+ *
+ * Precedence (per the OpenAPI Media Type Object plus the `Prefer: example=`
+ * directive):
+ * 1. A named example explicitly requested via `exampleName`.
+ * 2. The singular `example` keyword.
+ * 3. The first entry of the `examples` map.
+ *
+ * Returns a `{ value }` wrapper when an example is available — so a `null` or
+ * otherwise falsy value is still treated as a real example — or `undefined`
+ * to signal that the caller should fall back to generating a body from the
+ * schema. An example whose resolved `value` is `undefined` (for example, an
+ * Example Object that only carries an `externalValue`) is skipped, so the
+ * caller still gets a schema-generated body. An unknown `exampleName` simply
+ * falls through to the later steps.
+ */
+export const selectResponseExample = (mediaType, exampleName) => {
+    if (!mediaType) {
+        return undefined;
+    }
+    const { example, examples } = mediaType;
+    // 1. A named example requested via `Prefer: example=<name>`
+    if (exampleName && examples && exampleName in examples) {
+        const value = getResolvedRef(examples[exampleName])?.value;
+        if (value !== undefined) {
+            return { value };
+        }
+    }
+    // 2. The singular `example` keyword
+    if (example !== undefined) {
+        return { value: example };
+    }
+    // 3. The first entry of the `examples` map
+    if (examples) {
+        const firstKey = Object.keys(examples)[0];
+        if (firstKey !== undefined) {
+            const value = getResolvedRef(examples[firstKey])?.value;
+            if (value !== undefined) {
+                return { value };
+            }
+        }
+    }
+    // 4. Nothing defined: let the caller generate a body from the schema
+    return undefined;
+};

package/dist/utils/validate-request.d.ts

@@ -0,0 +1,14 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Create a Hono middleware bound to a single resolved operation that enforces its request contract.
+ *
+ * Validators are compiled once here (at route-setup time) and reused on every request. On any
+ * violation the middleware short-circuits with a `422` and a `application/problem+json` body;
+ * otherwise it calls `next()` and the normal mock handler runs.
+ *
+ * TODO: Parity follow-ups, intentionally deferred in this slice — response validation,
+ * header/cookie parameter validation, non-JSON body validation, and validation proxy mode.
+ */
+export declare const validateRequest: (operation: OpenAPIV3_1.OperationObject, pathItemParameters?: OpenAPIV3_1.PathItemObject["parameters"]) => MiddlewareHandler;
+//# sourceMappingURL=validate-request.d.ts.map

package/dist/utils/validate-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-request.d.ts","sourceRoot":"","sources":["../../src/utils/validate-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAMxD,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAmLtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAyDF,CAAA"}

package/dist/utils/validate-request.js

@@ -0,0 +1,187 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+/**
+ * Build a JSON Schema object for the parameters declared `in` the given location.
+ *
+ * Parameters arrive as strings, so the caller compiles these with `coerceTypes: true` to let
+ * `type: integer`/`boolean` validate correctly. Returns `null` when there is nothing to validate.
+ */
+const buildParameterSchema = (parameters, location) => {
+    const properties = {};
+    const required = [];
+    for (const parameterOrRef of parameters ?? []) {
+        const parameter = getResolvedRef(parameterOrRef);
+        if (parameter?.in !== location) {
+            continue;
+        }
+        if (parameter.schema) {
+            properties[parameter.name] = getResolvedRefDeep(parameter.schema);
+        }
+        if (parameter.required) {
+            required.push(parameter.name);
+        }
+    }
+    if (Object.keys(properties).length === 0 && required.length === 0) {
+        return null;
+    }
+    // Allow undeclared parameters to pass through; we only enforce what the operation declares.
+    return { type: 'object', properties, required, additionalProperties: true };
+};
+/**
+ * Merge path-item-level parameters with operation-level parameters.
+ *
+ * OpenAPI allows declaring `parameters` on the path item, where they apply to every operation under
+ * it. Operation-level parameters override path-item ones that share the same name and location.
+ */
+const mergeParameters = (pathItemParameters, operationParameters) => {
+    const byKey = new Map();
+    // Guard against malformed documents where `parameters` is not an array.
+    const pathItemList = Array.isArray(pathItemParameters) ? pathItemParameters : [];
+    const operationList = Array.isArray(operationParameters) ? operationParameters : [];
+    // Path-item parameters come first so that operation-level entries overwrite them by identity.
+    for (const parameterOrRef of [...pathItemList, ...operationList]) {
+        const parameter = getResolvedRef(parameterOrRef);
+        if (!parameter?.name || !parameter.in) {
+            continue;
+        }
+        byKey.set(`${parameter.in}:${parameter.name}`, parameterOrRef);
+    }
+    return [...byKey.values()];
+};
+/**
+ * Compile a single schema, failing open if it cannot compile.
+ *
+ * A malformed or uncompilable schema must not crash the server: we log and skip validation for that
+ * part only, consistent with how `x-seed` errors are swallowed during setup. Each schema is compiled
+ * in isolation so one broken schema never disables the others.
+ */
+const compileSchema = (ajv, schema, label) => {
+    if (!schema) {
+        return null;
+    }
+    try {
+        return ajv.compile(schema);
+    }
+    catch (error) {
+        console.error(`Error compiling ${label} validator, skipping validation for it:`, error);
+        return null;
+    }
+};
+/**
+ * Compile the validators for a single operation once, so they can be reused on every request.
+ */
+const compileValidators = (operation, pathItemParameters) => {
+    // Coerce string parameters to their declared types (integer, boolean, …).
+    const parameterAjv = new Ajv2020({ strict: false, allErrors: true, coerceTypes: true });
+    addFormats(parameterAjv);
+    // Do not coerce the JSON body; a JSON value already carries its type and coercion would mask errors.
+    const bodyAjv = new Ajv2020({ strict: false, allErrors: true });
+    addFormats(bodyAjv);
+    // Path-item parameters apply to every operation, so fold them in before building the schemas.
+    const parameters = mergeParameters(pathItemParameters, operation.parameters);
+    const requestBody = getResolvedRef(operation.requestBody);
+    // Build the body schema defensively; resolving a malformed `$ref` should not crash setup.
+    let bodySchema = null;
+    try {
+        const jsonSchema = getResolvedRef(requestBody?.content?.['application/json'])?.schema;
+        bodySchema = jsonSchema ? getResolvedRefDeep(jsonSchema) : null;
+    }
+    catch (error) {
+        console.error('Error resolving request body schema, skipping body validation:', error);
+    }
+    return {
+        path: compileSchema(parameterAjv, buildParameterSchema(parameters, 'path'), 'path parameter'),
+        query: compileSchema(parameterAjv, buildParameterSchema(parameters, 'query'), 'query parameter'),
+        body: compileSchema(bodyAjv, bodySchema, 'request body'),
+        // Required-body enforcement is independent of whether the body schema compiles.
+        bodyRequired: requestBody?.required === true,
+    };
+};
+/**
+ * Map Ajv errors into our violation shape. For path/query parameters the offending parameter name
+ * is prepended to the message so the response is readable without cross-referencing the pointer.
+ */
+const mapErrors = (errors, location) => (errors ?? []).map((error) => {
+    const missingProperty = typeof error.params === 'object' && error.params && 'missingProperty' in error.params
+        ? String(error.params.missingProperty)
+        : '';
+    const path = error.instancePath || (missingProperty ? `/${missingProperty}` : '');
+    const name = error.instancePath.replace(/^\//, '') || missingProperty;
+    const message = location !== 'body' && name ? `${name} ${error.message ?? ''}`.trim() : (error.message ?? '');
+    return { location, path, message };
+});
+/**
+ * Detect whether the request body should be treated as JSON. We only validate JSON bodies in this
+ * slice; an empty/absent Content-Type is treated as JSON to stay forgiving. This intentionally
+ * mirrors how `build-handler-context` parses the body, so we never validate a body the handler then
+ * fails to deliver as `req.body`.
+ */
+const isJsonRequest = (c) => {
+    const contentType = c.req.header('Content-Type')?.toLowerCase() ?? '';
+    return contentType === '' || contentType.includes('application/json');
+};
+/**
+ * Create a Hono middleware bound to a single resolved operation that enforces its request contract.
+ *
+ * Validators are compiled once here (at route-setup time) and reused on every request. On any
+ * violation the middleware short-circuits with a `422` and a `application/problem+json` body;
+ * otherwise it calls `next()` and the normal mock handler runs.
+ *
+ * TODO: Parity follow-ups, intentionally deferred in this slice — response validation,
+ * header/cookie parameter validation, non-JSON body validation, and validation proxy mode.
+ */
+export const validateRequest = (operation, pathItemParameters) => {
+    const validators = compileValidators(operation, pathItemParameters);
+    return async (c, next) => {
+        const violations = [];
+        // Path parameters (coerced from strings)
+        if (validators.path) {
+            const data = { ...c.req.param() };
+            if (!validators.path(data)) {
+                violations.push(...mapErrors(validators.path.errors, 'path'));
+            }
+        }
+        // Query parameters (coerced from strings)
+        if (validators.query) {
+            const data = { ...c.req.query() };
+            if (!validators.query(data)) {
+                violations.push(...mapErrors(validators.query.errors, 'query'));
+            }
+        }
+        // Request body — only `application/json` in this slice
+        if (validators.body || validators.bodyRequired) {
+            // Read from a clone so the original request stream stays intact for the mock or `x-handler`
+            // downstream. Consuming `c.req.text()` directly would leave `c.req.parseBody()` (used for
+            // form bodies) unable to reconstruct the body, so handlers would see it as undefined.
+            const raw = await c.req.raw.clone().text();
+            if (!raw) {
+                if (validators.bodyRequired) {
+                    violations.push({ location: 'body', path: '', message: 'Request body is required' });
+                }
+            }
+            else if (validators.body && isJsonRequest(c)) {
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (!validators.body(parsed)) {
+                        violations.push(...mapErrors(validators.body.errors, 'body'));
+                    }
+                }
+                catch {
+                    // The client sent a non-empty JSON body that cannot be parsed, so it cannot satisfy the
+                    // schema regardless of whether the body is required.
+                    violations.push({ location: 'body', path: '', message: 'Request body must be valid JSON' });
+                }
+            }
+        }
+        if (violations.length > 0) {
+            // Use `c.body` (not `c.json`) so the `application/problem+json` content type is preserved;
+            // `c.json` would force `application/json`.
+            return c.body(JSON.stringify({ error: 'Request validation failed', violations }), 422, {
+                'Content-Type': 'application/problem+json',
+            });
+        }
+        await next();
+    };
+};

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.10.18",
+  "version": "0.11.0",
   "engines": {
     "node": ">=22"
   },
@@ -52,13 +52,15 @@
   },
   "dependencies": {
     "@faker-js/faker": "10.4.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "hono": "^4.12.7",
     "yaml": "^2.8.3",
-    "@scalar/openapi-upgrader": "0.2.9",
+    "@scalar/helpers": "0.8.2",
     "@scalar/json-magic": "0.12.16",
     "@scalar/openapi-types": "0.9.1",
-    "@scalar/helpers": "0.8.2",
-    "@scalar/workspace-store": "0.54.1"
+    "@scalar/openapi-upgrader": "0.2.9",
+    "@scalar/workspace-store": "0.54.3"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",