@scalar/mock-server 0.14.4 → 0.16.0

package/dist/utils/set-up-device-authorization.js

@@ -0,0 +1,192 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { html } from 'hono/html';
+import { getPathFromUrl } from './get-open-auth-token-urls.js';
+/** Both endpoints compare the decoded client ID, regardless of credential location. */
+const getClientId = (clientId, authorization) => {
+    if (typeof clientId === 'string') {
+        return clientId;
+    }
+    if (!authorization?.startsWith('Basic ')) {
+        return '';
+    }
+    const credentials = Buffer.from(authorization.slice(6), 'base64').toString();
+    const separator = credentials.indexOf(':');
+    if (separator === -1) {
+        return '';
+    }
+    try {
+        return decodeURIComponent(credentials.slice(0, separator).replace(/\+/g, ' '));
+    }
+    catch {
+        return '';
+    }
+};
+/** Keeps the device form and its outcomes consistent with the mock OAuth authorization page. */
+const renderDevicePage = (title, heading, content) => html `
+  <!doctype html>
+  <html lang="en">
+    <head>
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width, initial-scale=1">
+      <title>${heading}</title>
+      <style>
+        * { box-sizing: border-box; }
+        body { margin: 0; min-height: 100svh; display: grid; place-items: center; padding: 32px 16px; background: #f3f4f6; color: #4b5563; font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; line-height: 1.5; }
+        main { width: 100%; max-width: 448px; }
+        .brand { display: flex; align-items: center; justify-content: center; gap: 8px; margin-bottom: 20px; color: #111827; font-size: 18px; font-weight: 500; }
+        .brand img { width: 24px; }
+        .brand span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+        .card { padding: 4px; border-radius: 8px; background: #f9fafb; box-shadow: 0 1px 3px #0000001a, 0 1px 2px #0000001a; }
+        h1 { margin: 0; padding: 8px 24px 12px; color: #1f2937; font-size: 16px; font-weight: 500; }
+        .content { padding: 24px; border-radius: 4px; background: white; }
+        p { margin: 0 0 20px; }
+        .content > p:last-child { margin-bottom: 0; }
+        label { display: block; margin-bottom: 8px; color: #374151; font-weight: 500; }
+        input { width: 100%; min-width: 0; padding: 12px; border: 1px solid #d1d5db; border-radius: 4px; background: #f9fafb; color: #111827; font: 18px ui-monospace, monospace; letter-spacing: .15em; }
+        .actions { display: flex; flex-direction: row-reverse; justify-content: space-between; gap: 12px; margin-top: 24px; }
+        button { padding: 8px 24px; border: 1px solid #e5e7eb; border-radius: 4px; background: white; color: #4b5563; font: inherit; cursor: pointer; }
+        button:hover { background: #f3f4f6; }
+        button[value="approve"] { border-color: black; background: black; color: white; }
+        button[value="approve"]:hover { background: #1f2937; }
+        :focus-visible { outline: 2px solid #2563eb; outline-offset: 3px; }
+        footer { margin-top: 20px; color: #6b7280; text-align: center; font-size: 12px; }
+        a { color: #4b5563; text-underline-offset: 2px; }
+      </style>
+    </head>
+    <body>
+      <main>
+        <div class="brand">
+          <img src="https://cdn.scalar.com/images/logo-dark.svg" alt="Scalar">
+          <span>${title}</span>
+        </div>
+        <section class="card" aria-labelledby="page-title">
+          <h1 id="page-title">${heading}</h1>
+          <div class="content">${content}</div>
+        </section>
+        <footer>
+          This authorization page is provided by the
+          <a href="https://scalar.com/tools/mock-server/getting-started" target="_blank" rel="noopener noreferrer">Scalar Mock Server</a>.
+        </footer>
+      </main>
+    </body>
+  </html>
+`;
+/** Registers a local RFC8628 approval flow before the permissive mock token handlers. */
+export const setUpDeviceAuthorization = (app, document) => {
+    const title = document?.info?.title ?? '';
+    const grants = new Map();
+    const devicePaths = new Map();
+    const securitySchemes = document?.components?.securitySchemes ?? {};
+    for (const rawScheme of Object.values(securitySchemes)) {
+        const scheme = getResolvedRef(rawScheme);
+        if (scheme?.type === 'oauth2' && scheme.flows?.deviceAuthorization) {
+            const flow = scheme.flows.deviceAuthorization;
+            devicePaths.set(getPathFromUrl(flow.deviceAuthorizationUrl || '/oauth/device'), getPathFromUrl(flow.tokenUrl || '/oauth/token'));
+        }
+    }
+    const tokenPaths = new Set(devicePaths.values());
+    const removeExpired = () => {
+        for (const [code, grant] of grants) {
+            if (grant.expiresAt <= Date.now()) {
+                grants.delete(code);
+            }
+        }
+    };
+    for (const [devicePath, tokenPath] of devicePaths) {
+        const verificationPath = `${devicePath.replace(/\/$/, '')}/verify`;
+        app.post(devicePath, async (c) => {
+            const body = await c.req.parseBody();
+            const clientId = getClientId(body.client_id, c.req.header('Authorization'));
+            c.header('Cache-Control', 'no-store');
+            c.header('Pragma', 'no-cache');
+            if (!clientId) {
+                return c.json({ error: 'invalid_request', error_description: 'Missing client_id' }, 400);
+            }
+            removeExpired();
+            const deviceCode = crypto.randomUUID();
+            const userCode = crypto.randomUUID().slice(0, 8).toUpperCase();
+            grants.set(deviceCode, {
+                clientId,
+                userCode,
+                tokenPath,
+                expiresAt: Date.now() + 600000,
+                nextPoll: 0,
+                interval: 5000,
+                status: 'pending',
+            });
+            const verificationUri = new URL(verificationPath, c.req.url).href;
+            return c.json({
+                device_code: deviceCode,
+                user_code: userCode,
+                verification_uri: verificationUri,
+                verification_uri_complete: `${verificationUri}?user_code=${userCode}`,
+                expires_in: 600,
+                interval: 5,
+            });
+        });
+        app.get(verificationPath, (c) => c.html(renderDevicePage(title, 'Authorize device', html `
+          <p>Enter the code shown in your API client to approve this mock authorization request.</p>
+          <form method="post">
+            <label for="user-code">Device code</label>
+            <input id="user-code" name="user_code" required value="${c.req.query('user_code') ?? ''}" autocomplete="one-time-code" spellcheck="false" autocapitalize="characters">
+            <div class="actions">
+              <button name="decision" value="approve">Approve</button>
+              <button name="decision" value="deny">Deny</button>
+            </div>
+          </form>
+        `)));
+        app.post(verificationPath, async (c) => {
+            const body = await c.req.parseBody();
+            const grant = [...grants.values()].find((entry) => entry.userCode === String(body.user_code).trim().toUpperCase() && entry.tokenPath === tokenPath);
+            if (!grant || grant.expiresAt <= Date.now() || grant.status !== 'pending') {
+                return c.html(renderDevicePage(title, 'Invalid or expired device code', html `<p>Start a new authorization request in your API client and enter the new device code.</p>`), 400);
+            }
+            if (body.decision !== 'approve' && body.decision !== 'deny') {
+                return c.html(renderDevicePage(title, 'Choose Approve or Deny', html `<p>Return to the device authorization form and choose whether to approve or deny the request.</p>`), 400);
+            }
+            grant.status = body.decision === 'approve' ? 'approved' : 'denied';
+            return c.html(renderDevicePage(title, grant.status === 'approved' ? 'Device authorized' : 'Device authorization denied', grant.status === 'approved'
+                ? html `<p>Device authorized. You can return to your API client.</p>`
+                : html `<p>Device authorization denied. You can return to your API client to start a new request.</p>`));
+        });
+    }
+    for (const tokenPath of tokenPaths) {
+        app.post(tokenPath, async (c, next) => {
+            const body = await c.req.parseBody();
+            if (body.grant_type !== 'urn:ietf:params:oauth:grant-type:device_code') {
+                return next();
+            }
+            c.header('Cache-Control', 'no-store');
+            c.header('Pragma', 'no-cache');
+            const clientId = getClientId(body.client_id, c.req.header('Authorization'));
+            const code = String(body.device_code ?? '');
+            const grant = grants.get(code);
+            if (!grant || grant.tokenPath !== tokenPath || grant.clientId !== clientId) {
+                return c.json({ error: 'invalid_grant' }, 400);
+            }
+            if (grant.expiresAt <= Date.now()) {
+                grants.delete(code);
+                return c.json({ error: 'expired_token' }, 400);
+            }
+            if (Date.now() < grant.nextPoll) {
+                grant.interval += 5000;
+                grant.nextPoll = Date.now() + grant.interval;
+                return c.json({ error: 'slow_down' }, 400);
+            }
+            grant.nextPoll = Date.now() + grant.interval;
+            if (grant.status === 'pending') {
+                return c.json({ error: 'authorization_pending' }, 400);
+            }
+            grants.delete(code);
+            if (grant.status === 'denied') {
+                return c.json({ error: 'access_denied' }, 400);
+            }
+            return c.json({
+                access_token: 'super-secret-access-token',
+                token_type: 'Bearer',
+                expires_in: 3600,
+                refresh_token: 'example-refresh-token',
+            });
+        });
+    }
+};

