@daloyjs/core 1.0.0-beta.6 → 1.0.0-rc.0

package/dist/mcp.js

@@ -25,17 +25,51 @@ export const MCP_PROTOCOL_VERSIONS = Object.freeze([
  * @since 1.0.0
  */
 export const MCP_DEFAULT_MAX_BODY_BYTES = 1 << 18;
+/**
+ * Protocol revision assumed when an HTTP request carries no
+ * `MCP-Protocol-Version` header, as required by the Streamable HTTP spec for
+ * backwards compatibility with pre-2025-06-18 clients.
+ */
+const LEGACY_ASSUMED_PROTOCOL_VERSION = "2025-03-26";
 const PARSE_ERROR = -32700;
 const INVALID_REQUEST = -32600;
 const METHOD_NOT_FOUND = -32601;
 const INVALID_PARAMS = -32602;
 const INTERNAL_ERROR = -32603;
+/**
+ * JSON Schema for the JSON-RPC 2.0 envelope every MCP response uses. Exposed
+ * through `toJSONSchema()` so the generated OpenAPI document describes the
+ * `/mcp` route honestly instead of leaving it an undocumented blind spot.
+ */
+const MCP_JSONRPC_ENVELOPE_JSON_SCHEMA = {
+    type: "object",
+    description: "JSON-RPC 2.0 envelope produced by the MCP Streamable HTTP endpoint.",
+    properties: {
+        jsonrpc: { type: "string", const: "2.0" },
+        id: { oneOf: [{ type: "string" }, { type: "number" }, { type: "null" }] },
+        result: { description: "Method result. Present on success; shape varies by MCP method." },
+        error: {
+            type: "object",
+            properties: {
+                code: { type: "integer" },
+                message: { type: "string" },
+                data: {},
+            },
+            required: ["code", "message"],
+            additionalProperties: false,
+        },
+    },
+    required: ["jsonrpc"],
+};
 const MCP_JSON_RESPONSE_SCHEMA = {
     "~standard": {
         version: 1,
         vendor: "daloyjs",
+        // Pass-through: the MCP handler fully controls the envelope it builds, so
+        // re-validating (or field-stripping) it here would only burn cycles.
         validate: (value) => ({ value }),
     },
+    toJSONSchema: () => MCP_JSONRPC_ENVELOPE_JSON_SCHEMA,
 };
 /**
  * Caller-correctable MCP tool/resource/prompt error.
@@ -103,21 +137,105 @@ function publicPrompt(prompt) {
     const { get: _get, ...rest } = prompt;
     return rest;
 }
+function publicResourceTemplate(template) {
+    const { read: _read, ...rest } = template;
+    return rest;
+}
 function normalizeToolResult(value) {
-    return typeof value === "string" ? { content: [{ type: "text", text: value }] } : value;
+    if (typeof value === "string")
+        return { content: [{ type: "text", text: value }] };
+    if (value.content && value.content.length > 0)
+        return value;
+    // Backwards compatibility: clients that predate `structuredContent` only
+    // read `content`, so mirror the structured payload into a text block.
+    const content = value.structuredContent !== undefined
+        ? [{ type: "text", text: JSON.stringify(value.structuredContent) }]
+        : [];
+    return { ...value, content };
 }
 function selectedProtocolVersion(requested, supported, preferred) {
     return supported.has(requested) ? requested : preferred;
 }
+function escapeRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Compile a simple RFC 6570 level-1 URI template into a matcher. Each
+ * `{name}` variable matches exactly one URI segment (`[^/]+`). Operators such
+ * as `{+path}` or `{?query}` are rejected so the handler never advertises a
+ * template it cannot match.
+ */
+function compileUriTemplate(template) {
+    const { uriTemplate } = template;
+    const variables = [];
+    let pattern = "";
+    let index = 0;
+    while (index < uriTemplate.length) {
+        const open = uriTemplate.indexOf("{", index);
+        if (open === -1) {
+            pattern += escapeRegExp(uriTemplate.slice(index));
+            break;
+        }
+        pattern += escapeRegExp(uriTemplate.slice(index, open));
+        const close = uriTemplate.indexOf("}", open);
+        if (close === -1) {
+            throw new TypeError(`MCP resource template "${uriTemplate}" has an unterminated "{".`);
+        }
+        const name = uriTemplate.slice(open + 1, close);
+        if (!/^[A-Za-z0-9_]+$/.test(name)) {
+            throw new TypeError(`MCP resource template "${uriTemplate}" uses an unsupported expression "{${name}}"; ` +
+                "only simple {name} variables are supported.");
+        }
+        variables.push(name);
+        pattern += "([^/]+)";
+        index = close + 1;
+    }
+    return { template, regex: new RegExp(`^${pattern}$`), variables };
+}
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * Streamable HTTP DNS-rebinding defense: decide whether a browser `Origin`
+ * may talk to this MCP endpoint. Same-origin and loopback origins are always
+ * allowed; anything else must be explicitly allowlisted.
+ */
+function isAllowedOrigin(origin, request, allowlist) {
+    const normalized = origin.toLowerCase();
+    if (allowlist.has(normalized))
+        return true;
+    if (normalized === "null")
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        return false;
+    }
+    const hostname = parsed.hostname;
+    if (LOOPBACK_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost"))
+        return true;
+    try {
+        return parsed.host === new URL(request.url).host;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Create a dependency-free MCP Streamable HTTP endpoint handler.
  *
  * The handler implements the server side of MCP over one HTTP endpoint:
  * `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`,
- * `resources/read`, `prompts/list`, and `prompts/get`. It accepts JSON-RPC
- * requests over `POST`, acknowledges notifications with `202`, validates the
- * `MCP-Protocol-Version` header, bounds request bodies, and returns JSON-RPC
- * errors for malformed input.
+ * `resources/templates/list`, `resources/read`, `prompts/list`, and
+ * `prompts/get`. It accepts JSON-RPC requests over `POST`, acknowledges
+ * notifications with `202`, validates the `MCP-Protocol-Version` header,
+ * bounds request bodies, enforces required prompt arguments, and returns
+ * JSON-RPC errors for malformed input.
+ *
+ * Security: per the Streamable HTTP spec's DNS-rebinding guidance, every
+ * request bearing an `Origin` header is validated. Same-origin and loopback
+ * origins pass; anything else is rejected with `403` unless listed in
+ * {@link McpHandlerOptions.allowedOrigins}.
  *
  * It intentionally does not spawn stdio servers, manage OAuth metadata, keep
  * durable sessions, or open server-initiated SSE streams. Use DaloyJS
@@ -128,6 +246,9 @@ function selectedProtocolVersion(requested, supported, preferred) {
  * @param options - Server identity, capabilities, limits, and response headers.
  * @returns A Fetch-compatible request handler suitable for {@link mcpRoutes}
  *   or for direct use in any web-standard runtime.
+ * @throws {TypeError} at construction for invalid serverInfo, protocol
+ *   versions, body limits, duplicate names/URIs, malformed `allowedOrigins`
+ *   entries, or unsupported URI template expressions.
  *
  * @example
  * ```ts
@@ -173,6 +294,7 @@ export function createMcpHandler(options) {
     }
     const tools = options.tools ?? [];
     const resources = options.resources ?? [];
+    const resourceTemplates = options.resourceTemplates ?? [];
     const prompts = options.prompts ?? [];
     const toolMap = new Map(tools.map((tool) => [tool.name, tool]));
     const resourceMap = new Map(resources.map((resource) => [resource.uri, resource]));
@@ -183,24 +305,68 @@ export function createMcpHandler(options) {
         throw new TypeError("MCP resource URIs must be unique.");
     if (promptMap.size !== prompts.length)
         throw new TypeError("MCP prompt names must be unique.");
+    if (new Set(resourceTemplates.map((template) => template.uriTemplate)).size !==
+        resourceTemplates.length) {
+        throw new TypeError("MCP resource template URIs must be unique.");
+    }
+    const compiledTemplates = resourceTemplates.map(compileUriTemplate);
+    const allowedOrigins = new Set();
+    for (const entry of options.allowedOrigins ?? []) {
+        const normalized = entry.toLowerCase();
+        if (normalized === "null") {
+            allowedOrigins.add(normalized);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = new URL(normalized);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!parsed || parsed.origin !== normalized) {
+            throw new TypeError(`MCP allowedOrigins entry "${entry}" must be a bare origin such as "https://app.example.com".`);
+        }
+        allowedOrigins.add(normalized);
+    }
     const exposeInternalErrors = options.exposeInternalErrors ??
         (typeof process === "object" && process.env?.NODE_ENV !== "production");
     const headers = options.headers;
+    const legacyAssumed = supported.has(LEGACY_ASSUMED_PROTOCOL_VERSION)
+        ? LEGACY_ASSUMED_PROTOCOL_VERSION
+        : preferred;
     async function handleRpcRequest(message, request) {
         const id = (message.id ?? null);
         const method = message.method;
         const params = asRecord(message.params);
-        const protocolVersion = selectedProtocolVersion(typeof params.protocolVersion === "string"
-            ? params.protocolVersion
-            : (request.headers.get("mcp-protocol-version") ?? ""), supported, preferred);
+        const headerVersion = request.headers.get("mcp-protocol-version");
+        // Per the Streamable HTTP spec, a request without the header is assumed
+        // to speak 2025-03-26; `initialize` negotiates via params instead.
+        const protocolVersion = method === "initialize"
+            ? selectedProtocolVersion(typeof params.protocolVersion === "string"
+                ? params.protocolVersion
+                : (headerVersion ?? ""), supported, preferred)
+            : headerVersion !== null
+                ? selectedProtocolVersion(headerVersion, supported, preferred)
+                : legacyAssumed;
         const ctx = { request, protocolVersion, id, method };
+        const cursor = params.cursor;
+        if (cursor !== undefined &&
+            (method === "tools/list" ||
+                method === "resources/list" ||
+                method === "resources/templates/list" ||
+                method === "prompts/list")) {
+            // This handler returns complete lists and never issues cursors, so any
+            // client-supplied cursor is unknown by definition.
+            return rpcError(id, INVALID_PARAMS, "Unknown pagination cursor.", undefined, 200, headers);
+        }
         switch (method) {
             case "initialize":
                 return rpcResult(id, {
                     protocolVersion,
                     capabilities: {
                         ...(tools.length > 0 ? { tools: {} } : {}),
-                        ...(resources.length > 0 ? { resources: {} } : {}),
+                        ...(resources.length > 0 || resourceTemplates.length > 0 ? { resources: {} } : {}),
                         ...(prompts.length > 0 ? { prompts: {} } : {}),
                     },
                     serverInfo: options.serverInfo,
@@ -229,23 +395,46 @@ export function createMcpHandler(options) {
             }
             case "resources/list":
                 return rpcResult(id, { resources: resources.map(publicResource) }, headers);
+            case "resources/templates/list":
+                return rpcResult(id, { resourceTemplates: resourceTemplates.map(publicResourceTemplate) }, headers);
             case "resources/read": {
                 const uri = typeof params.uri === "string" ? params.uri : "";
-                const resource = resourceMap.get(uri);
-                if (!resource) {
-                    return rpcError(id, INVALID_PARAMS, `Unknown resource: ${uri || "<missing>"}`, undefined, 200, headers);
-                }
-                try {
-                    const read = await resource.read(ctx);
-                    return rpcResult(id, { contents: Array.isArray(read) ? read : [read] }, headers);
-                }
-                catch (error) {
+                const readError = (error) => {
                     const message = error instanceof McpToolError ? error.message : "Resource read failed.";
                     const data = error instanceof McpToolError
                         ? undefined
                         : safeInternalErrorData(error, exposeInternalErrors);
                     return rpcError(id, error instanceof McpToolError ? INVALID_PARAMS : INTERNAL_ERROR, message, data, 200, headers);
+                };
+                const resource = resourceMap.get(uri);
+                if (resource) {
+                    try {
+                        const read = await resource.read(ctx);
+                        return rpcResult(id, { contents: Array.isArray(read) ? read : [read] }, headers);
+                    }
+                    catch (error) {
+                        return readError(error);
+                    }
+                }
+                if (uri) {
+                    for (const compiled of compiledTemplates) {
+                        const match = compiled.regex.exec(uri);
+                        if (!match)
+                            continue;
+                        const variables = {};
+                        compiled.variables.forEach((name, position) => {
+                            variables[name] = match[position + 1] ?? "";
+                        });
+                        try {
+                            const read = await compiled.template.read(uri, variables, ctx);
+                            return rpcResult(id, { contents: Array.isArray(read) ? read : [read] }, headers);
+                        }
+                        catch (error) {
+                            return readError(error);
+                        }
+                    }
                 }
+                return rpcError(id, INVALID_PARAMS, `Unknown resource: ${uri || "<missing>"}`, undefined, 200, headers);
             }
             case "prompts/list":
                 return rpcResult(id, { prompts: prompts.map(publicPrompt) }, headers);
@@ -255,8 +444,15 @@ export function createMcpHandler(options) {
                 if (!prompt) {
                     return rpcError(id, INVALID_PARAMS, `Unknown prompt: ${name || "<missing>"}`, undefined, 200, headers);
                 }
+                const promptArgs = asRecord(params.arguments);
+                const missing = (prompt.arguments ?? [])
+                    .filter((argument) => argument.required && promptArgs[argument.name] === undefined)
+                    .map((argument) => argument.name);
+                if (missing.length > 0) {
+                    return rpcError(id, INVALID_PARAMS, `Missing required prompt arguments: ${missing.join(", ")}`, undefined, 200, headers);
+                }
                 try {
-                    return rpcResult(id, await prompt.get(asRecord(params.arguments), ctx), headers);
+                    return rpcResult(id, await prompt.get(promptArgs, ctx), headers);
                 }
                 catch (error) {
                     const message = error instanceof McpToolError ? error.message : "Prompt rendering failed.";
@@ -271,6 +467,12 @@ export function createMcpHandler(options) {
         }
     }
     return async function handleMcpRequest(request) {
+        // Streamable HTTP requires Origin validation on every request to defeat
+        // DNS rebinding; invalid browser origins are refused with 403.
+        const origin = request.headers.get("origin");
+        if (origin !== null && !isAllowedOrigin(origin, request, allowedOrigins)) {
+            return rpcError(null, INVALID_REQUEST, "Origin is not allowed for this MCP endpoint.", undefined, 403, headers);
+        }
         if (request.method === "OPTIONS") {
             return new Response(null, {
                 status: 204,
@@ -284,6 +486,7 @@ export function createMcpHandler(options) {
                 capabilities: {
                     tools: tools.map((tool) => tool.name),
                     resources: resources.map((resource) => resource.uri),
+                    resourceTemplates: resourceTemplates.map((template) => template.uriTemplate),
                     prompts: prompts.map((prompt) => prompt.name),
                 },
                 hint: "Send JSON-RPC 2.0 over HTTP POST to this endpoint.",
@@ -387,6 +590,7 @@ export function mcpRoutes(path, handler) {
         202: { description: "MCP notification accepted", body: MCP_JSON_RESPONSE_SCHEMA },
         204: { description: "CORS preflight accepted" },
         400: { description: "Invalid MCP request" },
+        403: { description: "Origin not allowed" },
         405: { description: "Unsupported MCP transport method" },
         413: { description: "MCP request body too large" },
     };

package/dist/middleware.d.ts

@@ -78,16 +78,38 @@ export interface CspDirectivesOptions {
 }
 /** Options for {@link secureHeaders}. Every field can be disabled with `false`. */
 export interface SecureHeadersOptions {
+    /**
+     * `Content-Security-Policy` value: a raw header string, a
+     * {@link CspDirectivesOptions} object (enables nonces / Trusted Types),
+     * or `false` to omit. Defaults to
+     * `"default-src 'self'; frame-ancestors 'none'"`.
+     */
     contentSecurityPolicy?: string | false | CspDirectivesOptions;
+    /**
+     * `Strict-Transport-Security` settings (`maxAgeSeconds` in seconds).
+     * Defaults to `{ maxAgeSeconds: 31536000, includeSubDomains: true }`.
+     */
     hsts?: {
         maxAgeSeconds: number;
         includeSubDomains?: boolean;
         preload?: boolean;
     } | false;
+    /**
+     * `X-Frame-Options` value. Defaults to `"DENY"`. Disabling it with
+     * `false` while the CSP also lacks `frame-ancestors` throws at
+     * construction time (clickjacking guard).
+     */
     frameOptions?: "DENY" | "SAMEORIGIN" | false;
+    /** `Referrer-Policy` value. Defaults to `"no-referrer"`. */
     referrerPolicy?: string | false;
+    /**
+     * `Permissions-Policy` value. Defaults to
+     * `"camera=(), microphone=(), geolocation=(), clipboard-write=()"`.
+     */
     permissionsPolicy?: string | false;
+    /** `Cross-Origin-Opener-Policy` value. Defaults to `"same-origin"`. */
     crossOriginOpenerPolicy?: string | false;
+    /** `Cross-Origin-Resource-Policy` value. Defaults to `"same-origin"`. */
     crossOriginResourcePolicy?: string | false;
     /**
      * `Cross-Origin-Embedder-Policy` (COEP). Off by default because
@@ -101,7 +123,12 @@ export interface SecureHeadersOptions {
      * @since 0.37.0
      */
     crossOriginEmbedderPolicy?: "require-corp" | "credentialless" | "unsafe-none" | false;
+    /** Emit `X-Content-Type-Options: nosniff`. Defaults to `true`. */
     noSniff?: boolean;
+    /**
+     * Emit `X-XSS-Protection: 0` (disables the legacy XSS auditor, per
+     * modern guidance). Defaults to `false` (header omitted).
+     */
     xssProtection?: boolean;
     /**
      * Reporting API endpoint declarations rendered as the
@@ -165,6 +192,11 @@ export declare const SECURE_HEADERS_MARKER: unique symbol;
  * {@link SecureHeadersOptions} for the full list). Pass `false` for any
  * field to disable that header; handler-set headers always win.
  *
+ * @param opts - Per-header overrides. Pass `false` to disable a header.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with
+ * {@link SECURE_HEADERS_MARKER}.
+ * @throws {Error} When `frameOptions: false` is combined with a CSP that has
+ * no `frame-ancestors` directive (would disable every clickjacking defense).
  * @since 0.1.0
  */
 export declare function secureHeaders(opts?: SecureHeadersOptions): Hooks;
@@ -286,11 +318,30 @@ export declare const CSRF_HOOK_MARKER: unique symbol;
 export type CorsOriginAllow = (origin: string) => boolean;
 /** Options for {@link cors}. */
 export interface CorsOptions {
+    /**
+     * Allowed cross-origin caller(s): a single origin string, an array of
+     * origins, or a predicate. `"*"` is rejected with `credentials: true`
+     * and refused at boot on production `secureDefaults` apps.
+     */
     origin: string | string[] | ((origin: string) => boolean);
+    /**
+     * Verbs advertised on preflight (`Access-Control-Allow-Methods`).
+     * Defaults to `["GET", "HEAD", "POST"]`. `"*"` is rejected.
+     */
     methods?: string[];
+    /**
+     * Request headers advertised on preflight (`Access-Control-Allow-Headers`).
+     * Defaults to `["content-type", "authorization"]`.
+     */
     allowedHeaders?: string[];
+    /** Response headers exposed to browser JS (`Access-Control-Expose-Headers`). None by default. */
     exposedHeaders?: string[];
+    /**
+     * Emit `Access-Control-Allow-Credentials: true`. Defaults to `false`.
+     * Cannot be combined with a wildcard `origin`.
+     */
     credentials?: boolean;
+    /** Preflight cache lifetime in seconds (`Access-Control-Max-Age`). Defaults to `600`. */
     maxAgeSeconds?: number;
 }
 /**
@@ -327,6 +378,11 @@ export declare function cors(opts: CorsOptions): Hooks;
  * (`@daloyjs/core/rate-limit-redis`).
  */
 export interface RateLimitStore {
+    /**
+     * Record one request for `key` in the window of `windowMs` milliseconds
+     * and return the updated `count` plus the window's absolute reset time
+     * (`resetMs`, epoch milliseconds).
+     */
     hit(key: string, windowMs: number): Promise<{
         count: number;
         resetMs: number;
@@ -437,6 +493,9 @@ export interface LoginThrottleOptions {
  * same `groupId`) across related routes so an attacker cannot bypass the limit
  * by rotating between password, OTP, and reset endpoints.
  *
+ * @param opts - Throttle tuning (see {@link LoginThrottleOptions}); every field has a safe default.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`.
+ * @throws {Error} When `windowMs`/`max` are not positive integers or the delay options are negative.
  * @since 0.23.0
  */
 export declare function loginThrottle(opts?: LoginThrottleOptions): Hooks;
@@ -627,6 +686,11 @@ export interface CsrfOptions {
  *   allowedOrigins: ["https://app.example.com"],
  * }));
  * ```
+ *
+ * @param opts - Strategy, cookie/header names, and cookie attributes (see {@link CsrfOptions}).
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with {@link CSRF_HOOK_MARKER}.
+ * @throws {Error} When `strategy` is unknown or the cookie name/attributes are invalid
+ * (e.g. `__Host-` prefix without `secure: true`, `path: "/"`, and no `domain`).
  */
 export declare function csrf(opts?: CsrfOptions): Hooks;
 /** Options for {@link basicAuth}. */
@@ -723,6 +787,10 @@ export declare const REQUIRE_SCOPES_HOOK_MARKER: unique symbol;
  * });
  * ```
  *
+ * @param scopes - Required scope strings; must be non-empty and free of RFC 6749 illegal characters.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`,
+ * stamped with {@link REQUIRE_SCOPES_HOOK_MARKER}.
+ * @throws {Error} When `scopes` is empty or contains a non-string, empty, or illegal-character scope.
  * @since 0.21.0
  */
 export declare function requireScopes(scopes: readonly string[]): Hooks;

package/dist/middleware.js

@@ -148,6 +148,11 @@ export const SECURE_HEADERS_MARKER = Symbol.for("daloyjs.middleware.secureHeader
  * {@link SecureHeadersOptions} for the full list). Pass `false` for any
  * field to disable that header; handler-set headers always win.
  *
+ * @param opts - Per-header overrides. Pass `false` to disable a header.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with
+ * {@link SECURE_HEADERS_MARKER}.
+ * @throws {Error} When `frameOptions: false` is combined with a CSP that has
+ * no `frame-ancestors` directive (would disable every clickjacking defense).
  * @since 0.1.0
  */
 export function secureHeaders(opts = {}) {
@@ -706,6 +711,9 @@ function wait(ms) {
  * same `groupId`) across related routes so an attacker cannot bypass the limit
  * by rotating between password, OTP, and reset endpoints.
  *
+ * @param opts - Throttle tuning (see {@link LoginThrottleOptions}); every field has a safe default.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`.
+ * @throws {Error} When `windowMs`/`max` are not positive integers or the delay options are negative.
  * @since 0.23.0
  */
 export function loginThrottle(opts = {}) {
@@ -912,6 +920,11 @@ function csrfCookieAttributes(opts) {
  *   allowedOrigins: ["https://app.example.com"],
  * }));
  * ```
+ *
+ * @param opts - Strategy, cookie/header names, and cookie attributes (see {@link CsrfOptions}).
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with {@link CSRF_HOOK_MARKER}.
+ * @throws {Error} When `strategy` is unknown or the cookie name/attributes are invalid
+ * (e.g. `__Host-` prefix without `secure: true`, `path: "/"`, and no `domain`).
  */
 export function csrf(opts = {}) {
     const strategy = opts.strategy ?? "double-submit";
@@ -1191,6 +1204,10 @@ function readUserScopes(user) {
  * });
  * ```
  *
+ * @param scopes - Required scope strings; must be non-empty and free of RFC 6749 illegal characters.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`,
+ * stamped with {@link REQUIRE_SCOPES_HOOK_MARKER}.
+ * @throws {Error} When `scopes` is empty or contains a non-string, empty, or illegal-character scope.
  * @since 0.21.0
  */
 export function requireScopes(scopes) {

package/dist/mtls.d.ts

@@ -84,6 +84,9 @@ export type ClientCertificateSource = ClientCertificate | undefined | (() => Cli
  * Pass a thunk to defer the read until {@link getClientCertificate} is first
  * called; the resolved value is cached back onto the request.
  *
+ * @param request The incoming request to stash the certificate on.
+ * @param source The certificate, a lazy thunk producing one, or `undefined`
+ *   when the connection presented no client certificate.
  * @since 0.37.0
  */
 export declare function setClientCertificate(request: Request, source: ClientCertificateSource): void;
@@ -93,6 +96,8 @@ export declare function setClientCertificate(request: Request, source: ClientCer
  * adapter does not expose TLS peer info). If a lazy thunk was stashed, it is
  * resolved once and the result cached.
  *
+ * @param request The request previously seen by {@link setClientCertificate}.
+ * @returns The attached certificate, or `undefined` when none was presented.
  * @since 0.37.0
  */
 export declare function getClientCertificate(request: Request): ClientCertificate | undefined;
@@ -104,12 +109,19 @@ export declare function getClientCertificate(request: Request): ClientCertificat
  * @since 0.37.0
  */
 export interface PeerCertificateLike {
+    /** Subject RDN attributes keyed by short name (e.g. `CN`, `O`). */
     subject?: Record<string, string | string[]> | null;
+    /** Issuer RDN attributes keyed by short name. */
     issuer?: Record<string, string | string[]> | null;
+    /** Validity start as a Node-formatted date string. */
     valid_from?: string;
+    /** Validity end as a Node-formatted date string. */
     valid_to?: string;
+    /** SHA-256 fingerprint, colon-delimited hex as Node emits it. */
     fingerprint256?: string;
+    /** Certificate serial number as a hex string. */
     serialNumber?: string;
+    /** Subject Alternative Names rendered as `DNS:a, IP Address:1.2.3.4, ...`. */
     subjectaltname?: string;
 }
 /**
@@ -120,6 +132,9 @@ export interface PeerCertificateLike {
  * @param raw - The structured peer-certificate object from the TLS socket.
  * @param verified - Whether the socket reported `authorized === true` (the
  *   chain was verified against the configured CA).
+ * @returns The normalized certificate, or `undefined` when `raw` is missing
+ *   or carries no identifying fields (no subject, issuer, fingerprint, or
+ *   serial).
  * @since 0.37.0
  */
 export declare function normalizePeerCertificate(raw: PeerCertificateLike | null | undefined, verified: boolean): ClientCertificate | undefined;
@@ -131,8 +146,10 @@ export declare function normalizePeerCertificate(raw: PeerCertificateLike | null
  * and is the one returned. Because Envoy only emits XFCC for connections it
  * mutually authenticated, the result is marked `verified: true`.
  *
- * Returns `undefined` for an empty or unparseable header.
- *
+ * @param headerValue Raw XFCC header value; `null`/`undefined` are tolerated.
+ * @returns The certificate parsed from the first XFCC element, or `undefined`
+ *   for an empty or unparseable header. Only trust this header behind a proxy
+ *   you control that strips client-supplied XFCC.
  * @since 0.37.0
  */
 export declare function parseForwardedClientCert(headerValue: string | null | undefined): ClientCertificate | undefined;

package/dist/mtls.js

@@ -36,6 +36,9 @@ const CLIENT_CERT_SYMBOL = Symbol.for("daloyjs.clientCertificate");
  * Pass a thunk to defer the read until {@link getClientCertificate} is first
  * called; the resolved value is cached back onto the request.
  *
+ * @param request The incoming request to stash the certificate on.
+ * @param source The certificate, a lazy thunk producing one, or `undefined`
+ *   when the connection presented no client certificate.
  * @since 0.37.0
  */
 export function setClientCertificate(request, source) {
@@ -47,6 +50,8 @@ export function setClientCertificate(request, source) {
  * adapter does not expose TLS peer info). If a lazy thunk was stashed, it is
  * resolved once and the result cached.
  *
+ * @param request The request previously seen by {@link setClientCertificate}.
+ * @returns The attached certificate, or `undefined` when none was presented.
  * @since 0.37.0
  */
 export function getClientCertificate(request) {
@@ -67,6 +72,9 @@ export function getClientCertificate(request) {
  * @param raw - The structured peer-certificate object from the TLS socket.
  * @param verified - Whether the socket reported `authorized === true` (the
  *   chain was verified against the configured CA).
+ * @returns The normalized certificate, or `undefined` when `raw` is missing
+ *   or carries no identifying fields (no subject, issuer, fingerprint, or
+ *   serial).
  * @since 0.37.0
  */
 export function normalizePeerCertificate(raw, verified) {
@@ -205,8 +213,10 @@ function cnFromDN(dn) {
  * and is the one returned. Because Envoy only emits XFCC for connections it
  * mutually authenticated, the result is marked `verified: true`.
  *
- * Returns `undefined` for an empty or unparseable header.
- *
+ * @param headerValue Raw XFCC header value; `null`/`undefined` are tolerated.
+ * @returns The certificate parsed from the first XFCC element, or `undefined`
+ *   for an empty or unparseable header. Only trust this header behind a proxy
+ *   you control that strips client-supplied XFCC.
  * @since 0.37.0
  */
 export function parseForwardedClientCert(headerValue) {