@daloyjs/core 1.0.0-beta.5 → 1.0.0-beta.7

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

@@ -0,0 +1,574 @@
+import type { PathString, RouteDefinition } from "./types.js";
+/**
+ * Latest MCP protocol version DaloyJS negotiates by default.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25
+ * @since 1.0.0
+ */
+export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+/**
+ * Protocol revisions accepted by {@link createMcpHandler} unless the caller
+ * provides an explicit `protocolVersions` list.
+ *
+ * @since 1.0.0
+ */
+export declare const MCP_PROTOCOL_VERSIONS: readonly string[];
+/**
+ * Default maximum accepted JSON-RPC request body for a DaloyJS MCP endpoint.
+ * The cap is intentionally small because MCP calls should carry parameters,
+ * not bulk uploads. Raise it per endpoint when a real tool needs larger input.
+ *
+ * @since 1.0.0
+ */
+export declare const MCP_DEFAULT_MAX_BODY_BYTES: number;
+/**
+ * JSON value accepted in MCP schemas, structured results, and metadata.
+ *
+ * @since 1.0.0
+ */
+export type McpJsonValue = null | boolean | number | string | McpJsonValue[] | {
+    [key: string]: McpJsonValue;
+};
+/**
+ * JSON object used for MCP tool arguments and structured payloads.
+ *
+ * @since 1.0.0
+ */
+export type McpJsonObject = {
+    [key: string]: McpJsonValue;
+};
+/**
+ * JSON Schema fragment advertised to MCP clients for a tool or prompt
+ * argument object. DaloyJS does not bundle a schema validator here, so the
+ * schema is documentation and client-side guidance. Validate sensitive inputs
+ * inside your handler before touching databases, files, or remote services.
+ *
+ * @since 1.0.0
+ */
+export type McpJsonSchema = McpJsonObject;
+/**
+ * JSON-RPC id type accepted by MCP requests.
+ *
+ * @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.
+ *
+ * @since 1.0.0
+ */
+export interface McpServerInfo {
+    /** Stable machine-readable server name, for example `"acme-inventory-mcp"`. */
+    name: string;
+    /** Optional human-readable display title for MCP clients. */
+    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.
+ *
+ * @since 1.0.0
+ */
+export interface McpRequestContext {
+    /** The original HTTP request received by the DaloyJS route. */
+    request: Request;
+    /**
+     * 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. */
+    id: McpJsonRpcId;
+    /** Raw MCP method name, such as `"tools/call"` or `"resources/read"`. */
+    method: string;
+}
+/**
+ * Text content block returned from an MCP tool, resource, or prompt.
+ *
+ * @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;
+}
+/**
+ * Image content block returned from an MCP tool.
+ *
+ * `data` is base64-encoded image bytes. Keep images small; for large assets,
+ * return a resource link or URL-bearing text instead.
+ *
+ * @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;
+}
+/**
+ * Embedded resource content block returned from an MCP tool.
+ *
+ * @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;
+}
+/**
+ * Content block supported by the dependency-free MCP helper.
+ *
+ * @since 1.0.0
+ */
+export type McpContent = McpTextContent | McpImageContent | McpEmbeddedResourceContent;
+/**
+ * Result returned by an MCP tool handler.
+ *
+ * `isError` marks caller-correctable tool failures, such as invalid input or a
+ * domain error. Unexpected thrown errors become JSON-RPC internal errors and
+ * are redacted in production.
+ *
+ * @since 1.0.0
+ */
+export interface McpToolResult {
+    /**
+     * 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.
+ *
+ * @typeParam TArgs - Type expected in `params.arguments` for this tool.
+ * @param args - Tool arguments supplied by the MCP client. They are typed for
+ *   developer experience but are still untrusted JSON at runtime.
+ * @param ctx - Request metadata and the original HTTP request.
+ * @returns Text shorthand or a full {@link McpToolResult}.
+ * @throws {McpToolError} for caller-correctable failures that should be
+ *   returned as an MCP tool error result.
+ *
+ * @since 1.0.0
+ */
+export type McpToolHandler<TArgs extends Record<string, unknown> = Record<string, unknown>> = (args: TArgs, ctx: McpRequestContext) => string | McpToolResult | Promise<string | McpToolResult>;
+/**
+ * Definition of a callable MCP tool.
+ *
+ * Tools are model-controlled in MCP: clients may let the language model decide
+ * when to call them. Treat every tool as a public API operation and enforce
+ * authentication, authorization, rate limits, and validation before side
+ * effects.
+ *
+ * @typeParam TArgs - Type expected by this tool's handler.
+ * @since 1.0.0
+ */
+export interface McpTool<TArgs extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique tool name within this MCP server. Prefer namespaced verbs. */
+    name: string;
+    /** Optional human-readable title displayed by clients. */
+    title?: string;
+    /** Clear description of when the model should use this tool. */
+    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>;
+}
+/**
+ * Resource metadata returned from `resources/list`.
+ *
+ * @since 1.0.0
+ */
+export interface McpResource {
+    /** Unique resource URI, for example `"daloy://schema/inventory"`. */
+    uri: string;
+    /** Stable resource name. */
+    name: string;
+    /** Optional human-readable title. */
+    title?: string;
+    /** Optional description shown by clients. */
+    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`.
+ *
+ * Use either `text` for UTF-8 content or `blob` for base64-encoded binary
+ * content. Set `mimeType` so clients know how to present the resource.
+ *
+ * @since 1.0.0
+ */
+export interface McpResourceContents {
+    /** URI of the resource being returned. */
+    uri: string;
+    /** MIME type of the returned content. */
+    mimeType?: string;
+    /** UTF-8 text content. */
+    text?: string;
+    /** Base64-encoded binary content. */
+    blob?: string;
+}
+/**
+ * Definition of a readable MCP resource.
+ *
+ * Resources are application-controlled context. They are a good fit for
+ * schemas, read-only records, catalogs, runbooks, and other context a client
+ * can choose to include before a tool call.
+ *
+ * @since 1.0.0
+ */
+export interface McpResourceDefinition extends McpResource {
+    /**
+     * Read the resource contents for `resources/read`.
+     *
+     * @param ctx - Request metadata and the original HTTP request.
+     * @returns One or more content entries for this resource.
+     */
+    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.
+ *
+ * @since 1.0.0
+ */
+export interface McpPromptArgument {
+    /** Argument name accepted by the prompt. */
+    name: string;
+    /** Optional description displayed by clients. */
+    description?: string;
+    /** Whether the argument is required. */
+    required?: boolean;
+}
+/**
+ * Prompt metadata returned from `prompts/list`.
+ *
+ * @since 1.0.0
+ */
+export interface McpPrompt {
+    /** Unique prompt name within this MCP server. */
+    name: string;
+    /** Optional human-readable title. */
+    title?: string;
+    /** Optional prompt description. */
+    description?: string;
+    /**
+     * 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`.
+ *
+ * @since 1.0.0
+ */
+export interface McpPromptMessage {
+    /** Role that should receive the prompt content. */
+    role: "user" | "assistant";
+    /** Prompt content block. */
+    content: McpTextContent | McpImageContent | McpEmbeddedResourceContent;
+}
+/**
+ * Result returned by an MCP prompt handler.
+ *
+ * @since 1.0.0
+ */
+export interface McpPromptResult {
+    /** Optional description of the rendered prompt. */
+    description?: string;
+    /** Messages the client can inject into the model conversation. */
+    messages: McpPromptMessage[];
+}
+/**
+ * Definition of a reusable MCP prompt.
+ *
+ * @since 1.0.0
+ */
+export interface McpPromptDefinition extends McpPrompt {
+    /**
+     * Render the prompt for `prompts/get`.
+     *
+     * @param args - Prompt arguments supplied by the MCP client.
+     * @param ctx - Request metadata and the original HTTP request.
+     * @returns Prompt messages.
+     */
+    get: (args: Record<string, unknown>, ctx: McpRequestContext) => McpPromptResult | Promise<McpPromptResult>;
+}
+/**
+ * Caller-correctable MCP tool/resource/prompt error.
+ *
+ * Throw this when the model supplied bad arguments, referenced a missing
+ * domain object, or otherwise made a recoverable call. Tool errors become
+ * `{ isError: true }` tool results; resource and prompt errors become
+ * JSON-RPC invalid-params errors. Unexpected errors are treated as internal
+ * server failures and are redacted in production.
+ *
+ * @since 1.0.0
+ */
+export declare class McpToolError extends Error {
+    /**
+     * Create a recoverable MCP handler error.
+     *
+     * @param message - Safe, caller-visible explanation.
+     */
+    constructor(message: string);
+}
+/**
+ * Options for {@link createMcpHandler}.
+ *
+ * @since 1.0.0
+ */
+export interface McpHandlerOptions {
+    /** Server identity returned from the `initialize` handshake. */
+    serverInfo: McpServerInfo;
+    /** Optional guidance returned from `initialize`. */
+    instructions?: string;
+    /** Callable tools exposed through `tools/list` and `tools/call`. */
+    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[];
+    /**
+     * Protocol version returned when the client asks for an unsupported version.
+     * Defaults to {@link MCP_PROTOCOL_VERSION}.
+     */
+    preferredProtocolVersion?: string;
+    /** Maximum accepted JSON-RPC body size in bytes. Defaults to 256 KiB. */
+    maxBodyBytes?: number;
+    /**
+     * Extra headers added to every JSON response. Use this for endpoint-local
+     * cache, CORS, or deployment metadata. Authentication should usually live in
+     * DaloyJS middleware before the MCP route.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Include development error details in JSON-RPC internal errors. Defaults to
+     * `process.env.NODE_ENV !== "production"` when `process` exists.
+     */
+    exposeInternalErrors?: boolean;
+}
+/**
+ * Fetch-compatible handler returned by {@link createMcpHandler}.
+ *
+ * @param request - Incoming HTTP request for the MCP endpoint.
+ * @returns A standard `Response` containing a JSON-RPC response, `202` for
+ *   accepted notifications, or `405` for unsupported HTTP methods.
+ *
+ * @since 1.0.0
+ */
+export type McpHandler = (request: Request) => Promise<Response>;
+/**
+ * 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/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
+ * middleware for authentication and authorization, and run this on a dedicated
+ * Daloy app when your MCP server has a different trust boundary than your REST
+ * API.
+ *
+ * @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
+ * const mcp = createMcpHandler({
+ *   serverInfo: { name: "inventory-mcp", version: "1.0.0" },
+ *   tools: [
+ *     {
+ *       name: "inventory_lookup",
+ *       description: "Look up inventory by SKU.",
+ *       inputSchema: {
+ *         type: "object",
+ *         properties: { sku: { type: "string" } },
+ *         required: ["sku"],
+ *         additionalProperties: false,
+ *       },
+ *       handler: async ({ sku }) => `SKU ${sku} has 42 units.`,
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare function createMcpHandler(options: McpHandlerOptions): McpHandler;
+/**
+ * Build the Daloy route definitions for a Streamable HTTP MCP endpoint.
+ *
+ * Register each returned route on the Daloy app that should host MCP. A
+ * separate app is often the cleanest production shape: the REST API can keep
+ * its public contract and auth policy, while the MCP server can use its own
+ * bearer token, rate limit, network allowlist, and tool set.
+ *
+ * @param path - Public MCP endpoint path, usually `"/mcp"`.
+ * @param handler - Handler returned by {@link createMcpHandler}.
+ * @returns Route definitions for `POST`, `GET`, and `OPTIONS` on the same
+ *   path. `POST` is the actual MCP transport; `GET` gives a human-readable
+ *   405 hint because this helper does not open server-initiated SSE streams;
+ *   `OPTIONS` supports preflight when CORS middleware is installed.
+ *
+ * @example
+ * ```ts
+ * const app = new App();
+ * const mcp = createMcpHandler({ serverInfo, tools });
+ *
+ * for (const route of mcpRoutes("/mcp", mcp)) {
+ *   app.route(route);
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare function mcpRoutes(path: PathString, handler: McpHandler): RouteDefinition<PathString, "GET" | "POST" | "OPTIONS">[];