package/dist/utils/streaming-response.d.ts

@@ -0,0 +1,24 @@
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
+import type { Context } from 'hono';
+/** A finite mock stream, with its data-model value available to custom handlers. */
+type StreamingResponse = {
+    body: unknown;
+    chunks: string[];
+    contentType: string;
+};
+/**
+ * Build a finite response for media types with an OpenAPI 3.2 itemSchema.
+ * Explicit examples describe the whole response. Generated item-only streams contain three items,
+ * keeping array-valued items intact. A complete schema controls the sequence when also present.
+ */
+export declare const getStreamingResponse: (mediaType: (Omit<OpenAPIV3_2.MediaTypeObject, "itemSchema"> & {
+    itemSchema?: OpenAPIV3_2.MediaTypeObject["itemSchema"] | boolean;
+}) | undefined, contentType: string, options?: {
+    exampleName?: string;
+    variables?: Record<string, unknown>;
+    body?: unknown;
+}) => StreamingResponse | undefined;
+/** Write each mocked item separately and close the stream when the finite sequence is exhausted. */
+export declare const sendStreamingResponse: (c: Context, response: StreamingResponse) => Response;
+export {};
+//# sourceMappingURL=streaming-response.d.ts.map

package/dist/utils/streaming-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-response.d.ts","sourceRoot":"","sources":["../../src/utils/streaming-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAMnC,oFAAoF;AACpF,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,WACI,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,YAAY,CAAC,GAAG;IACjD,UAAU,CAAC,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,GAAG,OAAO,CAAA;CACjE,CAAC,GACF,SAAS,EACb,aAAa,MAAM,EACnB,UAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,KAC1F,iBAAiB,GAAG,SA8CtB,CAAA;AAED,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,GAAI,GAAG,OAAO,EAAE,UAAU,iBAAiB,KAAG,QAY/E,CAAA"}

