@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/input/params.js

@@ -0,0 +1,8 @@
+import { runSchema } from "../validation/validate-input.js";
+/**
+ * `params` validated by `schema`: what the schema produced, a promise of it only for an async
+ * validator. Without a schema (a `readableStream()` entry) the params pass as they are.
+ */
+export function paramsInput(schema, params) {
+    return schema === null ? params : runSchema(schema, params, "params");
+}

package/dist/input/query.d.ts

@@ -0,0 +1,10 @@
+/** The query as `.input({ search })` declares it. */
+import type { StandardSchemaLike } from "../validation/standard-schema.ts";
+import { type Shape } from "../validation/validate-input.ts";
+/**
+ * The query (ctx.searchAll, parsed once per request) validated by `schema`. Repeated keys follow
+ * `shape` (the schema's, computed once per route), and `__proto__`, `constructor` and `prototype`
+ * never reach it (H18.13). Without a schema (a `readableStream()` entry) the query passes
+ * unvalidated.
+ */
+export declare function searchInput(schema: StandardSchemaLike | null, searchAll: Readonly<Record<string, readonly string[]>>, shape?: Shape | null): unknown;

package/dist/input/query.js

@@ -0,0 +1,17 @@
+import { runSchema, shapedRecord, shapeOf } from "../validation/validate-input.js";
+/** ctx.searchAll as key/value pairs, in request order per key. */
+function* pairs(searchAll) {
+    for (const key in searchAll)
+        for (const value of searchAll[key])
+            yield [key, value];
+}
+/**
+ * The query (ctx.searchAll, parsed once per request) validated by `schema`. Repeated keys follow
+ * `shape` (the schema's, computed once per route), and `__proto__`, `constructor` and `prototype`
+ * never reach it (H18.13). Without a schema (a `readableStream()` entry) the query passes
+ * unvalidated.
+ */
+export function searchInput(schema, searchAll, shape = schema === null ? null : shapeOf(schema)) {
+    const record = shapedRecord(pairs(searchAll), shape);
+    return schema === null ? record : runSchema(schema, record, "search");
+}

