@scalar/mock-server 0.12.13 → 0.14.0

package/dist/utils/log-authentication-instructions.js

@@ -1,14 +1,18 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getPathFromUrl } from './get-open-auth-token-urls.js';
 /**
- * Log authentication instructions for different security schemes
+ * Log authentication instructions for different security schemes.
+ *
+ * Only the informational lines go through the provided `log` sink. Warnings and errors about
+ * security schemes the mock server cannot handle are printed unconditionally, so a silenced startup
+ * still surfaces schemes that will not work.
  */
-export function logAuthenticationInstructions(securitySchemes) {
+export function logAuthenticationInstructions(securitySchemes, log = (line) => console.log(line)) {
     if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
         return;
     }
-    console.log('Authentication:');
-    console.log();
+    log('Authentication:');
+    log('');
     Object.entries(securitySchemes).forEach(([_, rawScheme]) => {
         const scheme = getResolvedRef(rawScheme);
         // Skip schemes that could not be resolved (e.g. a `$ref` to a missing component)
@@ -18,25 +22,25 @@ export function logAuthenticationInstructions(securitySchemes) {
         switch (scheme.type) {
             case 'apiKey':
                 if (scheme.in === 'header') {
-                    console.log('✅ API Key Authentication');
-                    console.log(`   Use any API key in the ${scheme.name} header`);
-                    console.log();
-                    console.log(`   ${scheme.name}: YOUR_API_KEY_HERE`);
-                    console.log();
+                    log('✅ API Key Authentication');
+                    log(`   Use any API key in the ${scheme.name} header`);
+                    log('');
+                    log(`   ${scheme.name}: YOUR_API_KEY_HERE`);
+                    log('');
                 }
                 else if (scheme.in === 'query') {
-                    console.log('✅ API Key Authentication');
-                    console.log(`   Use any API key in the ${scheme.name} query parameter:`);
-                    console.log();
-                    console.log(`   ?${scheme.name}=YOUR_API_KEY_HERE`);
-                    console.log();
+                    log('✅ API Key Authentication');
+                    log(`   Use any API key in the ${scheme.name} query parameter:`);
+                    log('');
+                    log(`   ?${scheme.name}=YOUR_API_KEY_HERE`);
+                    log('');
                 }
                 else if (scheme.in === 'cookie') {
-                    console.log('✅ API Key Authentication');
-                    console.log(`   Use any API key in the ${scheme.name} cookie:`);
-                    console.log();
-                    console.log(`   Cookie: ${scheme.name}=YOUR_API_KEY_HERE`);
-                    console.log();
+                    log('✅ API Key Authentication');
+                    log(`   Use any API key in the ${scheme.name} cookie:`);
+                    log('');
+                    log(`   Cookie: ${scheme.name}=YOUR_API_KEY_HERE`);
+                    log('');
                 }
                 else {
                     console.error(`❌ Unsupported API Key Location: ${scheme.in}`);
@@ -44,18 +48,18 @@ export function logAuthenticationInstructions(securitySchemes) {
                 break;
             case 'http':
                 if (scheme.scheme === 'basic') {
-                    console.log('✅ HTTP Basic Authentication');
-                    console.log('   Use an Authorization header with any credentials ("username:password" in base64):');
-                    console.log();
-                    console.log('   Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=');
-                    console.log();
+                    log('✅ HTTP Basic Authentication');
+                    log('   Use an Authorization header with any credentials ("username:password" in base64):');
+                    log('');
+                    log('   Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=');
+                    log('');
                 }
                 else if (scheme.scheme === 'bearer') {
-                    console.log('✅ Bearer Token Authentication');
-                    console.log('   Use an Authorization header with any bearer token');
-                    console.log();
-                    console.log('   Authorization: Bearer YOUR_TOKEN_HERE');
-                    console.log();
+                    log('✅ Bearer Token Authentication');
+                    log('   Use an Authorization header with any bearer token');
+                    log('');
+                    log('   Authorization: Bearer YOUR_TOKEN_HERE');
+                    log('');
                 }
                 else {
                     console.error('❌ Unknown Security Scheme:', scheme);
@@ -66,38 +70,38 @@ export function logAuthenticationInstructions(securitySchemes) {
                     Object.keys(scheme.flows).forEach((flow) => {
                         switch (flow) {
                             case 'implicit':
-                                console.log('✅ OAuth 2.0 Implicit Flow');
-                                console.log('   Use the following URL to initiate the OAuth 2.0 Implicit Flow:');
-                                console.log();
-                                console.log(`   GET ${scheme?.flows?.implicit?.authorizationUrl || '/oauth/authorize'}?response_type=token&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPES`);
-                                console.log();
+                                log('✅ OAuth 2.0 Implicit Flow');
+                                log('   Use the following URL to initiate the OAuth 2.0 Implicit Flow:');
+                                log('');
+                                log(`   GET ${scheme?.flows?.implicit?.authorizationUrl || '/oauth/authorize'}?response_type=token&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPES`);
+                                log('');
                                 break;
                             case 'password':
-                                console.log('✅ OAuth 2.0 Password Flow');
-                                console.log('   Use the following URL to obtain an access token:');
-                                console.log();
-                                console.log(`   POST ${getPathFromUrl(scheme?.flows?.password?.tokenUrl || '/oauth/token')}`);
-                                console.log('   Content-Type: application/x-www-form-urlencoded');
-                                console.log();
-                                console.log('   grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET');
-                                console.log();
+                                log('✅ OAuth 2.0 Password Flow');
+                                log('   Use the following URL to obtain an access token:');
+                                log('');
+                                log(`   POST ${getPathFromUrl(scheme?.flows?.password?.tokenUrl || '/oauth/token')}`);
+                                log('   Content-Type: application/x-www-form-urlencoded');
+                                log('');
+                                log('   grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET');
+                                log('');
                                 break;
                             case 'clientCredentials':
-                                console.log('✅ OAuth 2.0 Client Credentials Flow');
-                                console.log('   Use the following URL to obtain an access token:');
-                                console.log();
-                                console.log(`   POST ${getPathFromUrl(scheme?.flows?.clientCredentials?.tokenUrl || '/oauth/token')}`);
-                                console.log('   Content-Type: application/x-www-form-urlencoded');
-                                console.log();
-                                console.log('   grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET');
-                                console.log();
+                                log('✅ OAuth 2.0 Client Credentials Flow');
+                                log('   Use the following URL to obtain an access token:');
+                                log('');
+                                log(`   POST ${getPathFromUrl(scheme?.flows?.clientCredentials?.tokenUrl || '/oauth/token')}`);
+                                log('   Content-Type: application/x-www-form-urlencoded');
+                                log('');
+                                log('   grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET');
+                                log('');
                                 break;
                             case 'authorizationCode':
-                                console.log('✅ OAuth 2.0 Authorization Code Flow');
-                                console.log('   Use the following URL to initiate the OAuth 2.0 Authorization Code Flow:');
-                                console.log();
-                                console.log('   GET', `${getPathFromUrl(scheme?.flows?.authorizationCode?.authorizationUrl || '/oauth/authorize')}?redirect_uri=https://YOUR_REDIRECT_URI_HERE`);
-                                console.log();
+                                log('✅ OAuth 2.0 Authorization Code Flow');
+                                log('   Use the following URL to initiate the OAuth 2.0 Authorization Code Flow:');
+                                log('');
+                                log(`   GET ${getPathFromUrl(scheme?.flows?.authorizationCode?.authorizationUrl || '/oauth/authorize')}?redirect_uri=https://YOUR_REDIRECT_URI_HERE`);
+                                log('');
                                 break;
                             default:
                                 console.warn(`Unsupported OAuth 2.0 flow: ${flow}`);
@@ -106,11 +110,11 @@ export function logAuthenticationInstructions(securitySchemes) {
                 }
                 break;
             case 'openIdConnect':
-                console.log('✅ OpenID Connect Authentication');
-                console.log('   Use the following OpenID Connect discovery URL:');
-                console.log();
-                console.log(`   ${getPathFromUrl(scheme.openIdConnectUrl || '/.well-known/openid-configuration')}`);
-                console.log();
+                log('✅ OpenID Connect Authentication');
+                log('   Use the following OpenID Connect discovery URL:');
+                log('');
+                log(`   ${getPathFromUrl(scheme.openIdConnectUrl || '/.well-known/openid-configuration')}`);
+                log('');
                 break;
             default:
                 console.warn(`Unsupported security scheme type: ${scheme.type}`);

package/dist/utils/path-parameters.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from 'hono';
+/**
+ * Read the path parameters of a request, without the ones synthesized for routing.
+ *
+ * A path segment Hono cannot match as written is registered as a parameter with a generated name
+ * (see `honoRouteFromPath`). That name is an implementation detail, so it has no business showing up
+ * in an `x-handler` context or among the variables a mocked response body is generated from.
+ *
+ * The names are read back off the matched route rather than recognized by their prefix, so a
+ * document that happens to declare a parameter of the same name keeps it.
+ */
+export declare const pathParameters: (context: Context) => Record<string, string>;
+//# sourceMappingURL=path-parameters.d.ts.map

package/dist/utils/path-parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-parameters.d.ts","sourceRoot":"","sources":["../../src/utils/path-parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAOnC;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAItE,CAAA"}

package/dist/utils/path-parameters.js

@@ -0,0 +1,17 @@
+import { LITERAL_PARAMETER_PREFIX } from '../utils/hono-route-from-path.js';
+/** Matches the parameters `honoRouteFromPath` synthesizes, which always carry an explicit pattern. */
+const synthesizedParameter = new RegExp(`:(${LITERAL_PARAMETER_PREFIX}\\d+)\\{`, 'g');
+/**
+ * Read the path parameters of a request, without the ones synthesized for routing.
+ *
+ * A path segment Hono cannot match as written is registered as a parameter with a generated name
+ * (see `honoRouteFromPath`). That name is an implementation detail, so it has no business showing up
+ * in an `x-handler` context or among the variables a mocked response body is generated from.
+ *
+ * The names are read back off the matched route rather than recognized by their prefix, so a
+ * document that happens to declare a parameter of the same name keeps it.
+ */
+export const pathParameters = (context) => {
+    const synthesized = new Set([...context.req.routePath.matchAll(synthesizedParameter)].map(([, name]) => name));
+    return Object.fromEntries(Object.entries(context.req.param()).filter(([name]) => !synthesized.has(name)));
+};

package/dist/utils/process-openapi-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAiD/B"}
+{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAsD/B"}

package/dist/utils/process-openapi-document.js

@@ -1,5 +1,8 @@
+import path from 'node:path';
+import { cwd } from 'node:process';
 import { bundle } from '@scalar/json-magic/bundle';
 import { fetchUrls, parseJson, parseYaml, readFiles } from '@scalar/json-magic/bundle/plugins/node';
+import { isFilePath } from '@scalar/json-magic/helpers/is-file-path';
 import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
 import { upgrade } from '@scalar/openapi-upgrader';
 /**
@@ -29,11 +32,15 @@ export async function processOpenApiDocument(document) {
         };
     }
     let bundled;
+    // Confine local file `$ref`s to the document's own directory (or the working directory when the
+    // document is an object or inline string), and refuse to fetch private or internal addresses.
+    // Without these guards a `$ref` could read arbitrary local files or reach internal services.
+    const basePath = typeof document === 'string' && isFilePath(document) ? path.dirname(path.resolve(document)) : cwd();
     try {
         // Bundle external references with Node.js plugins
         // Include parseJson and parseYaml to handle string inputs
         bundled = await bundle(document, {
-            plugins: [parseJson(), parseYaml(), readFiles(), fetchUrls()],
+            plugins: [parseJson(), parseYaml(), readFiles({ basePath }), fetchUrls({ blockPrivateNetworks: true })],
             treeShake: false,
         });
     }

package/dist/utils/replace-circular-markers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Replace the `'[circular]'` markers `getResolvedRefDeep` leaves in schema positions with an empty
+ * (always-valid) schema.
+ *
+ * A recursive schema — a `Node` whose `child` is another `Node` — resolves to a document where the
+ * recursion point is the *string* `'[circular]'`. Ajv rejects the whole schema for it
+ * (`data/properties/child must be object,boolean`), so a single recursive type silently disabled
+ * validation of the request body, or of every parameter in the same location. Accepting anything at
+ * the point where the cycle was cut keeps the rest of the schema enforceable.
+ *
+ * The rewrite only ever loosens what is enforced, so it can lose a violation but never invent one.
+ * That is why relaxing is tracked as it goes: under `not`, `if`, `oneOf` or `contains` a looser
+ * subschema would make the schema *stricter*, so those keywords are dropped rather than rewritten,
+ * and a sibling `unevaluatedProperties`/`unevaluatedItems` goes with a relaxed in-place applicator
+ * for the same reason.
+ *
+ * Only known schema positions are rewritten. A marker anywhere else — `enum`, `const`, `default`,
+ * `example`, or a vendor extension — is data rather than a schema Ajv compiles, so it is copied
+ * through untouched.
+ */
+export declare const replaceCircularMarkers: (schema: unknown) => unknown;
+//# sourceMappingURL=replace-circular-markers.d.ts.map

package/dist/utils/replace-circular-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-circular-markers.d.ts","sourceRoot":"","sources":["../../src/utils/replace-circular-markers.ts"],"names":[],"mappings":"AAgGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,OAAO,KAAG,OAoJxD,CAAA"}

package/dist/utils/replace-circular-markers.js

@@ -0,0 +1,226 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * The placeholder `getResolvedRefDeep` leaves behind wherever it had to cut a `$ref` cycle.
+ *
+ * The marker is owned by `@scalar/workspace-store`; the Ajv test in this file's suite resolves a real
+ * recursive schema, so it fails here if that sentinel ever changes.
+ */
+const CIRCULAR_MARKER = '[circular]';
+/**
+ * Keywords whose value is a schema, or an array of schemas.
+ *
+ * `items` covers the JSON Schema 2020-12 form as well as the older tuple form, which the walker reads
+ * structurally — a tuple `items` does not compile under 2020-12 either way, with or without a cut.
+ * `additionalItems` is listed for the same reason: Ajv 2020 ignores the keyword, but an older document
+ * carrying one still walks cleanly.
+ */
+const SCHEMA_KEYWORDS = new Set([
+    'additionalItems',
+    'additionalProperties',
+    'allOf',
+    'anyOf',
+    'contains',
+    'contentSchema',
+    'else',
+    'if',
+    'items',
+    'not',
+    'oneOf',
+    'prefixItems',
+    'propertyNames',
+    'then',
+    'unevaluatedItems',
+    'unevaluatedProperties',
+]);
+/**
+ * Keywords whose value maps names to schemas. Their keys are author-chosen names rather than
+ * keywords, so the walker must not read them as keywords of their own.
+ */
+const SCHEMA_MAP_KEYWORDS = new Set([
+    '$defs',
+    'definitions',
+    // Ajv 2020 still implements the draft-07 `dependencies`, so a marker under it has to be rewritten
+    // too. Its array form (`{ name: ['other'] }`) walks through untouched.
+    'dependencies',
+    'dependentSchemas',
+    'patternProperties',
+    'properties',
+]);
+/** Map keywords `additionalProperties` reads to decide which properties it still applies to */
+const PROPERTY_MAP_KEYWORDS = new Set(['patternProperties', 'properties']);
+/**
+ * Keywords that invert what a relaxed subschema means: matching more values there makes the schema as
+ * a whole reject more requests. Verified against Ajv — `not: {}` rejects every request, `if: {}`
+ * forces `then` onto every request, `oneOf: [{}, …]` rejects anything that also matches a sibling
+ * branch (a recursive union or a nullable recursive reference being the realistic cases), and a
+ * `contains` that matches more items can overshoot `maxContains`. Whenever the cycle was cut anywhere
+ * below one of these, the keyword is dropped instead, so a valid request is never turned away.
+ */
+const INVERTING_SCHEMA_KEYWORDS = new Set(['contains', 'if', 'not', 'oneOf']);
+/**
+ * In-place applicators, whose subschemas decide which properties and items count as evaluated. A
+ * relaxed branch stops contributing those annotations, so a sibling `unevaluatedProperties` or
+ * `unevaluatedItems` would start rejecting values it used to accept. `if` and `oneOf` are listed for
+ * completeness; a relaxed one of those is dropped by the inverting rule before it gets here, which
+ * clears the sibling anyway.
+ */
+const IN_PLACE_SCHEMA_KEYWORDS = new Set([
+    'allOf',
+    'anyOf',
+    'dependencies',
+    'dependentSchemas',
+    'else',
+    'if',
+    'oneOf',
+    'then',
+]);
+/**
+ * Keywords whose value has to be an array of schemas. A cut at the array itself cannot be answered
+ * with a schema, so the keyword is dropped rather than left as something Ajv refuses to compile.
+ * `oneOf` belongs here too but never reaches it, because the inverting rule already drops it.
+ */
+const SCHEMA_ARRAY_KEYWORDS = new Set(['allOf', 'anyOf', 'prefixItems']);
+/**
+ * Replace the `'[circular]'` markers `getResolvedRefDeep` leaves in schema positions with an empty
+ * (always-valid) schema.
+ *
+ * A recursive schema — a `Node` whose `child` is another `Node` — resolves to a document where the
+ * recursion point is the *string* `'[circular]'`. Ajv rejects the whole schema for it
+ * (`data/properties/child must be object,boolean`), so a single recursive type silently disabled
+ * validation of the request body, or of every parameter in the same location. Accepting anything at
+ * the point where the cycle was cut keeps the rest of the schema enforceable.
+ *
+ * The rewrite only ever loosens what is enforced, so it can lose a violation but never invent one.
+ * That is why relaxing is tracked as it goes: under `not`, `if`, `oneOf` or `contains` a looser
+ * subschema would make the schema *stricter*, so those keywords are dropped rather than rewritten,
+ * and a sibling `unevaluatedProperties`/`unevaluatedItems` goes with a relaxed in-place applicator
+ * for the same reason.
+ *
+ * Only known schema positions are rewritten. A marker anywhere else — `enum`, `const`, `default`,
+ * `example`, or a vendor extension — is data rather than a schema Ajv compiles, so it is copied
+ * through untouched.
+ */
+export const replaceCircularMarkers = (schema) => {
+    // `getResolvedRefDeep` returns a graph, not a tree: one resolved schema object is shared by every
+    // place that referenced it. Reusing the rewritten copy keeps a widely shared schema from being
+    // walked once per occurrence, and is what makes the walk terminate rather than recur forever should
+    // it ever be handed a genuinely cyclic object — which the resolver, having cut every cycle, is not
+    // able to produce.
+    //
+    // Schemas and schema maps are cached apart, because the same object read as one or the other
+    // rewrites differently: `{ not: … }` is a keyword in a schema and a schema named `not` in a map.
+    const rewritten = new WeakMap();
+    const rewrittenMaps = new WeakMap();
+    const asSchema = (value) => {
+        // The cycle was cut here, so nothing is known about the value any more: accept anything.
+        if (value === CIRCULAR_MARKER) {
+            return { value: {}, relaxed: true };
+        }
+        if (!isObject(value) && !Array.isArray(value)) {
+            return { value, relaxed: false };
+        }
+        const cached = rewritten.get(value);
+        if (cached) {
+            return cached;
+        }
+        // Register each copy before filling it, so a self-referencing value resolves to the copy itself.
+        if (Array.isArray(value)) {
+            const items = [];
+            const rewrite = { value: items, relaxed: false };
+            rewritten.set(value, rewrite);
+            for (const item of value) {
+                const child = asSchema(item);
+                items.push(child.value);
+                rewrite.relaxed ||= child.relaxed;
+            }
+            return rewrite;
+        }
+        const result = {};
+        const rewrite = { value: result, relaxed: false };
+        rewritten.set(value, rewrite);
+        let droppedIf = false;
+        let droppedContains = false;
+        let droppedPrefixItems = false;
+        let droppedPropertyMap = false;
+        // Whether this schema stopped saying which properties and items it accounted for — either a
+        // keyword was dropped outright, or a relaxed in-place branch no longer contributes what it did.
+        let annotationsLost = false;
+        for (const [keyword, child] of Object.entries(value)) {
+            if (!SCHEMA_KEYWORDS.has(keyword) && !SCHEMA_MAP_KEYWORDS.has(keyword)) {
+                // Data rather than a schema, so it is carried over as it stands. Nothing mutates the result,
+                // so sharing the value with the resolved document it came from is safe.
+                result[keyword] = child;
+                continue;
+            }
+            // A cut at an array-valued keyword itself cannot become a schema, so the keyword goes. A dropped
+            // keyword also stops saying which properties and items it accounted for, so any `unevaluated*`
+            // sibling has to go with it.
+            if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && child === CIRCULAR_MARKER) {
+                droppedPrefixItems ||= keyword === 'prefixItems';
+                rewrite.relaxed = true;
+                annotationsLost = true;
+                continue;
+            }
+            // A cut at a schema map itself leaves an empty map, which accounts for nothing any more, so an
+            // `unevaluated*` sibling has to go the same way a dropped keyword takes it.
+            if (SCHEMA_MAP_KEYWORDS.has(keyword) && child === CIRCULAR_MARKER) {
+                result[keyword] = {};
+                droppedPropertyMap ||= PROPERTY_MAP_KEYWORDS.has(keyword);
+                rewrite.relaxed = true;
+                annotationsLost = true;
+                continue;
+            }
+            const rewrittenChild = SCHEMA_MAP_KEYWORDS.has(keyword) && isObject(child) ? asSchemaMap(child) : asSchema(child);
+            if (INVERTING_SCHEMA_KEYWORDS.has(keyword) && rewrittenChild.relaxed) {
+                droppedIf ||= keyword === 'if';
+                droppedContains ||= keyword === 'contains';
+                rewrite.relaxed = true;
+                annotationsLost = true;
+                continue;
+            }
+            result[keyword] = rewrittenChild.value;
+            rewrite.relaxed ||= rewrittenChild.relaxed;
+            annotationsLost ||= rewrittenChild.relaxed && IN_PLACE_SCHEMA_KEYWORDS.has(keyword);
+        }
+        // `then` and `else` only apply alongside an `if`, so they leave with the dropped condition, and
+        // `minContains`/`maxContains` only qualify a `contains`.
+        if (droppedIf) {
+            delete result.then;
+            delete result.else;
+        }
+        if (droppedContains) {
+            delete result.minContains;
+            delete result.maxContains;
+        }
+        // `additionalProperties` and `items` only apply to what their siblings did not cover, so once that
+        // sibling is gone they would start policing values it used to account for.
+        if (droppedPropertyMap) {
+            delete result.additionalProperties;
+        }
+        if (droppedPrefixItems) {
+            delete result.items;
+        }
+        if (annotationsLost) {
+            delete result.unevaluatedProperties;
+            delete result.unevaluatedItems;
+        }
+        return rewrite;
+    };
+    /** Rewrite every schema under a map keyword, keeping its author-chosen names as they are */
+    const asSchemaMap = (map) => {
+        const cached = rewrittenMaps.get(map);
+        if (cached) {
+            return cached;
+        }
+        const result = {};
+        const rewrite = { value: result, relaxed: false };
+        rewrittenMaps.set(map, rewrite);
+        for (const [name, sub] of Object.entries(map)) {
+            const child = asSchema(sub);
+            result[name] = child.value;
+            rewrite.relaxed ||= child.relaxed;
+        }
+        return rewrite;
+    };
+    return asSchema(schema).value;
+};

package/dist/utils/request-matches-pinned-query.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from 'hono';
+import type { PinnedQueryParameter } from '../utils/split-path-key.js';
+/**
+ * Check whether a request carries every query parameter a path key pins.
+ *
+ * `/v1/messages?beta=true` describes a variant of `/v1/messages`, so it may only answer requests
+ * that actually send `beta=true`. A parameter pinned without a value (`?beta`) matches any value.
+ */
+export declare const requestMatchesPinnedQuery: (context: Context, query: PinnedQueryParameter[]) => boolean;
+//# sourceMappingURL=request-matches-pinned-query.d.ts.map

package/dist/utils/request-matches-pinned-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-matches-pinned-query.d.ts","sourceRoot":"","sources":["../../src/utils/request-matches-pinned-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,OAAO,EAAE,OAAO,oBAAoB,EAAE,KAAG,OASxF,CAAA"}

package/dist/utils/request-matches-pinned-query.js

@@ -0,0 +1,13 @@
+/**
+ * Check whether a request carries every query parameter a path key pins.
+ *
+ * `/v1/messages?beta=true` describes a variant of `/v1/messages`, so it may only answer requests
+ * that actually send `beta=true`. A parameter pinned without a value (`?beta`) matches any value.
+ */
+export const requestMatchesPinnedQuery = (context, query) => query.every(({ name, value }) => {
+    const values = context.req.queries(name);
+    if (!values?.length) {
+        return false;
+    }
+    return value === undefined || values.includes(value);
+});

package/dist/utils/resolve-logger.d.ts

@@ -0,0 +1,12 @@
+import type { MockServerLogger } from '../types.js';
+/**
+ * Resolve the `logger` option accepted by the mock server factories into a concrete sink.
+ *
+ * The option is a superset of a plain sink:
+ * - a function is used as-is,
+ * - `true` logs each line to the console,
+ * - `false` drops every line,
+ * - `undefined` falls back to the factory's default (`enabledByDefault`).
+ */
+export declare const resolveLogger: (logger: boolean | MockServerLogger | undefined, enabledByDefault: boolean) => MockServerLogger;
+//# sourceMappingURL=resolve-logger.d.ts.map

package/dist/utils/resolve-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-logger.d.ts","sourceRoot":"","sources":["../../src/utils/resolve-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,OAAO,GAAG,gBAAgB,GAAG,SAAS,EAC9C,kBAAkB,OAAO,KACxB,gBAQF,CAAA"}

package/dist/utils/resolve-logger.js

@@ -0,0 +1,16 @@
+/**
+ * Resolve the `logger` option accepted by the mock server factories into a concrete sink.
+ *
+ * The option is a superset of a plain sink:
+ * - a function is used as-is,
+ * - `true` logs each line to the console,
+ * - `false` drops every line,
+ * - `undefined` falls back to the factory's default (`enabledByDefault`).
+ */
+export const resolveLogger = (logger, enabledByDefault) => {
+    const value = logger ?? enabledByDefault;
+    if (typeof value === 'function') {
+        return value;
+    }
+    return value ? (line) => console.log(line) : () => undefined;
+};

package/dist/utils/sandbox.d.ts

@@ -0,0 +1,25 @@
+import type { StoreInterface } from './store-wrapper.js';
+/**
+ * Options for {@link runInSandbox}.
+ */
+type RunInSandboxOptions = {
+    /** User-supplied handler or seed code. It runs inside an async wrapper, so top-level `return` and `await` work. */
+    code: string;
+    /** Host store bridge (already wrapped with operation tracking). */
+    store: StoreInterface;
+    /** Plain-JSON values exposed to the guest as globals (for example `req`, `res`, `schema`). */
+    jsonGlobals?: Record<string, unknown>;
+    /** When true, exposes the guest-side `seed` helper. Requires a `schema` entry in {@link jsonGlobals}. */
+    includeSeed?: boolean;
+};
+/**
+ * Execute untrusted handler or seed code inside a QuickJS WebAssembly sandbox.
+ *
+ * The guest has no access to the host runtime (`process`, `require`, `fetch`,
+ * the `Function` constructor, and so on). It can only talk to the `store` and
+ * `faker` bridges and read the injected JSON globals. Memory and time limits
+ * bound the remaining denial-of-service risk.
+ */
+export declare function runInSandbox(options: RunInSandboxOptions): Promise<unknown>;
+export {};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/utils/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/utils/sandbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAiCrD;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,mHAAmH;IACnH,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,KAAK,EAAE,cAAc,CAAA;IACrB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,yGAAyG;IACzG,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AA8LD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAqEjF"}