package/dist/utils/streaming-response.js

@@ -0,0 +1,65 @@
+import { getStreamFormat } from '@scalar/helpers/http/is-streaming-content-type';
+import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
+import { serializeStreamExample } from '@scalar/workspace-store/helpers/serialize-stream-example';
+import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
+import { SchemaObjectSchema } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { stream } from 'hono/streaming';
+import { generateResponseExample } from './generate-response-example.js';
+import { selectResponseExample } from './select-response-example.js';
+/**
+ * Build a finite response for media types with an OpenAPI 3.2 itemSchema.
+ * Explicit examples describe the whole response. Generated item-only streams contain three items,
+ * keeping array-valued items intact. A complete schema controls the sequence when also present.
+ */
+export const getStreamingResponse = (mediaType, contentType, options = {}) => {
+    if (mediaType?.itemSchema === undefined) {
+        return undefined;
+    }
+    const format = getStreamFormat(contentType);
+    if (format === undefined || format === 'multipart') {
+        return undefined;
+    }
+    const example = options.body !== undefined ? { value: options.body } : selectResponseExample(mediaType, options.exampleName);
+    if (example && typeof example.value === 'string') {
+        return { body: example.value, chunks: [example.value], contentType };
+    }
+    const itemSchema = typeof mediaType.itemSchema === 'boolean' ? mediaType.itemSchema : getResolvedRefDeep(mediaType.itemSchema);
+    const completeSchema = typeof mediaType.schema === 'boolean' ? mediaType.schema : getResolvedRefDeep(mediaType.schema);
+    const generateBody = () => {
+        if (itemSchema === false || completeSchema === false) {
+            return [];
+        }
+        if (completeSchema === undefined) {
+            return Array.from({ length: 3 }, () => itemSchema === true
+                ? null
+                : generateResponseExample(coerceValue(SchemaObjectSchema, itemSchema), options.variables));
+        }
+        if (typeof completeSchema === 'object' && 'type' in completeSchema && completeSchema.type === 'array') {
+            return generateResponseExample(coerceValue(SchemaObjectSchema, {
+                ...completeSchema,
+                items: ('items' in completeSchema ? completeSchema.items : undefined) ?? itemSchema,
+            }), options.variables);
+        }
+        return generateResponseExample(coerceValue(SchemaObjectSchema, completeSchema), options.variables);
+    };
+    const body = example ? example.value : generateBody();
+    const items = body === undefined ? [] : Array.isArray(body) ? body : [body];
+    const chunks = items
+        .filter((item) => item !== undefined)
+        .map((item) => serializeStreamExample(item, contentType, true) ?? '');
+    return { body, chunks, contentType };
+};
+/** Write each mocked item separately and close the stream when the finite sequence is exhausted. */
+export const sendStreamingResponse = (c, response) => {
+    c.header('Content-Type', response.contentType);
+    c.header('Cache-Control', 'no-cache');
+    c.header('X-Accel-Buffering', 'no');
+    return stream(c, async (writer) => {
+        for (const chunk of response.chunks) {
+            if (writer.aborted) {
+                break;
+            }
+            await writer.write(chunk);
+        }
+    });
+};

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

