@scalar/mock-server 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @scalar/mock-server
 
+## 0.14.2
+
+### Patch Changes
+
+- [#10179](https://github.com/scalar/scalar/pull/10179): Serve OAuth2 authorization server metadata at the declared oauth2MetadataUrl, advertising local mock endpoints and the configured grants and scopes.
+
+  Normalize absolute OAuth token URLs to route paths when registering mock authentication routes.
+
+- [#10179](https://github.com/scalar/scalar/pull/10179): Warn when OAuth2 metadata routes collide with declared API paths. Keep the OAuth2 metadata field in OpenAPI 3.2 schemas and document the HTTP exception for local development.
+
+## 0.14.1
+
+### Patch Changes
+
+- [#10190](https://github.com/scalar/scalar/pull/10190): Update Hono to allow HTTP QUERY requests in default CORS preflight responses.
+- [#10164](https://github.com/scalar/scalar/pull/10164): Serve deprecated response schemas from the mock instead of answering a declared JSON response with an empty body, and generate a deprecated AsyncAPI message payload instead of sending `null`. `getExampleFromSchema` takes a new `includeDeprecated` option for callers that must produce a value satisfying the schema. A declared response header that generates no value is now skipped rather than clearing a header of the same name the mock already set, such as the CORS headers.
+- [#10140](https://github.com/scalar/scalar/pull/10140): Replace redundant type assertions with compiler-checked annotations, typed accumulators, and existing guards across helpers, API conversion, request handling, and schema rendering.
+
+  Narrow DOM elements and caught errors before accessing their properties. Correct header lookup to include missing values and handle them during PowerShell snippet generation.
+
+  Validate release-note provider responses, represent unresolved references and absent groups in helper return types, and require narrowing merged object values. Preserve AsyncAPI broker credentials separately from HTTP authentication schemes.
+
 ## 0.14.0
 
 ### Minor Changes

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,EAAgB,IAAI,EAA0B,MAAM,MAAM,CAAA;AAIjE,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAwD5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8NtF"}
+{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,IAAI,EAA0B,MAAM,MAAM,CAAA;AAIjE,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAwD5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2NtF"}

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":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAanC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,YA6HjF"}
+{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAcnC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,YA4HjF"}

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

@@ -5,6 +5,7 @@ import { accepts } from 'hono/accepts';
 import { streamSSE } from 'hono/streaming';
 import { collectSseEvents, isEventStreamContentType } from '../utils/collect-sse-events.js';
 import { findPreferredResponseKey } from '../utils/find-preferred-response-key.js';
+import { generateResponseExample } from '../utils/generate-response-example.js';
 import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { pathParameters } from '../utils/path-parameters.js';
@@ -36,10 +37,15 @@ export function mockAnyResponse(c, operation) {
     const headers = selectedResponse?.headers ?? {};
     Object.keys(headers).forEach((header) => {
         const headerObject = getResolvedRef(headers[header]);
+        // Headers need `includeDeprecated` but none of `generateResponseExample`'s other options — see
+        // the note on that helper for why passing them would change what declared headers emit.
         const value = headerObject?.schema
-            ? getExampleFromSchema(getResolvedRefDeep(headerObject.schema))
+            ? getExampleFromSchema(getResolvedRefDeep(headerObject.schema), { includeDeprecated: true })
             : null;
-        if (value !== null) {
+        // Loose check on purpose: Hono *deletes* a header when handed `undefined`. This loop is the first
+        // thing to set the declared headers, so in practice a delete removes a header set earlier by
+        // middleware — `cors()` sets `Access-Control-Allow-Origin` before the handler runs.
+        if (value != null) {
             c.header(header, value);
         }
     });
@@ -66,13 +72,7 @@ export function mockAnyResponse(c, operation) {
     const acceptedResponse = selectedResponse?.content?.[acceptedContentType];
     const responseSchema = acceptedResponse?.schema ? getResolvedRefDeep(acceptedResponse.schema) : undefined;
     /** Generates the response body from the schema, or returns `undefined` when there is no schema. */
-    const generateFromSchema = () => responseSchema
-        ? getExampleFromSchema(responseSchema, {
-            emptyString: 'string',
-            variables: pathParameters(c),
-            mode: 'read',
-        })
-        : undefined;
+    const generateFromSchema = () => responseSchema ? generateResponseExample(responseSchema, pathParameters(c)) : undefined;
     // Server-Sent Events are a framed, multi-event wire format, so they cannot go out as one buffered
     // body: a client reading the stream expects `data:` lines terminated by a blank line. Everything
     // else (JSON, XML, text) keeps taking the single-body path below.

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;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAqIxD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,gMA8D3F"}
+{"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;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AA+HxD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,gMAyD3F"}

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

@@ -1,8 +1,8 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
-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 { generateResponseExample } from '../utils/generate-response-example.js';
 import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { pathParameters } from '../utils/path-parameters.js';
@@ -47,11 +47,7 @@ function getExampleFromResponse(c, statusCode, responses, exampleName) {
     return selectedExample
         ? normalizeResponseBody(selectedExample.value, responseSchema)
         : responseSchema
-            ? normalizeResponseBody(getExampleFromSchema(responseSchema, {
-                emptyString: 'string',
-                variables: pathParameters(c),
-                mode: 'read',
-            }), responseSchema)
+            ? normalizeResponseBody(generateResponseExample(responseSchema, pathParameters(c)), responseSchema)
             : null;
 }
 /**

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,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAMnC,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,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;AA4DD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CAgD/B"}
+{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAOnC,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,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;AAqDD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CA4C/B"}

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

@@ -1,8 +1,8 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
-import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
 import { accepts } from 'hono/accepts';
 import { store } from '../libs/store.js';
+import { generateResponseExample } from './generate-response-example.js';
 import { normalizeResponseBody } from './normalize-response-body.js';
 import { pathParameters } from './path-parameters.js';
 import { createStoreWrapper } from './store-wrapper.js';
@@ -40,11 +40,7 @@ function getExampleFromResponse(c, statusCode, responses) {
     return acceptedResponse.example !== undefined
         ? normalizeResponseBody(acceptedResponse.example, responseSchema)
         : responseSchema
-            ? normalizeResponseBody(getExampleFromSchema(responseSchema, {
-                emptyString: 'string',
-                variables: pathParameters(c),
-                mode: 'read',
-            }), responseSchema)
+            ? normalizeResponseBody(generateResponseExample(responseSchema, pathParameters(c)), responseSchema)
             : null;
 }
 /**

package/dist/utils/deserialize-parameter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deserialize-parameter.d.ts","sourceRoot":"","sources":["../../src/utils/deserialize-parameter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oFAAoF;AACpF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAUtE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,iBAAiB,EAC3B,QAAQ,MAAM,EACd,UAAU,OAAO,KAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAGnC,CAAA;AA2BD,8GAA8G;AAC9G,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,OAU3E,CAAA;AAED,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,OAU5E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,MAAM,EA4B1F,CAAA;AAgGD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,oCAKvC;IACD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CAC7B,KAAG,MAAM,EAAE,GAAG,SAoBd,CAAA;AAgCD;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,qEAQxC;IACD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CACvC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,SAoEvC,CAAA"}
+{"version":3,"file":"deserialize-parameter.d.ts","sourceRoot":"","sources":["../../src/utils/deserialize-parameter.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,oFAAoF;AACpF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAUtE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,iBAAiB,EAC3B,QAAQ,MAAM,EACd,UAAU,OAAO,KAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAGnC,CAAA;AA2BD,8GAA8G;AAC9G,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,OAU3E,CAAA;AAED,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,OAU5E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,MAAM,EA4B1F,CAAA;AAgGD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,oCAKvC;IACD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CAC7B,KAAG,MAAM,EAAE,GAAG,SAoBd,CAAA;AAgCD;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,qEAQxC;IACD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CACvC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,SAoEvC,CAAA"}

package/dist/utils/deserialize-parameter.js

@@ -1,9 +1,4 @@
-/**
- * Helpers for turning string-encoded request parameters back into the structured values that JSON
- * Schema validation expects, following the OpenAPI `style`/`explode` serialization rules.
- *
- * @see https://spec.openapis.org/oas/v3.1.1.html#style-values
- */
+import { isObjectLike } from '@scalar/helpers/object/is-object';
 /** Default serialization style per parameter location. */
 const DEFAULT_STYLE = {
     query: 'form',
@@ -34,7 +29,7 @@ const matchesComposedSchema = (schema, predicate) => {
         const subSchemas = schema[keyword];
         if (Array.isArray(subSchemas)) {
             for (const subSchema of subSchemas) {
-                if (subSchema && typeof subSchema === 'object' && predicate(subSchema)) {
+                if (isObjectLike(subSchema) && predicate(subSchema)) {
                     return true;
                 }
             }
@@ -87,7 +82,7 @@ export const getObjectPropertyNames = (schema) => {
         const subSchemas = schema[keyword];
         if (Array.isArray(subSchemas)) {
             for (const subSchema of subSchemas) {
-                if (subSchema && typeof subSchema === 'object') {
+                if (isObjectLike(subSchema)) {
                     for (const name of getObjectPropertyNames(subSchema)) {
                         names.add(name);
                     }

package/dist/utils/generate-message.d.ts

@@ -2,7 +2,7 @@ import type { MockMessage, ResolvedChannel } from '../transports/types.js';
 /**
  * Generate an encoded mock frame for a channel message — the AsyncAPI analogue of the REST
  * mocker's response generation. Prefers a defined example, otherwise generates a value from the
- * message payload schema with the same `getExampleFromSchema` the HTTP mocker uses.
+ * message payload schema through the same `generateResponseExample` the HTTP mocker uses.
  *
  * @param channel - The resolved channel to mock a message for.
  * @param messageId - Which message to emit; defaults to the channel's first message.

package/dist/utils/generate-message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-message.d.ts","sourceRoot":"","sources":["../../src/utils/generate-message.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAmB,MAAM,oBAAoB,CAAA;AAWvF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAwBhG"}
+{"version":3,"file":"generate-message.d.ts","sourceRoot":"","sources":["../../src/utils/generate-message.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAmB,MAAM,oBAAoB,CAAA;AAYvF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAuBhG"}

package/dist/utils/generate-message.js

@@ -1,5 +1,5 @@
 import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
-import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+import { generateResponseExample } from '../utils/generate-response-example.js';
 /** Encode a generated value to a wire string. Strings pass through; everything else is JSON. */
 function encode(value) {
     if (typeof value === 'string') {
@@ -10,7 +10,7 @@ function encode(value) {
 /**
  * Generate an encoded mock frame for a channel message — the AsyncAPI analogue of the REST
  * mocker's response generation. Prefers a defined example, otherwise generates a value from the
- * message payload schema with the same `getExampleFromSchema` the HTTP mocker uses.
+ * message payload schema through the same `generateResponseExample` the HTTP mocker uses.
  *
  * @param channel - The resolved channel to mock a message for.
  * @param messageId - Which message to emit; defaults to the channel's first message.
@@ -29,10 +29,9 @@ export function generateMessage(channel, messageId) {
         value = message.examples[0];
     }
     else if (message.payload) {
-        value = getExampleFromSchema(getResolvedRefDeep(message.payload), {
-            emptyString: 'string',
-            mode: 'read',
-        });
+        // No `variables`: `generateMessage` is never handed the Hono context, so a channel route's path
+        // parameters are not in scope for `x-variable` substitution. It does run per request.
+        value = generateResponseExample(getResolvedRefDeep(message.payload));
     }
     return {
         data: encode(value),

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

@@ -0,0 +1,25 @@
+import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+/** The schema shape `getExampleFromSchema` accepts, so callers do not have to name it themselves. */
+export type ExampleSchema = Parameters<typeof getExampleFromSchema>[0];
+/**
+ * Generate a mocked response value from a schema the mock has declared.
+ *
+ * Every value the mock puts on the wire — an HTTP body, an SSE frame, a channel message — has to
+ * satisfy the schema it was declared with, which is why this passes `includeDeprecated: true`:
+ * `deprecated` marks a field as discouraged, not absent, so omitting it answered a declared JSON
+ * response with zero bytes and dropped required properties. Owning the option set in one place keeps
+ * a newly added response path from quietly missing that.
+ *
+ * Not for response headers. Two of the options here would change what an already-declared header
+ * emits: `emptyString` yields the literal `string` for a bare `type: 'string'` and switches on
+ * format-based generation (a `format: 'date-time'` header would emit a fabricated timestamp), and
+ * `mode: 'read'` drops a `writeOnly` header entirely. Headers set `includeDeprecated` on their own
+ * call instead.
+ *
+ * @param schema - The resolved schema to generate a value for.
+ * @param variables - Values for `x-variable` substitution, usually a request's path parameters.
+ *   Omitted by callers that have no request in scope, such as channel messages.
+ * @returns The generated value, or `undefined` when the schema yields nothing.
+ */
+export declare const generateResponseExample: (schema: ExampleSchema, variables?: Record<string, unknown>) => unknown;
+//# sourceMappingURL=generate-response-example.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generate-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/generate-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAE9E,qGAAqG;AACrG,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAA;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,aAAa,EAAE,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OAMjG,CAAA"}

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

@@ -0,0 +1,27 @@
+import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+/**
+ * Generate a mocked response value from a schema the mock has declared.
+ *
+ * Every value the mock puts on the wire — an HTTP body, an SSE frame, a channel message — has to
+ * satisfy the schema it was declared with, which is why this passes `includeDeprecated: true`:
+ * `deprecated` marks a field as discouraged, not absent, so omitting it answered a declared JSON
+ * response with zero bytes and dropped required properties. Owning the option set in one place keeps
+ * a newly added response path from quietly missing that.
+ *
+ * Not for response headers. Two of the options here would change what an already-declared header
+ * emits: `emptyString` yields the literal `string` for a bare `type: 'string'` and switches on
+ * format-based generation (a `format: 'date-time'` header would emit a fabricated timestamp), and
+ * `mode: 'read'` drops a `writeOnly` header entirely. Headers set `includeDeprecated` on their own
+ * call instead.
+ *
+ * @param schema - The resolved schema to generate a value for.
+ * @param variables - Values for `x-variable` substitution, usually a request's path parameters.
+ *   Omitted by callers that have no request in scope, such as channel messages.
+ * @returns The generated value, or `undefined` when the schema yields nothing.
+ */
+export const generateResponseExample = (schema, variables) => getExampleFromSchema(schema, {
+    emptyString: 'string',
+    variables,
+    mode: 'read',
+    includeDeprecated: true,
+});

package/dist/utils/get-oauth2-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
+/** The RFC8414 fields exposed by the mock authorization server. */
+type OAuth2Metadata = {
+    issuer: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    scopes_supported: string[];
+};
+/** Advertises local mock endpoints instead of sending clients to the real authorization server. */
+export declare const getOAuth2Metadata: (flows: OpenAPIV3_2.OAuth2SecurityScheme["flows"], origin: string) => OAuth2Metadata;
+export {};
+//# sourceMappingURL=get-oauth2-metadata.d.ts.map

package/dist/utils/get-oauth2-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-oauth2-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/get-oauth2-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,mEAAmE;AACnE,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wBAAwB,EAAE,MAAM,EAAE,CAAA;IAClC,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,QAAQ,MAAM,KAAG,cAqBpG,CAAA"}

package/dist/utils/get-oauth2-metadata.js

@@ -0,0 +1,23 @@
+import { getPathFromUrl } from './get-open-auth-token-urls.js';
+/** Advertises local mock endpoints instead of sending clients to the real authorization server. */
+export const getOAuth2Metadata = (flows, origin) => {
+    const authorizationFlow = flows?.authorizationCode ?? flows?.implicit;
+    const tokenFlow = flows?.authorizationCode ?? flows?.clientCredentials ?? flows?.password;
+    const localUrl = (url) => new URL(getPathFromUrl(url), origin).href;
+    const supportedFlows = [
+        { flow: flows?.authorizationCode, grant: 'authorization_code', response: 'code' },
+        { flow: flows?.implicit, grant: 'implicit', response: 'token' },
+        { flow: flows?.clientCredentials, grant: 'client_credentials' },
+        { flow: flows?.password, grant: 'password' },
+    ].filter(({ flow }) => flow);
+    return {
+        issuer: origin,
+        ...(authorizationFlow
+            ? { authorization_endpoint: localUrl(authorizationFlow.authorizationUrl ?? '/oauth/authorize') }
+            : {}),
+        ...(tokenFlow ? { token_endpoint: localUrl(tokenFlow.tokenUrl ?? '/oauth/token') } : {}),
+        response_types_supported: supportedFlows.flatMap(({ response }) => (response ? [response] : [])),
+        grant_types_supported: supportedFlows.map(({ grant }) => grant),
+        scopes_supported: [...new Set(supportedFlows.flatMap(({ flow }) => Object.keys(flow?.scopes ?? {})))],
+    };
+};

package/dist/utils/get-open-auth-token-urls.d.ts

@@ -1,7 +1,10 @@
 import type { OpenAPI } from '@scalar/openapi-types';
 /**
- * Extract path from URL
+ * Extract path from URL. Metadata is fetched at its exact declared URL, so its routes
+ * preserve trailing slashes instead of using the token-route normalization.
  */
-export declare function getPathFromUrl(url: string): string;
+export declare function getPathFromUrl(url: string, { preserveTrailingSlash }?: {
+    preserveTrailingSlash?: boolean;
+}): string;
 export declare function getOpenAuthTokenUrls(schema?: OpenAPI.Document): string[];
 //# sourceMappingURL=get-open-auth-token-urls.d.ts.map

package/dist/utils/get-open-auth-token-urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAG5E;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAuCxE"}
+{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAG5E;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,EAAE,qBAA6B,EAAE,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1E,MAAM,CAYR;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAuCxE"}

package/dist/utils/get-open-auth-token-urls.js

@@ -1,14 +1,15 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 /**
- * Extract path from URL
+ * Extract path from URL. Metadata is fetched at its exact declared URL, so its routes
+ * preserve trailing slashes instead of using the token-route normalization.
  */
-export function getPathFromUrl(url) {
+export function getPathFromUrl(url, { preserveTrailingSlash = false } = {}) {
     try {
         // Handle relative URLs by prepending a base
         const urlObject = url.startsWith('http') ? new URL(url) : new URL(url, 'http://example.com');
         // Normalize: remove trailing slash except for root path
         const path = urlObject.pathname;
-        return path === '/' ? path : path.replace(/\/$/, '');
+        return preserveTrailingSlash || path === '/' ? path : path.replace(/\/$/, '');
     }
     catch {
         // If URL is invalid, return the original string

package/dist/utils/log-authentication-instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QAwHpD"}
+{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QAiIpD"}

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

@@ -66,6 +66,13 @@ export function logAuthenticationInstructions(securitySchemes, log = (line) => c
                 }
                 break;
             case 'oauth2':
+                if ('oauth2MetadataUrl' in scheme &&
+                    typeof scheme.oauth2MetadataUrl === 'string' &&
+                    scheme.oauth2MetadataUrl.trim()) {
+                    log('✅ OAuth 2.0 Authorization Server Metadata');
+                    log(`   GET ${getPathFromUrl(scheme.oauth2MetadataUrl, { preserveTrailingSlash: true })}`);
+                    log('');
+                }
                 if (scheme.flows) {
                     Object.keys(scheme.flows).forEach((flow) => {
                         switch (flow) {

package/dist/utils/set-up-authentication-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAOhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QAmG7E"}
+{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QA+G7E"}

package/dist/utils/set-up-authentication-routes.js

@@ -1,6 +1,7 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { respondWithAuthorizePage } from '../routes/respond-with-authorize-page.js';
 import { respondWithToken } from '../routes/respond-with-token.js';
+import { getOAuth2Metadata } from './get-oauth2-metadata.js';
 import { getOpenAuthTokenUrls, getPathFromUrl } from './get-open-auth-token-urls.js';
 /**
  * Helper function to set up authentication routes for OAuth 2.0 flows
@@ -36,11 +37,20 @@ export function setUpAuthenticationRoutes(app, schema) {
             return;
         }
         if (scheme.type === 'oauth2') {
+            if ('oauth2MetadataUrl' in scheme &&
+                typeof scheme.oauth2MetadataUrl === 'string' &&
+                scheme.oauth2MetadataUrl.trim()) {
+                const metadataPath = getPathFromUrl(scheme.oauth2MetadataUrl, { preserveTrailingSlash: true });
+                if (schema?.paths && Object.hasOwn(schema.paths, metadataPath)) {
+                    console.warn(`OAuth2 metadata route "${metadataPath}" collides with a declared API path.`);
+                }
+                app.get(metadataPath, (c) => c.json(getOAuth2Metadata(scheme.flows, new URL(c.req.url).origin)));
+            }
             if (scheme.flows?.authorizationCode) {
                 const authorizeRoute = scheme.flows.authorizationCode.authorizationUrl ?? '/oauth/authorize';
                 const tokenRoute = scheme.flows.authorizationCode.tokenUrl ?? '/oauth/token';
                 authorizeUrls.add(getPathFromUrl(authorizeRoute));
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
             if (scheme.flows?.implicit) {
                 const authorizeRoute = scheme.flows.implicit.authorizationUrl ?? '/oauth/authorize';
@@ -48,11 +58,11 @@ export function setUpAuthenticationRoutes(app, schema) {
             }
             if (scheme.flows?.password) {
                 const tokenRoute = scheme.flows.password.tokenUrl ?? '/oauth/token';
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
             if (scheme.flows?.clientCredentials) {
                 const tokenRoute = scheme.flows.clientCredentials.tokenUrl ?? '/oauth/token';
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
         }
         else if (scheme.type === 'openIdConnect') {
@@ -74,7 +84,7 @@ export function setUpAuthenticationRoutes(app, schema) {
                 const authorizeRoute = '/oauth/authorize';
                 const tokenRoute = '/oauth/token';
                 authorizeUrls.add(getPathFromUrl(authorizeRoute));
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
         }
     });

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.14.0",
+  "version": "0.14.2",
   "engines": {
     "node": ">=22"
   },
@@ -53,17 +53,17 @@
   "dependencies": {
     "@faker-js/faker": "10.4.0",
     "@hono/node-ws": "^1.2.0",
+    "@scalar/helpers": "0.12.0",
+    "@scalar/json-magic": "0.14.0",
+    "@scalar/openapi-types": "0.9.6",
+    "@scalar/openapi-upgrader": "0.2.17",
+    "@scalar/types": "0.20.0",
+    "@scalar/workspace-store": "0.62.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "hono": "^4.12.7",
+    "hono": "^4.13.7",
     "quickjs-emscripten": "0.32.0",
-    "yaml": "^2.9.0",
-    "@scalar/helpers": "0.11.3",
-    "@scalar/json-magic": "0.13.4",
-    "@scalar/openapi-types": "0.9.5",
-    "@scalar/openapi-upgrader": "0.2.15",
-    "@scalar/types": "0.19.0",
-    "@scalar/workspace-store": "0.60.0"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",