package/dist/mcp/mount.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `mcp(app, path, handler, options?)` (bit 21 e, H24.3): the app's own tools over MCP's Streamable HTTP, served at
+ * `path` by the handler the plugin generates (`_gen/mcp.gen.ts`'s `mcpHandler`), typed against its shape alone, so
+ * core imports nothing of honey-clients. POST, GET and DELETE are plain routes on the handle (its basePath and every
+ * middleware apply; the handler answers GET and DELETE 405), internal and served, so they stay out of the documents
+ * and out of the tool set. Each call dispatches in-process through `app.fetch` with the request's env and execution
+ * context, every middleware and the operation's own auth running again; only the credential headers the tools'
+ * schemes name ride it. A plain function the app imports (`@lovrozagar/honey/mcp`), so an app serving no MCP
+ * bundles none of it.
+ *
+ * Auth, fail-closed: when any tool's operation requires a credential, the mount needs `authenticate`, run on every
+ * request before any dispatch; `false` is HTTP 401 with the scheme's challenge. Its answer reaches the tools only as
+ * the credential the request carries, which the inner routes check again. Mounting secured tools without it throws,
+ * with no exception.
+ *
+ * OAuth (bit 21 f, opt-in, H23): `oauth` takes what `oauth(options)` from `@lovrozagar/honey/mcp/oauth` returns,
+ * so an app that never imports it bundles none of the resource server. Here is only its hook: called once at mount
+ * (its refusals before any route registers), its challenge on every 401 and on the handler's challenged 403, its
+ * metadata route registered after the endpoint's. It needs `authenticate`, even when no tool declares security.
+ *
+ * Files (bit 21 g, opt-in, H23): `uploads` takes what `uploads(options)` from `@lovrozagar/honey/mcp/uploads`
+ * returns (called once at mount, its PUT route registered once the endpoint's path is checked free; each request's
+ * uploads handed to the handler), and `urlFiles` what `urlFiles(options)` from `@lovrozagar/honey/mcp/url-files` returns. Neither is
+ * imported here, so a mount without them bundles none of either.
+ */
+import type { HoneyContext } from "../context/context.ts";
+/** What the mount hands the handler on each request. */
+export type McpMount = {
+    /** the app, in process: each tool call's request through every middleware and its route */
+    readonly dispatch: (request: Request) => Promise<Response>;
+    /** the browser origins served beside the endpoint's own */
+    readonly origins: readonly string[];
+    /** the most bytes a request body may hold; the handler's own cap when unset */
+    readonly max: number | undefined;
+    /** this request's uploads, when the mount takes them */
+    readonly uploads: McpUploading | undefined;
+    /** the URL file fetch, when the mount has one */
+    readonly fetchFile: McpFileFetch | undefined;
+};
+/** A call an upload is bound to: the credential headers its request carried, the tool, every argument. */
+export type McpUploadScope = {
+    readonly credential: string;
+    readonly tool: string;
+    readonly args: Record<string, unknown>;
+};
+/** A file an upload is for: its id in the call, its declared size, its SHA-256 (base64url). */
+export type McpUploadFile = {
+    readonly id: string;
+    readonly size: number;
+    readonly digest: string;
+};
+/**
+ * One request's uploads: the URL a token is PUT under (`base/<token>`), the most bytes a file may declare, a file's
+ * token, and its bytes on the call's retry, taken once; `take` rejects a token the call does not hold and resolves the
+ * rule a missing upload breaks.
+ */
+export type McpUploading = {
+    readonly base: string;
+    readonly max: number;
+    readonly issue: (scope: McpUploadScope, file: McpUploadFile) => Promise<string>;
+    readonly take: (scope: McpUploadScope, file: McpUploadFile, token: string) => Promise<Uint8Array | string>;
+};
+/**
+ * The hook `uploads(options)` returns: called once at mount, once the endpoint's path is checked free, it registers the
+ * upload route and returns each request's uploads.
+ */
+export type McpUploads = (app: unknown, path: string) => (request: Request) => McpUploading;
+/** What `urlFiles(options)` returns: a file's bytes, type and name fetched from its URL; rejects with the rule broken. */
+export type McpFileFetch = (url: string, signal: AbortSignal) => Promise<{
+    readonly bytes: Uint8Array;
+    readonly type: string;
+    readonly name?: string;
+}>;
+/** The generated handler (`mcpHandler`): whether a tool requires a credential, the challenge it names, the endpoint. */
+export type McpHandler = {
+    readonly secured: boolean;
+    readonly challenge: string;
+    readonly fetch: (request: Request, mount: McpMount) => Promise<Response>;
+};
+/**
+ * The resource-server hook `oauth(options)` returns: called once at mount with the app and the mount path, it refuses
+ * an endpoint its options don't fit and answers the endpoint's Bearer challenges and its metadata route.
+ */
+export type McpProtectedResource = (app: unknown, path: string) => {
+    /** the challenge of a `status` refusal of `request`, the handler's own `inner` challenge carried over */
+    readonly challenge: (request: Request, status: number, inner?: string | null) => string;
+    /** registers the metadata route, once the endpoint's own are */
+    readonly register: () => void;
+};
+/**
+ * Whether `request` carries a credential the app accepts; `false` is refused before any dispatch. `ctx` is the
+ * mounting handle's own, as its routes see it: its env, and what its middleware adds.
+ */
+export type McpAuthenticate<TCtx = HoneyContext<unknown>> = (request: Request, ctx: TCtx) => boolean | Promise<boolean>;
+/** The ctx a handle's routes are given (its `$ctx`); any app's, for anything else. */
+type CtxOf<A> = A extends {
+    readonly $ctx: infer TCtx;
+} ? TCtx : HoneyContext<unknown>;
+/** What `mcp()` takes beside the handler; `TCtx` is the ctx `authenticate` is given, any app's by default. */
+export type McpOptions<TCtx = HoneyContext<unknown>> = {
+    /** the check run on every request before any dispatch; required when a tool requires a credential */
+    readonly authenticate?: McpAuthenticate<TCtx>;
+    /** browser origins served beside the endpoint's own; any other Origin is 403 */
+    readonly origins?: readonly string[];
+    /** the most bytes a request body may hold (4 MiB by default); the app's bodyLimit applies before it */
+    readonly maxBodyBytes?: number;
+    /** the opt-in OAuth 2.1 resource-server role: RFC 9728 metadata and Bearer challenges pointing at it */
+    readonly oauth?: McpProtectedResource;
+    /** out-of-band file uploads, through the file-uploads extension: what `uploads(options)` returns */
+    readonly uploads?: McpUploads;
+    /** file arguments given as https URLs the app fetches: what `urlFiles(options)` returns */
+    readonly urlFiles?: McpFileFetch;
+};
+/** Serve `handler`'s tools at `path` on `app`; returns `app`. */
+export declare function mcp<A>(app: A, path: string, handler: McpHandler, options?: McpOptions<CtxOf<A>>): A;
+export {};

package/dist/mcp/mount.js

@@ -0,0 +1,45 @@
+import { isStaticPattern, joinPatterns, parsePattern } from "../routing/pattern.js";
+import { assertRouteFree, GRAPH, SERVED, VIEW } from "../routing/register.js";
+const METHODS = ["post", "get", "delete"];
+/** An answer of `status` with no body, its `challenge` the only header. */
+const refusal = (status, challenge) => new Response(null, { headers: { "www-authenticate": challenge }, status });
+/** Serve `handler`'s tools at `path` on `app`; returns `app`. */
+export function mcp(app, path, handler, options = {}) {
+    const { authenticate, maxBodyBytes, oauth, origins = [], uploads, urlFiles } = options;
+    if (oauth !== undefined && typeof authenticate !== "function")
+        throw new Error(`mcp(${path}): oauth makes it a protected resource, so it needs authenticate: (request, ctx) => boolean`);
+    if (handler.secured && typeof authenticate !== "function")
+        throw new Error(`mcp(${path}): its tools require a credential, so it needs authenticate: (request, ctx) => boolean, run on ` +
+            "every request before any call");
+    const handle = app;
+    const segments = parsePattern(joinPatterns(handle[VIEW].basePath, path));
+    if (!isStaticPattern(segments))
+        throw new Error(`cannot serve MCP at ${path}: its path is fixed, with no parameter`);
+    const resource = oauth?.(app, path);
+    for (const method of METHODS)
+        assertRouteFree(handle[GRAPH], method.toUpperCase(), segments);
+    const files = uploads?.(app, path);
+    const serve = async (ctx) => {
+        if (typeof authenticate === "function" && !(await authenticate(ctx.req, ctx)))
+            return ctx.res.raw(refusal(401, resource ? resource.challenge(ctx.req, 401) : handler.challenge));
+        const dispatch = async (request) => handle.fetch(request, ctx.env, ctx.executionCtx);
+        const answer = await handler.fetch(ctx.req, {
+            dispatch,
+            fetchFile: urlFiles,
+            max: maxBodyBytes,
+            origins,
+            uploads: files?.(ctx.req),
+        });
+        const inner = answer.headers.get("www-authenticate");
+        /* under oauth the handler's 401, or its 403 with a challenge (insufficient_scope; an Origin 403 has none), is ours */
+        if (resource && (answer.status === 401 || (answer.status === 403 && inner !== null)))
+            return ctx.res.raw(refusal(answer.status, resource.challenge(ctx.req, answer.status, inner)));
+        return ctx.res.raw(answer);
+    };
+    for (const method of METHODS)
+        handle[method](path)
+            .meta({ internal: true, [SERVED]: true })
+            .handler(serve);
+    resource?.register();
+    return app;
+}

package/dist/mcp/oauth.d.ts

@@ -0,0 +1,14 @@
+import type { McpProtectedResource } from "./mount.ts";
+/** The options of `oauth()`: the resource server's metadata and where its tokens come from. */
+export type McpOAuthOptions = {
+    /** issuer URLs of the authorization servers whose tokens the endpoint takes; at least one (RFC 9728 §2, MCP) */
+    readonly authorizationServers: readonly string[];
+    /** scopes a client may ask for, offered when a 401 names none; never `offline_access` (RFC 9728 §2) */
+    readonly scopesSupported?: readonly string[];
+    /** the endpoint's canonical URL, for an app whose requests do not carry its public origin (behind a proxy) */
+    readonly resource?: string;
+    /** the endpoint's name as a user sees it (RFC 9728 §2 `resource_name`) */
+    readonly resourceName?: string;
+};
+/** The resource-server hook for `mcp()`'s `oauth`: `options` refused now when the spec forbids them. */
+export declare function oauth(options: McpOAuthOptions): McpProtectedResource;

package/dist/mcp/oauth.js

@@ -0,0 +1,88 @@
+import { joinPatterns, parsePattern } from "../routing/pattern.js";
+import { assertRouteFree, GRAPH, SERVED, VIEW } from "../routing/register.js";
+import { startRoute } from "../routing/route-builder.js";
+const WELL_KNOWN = "/.well-known/oauth-protected-resource";
+/* an auth-param, its value a token or a whole quoted-string (RFC 9110 §11.2), so a quoted "scope=" is no param */
+const PARAM = /([\w!#$%&'*+.^`|~-]+)\s*=\s*("(?:[^"\\]|\\.)*"|[^\s,]*)/g;
+/* RFC 6749 §3.3's scope-token */
+const SCOPE = /^[\x21\x23-\x5b\x5d-\x7e]+$/;
+/* OAuth asks for TLS everywhere but a loopback host, where a local server has none (RFC 8252 §8.3) */
+const LOOPBACK = ["localhost", "127.0.0.1", "[::1]"];
+/** `value` as an OAuth party's URL: https (http on a loopback host) with no userinfo, query or fragment. */
+function secure(value) {
+    const url = URL.canParse(value) && !/[?#]/.test(value) ? new URL(value) : undefined;
+    const scheme = url?.protocol === "https:" || (url?.protocol === "http:" && LOOPBACK.includes(url.hostname));
+    return scheme && url?.username === "" && url.password === "" ? url : undefined;
+}
+/** `value` as an auth-param's quoted-string (RFC 9110 §5.6.4). */
+const quoted = (value) => `"${value.replace(/[\\"]/g, "\\$&")}"`;
+/** The scopes a Bearer challenge names: its scope param read past every quoted string, valid tokens, once each. */
+function scopesOf(challenge) {
+    if (!/^\s*Bearer\b/i.test(challenge ?? ""))
+        return [];
+    let scope = "";
+    const params = challenge.matchAll(PARAM);
+    for (const [, name, value] of params)
+        if (name.toLowerCase() === "scope")
+            scope = value.startsWith('"') ? value.slice(1, -1).replace(/\\(.)/g, "$1") : value;
+    return [...new Set(scope.split(" ").filter((each) => SCOPE.test(each) && each !== "offline_access"))];
+}
+/** A refusal of `oauth()`'s options, saying why. */
+const refuse = (why) => new Error(`oauth(): ${why}`);
+/** Refuse `options` the spec forbids, naming the option. */
+function check({ authorizationServers, scopesSupported }) {
+    if (authorizationServers.length === 0)
+        throw refuse("authorizationServers lists no authorization server; RFC 9728 metadata needs at least one");
+    for (const issuer of authorizationServers)
+        if (secure(issuer) === undefined)
+            throw refuse(`authorizationServers names ${issuer}, which is no https URL without userinfo, a query or a fragment`);
+    for (const scope of scopesSupported ?? []) {
+        if (scope === "offline_access")
+            throw refuse("scopesSupported lists offline_access, a scope the authorization server grants and a resource never asks for");
+        if (!SCOPE.test(scope))
+            throw refuse(`scopesSupported lists ${JSON.stringify(scope)}, which is no scope token`);
+    }
+}
+/** The resource-server hook for `mcp()`'s `oauth`: `options` refused now when the spec forbids them. */
+export function oauth(options) {
+    check(options);
+    const { authorizationServers, resource, resourceName, scopesSupported } = options;
+    return (app, at) => {
+        const handle = app;
+        const graph = handle[GRAPH];
+        /* the URL a client sees: the prefix the app strips, the basePath, the path; no trailing slash, so the endpoint
+         * at the root is its bare origin (MCP "Canonical Server URI") */
+        const endpoint = joinPatterns(graph.settings.stripPrefix ?? "/", joinPatterns(handle[VIEW].basePath, at));
+        const tail = endpoint.replace(/\/$/, "");
+        const fixed = resource === undefined ? undefined : secure(resource);
+        if (resource !== undefined && fixed?.pathname.replace(/\/$/, "") !== tail)
+            throw new Error(`mcp(${at}): oauth's resource ${resource} is not this endpoint's URL, whose path is ${endpoint}`);
+        const path = WELL_KNOWN + tail;
+        assertRouteFree(graph, "GET", parsePattern(path));
+        const origin = (url) => fixed?.origin ?? new URL(url).origin;
+        return {
+            challenge: (request, status, inner) => {
+                const error = status === 403 ? "insufficient_scope" : request.headers.has("authorization") && "invalid_token";
+                const scope = scopesOf(inner).join(" ");
+                const metadata = `resource_metadata=${quoted(origin(request.url) + path)}`;
+                const params = [error && `error=${quoted(error)}`, scope && `scope=${quoted(scope)}`];
+                return `Bearer ${[...params.filter(Boolean), metadata].join(", ")}`;
+            },
+            /* on the root, under the handle's middleware: the metadata sits beside the origin, not under the basePath */
+            register: () => void startRoute(graph, { ...handle[VIEW], basePath: "/" }, handle, {
+                extraMethods: [],
+                method: "GET",
+                path,
+            })
+                .meta({ internal: true, [SERVED]: true })
+                .handler((ctx) => ctx.res.raw(Response.json({
+                resource: origin(ctx.req.url) + tail,
+                authorization_servers: authorizationServers,
+                ...(scopesSupported && { scopes_supported: scopesSupported }),
+                /* MCP sends the token in the Authorization header alone, never the query or body */
+                bearer_methods_supported: ["header"],
+                ...(resourceName !== undefined && { resource_name: resourceName }),
+            }))),
+        };
+    };
+}

package/dist/mcp/uploads.d.ts

@@ -0,0 +1,36 @@
+import type { McpUploads } from "./mount.ts";
+/**
+ * Where uploads wait for their call's retry. Each method may be async. On Workers, the atomic claim and take are a D1
+ * row or a Durable Object's (`INSERT … ON CONFLICT DO NOTHING`, `DELETE … RETURNING`) and the bytes R2's, since either
+ * row holds at most 2 MB; KV is eventually consistent, so two claims can both succeed there, and it cannot keep an
+ * upload one-shot.
+ */
+export type UploadStore = {
+    /** marks `id` used, atomically: true for its first claim alone; it need be kept only until `expires` (ms epoch) */
+    readonly claim: (id: string, expires: number) => boolean | Promise<boolean>;
+    /** keeps a claimed upload's checked bytes until they are taken or `expires` passes */
+    readonly put: (id: string, bytes: Uint8Array, expires: number) => void | Promise<void>;
+    /** the bytes kept under `id`, removed as they are returned, atomically, so one caller alone gets them */
+    readonly take: (id: string) => Uint8Array | undefined | Promise<Uint8Array | undefined>;
+};
+/** The options of `uploads()`. */
+export type McpUploadsOptions = {
+    /** the HMAC key its tokens are signed with: at least 32 characters, the app's own secret */
+    readonly secret: string;
+    /** where uploads wait for their call's retry */
+    readonly store: UploadStore;
+    /** how long a token works, in ms: 10 minutes by default */
+    readonly ttlMs?: number;
+    /** the most bytes one file may declare: 50 MiB by default */
+    readonly maxBytes?: number;
+    /** the endpoint's public origin, for an app whose requests do not carry it (behind a proxy) */
+    readonly origin?: string;
+};
+/** The uploads hook for `mcp()`'s `uploads`: `options` refused now when they cannot work. */
+export declare function uploads(options: McpUploadsOptions): McpUploads;
+/**
+ * An in-memory UploadStore, for one process: development, tests, a single Node or Bun server. Its claim is atomic
+ * (no await between its check and its mark). Not for Workers or any app on more than one instance: each isolate has
+ * its own memory, so an upload PUT to one is missing on another.
+ */
+export declare function memoryUploadStore(): UploadStore;

package/dist/mcp/uploads.js

@@ -0,0 +1,171 @@
+import { joinPatterns, parsePattern } from "../routing/pattern.js";
+import { assertRouteFree, GRAPH, SERVED, VIEW } from "../routing/register.js";
+// per-process-constant: text-codec
+const TEXT = /* @__PURE__ */ new TextEncoder();
+/** `bytes` as base64url, unpadded. */
+const base64url = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes)))
+    .replace(/=+$/, "")
+    .replaceAll("+", "-")
+    .replaceAll("/", "_");
+/** `bytes`' SHA-256 as a FileInput's digest: base64url, unpadded. */
+async function digestOf(bytes) {
+    const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return base64url(hash);
+}
+/** `value` as JSON with every object's keys sorted, so equal arguments are equal text whatever their order. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    /* arguments are JSON, so every other value has its JSON text */
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    const object = value;
+    return `{${Object.keys(object)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonical(object[key])}`)
+        .join(",")}}`;
+}
+/** `request`'s body, at most `max` bytes counted as they stream; undefined past it. */
+async function bodyOf(request, max) {
+    const chunks = [];
+    let size = 0;
+    const reader = request.body?.getReader();
+    for (let read = await reader?.read(); read && !read.done; read = await reader?.read()) {
+        if ((size += read.value.length) > max)
+            return void (await reader?.cancel());
+        chunks.push(read.value);
+    }
+    return new Uint8Array(await new Blob(chunks).arrayBuffer());
+}
+/** A refusal of the upload route, its rule as text. */
+const refused = (status, rule) => new Response(rule, { status });
+/** A refusal of `uploads()`'s options, saying why. */
+const refuse = (why) => new Error(`uploads(): ${why}`);
+/** Whether `value` is a whole number of at least `least`. */
+const whole = (value, least) => Number.isSafeInteger(value) && value >= least;
+/** The MACs under `secret`, each naming what it signs so no value of one kind passes for another. */
+function signer(secret) {
+    const key = crypto.subtle.importKey("raw", TEXT.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]);
+    const mac = async (kind, text) => base64url(await crypto.subtle.sign("HMAC", await key, TEXT.encode(`${kind}\n${text}`)));
+    return {
+        call: (tool, args, id) => mac("call", canonical([tool, args, id])),
+        principal: (credential) => mac("principal", credential),
+        /** `fields` as a token: each, then their MAC */
+        token: async (fields) => `${fields.join(".")}.${await mac("upload", fields.join("."))}`,
+        /** `token`'s fields when this app signed it; its expiry unchecked */
+        signed: async (token) => {
+            const parts = token.split(".");
+            const fields = parts.slice(0, 6);
+            return parts.length === 7 && (await mac("upload", fields.join("."))) === parts[6] ? fields : undefined;
+        },
+    };
+}
+/** The upload route's answer to a PUT of `token`: the bytes kept under its claim, else the rule broken. */
+async function stored(sign, store, token, request) {
+    const fields = await sign.signed(token);
+    if (fields === undefined)
+        return refused(403, "the upload token is not this app's");
+    const [id, expires, size, digest] = fields;
+    if (Date.now() > Number(expires))
+        return refused(403, "the upload token has expired");
+    const bytes = await bodyOf(request, Number(size));
+    if (bytes === undefined)
+        return refused(413, `the upload is past its ${size} bytes`);
+    if (bytes.length !== Number(size))
+        return refused(400, `the upload is not its ${size} bytes`);
+    if ((await digestOf(bytes)) !== digest)
+        return refused(400, "the upload does not match its digest");
+    if (!(await store.claim(id, Number(expires))))
+        return refused(409, "the upload token is used");
+    await store.put(id, bytes, Number(expires));
+    return new Response(null, { status: 204 });
+}
+/** One request's uploads under `base`: a file's token, and on the retry its bytes, taken once. */
+function uploading(sign, store, limits, base) {
+    const upload = {
+        base,
+        issue: async ({ args, credential, tool }, file) => sign.token([
+            base64url(crypto.getRandomValues(new Uint8Array(16))),
+            String(Date.now() + limits.ttlMs),
+            String(file.size),
+            file.digest,
+            await sign.principal(credential),
+            await sign.call(tool, args, file.id),
+        ]),
+        max: limits.maxBytes,
+        take: async ({ args, credential, tool }, file, token) => {
+            const fields = await sign.signed(token);
+            if (fields === undefined)
+                throw new Error("requestState holds no upload token of this app's");
+            const [id, expires, size, digest, principal, call] = fields;
+            if (Date.now() > Number(expires))
+                throw new Error("requestState's upload token has expired");
+            if (principal !== (await sign.principal(credential)))
+                throw new Error("requestState's upload was made under another credential");
+            if (call !== (await sign.call(tool, args, file.id)))
+                throw new Error("requestState's upload is another call's");
+            const bytes = await store.take(id);
+            if (bytes === undefined)
+                return "was not uploaded, or its upload was taken";
+            const intact = bytes.length === Number(size) && (await digestOf(bytes)) === digest;
+            return intact ? bytes : "does not match its upload's digest";
+        },
+    };
+    return upload;
+}
+/** The uploads hook for `mcp()`'s `uploads`: `options` refused now when they cannot work. */
+export function uploads(options) {
+    const { maxBytes = 52_428_800, origin, secret, store, ttlMs = 600_000 } = options;
+    if (secret.length < 32)
+        throw refuse("secret needs at least 32 characters, the app's own");
+    if (!whole(ttlMs, 1))
+        throw refuse("ttlMs is no whole number of milliseconds");
+    if (!whole(maxBytes, 0))
+        throw refuse("maxBytes is no whole number of bytes");
+    if (origin !== undefined && (!URL.canParse(origin) || new URL(origin).origin !== origin))
+        throw refuse(`origin ${origin} is no origin: a scheme, a host and a port alone`);
+    const sign = signer(secret);
+    return (app, at) => {
+        const handle = app;
+        const graph = handle[GRAPH];
+        const route = joinPatterns(at, "uploads/:token");
+        assertRouteFree(graph, "PUT", parsePattern(joinPatterns(handle[VIEW].basePath, route)));
+        /* the URL a client PUTs to: the prefix the app strips, the basePath, the route */
+        const tail = joinPatterns(graph.settings.stripPrefix ?? "/", joinPatterns(handle[VIEW].basePath, at));
+        handle
+            .put(route)
+            .meta({ internal: true, [SERVED]: true })
+            .handler(async (ctx) => ctx.res.raw(await stored(sign, store, ctx.params.token, ctx.req)));
+        return (request) => uploading(sign, store, { maxBytes, ttlMs }, `${origin ?? new URL(request.url).origin}${tail.replace(/\/$/, "")}/uploads`);
+    };
+}
+/**
+ * An in-memory UploadStore, for one process: development, tests, a single Node or Bun server. Its claim is atomic
+ * (no await between its check and its mark). Not for Workers or any app on more than one instance: each isolate has
+ * its own memory, so an upload PUT to one is missing on another.
+ */
+export function memoryUploadStore() {
+    const claims = new Map();
+    const kept = new Map();
+    return {
+        claim: (id, expires) => {
+            const now = Date.now();
+            for (const [each, until] of claims)
+                if (until < now)
+                    claims.delete(each);
+            for (const [each, upload] of kept)
+                if (upload.expires < now)
+                    kept.delete(each);
+            if (claims.has(id))
+                return false;
+            claims.set(id, expires);
+            return true;
+        },
+        put: (id, bytes, expires) => void kept.set(id, { bytes, expires }),
+        take: (id) => {
+            const upload = kept.get(id);
+            kept.delete(id);
+            return upload && upload.expires >= Date.now() ? upload.bytes : undefined;
+        },
+    };
+}

package/dist/mcp/url-files.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `urlFiles(options)` (bit 21 g, H24.5), `@lovrozagar/honey/mcp/url-files`: a mounted tool's file argument given as
+ * `{url}`, fetched by the app, handed to `mcp(app, path, handler, { urlFiles: urlFiles(options) })`. Off unless
+ * imported and passed (H23); a mount without it shows no `{url}` value and refuses one. The guards, each its rule:
+ * - **the host** is one the list names exactly (its port too, when not 443); an entry `*.example.com` names every
+ *   host under example.com, never example.com itself, and nothing else matches by suffix. The list holds names alone:
+ *   an IP literal is refused when the list is made, in any form the URL parser reads as one (decimal, octal, hex,
+ *   IPv4-mapped IPv6), so no private, loopback or link-local address is ever listed;
+ * - **https** alone, with no userinfo;
+ * - **no redirect**, to any host: a 3xx is the refusal (an allowed host that redirects is not followed to another);
+ * - **the size**, counted as the body streams, past `maxBytes` refused (Content-Length never trusted);
+ * - **the time**, headers and body together, past `timeoutMs` refused;
+ * - **no credential** of the request is sent: the fetch carries no header of its own.
+ * DNS is not resolved here. The hosts are the operator's own choice, so their names are trusted as far as their
+ * owners are: a listed host whose DNS points at a private address is the operator's to not list. Resolving first
+ * would not close it either, since fetch resolves again (rebinding), and fetch cannot be pinned to an address on
+ * Workers or Bun. Workers' fetch reaches no private range at all.
+ */
+import type { McpFileFetch } from "./mount.ts";
+/** The options of `urlFiles()`. */
+export type McpUrlFilesOptions = {
+    /** the hosts files are fetched from, each exact (`files.example.com`, `files.example.com:8443`) or `*.example.com` */
+    readonly hosts: readonly string[];
+    /** the most bytes a file may hold: 50 MiB by default */
+    readonly maxBytes?: number;
+    /** how long a fetch may take, headers and body, in ms: 30 s by default */
+    readonly timeoutMs?: number;
+    /** the fetch it runs: the platform's by default */
+    readonly fetch?: (request: Request) => Promise<Response>;
+};
+/** The URL file fetch for `mcp()`'s `urlFiles`: `options` refused now when they cannot work. */
+export declare function urlFiles(options: McpUrlFilesOptions): McpFileFetch;

package/dist/mcp/url-files.js

@@ -0,0 +1,75 @@
+/* an IPv4 literal as the URL parser writes every form of one, or an IPv6 literal */
+const LITERAL = /^(?:\d+\.\d+\.\d+\.\d+|\[.*\])$/;
+/** A refusal of `urlFiles()`'s options, saying why. */
+const refuse = (why) => new Error(`urlFiles(): ${why}`);
+/** `entry`'s host as a URL's `host` reads it: lower case, its default port dropped; refused when it is no bare name. */
+function hostOf(entry) {
+    const url = /^[^/@?#\\\s]+$/.test(entry) && URL.canParse(`https://${entry}`) ? new URL(`https://${entry}`) : undefined;
+    if (url === undefined)
+        throw refuse(`hosts names ${entry}, which is no host`);
+    if (LITERAL.test(url.hostname))
+        throw refuse(`hosts names ${entry}, an IP address; list hosts by name`);
+    return url.host;
+}
+/** `answer`'s body, at most `max` bytes counted as it streams; refused past it, or when the answer is no 200. */
+async function bodyOf(answer, max) {
+    if (answer.status !== 200) {
+        await answer.body?.cancel();
+        const redirect = answer.status >= 300 && answer.status < 400 ? ", a redirect, which is never followed" : "";
+        throw new Error(`answered ${answer.status}${redirect}`);
+    }
+    const chunks = [];
+    let size = 0;
+    const reader = answer.body?.getReader();
+    for (let read = await reader?.read(); read && !read.done; read = await reader?.read()) {
+        if ((size += read.value.length) > max) {
+            await reader?.cancel();
+            throw new Error(`is past the ${max}-byte cap`);
+        }
+        chunks.push(read.value);
+    }
+    return new Uint8Array(await new Blob(chunks).arrayBuffer());
+}
+/** The URL file fetch for `mcp()`'s `urlFiles`: `options` refused now when they cannot work. */
+export function urlFiles(options) {
+    const { maxBytes = 52_428_800, timeoutMs = 30_000 } = options;
+    if (options.hosts.length === 0)
+        throw refuse("hosts lists no host");
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        throw refuse("maxBytes is no whole number of bytes");
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
+        throw refuse("timeoutMs is no whole number of milliseconds");
+    const exact = new Set();
+    const under = [];
+    for (const entry of options.hosts)
+        if (entry.startsWith("*."))
+            under.push(`.${hostOf(entry.slice(2))}`);
+        else
+            exact.add(hostOf(entry));
+    const fetcher = options.fetch ?? ((request) => fetch(request));
+    /** `value` as a URL this fetch may read: https, no userinfo, on a listed host */
+    const allowed = (value) => {
+        const url = URL.canParse(value) ? new URL(value) : undefined;
+        if (url?.protocol !== "https:" || url.username !== "" || url.password !== "")
+            throw new Error("is no https URL, or carries userinfo");
+        if (!exact.has(url.host) && !under.some((suffix) => url.host.endsWith(suffix)))
+            throw new Error(`is on ${url.host}, a host this server fetches no file from`);
+        return url;
+    };
+    return async (value, signal) => {
+        const url = allowed(value);
+        const timeout = AbortSignal.timeout(timeoutMs);
+        try {
+            const answer = await fetcher(new Request(url, { redirect: "manual", signal: AbortSignal.any([signal, timeout]) }));
+            const bytes = await bodyOf(answer, maxBytes);
+            const name = url.pathname.split("/").pop();
+            return { bytes, type: answer.headers.get("content-type") ?? "application/octet-stream", ...(name && { name }) };
+            /* a fetch the clock aborted says so; any other refusal is its own */
+        }
+        catch (error) {
+            if (timeout.aborted)
+                throw new Error(`took longer than ${timeoutMs} ms`, { cause: error });
+            throw error;
+        }
+    };
+}

package/dist/meta/meta-spec-apply.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Applying a compiled metaSpec to one route: each entry's value, from route meta or the route's
+ * schema metadata, turned into operation fields; then `meta.extensions`; then the totality check.
+ */
+import type { CompiledMetaSpec } from "./meta-spec.ts";
+import { type MetaSpecDiagnostics, type SchemaMetaLookup } from "./meta-spec-validate.ts";
+export type ApplyMetaSpecArgs = {
+    readonly diagnostics: MetaSpecDiagnostics;
+    readonly filter: (key: string) => boolean;
+    readonly kind: "http" | "ws";
+    readonly meta: Readonly<Record<string, unknown>> | null;
+    readonly method: string;
+    /** written in place */
+    readonly operation: Record<string, unknown>;
+    readonly path: string;
+    readonly profile: string;
+    /** the route's schema metadata; schema entries are skipped without it */
+    readonly schemaMeta?: SchemaMetaLookup;
+    readonly spec: CompiledMetaSpec;
+};
+/**
+ * Write the operation fields `spec` derives for one route into `operation`. A key is written at
+ * its first, highest-ranked contribution: route meta over schema metadata, `meta.extensions` over both.
+ */
+export declare function applyMetaSpec(args: ApplyMetaSpecArgs): void;