@daloyjs/core 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/app.js

@@ -2,17 +2,17 @@ import { Router } from "./router.js";
 import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
 import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
 import { validate } from "./schema.js";
-import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey } from "./security.js";
+import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
 import { createLogger, noopLogger } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
 import { asyncapiHtml, docsContentSecurityPolicy, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
 import { generateAsyncAPI, asyncapiToYAML, } from "./asyncapi.js";
 import { secureHeaders as secureHeadersMiddleware, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, CSRF_HOOK_MARKER, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, SECURE_HEADERS_MARKER, } from "./middleware.js";
 import { COMPRESSION_HOOK_MARKER } from "./compression.js";
-import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
-import { loadShedding as loadSheddingMiddleware } from "./load-shedding.js";
+import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER } from "./session.js";
+import { loadShedding as loadSheddingMiddleware, } from "./load-shedding.js";
 import { httpMetrics, MetricsRegistry, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
-import { Scheduler, } from "./scheduler.js";
+import { Scheduler } from "./scheduler.js";
 import { securitySchemeRequiresPayloadAuth } from "./security-schemes.js";
 import { assertBehindProxy } from "./conn-info.js";
 const AUTO_SECURE_HEADERS_MARKER = Symbol.for("daloyjs.app.autoSecureHeaders");
@@ -260,10 +260,10 @@ export class App {
     inflight = 0;
     draining = false;
     /**
-      * CORS origin allowlist predicates from the currently active group-level
-      * hooks. Used for unmatched routes; matched routes use the snapshot stored
-      * on their compiled route so later `app.use(cors(...))` calls do not
-      * retroactively loosen earlier routes.
+     * CORS origin allowlist predicates from the currently active group-level
+     * hooks. Used for unmatched routes; matched routes use the snapshot stored
+     * on their compiled route so later `app.use(cors(...))` calls do not
+     * retroactively loosen earlier routes.
      */
     corsOriginAllows = [];
     /**
@@ -289,9 +289,9 @@ export class App {
      */
     responseBodySchemaAuditDone = false;
     /**
-    * Cached merge of `options.hooks` only. Used on the cold 404/405 path
-    * and as the baseline for cross-origin guard decisions when no route
-    * matches.
+     * Cached merge of `options.hooks` only. Used on the cold 404/405 path
+     * and as the baseline for cross-origin guard decisions when no route
+     * matches.
      */
     _globalHooksCache;
     _globalCorsAllowsCache;
@@ -307,6 +307,19 @@ export class App {
         }
         return this._globalCorsAllowsCache;
     }
+    /**
+     * Cached merge of `options.hooks` plus every `app.use()` group hook, used on
+     * the cold dispatch path (404, 405, and OPTIONS preflight) so perimeter
+     * `beforeHandle` guards registered via `app.use()` still cover requests that
+     * match no route.
+     */
+    _coldPathHooksCache;
+    get coldPathHooks() {
+        if (this._coldPathHooksCache === undefined) {
+            this._coldPathHooksCache = mergeHooks([this.options.hooks ?? {}, ...this.groupHooks]);
+        }
+        return this._coldPathHooksCache;
+    }
     constructor(options = {}) {
         const resolved = applySecurityPreset(options);
         this.options = {
@@ -319,8 +332,7 @@ export class App {
         this.log =
             options.logger === false
                 ? noopLogger
-                : options.logger &&
-                    typeof options.logger.info === "function"
+                : options.logger && typeof options.logger.info === "function"
                     ? options.logger
                     : createLogger({ level: options.logger?.level ?? "info" });
         this.warnOnEnvMismatch();
@@ -373,7 +385,7 @@ export class App {
                 "If you really need this in production, also pass " +
                 "acknowledgeInsecureDefaults: true to confirm. Prefer per-feature opt-outs " +
                 "(secureHeaders: false, corsCrossOriginGuard: false, crashOnUnhandledRejection: false, " +
-                "trustProxy: false, csrf: \"off\") instead. " +
+                'trustProxy: false, csrf: "off") instead. ' +
                 "See https://daloyjs.dev/docs/security/secure-defaults-enforcement.");
         }
         if (!insecureDefaultsLoggedThisProcess) {
@@ -438,9 +450,7 @@ export class App {
             secureHeaders: o.secureDefaults !== false && o.secureHeaders !== false,
             corsCrossOriginGuard: o.secureDefaults !== false && o.corsCrossOriginGuard !== false,
             csrf: o.csrf === "off" ? "off" : "on",
-            crashOnUnhandledRejection: o.crashOnUnhandledRejection === undefined
-                ? "default"
-                : o.crashOnUnhandledRejection,
+            crashOnUnhandledRejection: o.crashOnUnhandledRejection === undefined ? "default" : o.crashOnUnhandledRejection,
             trustProxy: o.trustProxy === undefined ? "unconfigured" : o.trustProxy,
             bodyLimitBytes: this.options.bodyLimitBytes,
             requestTimeoutMs: this.options.requestTimeoutMs,
@@ -464,8 +474,7 @@ export class App {
         if (this.options.secureDefaults === false)
             return;
         if (this.options.secureHeaders !== false) {
-            const opts = this.options.secureHeaders &&
-                typeof this.options.secureHeaders === "object"
+            const opts = this.options.secureHeaders && typeof this.options.secureHeaders === "object"
                 ? this.options.secureHeaders
                 : {};
             const auto = secureHeadersMiddleware(opts);
@@ -474,9 +483,7 @@ export class App {
         }
         // Opt-in load-shedding pressure monitor.
         if (this.options.loadShedding) {
-            const lsOpts = typeof this.options.loadShedding === "object"
-                ? this.options.loadShedding
-                : {};
+            const lsOpts = typeof this.options.loadShedding === "object" ? this.options.loadShedding : {};
             this.groupHooks.push(loadSheddingMiddleware(lsOpts));
         }
     }
@@ -583,10 +590,7 @@ export class App {
             return;
         if (this.options.corsCrossOriginGuard === false)
             return;
-        if (method !== "POST" &&
-            method !== "PUT" &&
-            method !== "PATCH" &&
-            method !== "DELETE") {
+        if (method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") {
             return;
         }
         const origin = request.headers.get("origin");
@@ -704,8 +708,7 @@ export class App {
      * `test`, which is a known, non-production answer).
      */
     isEnvIndeterminate() {
-        if (this.options.env !== undefined ||
-            this.options.production !== undefined) {
+        if (this.options.env !== undefined || this.options.production !== undefined) {
             return false;
         }
         const nodeEnv = typeof process !== "undefined" && typeof process.env !== "undefined"
@@ -917,15 +920,11 @@ export class App {
         };
         const generate = async () => generateOpenAPI(this, {
             info: await resolveInfo(),
-            ...(this.options.openapi?.servers
-                ? { servers: this.options.openapi.servers }
-                : {}),
+            ...(this.options.openapi?.servers ? { servers: this.options.openapi.servers } : {}),
             ...(this.options.openapi?.securitySchemes
                 ? { securitySchemes: this.options.openapi.securitySchemes }
                 : {}),
-            ...(this.options.openapi?.webhooks
-                ? { webhooks: this.options.openapi.webhooks }
-                : {}),
+            ...(this.options.openapi?.webhooks ? { webhooks: this.options.openapi.webhooks } : {}),
         });
         this.route({
             method: "GET",
@@ -997,6 +996,7 @@ export class App {
                         title,
                         configuration: opts.swagger,
                         assets: opts.assets,
+                        auth: opts.auth,
                     })
                     : ui === "redoc"
                         ? redocHtml({
@@ -1004,12 +1004,14 @@ export class App {
                             title,
                             configuration: opts.redoc,
                             assets: opts.assets,
+                            auth: opts.auth,
                         })
                         : scalarHtml({
                             specUrl: openapiPath,
                             title,
                             configuration: scalarConfigurationWithPreferredAuth(opts.scalar, this.options.openapi?.securitySchemes),
                             assets: opts.assets,
+                            auth: opts.auth,
                         });
                 return {
                     status: 200,
@@ -1059,9 +1061,7 @@ export class App {
      */
     mountAsyncAPI(opts) {
         const jsonPath = (opts.jsonPath ?? "/asyncapi.json");
-        const yamlPath = opts.yamlPath === false
-            ? null
-            : (opts.yamlPath ?? "/asyncapi.yaml");
+        const yamlPath = opts.yamlPath === false ? null : (opts.yamlPath ?? "/asyncapi.yaml");
         const uiPath = (opts.path ?? "/asyncapi");
         const tags = opts.tags ?? ["AsyncAPI"];
         const resolveInfo = async () => {
@@ -1239,10 +1239,7 @@ export class App {
             ...corsOriginAllowsFromHooks([globalHookLayer]),
             ...corsOriginAllows,
         ];
-        const securityMarkers = securityMarkersFromHooks([
-            globalHookLayer,
-            ...sources,
-        ]);
+        const securityMarkers = securityMarkersFromHooks([globalHookLayer, ...sources]);
         this.router.add(def.method, fullPath, { def: merged, hooks, mergedHooks, hasFinalizeHook, corsOriginAllows, fullCorsOriginAllows }, def.operationId);
         // `routes` is statically a readonly tuple so the typed client can infer
         // per-route methods; at runtime it is a growable array, so we push through
@@ -1298,7 +1295,7 @@ export class App {
             handler.acknowledgeCrossOriginUpgrade !== true) {
             throw new Error(`app.ws(${JSON.stringify(fullPath)}): production WebSocket routes must ` +
                 "guard against Cross-Site WebSocket Hijacking (CSWSH). Set " +
-                "{ allowedOrigins: \"same-origin\" } or an explicit origin allowlist, " +
+                '{ allowedOrigins: "same-origin" } or an explicit origin allowlist, ' +
                 "or pass { acknowledgeCrossOriginUpgrade: true } for an intentionally " +
                 "public route. See https://daloyjs.dev/docs/websocket " +
                 "and CVE-2026-27148 (Storybook) for the attack pattern.");
@@ -1368,9 +1365,7 @@ export class App {
      */
     readinesscheck(opts = {}) {
         this.registerHealthRoute("readinesscheck", opts, () => {
-            if (this.draining ||
-                this.pendingPlugins.size > 0 ||
-                this.pluginBootError.failed) {
+            if (this.draining || this.pendingPlugins.size > 0 || this.pluginBootError.failed) {
                 return {
                     status: 503,
                     body: { status: "not-ready" },
@@ -1415,9 +1410,7 @@ export class App {
     metrics(opts = {}) {
         const path = (opts.path ?? "/metrics");
         const registry = opts.registry ?? new MetricsRegistry();
-        const rateLimitConfig = opts.rateLimit === false
-            ? null
-            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
         const token = opts.token;
         // Refuse-to-boot: an unauthenticated metrics scrape in production is a
         // documented info-disclosure surface (route inventory, latency
@@ -1442,9 +1435,8 @@ export class App {
             buckets: opts.buckets,
             exclude,
         }));
-        const buckets = rateLimitConfig
-            ? new Map()
-            : null;
+        this._coldPathHooksCache = undefined;
+        const buckets = rateLimitConfig ? new Map() : null;
         this.route({
             method: "GET",
             path,
@@ -1548,9 +1540,7 @@ export class App {
         const isHealth = kind === "healthcheck";
         const defaultPath = (isHealth ? "/healthz" : "/readyz");
         const path = (opts.path ?? defaultPath);
-        const rateLimitConfig = opts.rateLimit === false
-            ? null
-            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
         const token = opts.token;
         // Refuse-to-boot: unauthenticated health/ready probes in
         // production are a documented info-disclosure surface (process uptime,
@@ -1564,9 +1554,7 @@ export class App {
                 `Authorization: Bearer <token>, or pass acknowledgeUnauthenticated: true ` +
                 `to acknowledge that this probe is reachable without credentials.`);
         }
-        const buckets = rateLimitConfig
-            ? new Map()
-            : null;
+        const buckets = rateLimitConfig ? new Map() : null;
         this.route({
             method: "GET",
             path,
@@ -1623,8 +1611,8 @@ export class App {
      * when omitted). Returns `204 No Content` so browsers stop retrying.
      *
      * Combine with `secureHeaders({ reportingEndpoints, reportTo })` to wire
-    * the browser to this endpoint. The route is registered as publicly
-    * reachable; that is required for the browser
+     * the browser to this endpoint. The route is registered as publicly
+     * reachable; that is required for the browser
      * Reporting API to send to it.
      *
      */
@@ -1637,12 +1625,8 @@ export class App {
         if (!Number.isInteger(maxBytes) || maxBytes <= 0 || maxBytes > HARD_MAX) {
             throw new Error(`cspReportRoute(): maxBodyBytes must be a positive integer <= ${HARD_MAX}.`);
         }
-        const rateLimitConfig = opts.rateLimit === false
-            ? null
-            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
-        const buckets = rateLimitConfig
-            ? new Map()
-            : null;
+        const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const buckets = rateLimitConfig ? new Map() : null;
         const log = this.log;
         // Only log report bodies when explicitly enabled. In
         // production this is opt-in; in development the body is included by
@@ -1759,10 +1743,7 @@ export class App {
         child.bootGuard = this.bootGuard;
         child.log = this.log;
         child.prefix = joinPath(this.prefix, prefix);
-        child.groupHooks = [
-            ...this.groupHooks,
-            ...(config.hooks ? [config.hooks] : []),
-        ];
+        child.groupHooks = [...this.groupHooks, ...(config.hooks ? [config.hooks] : [])];
         child.corsOriginAllows = corsOriginAllowsFromHooks(child.groupHooks);
         child.groupTags = [...this.groupTags, ...(config.tags ?? [])];
         child.groupAuth = config.auth ?? this.groupAuth;
@@ -1806,12 +1787,12 @@ export class App {
         // "set only if absent" semantics mean the second installation would be
         // a silent no-op).
         if (hooks[SECURE_HEADERS_MARKER] === true) {
-            const autoIdx = this.groupHooks.findIndex((h) => h[AUTO_SECURE_HEADERS_MARKER] ===
-                true);
+            const autoIdx = this.groupHooks.findIndex((h) => h[AUTO_SECURE_HEADERS_MARKER] === true);
             if (autoIdx >= 0)
                 this.groupHooks.splice(autoIdx, 1);
         }
         this.groupHooks.push(hooks);
+        this._coldPathHooksCache = undefined;
         if (hooks[CORS_HOOK_MARKER] === true) {
             this.corsOriginAllows = corsOriginAllowsFromHooks(this.groupHooks);
         }
@@ -1854,10 +1835,10 @@ export class App {
             const hooks = { [ext.event]: ext.handler };
             this.groupHooks.push(hooks);
         }
+        this._coldPathHooksCache = undefined;
     }
     decorate(key, value, opts = {}) {
-        if (Object.prototype.hasOwnProperty.call(this.decorations, key) &&
-            opts.override !== true) {
+        if (Object.prototype.hasOwnProperty.call(this.decorations, key) && opts.override !== true) {
             // Namespace-protected decorators. Refuse to silently
             // shadow an existing decoration; emit a once-per-process warn naming
             // both decorators on the explicit-override path.
@@ -2005,9 +1986,7 @@ export class App {
                 this.log.error({ err, plugin: event.name }, "onPluginInstalled listener failed");
             }
         }
-        return promises.length > 0
-            ? Promise.all(promises).then(() => undefined)
-            : undefined;
+        return promises.length > 0 ? Promise.all(promises).then(() => undefined) : undefined;
     }
     /**
      * Wait until every async plugin registered with {@link App.register} has
@@ -2144,7 +2123,10 @@ export class App {
                 this.assertCrossOriginAllowed(request, requestUrl, method, match.handler.fullCorsOriginAllows);
             }
             else {
-                this.assertCrossOriginAllowed(request, requestUrl, method, [...this.globalCorsAllows, ...this.corsOriginAllows]);
+                this.assertCrossOriginAllowed(request, requestUrl, method, [
+                    ...this.globalCorsAllows,
+                    ...this.corsOriginAllows,
+                ]);
             }
             if (!match || internalHidden) {
                 if (internalHidden) {
@@ -2168,9 +2150,10 @@ export class App {
                 // `decorations`, iterate headers, or materialize a `Headers`
                 // instance just to be thrown away. The 204 OPTIONS preflight branch
                 // below uses its own `synthCtx`, so this skip is safe for it too.
+                const coldGuards = method === "OPTIONS" ? undefined : this.coldPathHooks.beforeHandle;
                 const needsCtx = allowed.length > 0 && method === "OPTIONS"
                     ? false // OPTIONS path builds synthCtx
-                    : activeErrorHook !== undefined;
+                    : activeErrorHook !== undefined || coldGuards !== undefined;
                 if (needsCtx) {
                     // `query` and `headers` are materialized lazily — the common
                     // `onError` hook reads `requestId` / path and never touches them,
@@ -2194,20 +2177,36 @@ export class App {
                             const qs = hi === -1 ? reqUrl.slice(qi + 1) : reqUrl.slice(qi + 1, hi);
                             return (_query = Object.fromEntries(new URLSearchParams(qs)));
                         },
-                        set query(v) { _query = v; },
+                        set query(v) {
+                            _query = v;
+                        },
                         get headers() {
                             return (_headers ??= headersToObject(reqRef.headers));
                         },
-                        set headers(v) { _headers = v; },
+                        set headers(v) {
+                            _headers = v;
+                        },
                         body: undefined,
                         state: { ...this.decorations, requestId, log },
-                        set: { headers: new Headers() },
+                        set: new LazyResponseSet(),
                         // Cast through `unknown`: this is a deliberately minimal bootstrap
                         // context for the cold 404 path (no user state populated yet), so
                         // it must compile even when a consumer augments `AppState`.
                     };
                     ctx.set.headers.set("x-request-id", requestId);
                 }
+                if (coldGuards !== undefined) {
+                    const guardResult = coldGuards(ctx);
+                    const guarded = isPromiseLike(guardResult) ? await guardResult : guardResult;
+                    if (guarded instanceof Response) {
+                        copyContextHeaders(ctx, guarded);
+                        if (!guarded.headers.has("x-request-id")) {
+                            guarded.headers.set("x-request-id", requestId);
+                        }
+                        const fin = finalizeResponse(guarded, ctx, this.coldPathHooks, stripFingerprint);
+                        return isPromiseLike(fin) ? await fin : fin;
+                    }
+                }
                 if (allowed.length > 0) {
                     if (method === "OPTIONS") {
                         // Synthesize a preflight: let global hooks (e.g. CORS) intercept;
@@ -2221,14 +2220,13 @@ export class App {
                             headers: headersToObject(request.headers),
                             body: undefined,
                             state: { ...this.decorations, requestId, log },
-                            set: { headers: new Headers() },
+                            set: new LazyResponseSet(),
                         };
-                        const preflightHooks = mergeHooks([
-                            this.options.hooks ?? {},
-                            ...this.groupHooks,
-                        ]);
+                        const preflightHooks = this.coldPathHooks;
                         const interceptedResult = preflightHooks.beforeHandle?.(synthCtx);
-                        const intercepted = isPromiseLike(interceptedResult) ? await interceptedResult : interceptedResult;
+                        const intercepted = isPromiseLike(interceptedResult)
+                            ? await interceptedResult
+                            : interceptedResult;
                         if (intercepted instanceof Response) {
                             copyContextHeaders(synthCtx, intercepted);
                             const fin = finalizeResponse(intercepted, synthCtx, preflightHooks, stripFingerprint);
@@ -2328,7 +2326,9 @@ export class App {
                 return finalizedRaw;
             }
             const serializeResultRes = serializeResult(result, def, this.options.validateResponses ?? true);
-            let response = isPromiseLike(serializeResultRes) ? await serializeResultRes : serializeResultRes;
+            let response = isPromiseLike(serializeResultRes)
+                ? await serializeResultRes
+                : serializeResultRes;
             copyContextHeaders(ctx, response);
             // `serializeResult` always builds a fresh Response with no request id —
             // skip the `has()` probe and set directly. Saves one undici contains()
@@ -2379,8 +2379,7 @@ export class App {
             // problem errors short-circuit before any signal/option lookup.
             const isHttp = err instanceof HttpError;
             const disconnectCode = isHttp ? 0 : (this.options.disconnectStatusCode ?? 499);
-            if (disconnectCode > 0 &&
-                request.signal?.aborted === true) {
+            if (disconnectCode > 0 && request.signal?.aborted === true) {
                 log.info({ event: "request.disconnected", status: disconnectCode }, "Client disconnected before response was sent");
                 const res = new Response(null, {
                     status: disconnectCode,
@@ -2437,9 +2436,7 @@ export class App {
      * @returns Fulfills with the `Response` produced by the matching handler.
      */
     request(input, init) {
-        const url = typeof input === "string" && input.startsWith("/")
-            ? `http://test.local${input}`
-            : input;
+        const url = typeof input === "string" && input.startsWith("/") ? `http://test.local${input}` : input;
         const req = url instanceof Request ? url : new Request(url, init);
         return this.fetch(req);
     }
@@ -2594,9 +2591,7 @@ function healthRouteKey(request) {
     // so even apps that trust forwarded headers should not let an attacker
     // bypass the per-IP cap by spoofing the header. Fall back to a constant
     // key when no proxy header is available (single shared bucket).
-    return (request.headers.get("x-real-ip") ??
-        request.headers.get("fly-client-ip") ??
-        "global");
+    return request.headers.get("x-real-ip") ?? request.headers.get("fly-client-ip") ?? "global";
 }
 function corsOriginAllowsFromHooks(layers) {
     const allows = [];
@@ -2710,9 +2705,7 @@ export function topoSortExtensions(exts) {
             const bHeaders = b.responseHeaders;
             if (!bHeaders || bHeaders.length === 0)
                 continue;
-            const overlap = bHeaders
-                .map((h) => h.toLowerCase())
-                .filter((h) => aSet.has(h));
+            const overlap = bHeaders.map((h) => h.toLowerCase()).filter((h) => aSet.has(h));
             if (overlap.length === 0)
                 continue;
             const declared = (a.before ?? []).includes(b.name) ||
@@ -2743,10 +2736,7 @@ function securityMarkersFromHooks(layers) {
     return { hasSession, hasCsrf };
 }
 function isStateChangingMethod(method) {
-    return (method === "POST" ||
-        method === "PUT" ||
-        method === "PATCH" ||
-        method === "DELETE");
+    return method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
 }
 /**
  * Extract the pathname from a fully-qualified request URL without
@@ -2777,9 +2767,7 @@ function getPathnameFast(url) {
     return url.slice(pathStart, end);
 }
 function mergeHooks(layers) {
-    const pick = (key) => layers
-        .map((h) => h[key])
-        .filter((f) => typeof f === "function");
+    const pick = (key) => layers.map((h) => h[key]).filter((f) => typeof f === "function");
     const requiredScopes = requiredScopesFromHooks(layers);
     const beforeHandle = mergeBeforeHandle(firstResponse(pick("beforeHandle")), requiredScopes);
     const hooks = {
@@ -2880,9 +2868,7 @@ function scalarConfigurationWithPreferredAuth(configuration, schemes) {
     return {
         ...(configuration ?? {}),
         authentication: {
-            ...(authentication &&
-                typeof authentication === "object" &&
-                !Array.isArray(authentication)
+            ...(authentication && typeof authentication === "object" && !Array.isArray(authentication)
                 ? authentication
                 : {}),
             preferredSecurityScheme,
@@ -3172,7 +3158,8 @@ function buildContext(request, getUrl, rawParams, def, opts) {
         }
         if (def.request?.body) {
             const ct = (request.headers.get("content-type") ?? "").toLowerCase();
-            const allowed = def.accepts ?? opts.allowedContentTypes ?? [
+            const allowed = def.accepts ??
+                opts.allowedContentTypes ?? [
                 "application/json",
                 "application/x-www-form-urlencoded",
                 "multipart/form-data",
@@ -3214,7 +3201,7 @@ function toIssues(issues) {
     return issues.map((i) => ({
         message: i.message,
         path: (i.path ?? [])
-            .map((p) => typeof p === "object" && p && "key" in p ? p.key : p)
+            .map((p) => (typeof p === "object" && p && "key" in p ? p.key : p))
             .join("."),
     }));
 }
@@ -3271,8 +3258,7 @@ async function readBody(req, ct, limit, multipart) {
                 typeof v.arrayBuffer === "function";
             if (isFile) {
                 files++;
-                if (multipart?.maxFileBytes !== undefined &&
-                    v.size > multipart.maxFileBytes) {
+                if (multipart?.maxFileBytes !== undefined && v.size > multipart.maxFileBytes) {
                     throw new PayloadTooLargeError(multipart.maxFileBytes);
                 }
             }
@@ -3511,9 +3497,7 @@ function readHostPackageJsonInfo() {
             // deno.jsonc allows // line comments and /* block */ comments. Strip
             // them before parsing — naively, but well enough for typical manifests.
             const text = allowComments
-                ? raw
-                    .replace(/\/\*[\s\S]*?\*\//g, "")
-                    .replace(/(^|[^:\\])\/\/.*$/gm, "$1")
+                ? raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:\\])\/\/.*$/gm, "$1")
                 : raw;
             return JSON.parse(text);
         };

package/dist/docs.d.ts

@@ -254,6 +254,42 @@ export interface DocsAssetOptions {
      */
     crossOrigin?: "anonymous" | "use-credentials";
 }
+/**
+ * Provider-neutral login launcher rendered into generated docs pages.
+ *
+ * Use this when the OpenAPI docs should expose a visible authorization control
+ * that sends developers to a local login form or to an external identity
+ * provider such as Entra ID, Auth0, Better Auth, Clerk, Okta, Keycloak, or any
+ * other OAuth2/OIDC front end. The launcher only opens the configured URL; it
+ * never stores tokens or bypasses the OpenAPI UI's normal security-scheme
+ * handling.
+ *
+ * @since 0.43.0
+ */
+export interface DocsAuthLauncherOptions {
+    /**
+     * Absolute `http(s)` URL or same-origin/relative URL for the login or
+     * authorization entry point. `javascript:`, `data:`, and other executable
+     * schemes are refused when the HTML is generated.
+     */
+    loginUrl: string;
+    /** Button text. Defaults to `"Authorize"`. */
+    label?: string;
+    /**
+     * Accessible helper text shown as the button title and screen-reader label.
+     * Defaults to `"Open login or identity provider"`.
+     */
+    description?: string;
+    /**
+     * How to open {@link DocsAuthLauncherOptions.loginUrl}. Defaults to
+     * `"popup"` so docs remain open while the provider flow runs.
+     */
+    target?: "popup" | "_blank" | "_self";
+    /** Popup width in CSS/device pixels. Defaults to `520`. */
+    popupWidth?: number;
+    /** Popup height in CSS/device pixels. Defaults to `720`. */
+    popupHeight?: number;
+}
 /** Shared options for {@link scalarHtml}, {@link swaggerUiHtml}, and {@link redocHtml}. */
 export interface DocsOptions {
     /** Absolute or relative URL of the OpenAPI document to render. */
@@ -267,6 +303,14 @@ export interface DocsOptions {
     assets?: DocsAssetOptions;
     /** CSP `nonce` to apply to inline/script tags; must match the response CSP. */
     scriptNonce?: string;
+    /**
+     * Optional authorization launcher rendered into the docs page. It gives
+     * Scalar, Swagger UI, and Redoc a consistent visible button that opens a
+     * local login form or third-party identity-provider authorization URL.
+     *
+     * @since 0.43.0
+     */
+    auth?: DocsAuthLauncherOptions;
 }
 /** Options for {@link scalarHtml}; adds Scalar-specific UI configuration. */
 export interface ScalarHtmlOptions extends DocsOptions {