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

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { validate, isStandardSchema } from "./schema.js";
 export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
 export type { ChangeSeverity, OpenAPIChange, OpenAPIDiffResult } from "./openapi-diff.js";
 export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, mcpRoutes, } from "./mcp.js";
-export type { McpContent, McpEmbeddedResourceContent, McpHandler, McpHandlerOptions, McpImageContent, McpJsonObject, McpJsonRpcId, McpJsonSchema, McpJsonValue, McpPrompt, McpPromptArgument, McpPromptDefinition, McpPromptMessage, McpPromptResult, McpRequestContext, McpResource, McpResourceContents, McpResourceDefinition, McpServerInfo, McpTextContent, McpTool, McpToolHandler, McpToolResult, } from "./mcp.js";
+export type { McpContent, McpEmbeddedResourceContent, McpHandler, McpHandlerOptions, McpIcon, McpImageContent, McpJsonObject, McpJsonRpcId, McpJsonSchema, McpJsonValue, McpPrompt, McpPromptArgument, McpPromptDefinition, McpPromptMessage, McpPromptResult, McpRequestContext, McpResource, McpResourceContents, McpResourceDefinition, McpResourceTemplate, McpResourceTemplateDefinition, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolHandler, McpToolResult, } from "./mcp.js";
 export { readBodyLimited, safeJsonParse, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
 export type { WebhookHmacAlgorithm } from "./security.js";
 export { requestId, secureHeaders, SECURE_HEADERS_MARKER, cors, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, rateLimit, loginThrottle, timing, bearerAuth, basicAuth, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";

package/dist/ip-restriction.d.ts

@@ -53,13 +53,18 @@ export interface IpRestrictionOptions {
 }
 /** @internal Parsed IP address (shared with `fetchGuard()`). */
 export interface ParsedIp {
+    /** Big-endian address bytes: 4 bytes for IPv4, 16 for IPv6. */
     bytes: Uint8Array;
+    /** Address family: `4` for IPv4, `6` for IPv6. */
     family: 4 | 6;
 }
 /** @internal Compiled CIDR matcher (shared with `fetchGuard()`). */
 export interface IpMatcher {
+    /** Address family the matcher applies to: `4` or `6`. */
     family: 4 | 6;
+    /** CIDR prefix length in bits (0-32 for IPv4, 0-128 for IPv6). */
     prefix: number;
+    /** Network address bytes with all host bits masked to zero. */
     bytes: Uint8Array;
 }
 /**
@@ -80,12 +85,44 @@ export interface IpMatcher {
  * On reject the middleware throws a {@link ForbiddenError}, which Daloy
  * renders as RFC 9457 `application/problem+json`.
  *
+ * @param opts Allow/deny lists plus IP-resolution options; see
+ *   {@link IpRestrictionOptions}. Deny matches always win over allow.
+ * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ *   failing closed (403) when the client IP cannot be resolved or parsed.
+ * @throws Error at setup time when neither `allow` nor `deny` is provided,
+ *   or when a pattern is not a valid IP/CIDR.
  * @since 0.19.0
  */
 export declare function ipRestriction(opts: IpRestrictionOptions): Hooks;
-/** @internal */
+/**
+ * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing
+ * only the matcher's prefix bits. IPv4-mapped IPv6 addresses
+ * (`::ffff:a.b.c.d`) are normalized so they match IPv4 matchers.
+ *
+ * @param ip Parsed client address from {@link parseIp}.
+ * @param m Compiled matcher from {@link compileCidrMatcher}.
+ * @returns `true` when the address is within the matcher's range.
+ * @internal
+ */
 export declare function matchesMatcher(ip: ParsedIp, m: IpMatcher): boolean;
-/** @internal */
+/**
+ * Compile an IP or CIDR pattern (e.g. `"10.0.0.0/8"`, `"::1"`) into an
+ * {@link IpMatcher}. A bare address gets a full-length prefix (/32 or /128);
+ * host bits beyond the prefix are masked to zero.
+ *
+ * @param input IPv4/IPv6 address, optionally with a `/prefix` suffix.
+ * @returns The compiled matcher used by {@link matchesMatcher}.
+ * @throws Error when the address or CIDR prefix is invalid.
+ * @internal
+ */
 export declare function compileCidrMatcher(input: string): IpMatcher;
-/** @internal */
+/**
+ * Parse an IPv4 or IPv6 address string into raw bytes. Supports IPv6 `::`
+ * compression and IPv4-mapped tails (`::ffff:1.2.3.4`).
+ *
+ * @param input Address string; surrounding whitespace is trimmed.
+ * @returns The parsed address, or `undefined` when the input is not a valid
+ *   IP (callers treat unparseable addresses as a rejection, failing closed).
+ * @internal
+ */
 export declare function parseIp(input: string): ParsedIp | undefined;

package/dist/ip-restriction.js

@@ -26,6 +26,12 @@ import { ForbiddenError } from "./errors.js";
  * On reject the middleware throws a {@link ForbiddenError}, which Daloy
  * renders as RFC 9457 `application/problem+json`.
  *
+ * @param opts Allow/deny lists plus IP-resolution options; see
+ *   {@link IpRestrictionOptions}. Deny matches always win over allow.
+ * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ *   failing closed (403) when the client IP cannot be resolved or parsed.
+ * @throws Error at setup time when neither `allow` nor `deny` is provided,
+ *   or when a pattern is not a valid IP/CIDR.
  * @since 0.19.0
  */
 export function ipRestriction(opts) {
@@ -64,7 +70,16 @@ function forwardedIpResolver(ctx) {
         return forwarded.split(",")[0]?.trim();
     return headers.get("x-real-ip") ?? undefined;
 }
-/** @internal */
+/**
+ * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing
+ * only the matcher's prefix bits. IPv4-mapped IPv6 addresses
+ * (`::ffff:a.b.c.d`) are normalized so they match IPv4 matchers.
+ *
+ * @param ip Parsed client address from {@link parseIp}.
+ * @param m Compiled matcher from {@link compileCidrMatcher}.
+ * @returns `true` when the address is within the matcher's range.
+ * @internal
+ */
 export function matchesMatcher(ip, m) {
     const candidate = normalizeFamily(ip, m.family);
     if (!candidate)
@@ -83,7 +98,16 @@ export function matchesMatcher(ip, m) {
     const mask = 0xff << (8 - remaining);
     return ((candidate[fullBytes] ^ expected[fullBytes]) & mask) === 0;
 }
-/** @internal */
+/**
+ * Compile an IP or CIDR pattern (e.g. `"10.0.0.0/8"`, `"::1"`) into an
+ * {@link IpMatcher}. A bare address gets a full-length prefix (/32 or /128);
+ * host bits beyond the prefix are masked to zero.
+ *
+ * @param input IPv4/IPv6 address, optionally with a `/prefix` suffix.
+ * @returns The compiled matcher used by {@link matchesMatcher}.
+ * @throws Error when the address or CIDR prefix is invalid.
+ * @internal
+ */
 export function compileCidrMatcher(input) {
     let addr = input;
     let prefixStr;
@@ -135,7 +159,15 @@ function applyPrefixMask(bytes, prefix) {
     }
     return out;
 }
-/** @internal */
+/**
+ * Parse an IPv4 or IPv6 address string into raw bytes. Supports IPv6 `::`
+ * compression and IPv4-mapped tails (`::ffff:1.2.3.4`).
+ *
+ * @param input Address string; surrounding whitespace is trimmed.
+ * @returns The parsed address, or `undefined` when the input is not a valid
+ *   IP (callers treat unparseable addresses as a rejection, failing closed).
+ * @internal
+ */
 export function parseIp(input) {
     const trimmed = input.trim();
     if (trimmed.includes(":"))

package/dist/jwk.d.ts

@@ -4,6 +4,7 @@ import type { BaseContext, Hooks } from "./types.js";
 export type JwkAlgorithm = Exclude<JwtAlgorithm, "HS256" | "HS384" | "HS512">;
 /** Minimal JWKS document shape (RFC 7517 §5). */
 export interface JwkSet {
+    /** Public JWKs; each entry should carry a `kid` so tokens can select their key. */
     keys: JsonWebKey[];
 }
 /**
@@ -13,7 +14,11 @@ export interface JwkSet {
 export type JwkSource = JwkSet | string | (() => JwkSet | Promise<JwkSet>);
 /** Per-request payload-revalidation hook. */
 export type JwkVerifyHook = (payload: Record<string, unknown>, ctx: BaseContext<any, any>) => boolean | void | Promise<boolean | void>;
-/** Options for {@link jwk}. */
+/**
+ * Options for {@link jwk}: the JWKS source and asymmetric algorithm allowlist
+ * are required; issuer / audience / clock-skew checks, JWKS fetch caching,
+ * and a per-request revalidation hook are opt-in.
+ */
 export interface JwkOptions {
     /** JWKS source (object, URL, or resolver). */
     jwks: JwkSource;
@@ -91,6 +96,12 @@ export interface JwkOptions {
  * });
  * ```
  *
+ * @param opts - JWKS source, algorithm allowlist, and claim checks; see
+ *   {@link JwkOptions}.
+ * @returns A {@link Hooks} object to pass to `app.use()` or a route's `hooks`;
+ *   failed auth yields a `401` problem+json with `WWW-Authenticate`.
+ * @throws {Error} at construction for missing options, an empty or
+ *   symmetric-containing allowlist, invalid TTLs, or a malformed realm.
  * @since 0.22.0
  */
 export declare function jwk(opts: JwkOptions): Hooks;

package/dist/jwk.js

@@ -161,6 +161,12 @@ function makeJwksLoader(source, fetchImpl, ttlSeconds, maxStaleSeconds) {
  * });
  * ```
  *
+ * @param opts - JWKS source, algorithm allowlist, and claim checks; see
+ *   {@link JwkOptions}.
+ * @returns A {@link Hooks} object to pass to `app.use()` or a route's `hooks`;
+ *   failed auth yields a `401` problem+json with `WWW-Authenticate`.
+ * @throws {Error} at construction for missing options, an empty or
+ *   symmetric-containing allowlist, invalid TTLs, or a malformed realm.
  * @since 0.22.0
  */
 export function jwk(opts) {

package/dist/jwt.d.ts

@@ -23,19 +23,24 @@ export type JwtAlgorithm = "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS
 export declare const DEFAULT_JWT_MAX_LIFETIME_SECONDS: number;
 /** Structured error thrown by every JWT helper. */
 export declare class JwtError extends Error {
+    /** Stable machine-readable error code (e.g. `"alg_none_refused"`, `"weak_hs_secret"`). */
     readonly code: string;
     constructor(code: string, message: string);
 }
 /** Result of a successful verify. */
 export interface JwtVerified {
+    /** Decoded JOSE header (`alg`, `kid`, `typ`, ...). */
     readonly header: Record<string, unknown>;
+    /** Decoded claims payload after signature and time-claim checks passed. */
     readonly payload: Record<string, unknown>;
 }
 /** Key material accepted by the signer/verifier. */
 export type JwtKeyMaterial = CryptoKey | Uint8Array | JsonWebKey;
 /** Options for {@link createJwtSigner}. */
 export interface JwtSignerOptions {
+    /** Signing algorithm. `"none"` is always refused. */
     alg: JwtAlgorithm;
+    /** Signing key. HS* secrets shorter than 32 bytes and RSA keys under 2048 bits are refused. */
     key: JwtKeyMaterial;
     /**
      * Maximum allowed `exp - iat` window in seconds. Required: refuse-at-
@@ -98,6 +103,10 @@ export interface JwtVerifierOptions {
  * `acknowledgeNoExp: true` was set at construction outside production) and
  * refuses payloads whose `exp - (iat | now)` exceeds `maxLifetimeSeconds`.
  *
+ * @param opts - Algorithm, key, and lifetime policy; see {@link JwtSignerOptions}.
+ * @returns An object whose `sign(payload)` resolves to the compact JWS string.
+ * @throws {JwtError} for `alg: "none"`, unknown algorithms, weak keys, a
+ *   missing/invalid `maxLifetimeSeconds`, or `acknowledgeNoExp` in production.
  * @since 0.21.0
  */
 export declare function createJwtSigner(opts: JwtSignerOptions): {
@@ -110,6 +119,11 @@ export declare function createJwtSigner(opts: JwtSignerOptions): {
  * refuses-at-construction when a symmetric algorithm (`HS*`) is mixed with
  * a JWK / JWKS-shaped key source (the documented confused-deputy attack).
  *
+ * @param opts - Allowlist, key source, and claim checks; see {@link JwtVerifierOptions}.
+ * @returns An object whose `verify(token)` resolves to the decoded
+ *   {@link JwtVerified} or rejects with {@link JwtError}.
+ * @throws {JwtError} at construction for an empty/invalid allowlist, `"none"`
+ *   in the allowlist, weak HS* secrets, or HS* mixed with a JWK source.
  * @since 0.21.0
  */
 export declare function createJwtVerifier(opts: JwtVerifierOptions): {

package/dist/jwt.js

@@ -60,6 +60,7 @@ const MIN_RSA_KEY_BITS = 2048;
 export const DEFAULT_JWT_MAX_LIFETIME_SECONDS = 30 * 24 * 60 * 60;
 /** Structured error thrown by every JWT helper. */
 export class JwtError extends Error {
+    /** Stable machine-readable error code (e.g. `"alg_none_refused"`, `"weak_hs_secret"`). */
     code;
     constructor(code, message) {
         super(`[${code}] ${message}`);
@@ -228,6 +229,10 @@ function buildSignAlgorithm(alg) {
  * `acknowledgeNoExp: true` was set at construction outside production) and
  * refuses payloads whose `exp - (iat | now)` exceeds `maxLifetimeSeconds`.
  *
+ * @param opts - Algorithm, key, and lifetime policy; see {@link JwtSignerOptions}.
+ * @returns An object whose `sign(payload)` resolves to the compact JWS string.
+ * @throws {JwtError} for `alg: "none"`, unknown algorithms, weak keys, a
+ *   missing/invalid `maxLifetimeSeconds`, or `acknowledgeNoExp` in production.
  * @since 0.21.0
  */
 export function createJwtSigner(opts) {
@@ -326,6 +331,11 @@ function normalizeStringSet(value) {
  * refuses-at-construction when a symmetric algorithm (`HS*`) is mixed with
  * a JWK / JWKS-shaped key source (the documented confused-deputy attack).
  *
+ * @param opts - Allowlist, key source, and claim checks; see {@link JwtVerifierOptions}.
+ * @returns An object whose `verify(token)` resolves to the decoded
+ *   {@link JwtVerified} or rejects with {@link JwtError}.
+ * @throws {JwtError} at construction for an empty/invalid allowlist, `"none"`
+ *   in the allowlist, weak HS* secrets, or HS* mixed with a JWK source.
  * @since 0.21.0
  */
 export function createJwtVerifier(opts) {

package/dist/load-shedding.d.ts

@@ -65,6 +65,9 @@ export interface LoadSheddingSnapshot {
  *   retryAfterSeconds: 5,
  * }));
  * ```
+ *
+ * @param opts - Pressure thresholds (event-loop delay default 1000 ms, ELU default 0.98, optional heap/RSS byte caps), sampling interval, `Retry-After` seconds, and an optional custom `healthCheck`.
+ * @returns A {@link Hooks} bundle that sheds requests with `503` + `Retry-After` while pressure thresholds are exceeded.
  */
 export declare function loadShedding(opts?: LoadSheddingOptions): Hooks;
 /**

package/dist/load-shedding.js

@@ -37,6 +37,9 @@ async function tryLoadPerfHooks() {
  *   retryAfterSeconds: 5,
  * }));
  * ```
+ *
+ * @param opts - Pressure thresholds (event-loop delay default 1000 ms, ELU default 0.98, optional heap/RSS byte caps), sampling interval, `Retry-After` seconds, and an optional custom `healthCheck`.
+ * @returns A {@link Hooks} bundle that sheds requests with `503` + `Retry-After` while pressure thresholds are exceeded.
  */
 export function loadShedding(opts = {}) {
     const maxDelay = opts.maxEventLoopDelayMs ?? 1000;

package/dist/logger.d.ts

@@ -10,13 +10,21 @@ export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
  * thin adapter; the default implementation is {@link createLogger}.
  */
 export interface Logger {
+    /** Minimum level emitted; records below this level are dropped. */
     level: LogLevel;
+    /** Log at `trace` level. Pass a fields object plus optional message, or a message string. */
     trace(obj: object | string, msg?: string): void;
+    /** Log at `debug` level. Pass a fields object plus optional message, or a message string. */
     debug(obj: object | string, msg?: string): void;
+    /** Log at `info` level. Pass a fields object plus optional message, or a message string. */
     info(obj: object | string, msg?: string): void;
+    /** Log at `warn` level. Pass a fields object plus optional message, or a message string. */
     warn(obj: object | string, msg?: string): void;
+    /** Log at `error` level. Pass a fields object plus optional message, or a message string. */
     error(obj: object | string, msg?: string): void;
+    /** Log at `fatal` level. Pass a fields object plus optional message, or a message string. */
     fatal(obj: object | string, msg?: string): void;
+    /** Return a derived logger whose records always include `bindings` merged into each record. */
     child(bindings: Record<string, unknown>): Logger;
 }
 /**
@@ -63,7 +71,9 @@ export interface LoggerRedactionOptions {
 export declare const DEFAULT_REDACT_KEYS: readonly string[];
 /** Options for {@link createLogger}. */
 export interface ConsoleLoggerOptions {
+    /** Minimum level to emit. Defaults to `"info"`. */
     level?: LogLevel;
+    /** Fields merged into every record emitted by this logger and its children. */
     bindings?: Record<string, unknown>;
     /** Where to write. Defaults to process.stdout.write or console.log. */
     write?: (line: string) => void;
@@ -89,6 +99,9 @@ interface ResolvedRedaction {
  * `cfg.redactJwt` is on) with `cfg.censor`. Exported for direct use by
  * custom logger implementations that want the same defaults.
  *
+ * @param record - Log record to redact. Mutated in place (cycle-safe, depth-capped).
+ * @param cfg - Resolved redaction settings (key set, censor, JWT/credential toggles, max depth).
+ * @returns The same `record` object, for chaining.
  * @since 0.15.0
  */
 export declare function redactRecord(record: Record<string, unknown>, cfg: ResolvedRedaction): Record<string, unknown>;

package/dist/logger.js

@@ -123,6 +123,9 @@ function redactString(value, cfg) {
  * `cfg.redactJwt` is on) with `cfg.censor`. Exported for direct use by
  * custom logger implementations that want the same defaults.
  *
+ * @param record - Log record to redact. Mutated in place (cycle-safe, depth-capped).
+ * @param cfg - Resolved redaction settings (key set, censor, JWT/credential toggles, max depth).
+ * @returns The same `record` object, for chaining.
  * @since 0.15.0
  */
 export function redactRecord(record, cfg) {

package/dist/mcp.d.ts

@@ -52,6 +52,22 @@ export type McpJsonSchema = McpJsonObject;
  * @since 1.0.0
  */
 export type McpJsonRpcId = string | number | null;
+/**
+ * Icon metadata clients may render next to a server, tool, resource, or
+ * prompt (MCP 2025-11-25, SEP-973).
+ *
+ * @since 1.0.0
+ */
+export interface McpIcon {
+    /** Icon URL. Prefer `https:` or `data:` URIs that clients can fetch safely. */
+    src: string;
+    /** Optional icon media type, e.g. `"image/png"`. */
+    mimeType?: string;
+    /** Optional pixel sizes the icon is available in, e.g. `["48x48"]`. */
+    sizes?: string[];
+    /** Optional theme the icon is designed for. */
+    theme?: "light" | "dark";
+}
 /**
  * Identity block returned from the MCP `initialize` handshake.
  *
@@ -64,6 +80,12 @@ export interface McpServerInfo {
     title?: string;
     /** Server version surfaced to clients for debugging and compatibility. */
     version: string;
+    /** Optional human-readable server description (MCP 2025-11-25). */
+    description?: string;
+    /** Optional homepage URL for this server (MCP 2025-11-25). */
+    websiteUrl?: string;
+    /** Optional icons clients may display for this server (MCP 2025-11-25). */
+    icons?: McpIcon[];
 }
 /**
  * Per-request context passed to tool, resource, and prompt handlers.
@@ -74,9 +96,10 @@ export interface McpRequestContext {
     /** The original HTTP request received by the DaloyJS route. */
     request: Request;
     /**
-     * Protocol version selected for this call. Before `initialize`, this is the
-     * version from the `MCP-Protocol-Version` header when present, otherwise the
-     * handler's preferred protocol version.
+     * Protocol version selected for this call. `initialize` negotiates it from
+     * `params.protocolVersion`; other calls take the `MCP-Protocol-Version`
+     * header, falling back to `2025-03-26` (the spec's assumption for
+     * headerless requests) when supported, otherwise the preferred version.
      */
     protocolVersion: string;
     /** JSON-RPC id for request/response correlation. */
@@ -90,7 +113,9 @@ export interface McpRequestContext {
  * @since 1.0.0
  */
 export interface McpTextContent {
+    /** Discriminator literal identifying this block as text. */
     type: "text";
+    /** The plain-text payload of the block. */
     text: string;
 }
 /**
@@ -102,8 +127,11 @@ export interface McpTextContent {
  * @since 1.0.0
  */
 export interface McpImageContent {
+    /** Discriminator literal identifying this block as an image. */
     type: "image";
+    /** Base64-encoded image bytes. */
     data: string;
+    /** Image media type, e.g. `"image/png"`. */
     mimeType: string;
 }
 /**
@@ -112,7 +140,9 @@ export interface McpImageContent {
  * @since 1.0.0
  */
 export interface McpEmbeddedResourceContent {
+    /** Discriminator literal identifying this block as an embedded resource. */
     type: "resource";
+    /** The embedded resource contents (uri plus text or base64 blob). */
     resource: McpResourceContents;
 }
 /**
@@ -131,13 +161,36 @@ export type McpContent = McpTextContent | McpImageContent | McpEmbeddedResourceC
  * @since 1.0.0
  */
 export interface McpToolResult {
-    /** Human or model-readable content blocks returned to the MCP client. */
-    content: McpContent[];
+    /**
+     * Human or model-readable content blocks returned to the MCP client. When
+     * omitted, {@link createMcpHandler} backfills a text block serializing
+     * `structuredContent` so pre-2025-06-18 clients still receive output.
+     */
+    content?: McpContent[];
     /** Optional structured payload for clients that can consume typed output. */
     structuredContent?: McpJsonObject;
     /** Set to `true` for domain/tool errors the model may recover from. */
     isError?: boolean;
 }
+/**
+ * Behavioral hints a tool can advertise to MCP clients. Hints are untrusted
+ * metadata for UX decisions (confirmation prompts, badges); clients must not
+ * rely on them for security decisions.
+ *
+ * @since 1.0.0
+ */
+export interface McpToolAnnotations {
+    /** Human-readable title for the tool. */
+    title?: string;
+    /** Hint that the tool does not modify its environment. */
+    readOnlyHint?: boolean;
+    /** Hint that the tool may perform destructive updates. */
+    destructiveHint?: boolean;
+    /** Hint that repeated calls with the same arguments have no extra effect. */
+    idempotentHint?: boolean;
+    /** Hint that the tool interacts with external entities. */
+    openWorldHint?: boolean;
+}
 /**
  * Handler for a single MCP tool.
  *
@@ -172,6 +225,16 @@ export interface McpTool<TArgs extends Record<string, unknown> = Record<string,
     description: string;
     /** JSON Schema for `params.arguments`. */
     inputSchema: McpJsonSchema;
+    /**
+     * Optional JSON Schema describing `structuredContent` in tool results
+     * (MCP 2025-06-18). When set, handlers should return `structuredContent`
+     * matching it.
+     */
+    outputSchema?: McpJsonSchema;
+    /** Optional behavioral hints for clients. */
+    annotations?: McpToolAnnotations;
+    /** Optional icons clients may display for this tool (MCP 2025-11-25). */
+    icons?: McpIcon[];
     /** Execute the tool with untrusted JSON arguments. */
     handler: McpToolHandler<TArgs>;
 }
@@ -191,6 +254,8 @@ export interface McpResource {
     description?: string;
     /** MIME type returned by `resources/read`, such as `"application/json"`. */
     mimeType?: string;
+    /** Optional icons clients may display for this resource (MCP 2025-11-25). */
+    icons?: McpIcon[];
 }
 /**
  * Resource payload returned from `resources/read`.
@@ -228,6 +293,51 @@ export interface McpResourceDefinition extends McpResource {
      */
     read: (ctx: McpRequestContext) => McpResourceContents | McpResourceContents[] | Promise<McpResourceContents | McpResourceContents[]>;
 }
+/**
+ * Resource template metadata returned from `resources/templates/list`.
+ *
+ * @since 1.0.0
+ */
+export interface McpResourceTemplate {
+    /**
+     * URI template for this resource family, e.g. `"daloy://records/{id}"`.
+     * DaloyJS supports simple `{name}` variables (RFC 6570 level 1); each
+     * variable matches one URI segment (no `/`).
+     */
+    uriTemplate: string;
+    /** Stable template name. */
+    name: string;
+    /** Optional human-readable title. */
+    title?: string;
+    /** Optional description shown by clients. */
+    description?: string;
+    /** MIME type of resources produced by this template. */
+    mimeType?: string;
+    /** Optional icons clients may display for this template (MCP 2025-11-25). */
+    icons?: McpIcon[];
+}
+/**
+ * Definition of a parameterized MCP resource template.
+ *
+ * Templates answer `resources/read` for URIs that match `uriTemplate` but are
+ * not listed as concrete resources. Template variables arrive as raw URI
+ * segment strings; validate them before touching databases or files.
+ *
+ * @since 1.0.0
+ */
+export interface McpResourceTemplateDefinition extends McpResourceTemplate {
+    /**
+     * Read a resource instantiated from this template for `resources/read`.
+     *
+     * @param uri - The full resource URI requested by the client.
+     * @param variables - Template variable values extracted from `uri`.
+     * @param ctx - Request metadata and the original HTTP request.
+     * @returns One or more content entries for this resource.
+     * @throws {McpToolError} for caller-correctable failures such as an unknown
+     *   record id; these become JSON-RPC invalid-params errors.
+     */
+    read: (uri: string, variables: Record<string, string>, ctx: McpRequestContext) => McpResourceContents | McpResourceContents[] | Promise<McpResourceContents | McpResourceContents[]>;
+}
 /**
  * Argument metadata for an MCP prompt.
  *
@@ -253,8 +363,14 @@ export interface McpPrompt {
     title?: string;
     /** Optional prompt description. */
     description?: string;
-    /** Prompt arguments clients may supply to `prompts/get`. */
+    /**
+     * Prompt arguments clients may supply to `prompts/get`. Arguments marked
+     * `required: true` are enforced by {@link createMcpHandler}: a `prompts/get`
+     * call missing one fails with a JSON-RPC invalid-params error.
+     */
     arguments?: McpPromptArgument[];
+    /** Optional icons clients may display for this prompt (MCP 2025-11-25). */
+    icons?: McpIcon[];
 }
 /**
  * Message returned from `prompts/get`.
@@ -326,8 +442,25 @@ export interface McpHandlerOptions {
     tools?: readonly McpTool[];
     /** Readable resources exposed through `resources/list` and `resources/read`. */
     resources?: readonly McpResourceDefinition[];
+    /**
+     * Parameterized resource templates exposed through
+     * `resources/templates/list` and matched by `resources/read` when a URI is
+     * not a listed concrete resource.
+     */
+    resourceTemplates?: readonly McpResourceTemplateDefinition[];
     /** Reusable prompts exposed through `prompts/list` and `prompts/get`. */
     prompts?: readonly McpPromptDefinition[];
+    /**
+     * Extra `Origin` header values allowed on MCP requests, e.g.
+     * `"https://app.example.com"` (or the literal `"null"` for opaque origins).
+     *
+     * The MCP Streamable HTTP spec requires servers to validate `Origin` to
+     * prevent DNS rebinding attacks. DaloyJS always allows requests without an
+     * `Origin` header (non-browser MCP clients), same-origin requests, and
+     * loopback origins (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`); every
+     * other origin is rejected with `403` unless listed here.
+     */
+    allowedOrigins?: readonly string[];
     /** Accepted MCP protocol versions. Defaults to {@link MCP_PROTOCOL_VERSIONS}. */
     protocolVersions?: readonly string[];
     /**
@@ -364,10 +497,16 @@ export type McpHandler = (request: Request) => Promise<Response>;
  *
  * 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
@@ -378,6 +517,9 @@ export type McpHandler = (request: Request) => Promise<Response>;
  * @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