@@ -1 +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;AAoStD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAkKF,CAAA"}
+{"version":3,"file":"validate-request.d.ts","sourceRoot":"","sources":["../../src/utils/validate-request.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,uBAAuB,CAAA;AAMrE,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAuTtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAmLF,CAAA"}

package/dist/utils/validate-request.js

@@ -1,9 +1,12 @@
+import { getFirstMediaType } from '@scalar/helpers/http/get-first-media-type';
+import { parseMimeType } from '@scalar/helpers/http/mime-type';
 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';
 import { getCookie } from 'hono/cookie';
 import { deserializeArrayParameter, deserializeObjectParameter, getObjectPropertyNames, isArraySchema, isObjectSchema, resolveSerialization, } from './deserialize-parameter.js';
+import { findQuerystringParameter, getQuerystringJsonSchema, parseQuerystringParameter } from './querystring-parameter.js';
 import { replaceCircularMarkers } from './replace-circular-markers.js';
 /**
  * Prepare a resolved schema for Ajv by replacing the `'[circular]'` markers a recursive schema leaves
@@ -113,7 +116,7 @@ const mergeParameters = (pathItemParameters, operationParameters) => {
  * in isolation so one broken schema never disables the others.
  */
 const compileSchema = (ajv, schema, label) => {
-    if (!schema) {
+    if (schema === null || schema === undefined) {
         return null;
     }
     try {
@@ -140,6 +143,9 @@ const compileValidators = (operation, pathItemParameters) => {
     const queryParameters = buildParameterSchema(parameters, 'query');
     const headerParameters = buildParameterSchema(parameters, 'header');
     const cookieParameters = buildParameterSchema(parameters, 'cookie');
+    const querystringParameter = findQuerystringParameter(operation, pathItemParameters);
+    const [querystringContentType, querystringMedia] = getFirstMediaType(querystringParameter?.content) ?? [];
+    const querystringSchema = querystringMedia?.schema;
     const requestBody = getResolvedRef(operation.requestBody);
     // Build the body schema defensively; resolving a malformed `$ref` should not crash setup.
     let bodySchema = null;
@@ -151,6 +157,9 @@ const compileValidators = (operation, pathItemParameters) => {
         console.error('Error resolving request body schema, skipping body validation:', error);
     }
     return {
+        querystringParameter,
+        querystringJson: compileSchema(bodyAjv, getQuerystringJsonSchema(querystringParameter), 'querystring JSON properties'),
+        querystring: compileSchema(parseMimeType(querystringContentType).essence === 'application/x-www-form-urlencoded' ? parameterAjv : bodyAjv, querystringSchema === undefined ? null : asCompilableSchema(getResolvedRefDeep(querystringSchema)), 'querystring parameter'),
         path: compileSchema(parameterAjv, pathParameters?.schema ?? null, 'path parameter'),
         query: compileSchema(parameterAjv, queryParameters?.schema ?? null, 'query parameter'),
         header: compileSchema(parameterAjv, headerParameters?.schema ?? null, 'header parameter'),
@@ -312,6 +321,25 @@ export const validateRequest = (operation, pathItemParameters) => {
                 violations.push(...mapErrors(validator.errors, location));
             }
         }
+        if (validators.querystringParameter) {
+            try {
+                const value = parseQuerystringParameter(c.req.url, validators.querystringParameter);
+                if (value === undefined) {
+                    if (validators.querystringParameter.required) {
+                        violations.push({ location: 'query', path: '', message: 'Query string is required' });
+                    }
+                }
+                else if (validators.querystringJson && !validators.querystringJson(value)) {
+                    violations.push(...mapErrors(validators.querystringJson.errors, 'query'));
+                }
+                else if (validators.querystring && !validators.querystring(value)) {
+                    violations.push(...mapErrors(validators.querystring.errors, 'query'));
+                }
+            }
+            catch {
+                violations.push({ location: 'query', path: '', message: 'Query string could not be decoded' });
+            }
+        }
         // 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`

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.14.4",
+  "version": "0.16.0",
   "engines": {
     "node": ">=22"
   },
@@ -52,21 +52,24 @@
   },
   "dependencies": {
     "@faker-js/faker": "10.6.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.1",
-    "@scalar/workspace-store": "0.64.0",
+    "@hono/node-server": "^2.1.1",
+    "@scalar/helpers": "0.14.0",
+    "@scalar/json-magic": "0.15.1",
+    "@scalar/openapi-types": "0.9.7",
+    "@scalar/openapi-upgrader": "0.3.1",
+    "@scalar/types": "0.22.0",
+    "@scalar/workspace-store": "0.66.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "hono": "^4.13.7",
+    "hono": "^4.13.8",
     "quickjs-emscripten": "0.32.0",
+    "ws": "8.21.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",
+    "@types/ws": "8.18.1",
+    "undici": "7.24.4",
     "vite": "8.1.5"
   },
   "scripts": {