devframe 0.9.8 → 0.9.10

package/dist/adapters/initiate.d.mts

@@ -1,7 +1,7 @@
-import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "../ws-server-VyHlanzy.mjs";
-import { Ct as DevframeAuthHandler, F as DevframeDefinition, G as McpRouteOptions, U as DevframeSseOptions, W as DevframeWsOptions, bt as DevframeStorageScope, o as DevframeNodeContext, s as DevframeNodeRpcSession, t as ConnectionMeta } from "../context-CLF4-8Pp.mjs";
-import { o as StaticAssetsSource } from "../remote-assets-B13_vRkJ.mjs";
-import { c as StartedServer, f as DevframeInstanceRecord } from "../instance-shell-Tcp5hGoq.mjs";
+import { c as DevframeNodeRpcSessionMeta, l as DevframeRpcConnection, n as WsOriginRegistry } from "../ws-server-D2nv68Hg.mjs";
+import { F as DevframeDefinition, St as DevframeStorageScope, Tt as DevframeAuthHandler, U as DevframeSseOptions, W as DevframeWsOptions, o as DevframeNodeContext, q as McpSetting, s as DevframeNodeRpcSession, t as ConnectionMeta } from "../context-CHW4BZOj.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-eBvSKZMS.mjs";
+import { c as StartedServer, f as DevframeInstanceRecord } from "../instance-shell-DZipaP9k.mjs";
 import { Buffer } from "node:buffer";
 import { IncomingMessage, Server, ServerResponse } from "node:http";
 import { Duplex } from "node:stream";
@@ -9,7 +9,7 @@ import { H3 } from "h3";
 //#region src/adapters/initiate.d.ts
 interface InitDevframeOptions {
   /**
-   * Mount base the handler answers under (e.g. `/__my-tool/`) — required so
+   * Mount base the handler answers under (e.g. `/__my-tool/`), required so
    * the mount path is explicit at the call site. A handler is by definition
    * mounted *inside* a host app's origin; the resolved value is echoed back
    * as {@link DevframeInstance.base} so route/middleware code references it
@@ -19,8 +19,8 @@ interface InitDevframeOptions {
   base: string;
   /**
    * Override the definition's `clientAssets` (or deprecated `cli.distDir`).
-   * When neither is set — or `false` is passed to suppress the definition's
-   * own client assets — the handler runs in **bridge mode**: only
+   * When neither is set (or `false` is passed to suppress the definition's
+   * own client assets), the handler runs in **bridge mode**: only
    * `__connection.json`, the WS endpoint, and the MCP route (when enabled) are
    * served; the SPA is hosted elsewhere.
    */
@@ -36,20 +36,20 @@ interface InitDevframeOptions {
    */
   server?: Server;
   /**
-   * Explicit control over how the browser reaches the RPC WebSocket —
+   * Explicit control over how the browser reaches the RPC WebSocket,
    * advertised in `__connection.json`. The **local binding** resolves in
    * precedence order `ws.port` (pinned side-car) > `server` (shared upgrade)
    * > `ws.sidecar` (auto-port side-car) > none (the host drives the socket
    * through {@link DevframeInstance.attach}). `ws.url` controls the
    * advertisement* only: the browser dials it verbatim (a tunnel/relay),
-   * while the local binding keeps following the options above — and on its
+   * while the local binding keeps following the options above; on its
    * own it means an external server owns both the transport and its auth.
-   * Pass `false` to serve no WebSocket at all — clients connect over the
+   * Pass `false` to serve no WebSocket at all; clients connect over the
    * SSE endpoint instead (`backend: 'sse'`).
    */
   ws?: DevframeWsOptions | false;
   /**
-   * SSE RPC endpoint control — enabled by default at `<base>__sse` as the
+   * SSE RPC endpoint control, enabled by default at `<base>__sse` as the
    * more portable transport alongside the WebSocket. Pass `false` to
    * disable, or a {@link DevframeSseOptions} to rename the route.
    */
@@ -67,21 +67,24 @@ interface InitDevframeOptions {
    * (derived from the first request, or `origin`). Pass a
    * {@link DevframeAuthHandler} for a custom scheme, or `false` to opt out
    * for a single-user localhost setup that owns the trust boundary another
-   * way. Ignored for the `ws.url` tier — the server behind that URL owns auth.
+   * way. Ignored for the `ws.url` tier, since the server behind that URL owns auth.
    */
   auth?: boolean | DevframeAuthHandler;
   /**
    * Expose a route-based MCP server (Streamable-HTTP) at `<base>__mcp` and
    * advertise it in `__connection.json`. Overrides `def.cli?.mcp`;
-   * `undefined` falls through to it. See {@link McpRouteOptions}.
+   * `undefined` falls through to it, then to the `'auto'` default (mount
+   * once the agent surface is non-empty). See {@link McpSetting}.
    */
-  mcp?: boolean | McpRouteOptions;
+  mcp?: McpSetting;
   /**
    * Public origin the host app is reachable at (e.g. `http://localhost:3000`),
-   * or a getter for hosts that resolve it late. When omitted (or the getter
-   * returns a falsy value), it is derived lazily from the first request the
-   * handler serves — used for the auth banner's magic link and absolute dock
-   * URLs.
+   * or a getter for hosts that resolve it late. Backs the auth banner's magic
+   * link and absolute dock URLs. When omitted (or the getter returns a falsy
+   * value), it is derived from a served request, but only when that request's
+   * own origin is loopback or exactly matches an `allowedOrigins` entry; a raw
+   * inbound `Host`/URL authority and forwarded headers are never adopted. Set
+   * this explicitly for a non-loopback deployment (proxy, LAN, public host).
    */
   origin?: string | (() => string);
   /**
@@ -104,7 +107,7 @@ interface InitDevframeOptions {
   allowedOrigins?: readonly string[] | WsOriginRegistry | false;
   /**
    * h3 app to mount the handler's routes on. When omitted a fresh internal
-   * app is created — the common middleware case. An adapter that owns the
+   * app is created, the common middleware case. An adapter that owns the
    * whole server (e.g. `createDevServer`) passes its own app so callers can
    * compose custom routes ahead of devframe's.
    */
@@ -138,19 +141,19 @@ interface DevframeInstance {
   /**
    * The normalized mount base this instance answers under (leading and
    * trailing slash, e.g. `/__my-tool/`). Reference it when wiring the mount
-   * — route guards, middleware path checks — instead of repeating the
+   * (route guards, middleware path checks) instead of repeating the
    * string.
    */
   base: string;
   /**
-   * Web-standard request handler — mount it on a catch-all route under
+   * Web-standard request handler; mount it on a catch-all route under
    * {@link DevframeInstance.base} (Next.js route handler, SvelteKit
    * `+server.ts`, Hono `c.req.raw`, Nitro `toWebRequest(event)`, …).
    * Requests outside the base 404.
    */
   handler: (request: Request) => Promise<Response>;
   /**
-   * Connect/Express-style middleware over the same surface — for
+   * Connect/Express-style middleware over the same surface, for
    * `viteServer.middlewares.use(handler.nodeMiddleware)` or any other
    * node middleware stack. Mount it un-prefixed: paths outside the base
    * call `next()` so the rest of the stack keeps working.
@@ -158,7 +161,7 @@ interface DevframeInstance {
   nodeMiddleware: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
   /**
    * Route a host server's `upgrade` events to the RPC socket, returning a
-   * detach function — the manual counterpart to the `server` option, for
+   * detach function, the manual counterpart to the `server` option, for
    * hosts that get their `node:http` server only after the instance exists.
    * Available on the default tier; a configured transport (`server`,
    * `ws.port`, `ws.sidecar`, `ws.url`) already owns the socket and reports
@@ -175,10 +178,10 @@ interface DevframeInstance {
   /**
    * Resolves once `def.setup` has run and the WebSocket binding is live.
    * `handler`/`nodeMiddleware` await it internally, so hosts never race
-   * initialization — await it yourself only when you need the timing.
+   * initialization; await it yourself only when you need the timing.
    */
   ready: Promise<void>;
-  /** The node context, once initialized — for advanced wiring (own WS transport, extra RPC registration). */
+  /** The node context, once initialized, for advanced wiring (own WS transport, extra RPC registration). */
   context: Promise<DevframeNodeContext>;
   /**
    * The `ConnectionMeta` this handler serves at `<base>__connection.json`.
@@ -204,7 +207,7 @@ interface DevframeInstanceInternals {
 /** @internal */
 declare function getInstanceInternals(handler: object): DevframeInstanceInternals;
 /**
- * Serve a devframe through one framework-agnostic, web-standard handler —
+ * Serve a devframe through one framework-agnostic, web-standard handler:
  * the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the
  * auth gate, and the optional MCP route, all under a single mount base.
  * Mount `handler` on any framework's catch-all route (or `nodeMiddleware` on
@@ -212,10 +215,10 @@ declare function getInstanceInternals(handler: object): DevframeInstanceInternal
  *
  * The factory is synchronous and kicks off initialization eagerly;
  * `handler`/`nodeMiddleware` await readiness internally. Nothing binds a port
- * on its own: the WebSocket resolves in precedence order — `ws.port` (pinned
+ * on its own: the WebSocket resolves in precedence order: `ws.port` (pinned
  * side-car) > `server` (shared upgrade at `<base>__ws`) > `ws.sidecar`
  * (auto-port side-car) > the host driving upgrades itself through
- * {@link DevframeInstance.attach} — while `ws.url`, when set, overrides the
+ * {@link DevframeInstance.attach}. Meanwhile `ws.url`, when set, overrides the
  * advertised* endpoint (the tunnel pattern) and on its own hands the whole
  * transport to an external server. `__connection.json` reflects whichever
  * combination is active.

package/dist/adapters/initiate.mjs

@@ -1,2 +1,2 @@
-import { n as getInstanceInternals, r as initDevframe } from "../dev-CzkPCJwi.mjs";
+import { n as getInstanceInternals, r as initDevframe } from "../dev-CRYHx7iG.mjs";
 export { getInstanceInternals, initDevframe };

package/dist/adapters/mcp.d.mts

@@ -1,4 +1,4 @@
-import { F as DevframeDefinition, o as DevframeNodeContext } from "../context-CLF4-8Pp.mjs";
+import { F as DevframeDefinition, G as McpAuthorization, o as DevframeNodeContext } from "../context-CHW4BZOj.mjs";
 import { H3 } from "h3";
 import "@modelcontextprotocol/server";
 //#region src/adapters/mcp/build-server.d.ts
@@ -6,15 +6,15 @@ interface CreateMcpServerOptions {
   /**
    * Transport to use. `createMcpServer` itself runs `'stdio'` (a standalone
    * process with its own host context); the Streamable-HTTP transport is
-   * served route-based by the dev server instead — see `mountMcpHttp` and
+   * served route-based by the dev server instead; see `mountMcpHttp` and
    * the `mcp` option on `createDevServer` / `createCac`'s `--mcp` flag.
    */
   transport?: 'stdio';
   /**
    * Expose shared-state keys as MCP resources.
-   * - `true` (default) — every key the host publishes
-   * - `false` — none
-   * - `(key) => boolean` — filter
+   * - `true` (default): every key the host publishes
+   * - `false`: none
+   * - `(key) => boolean`: filter
    */
   exposeSharedState?: boolean | ((key: string) => boolean);
   /** Override the name reported in the MCP handshake. */
@@ -41,8 +41,17 @@ interface CreateMcpFetchHandlerOptions {
   serverName: string;
   /** Version reported in the MCP handshake. */
   serverVersion: string;
-  /** Expose shared-state keys as MCP resources — see `buildMcpServerFromContext`. */
+  /** Expose shared-state keys as MCP resources; see `buildMcpServerFromContext`. */
   exposeSharedState: boolean | ((key: string) => boolean);
+  /**
+   * Optional identity check, layered on top of the origin gate and checked
+   * **after** it: a bearer token string (matched in constant time against
+   * `Authorization: Bearer <token>`), a `(request) => boolean` callback, or
+   * `false` (the default) for origin-only, trusting same-machine callers. A
+   * callback governs identity only and cannot relax the origin gate. See
+   * {@link McpAuthorization}.
+   */
+  authorization?: McpAuthorization;
   /**
    * Origin allow-list beyond the loopback default. `false` disables the
    * origin gate entirely. Default: loopback-only.
@@ -57,7 +66,7 @@ interface CreateMcpFetchHandlerOptions {
 interface McpFetchHandler {
   /**
    * WHATWG-`fetch` handler for the MCP endpoint. Hand every method
-   * (POST/GET/DELETE) on the endpoint's path to it — routing by path is the
+   * (POST/GET/DELETE) on the endpoint's path to it; routing by path is the
    * host's job.
    */
   fetch: (request: Request) => Promise<Response>;
@@ -66,22 +75,27 @@ interface McpFetchHandler {
 }
 /**
  * Build a framework-agnostic MCP endpoint over a devframe context: a
- * web-standard `Request → Response` handler any host can mount — h3 (see
+ * web-standard `Request → Response` handler any host can mount: h3 (see
  * `mountMcpHttp`), a Next.js App Router route, or any other fetch-shaped
  * server.
  *
  * The endpoint is **stateless**: it serves the 2026-07-28 revision per request
  * through the SDK's {@link createMcpHandler}, which builds a fresh MCP server
  * (from the shared, live `ctx` via `buildMcpServerFromContext`) for each
- * request — no `Mcp-Session-Id` registry, no session-local routing, no
+ * request: no `Mcp-Session-Id` registry, no session-local routing, no
  * GET/DELETE teardown protocol. 2025-era clients are still served through the
  * SDK's default stateless legacy path. `list_changed` events reach modern
  * `subscriptions/listen` streams through the handler's `notify` bus.
  *
  * The origin gate guards every request: loopback-default DNS-rebinding
- * protection that — unlike the WS upgrade's `isAllowedOrigin` — also rejects
- * `Origin`-less requests, so a route-based endpoint isn't reachable by an
- * arbitrary local process.
+ * protection that (unlike the WS upgrade's `isAllowedOrigin`) also rejects
+ * `Origin`-less requests, so a route-based endpoint isn't reachable by a
+ * browser or a remote host (a disallowed origin gets `403`). It trusts
+ * same-machine callers by default. When that isn't your trust boundary, add
+ * an optional identity gate ({@link CreateMcpFetchHandlerOptions.authorization}),
+ * checked after the origin gate: a bearer/callback check that proves *who* is
+ * calling (a missing/invalid credential gets `401` with a
+ * `WWW-Authenticate: Bearer` challenge).
  */
 declare function createMcpFetchHandler(ctx: DevframeNodeContext, options: CreateMcpFetchHandlerOptions): McpFetchHandler;
 //#endregion
@@ -92,11 +106,11 @@ interface MountedMcpHttp {
   dispose: () => Promise<void>;
 }
 /**
- * Mount a stateless MCP endpoint on an h3 app at `path` — the h3 binding over
+ * Mount a stateless MCP endpoint on an h3 app at `path`: the h3 binding over
  * {@link createMcpFetchHandler}, which owns the per-request serving, the
  * origin gate, and the transport plumbing.
  *
- * The handler is web-standard — it takes the h3 event's web `Request` and
+ * The handler is web-standard: it takes the h3 event's web `Request` and
  * returns a web `Response` (an SSE `ReadableStream` body for a
  * `subscriptions/listen` stream). We copy that response onto `event.res` and
  * return its body rather than returning the `Response` object directly, so an

package/dist/adapters/mcp.mjs

@@ -1,11 +1,12 @@
-import { t as Diagnostic } from "../nostics-CzECRXpE.mjs";
-import { t as DEVFRAME_EVENTS } from "../events-4daw0uK9.mjs";
-import { i as isAllowedOrigin } from "../ws-server-Y_AumUQH.mjs";
-import { t as diagnostics } from "../diagnostics-BXWW3VK-.mjs";
-import { t as createHostContext } from "../context-omlma_1n.mjs";
-import { t as toAgentToolName } from "../agent-tool-name-EgfoFO8C.mjs";
-import process from "node:process";
+import { t as Diagnostic } from "../nostics-D0PvLZsn.mjs";
+import { t as DEVFRAME_EVENTS } from "../events-BV4Dj59a.mjs";
+import { t as isAllowedOrigin } from "../origin-DZit9g29.mjs";
+import { r as timingSafeEqual } from "../crypto-token-TVbGGFuj.mjs";
+import { t as diagnostics } from "../diagnostics-DZA6KQ_Z.mjs";
+import { t as createHostContext } from "../context-B29Oh0oA.mjs";
+import { t as toAgentToolName } from "../agent-tool-name-DGzeuWcO.mjs";
 import { join } from "pathe";
+import process from "node:process";
 import { homedir } from "node:os";
 import { defineHandler } from "h3";
 import { Server, createMcpHandler } from "@modelcontextprotocol/server";
@@ -65,7 +66,7 @@ function stringifyForMcp(value) {
 * Format a thrown value for an MCP `isError` text payload.
 *
 * A nostics `Diagnostic` (every coded devframe error) becomes structured
-* JSON — `{ error: { code, message, fix?, docs? } }` — so an agent receives
+* JSON (`{ error: { code, message, fix?, docs? } }`), so an agent receives
 * the actionable next step (`fix`) and the docs URL instead of a bare
 * message string. Other errors surface `Error.name`/`message`, plus one
 * level of `cause.message` so context isn't dropped silently.
@@ -93,7 +94,7 @@ const FALLBACK_OBJECT_SCHEMA = Object.freeze({
 *
 * Devframe stays validator-neutral, so conversion uses the schema's own
 * [Standard JSON Schema](https://standardschema.dev/) converter
-* (`~standard.jsonSchema`) when the validator provides one — zod 4 does,
+* (`~standard.jsonSchema`) when the validator provides one; zod 4 does,
 * for example. Validators without a native converter (e.g. valibot) degrade
 * to a permissive object schema rather than pulling in a converter library.
 */
@@ -116,7 +117,7 @@ function returnToJsonSchema(schema) {
 }
 /**
 * JSON Schema for an RPC function's positional args on the agent/MCP
-* surface. Each positional arg is advertised under `arg0` / `arg1` / … —
+* surface. Each positional arg is advertised under `arg0` / `arg1` / …,
 * matching how the agent bridge coerces the incoming object payload back
 * into positional arguments.
 *
@@ -152,7 +153,7 @@ function argsToJsonSchema(args) {
 //#region src/adapters/mcp/build-server.ts
 /**
 * Build a fresh MCP {@link Server} over a devframe context, registering its
-* tool and resource handlers. This is a pure factory — it sets up no
+* tool and resource handlers. This is a pure factory: it sets up no
 * long-lived subscriptions and holds no per-connection state, so it is safe
 * to call once per request under `createMcpHandler` or once per connection
 * under `serveStdio`. Change notifications are published separately: over
@@ -265,9 +266,9 @@ async function createMcpServer(definition, options = {}) {
 	} };
 }
 /**
-* Id of the built-in shared-state read tool — namespaced like every other
+* Id of the built-in shared-state read tool, namespaced like every other
 * built-in (`devframe:<area>:<fn>`). Tool-shaped access matters because many
-* MCP clients only consume tools — the parallel `devframe://state/<key>`
+* MCP clients only consume tools; the parallel `devframe://state/<key>`
 * resource projection stays for the clients that do read resources.
 */
 const READ_STATE_TOOL = "devframe:state:read";
@@ -310,8 +311,8 @@ function registerToolHandlers(server, ctx, exposeSharedState) {
 	const warnedCollisions = /* @__PURE__ */ new Set();
 	/**
 	* Resolve a wire tool name back to the registered {@link AgentTool}.
-	* Wire-name matching runs first, in manifest order — the same tool the
-	* list projection advertises under that name — with a raw-id fallback so
+	* Wire-name matching runs first, in manifest order (the same tool the
+	* list projection advertises under that name), with a raw-id fallback so
 	* a colon-namespaced id keeps working as a call name.
 	*/
 	const resolveTool = (name) => {
@@ -375,6 +376,7 @@ function registerToolHandlers(server, ctx, exposeSharedState) {
 	});
 }
 function registerResourceHandlers(server, ctx, exposeSharedState) {
+	const stateFilter = sharedStateFilter(exposeSharedState);
 	server.setRequestHandler("resources/list", async () => {
 		const resources = ctx.agent.list().resources.map((resource) => ({
 			uri: resource.uri,
@@ -382,17 +384,14 @@ function registerResourceHandlers(server, ctx, exposeSharedState) {
 			description: resource.description,
 			mimeType: resource.mimeType
 		}));
-		if (exposeSharedState !== false) {
-			const filter = typeof exposeSharedState === "function" ? exposeSharedState : () => true;
-			for (const key of ctx.rpc.sharedState.keys()) {
-				if (!filter(key)) continue;
-				resources.push({
-					uri: `devframe://state/${encodeURIComponent(key)}`,
-					name: key,
-					description: `Shared state: ${key}`,
-					mimeType: "application/json"
-				});
-			}
+		if (stateFilter) for (const key of ctx.rpc.sharedState.keys()) {
+			if (!stateFilter(key)) continue;
+			resources.push({
+				uri: `devframe://state/${encodeURIComponent(key)}`,
+				name: key,
+				description: `Shared state: ${key}`,
+				mimeType: "application/json"
+			});
 		}
 		return { resources };
 	});
@@ -407,17 +406,20 @@ function registerResourceHandlers(server, ctx, exposeSharedState) {
 				text: content.text ?? stringifyForMcp(content.json)
 			}] };
 		}
-		if (parsed.kind === "state") return { contents: [{
-			uri,
-			mimeType: "application/json",
-			text: stringifyForMcp((await ctx.rpc.sharedState.get(parsed.key)).value())
-		}] };
+		if (parsed.kind === "state") {
+			if (!stateFilter || !stateFilter(parsed.key)) throw diagnostics.DF0048({ key: parsed.key });
+			return { contents: [{
+				uri,
+				mimeType: "application/json",
+				text: stringifyForMcp((await ctx.rpc.sharedState.get(parsed.key)).value())
+			}] };
+		}
 		throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`);
 	});
 }
 /**
 * MCP constrains a tool's `outputSchema` to a JSON Schema of `type:
-* "object"` — clients (the SDK included) reject anything else. Non-object
+* "object"`; clients (the SDK included) reject anything else. Non-object
 * return schemas (e.g. a schema for `void` / a bare string) simply project
 * no output schema; the text content still carries the result.
 */
@@ -477,26 +479,56 @@ function parseResourceUri(uri) {
 //#endregion
 //#region src/adapters/mcp/fetch.ts
 /**
+* Parse exactly one `Authorization: Bearer <token>` credential, returning the
+* token or `undefined` for a missing, malformed, empty, or multi-credential
+* header. The token itself is never logged. `\S+` rejects the whitespace that
+* a second credential (fetch merges duplicate headers as `a, b`) or an empty
+* value would introduce.
+*/
+function parseBearerToken(header) {
+	if (!header) return void 0;
+	const match = /^Bearer (\S+)$/i.exec(header.trim());
+	return match ? match[1] : void 0;
+}
+/**
+* Resolve the identity gate for one request. `false` is the origin-only
+* opt-out; a callback delegates identity; a string requires a constant-time
+* bearer match. Never reveals whether a supplied token was close to correct.
+*/
+async function isAuthorized(req, authorization) {
+	if (authorization === false) return true;
+	if (typeof authorization === "function") return await authorization(req) === true;
+	const token = parseBearerToken(req.headers.get("authorization"));
+	if (token === void 0) return false;
+	return timingSafeEqual(token, authorization);
+}
+/**
 * Build a framework-agnostic MCP endpoint over a devframe context: a
-* web-standard `Request → Response` handler any host can mount — h3 (see
+* web-standard `Request → Response` handler any host can mount: h3 (see
 * `mountMcpHttp`), a Next.js App Router route, or any other fetch-shaped
 * server.
 *
 * The endpoint is **stateless**: it serves the 2026-07-28 revision per request
 * through the SDK's {@link createMcpHandler}, which builds a fresh MCP server
 * (from the shared, live `ctx` via `buildMcpServerFromContext`) for each
-* request — no `Mcp-Session-Id` registry, no session-local routing, no
+* request: no `Mcp-Session-Id` registry, no session-local routing, no
 * GET/DELETE teardown protocol. 2025-era clients are still served through the
 * SDK's default stateless legacy path. `list_changed` events reach modern
 * `subscriptions/listen` streams through the handler's `notify` bus.
 *
 * The origin gate guards every request: loopback-default DNS-rebinding
-* protection that — unlike the WS upgrade's `isAllowedOrigin` — also rejects
-* `Origin`-less requests, so a route-based endpoint isn't reachable by an
-* arbitrary local process.
+* protection that (unlike the WS upgrade's `isAllowedOrigin`) also rejects
+* `Origin`-less requests, so a route-based endpoint isn't reachable by a
+* browser or a remote host (a disallowed origin gets `403`). It trusts
+* same-machine callers by default. When that isn't your trust boundary, add
+* an optional identity gate ({@link CreateMcpFetchHandlerOptions.authorization}),
+* checked after the origin gate: a bearer/callback check that proves *who* is
+* calling (a missing/invalid credential gets `401` with a
+* `WWW-Authenticate: Bearer` challenge).
 */
 function createMcpFetchHandler(ctx, options) {
 	const allowedOrigins = options.allowedOrigins;
+	const authorization = options.authorization ?? false;
 	const handler = createMcpHandler(() => buildMcpServerFromContext(ctx, {
 		serverName: options.serverName,
 		serverVersion: options.serverVersion,
@@ -512,7 +544,11 @@ function createMcpFetchHandler(ctx, options) {
 	});
 	async function handle(req) {
 		const origin = req.headers.get("origin") ?? void 0;
-		if (allowedOrigins !== false && (origin === void 0 || !isAllowedOrigin(origin, allowedOrigins ?? []))) return new Response("Forbidden: origin required", { status: 403 });
+		if (allowedOrigins !== false && (origin === void 0 || !isAllowedOrigin(origin, allowedOrigins ?? []))) return new Response("Forbidden", { status: 403 });
+		if (!await isAuthorized(req, authorization)) return new Response("Unauthorized", {
+			status: 401,
+			headers: { "WWW-Authenticate": "Bearer" }
+		});
 		return handler.fetch(req);
 	}
 	return {
@@ -526,11 +562,11 @@ function createMcpFetchHandler(ctx, options) {
 //#endregion
 //#region src/adapters/mcp/http.ts
 /**
-* Mount a stateless MCP endpoint on an h3 app at `path` — the h3 binding over
+* Mount a stateless MCP endpoint on an h3 app at `path`: the h3 binding over
 * {@link createMcpFetchHandler}, which owns the per-request serving, the
 * origin gate, and the transport plumbing.
 *
-* The handler is web-standard — it takes the h3 event's web `Request` and
+* The handler is web-standard: it takes the h3 event's web `Request` and
 * returns a web `Response` (an SSE `ReadableStream` body for a
 * `subscriptions/listen` stream). We copy that response onto `event.res` and
 * return its body rather than returning the `Response` object directly, so an

package/dist/{agent-tool-name-EgfoFO8C.mjs → agent-tool-name-DGzeuWcO.mjs}

@@ -7,13 +7,13 @@ const MAX_TOOL_NAME_LENGTH = 128;
 /**
 * Derive the wire-safe agent tool name for an internal tool id.
 *
-* Devframe tool ids are colon-namespaced — `devframe:<area>:<fn>` for
+* Devframe tool ids are colon-namespaced: `devframe:<area>:<fn>` for
 * built-ins, `devframes:plugin:<slug>:<fn>` for plugin RPCs, and hub
 * command ids for command-derived tools. MCP clients constrain tool names
 * to `^[a-zA-Z0-9_-]{1,128}$`, so the agent/MCP boundary derives the wire
 * name automatically: every run of characters outside `[a-zA-Z0-9_-]`
 * becomes a single `_`, truncated to 128 characters. Internal ids never
-* change — resolution back to the id happens at the boundary.
+* change; resolution back to the id happens at the boundary.
 *
 * ```
 * devframe:state:read          → devframe_state_read

package/dist/cli/main.d.mts

@@ -1,6 +1,6 @@
 //#region src/cli/main.d.ts
 /**
- * The `devframe` bin — the framework's own CLI, distinct from the per-app
+ * The `devframe` bin is the framework's own CLI, distinct from the per-app
  * CLI shells authors build with `createCac(definition)`. It hosts the
  * app-independent commands; today that is `connect`, the MCP connector.
  */

package/dist/cli/main.mjs

@@ -1,18 +1,37 @@
-import { t as Diagnostic } from "../nostics-CzECRXpE.mjs";
-import { t as diagnostics } from "../diagnostics-BXWW3VK-.mjs";
-import { n as listLiveDevframeInstances, r as probeDevframeOrigin } from "../instance-registry-BjlMQbFB.mjs";
-import { t as toAgentToolName } from "../agent-tool-name-EgfoFO8C.mjs";
+import { t as Diagnostic } from "../nostics-D0PvLZsn.mjs";
+import { t as diagnostics } from "../diagnostics-DZA6KQ_Z.mjs";
+import { n as listLiveDevframeInstances, r as probeDevframeOrigin } from "../instance-registry-DCq762YJ.mjs";
+import { t as toAgentToolName } from "../agent-tool-name-DGzeuWcO.mjs";
 import process from "node:process";
 import { joinURL } from "ufo";
 import { cac } from "cac";
 //#region src/cli/connect.ts
+/**
+* Resolve the per-record bearer from the {@link ConnectServerOptions.authToken}
+* option. Exported for focused tests of the credential resolution.
+*/
+function resolveAuthToken(authToken, record) {
+	return typeof authToken === "function" ? authToken(record) : authToken;
+}
+/**
+* Build the request headers the connector sends to one instance's MCP route:
+* the instance's own (loopback) `origin` so the route's origin gate accepts
+* this native client, plus `Authorization: Bearer <token>` when a bearer is
+* configured. The bearer appears **only** here, never in the connection URL,
+* the registry records, or the indexed results. Exported for focused tests.
+*/
+function buildInstanceRequestHeaders(url, token) {
+	const headers = { origin: new URL(url).origin };
+	if (token) headers.authorization = `Bearer ${token}`;
+	return headers;
+}
 const INDEX_TOOL = toAgentToolName("devframe:connect:list-instances");
 const CALL_TOOL = toAgentToolName("devframe:connect:call-tool");
 const MCP_DISABLED_HINT = "This instance runs without an MCP route. Restart it with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.";
 const GATEWAY_TOOLS = [{
 	name: INDEX_TOOL,
 	title: "Discover running devframes",
-	description: "Discover every running devframe dev server on this machine and list each one's MCP tools. Call this FIRST, before assuming which devtools are available — the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
+	description: "Discover every running devframe dev server on this machine and list each one's MCP tools. Call this FIRST, before assuming which devtools are available; the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
 	inputSchema: {
 		type: "object",
 		properties: {}
@@ -48,12 +67,12 @@ const GATEWAY_TOOLS = [{
 /**
 * Start the devframe MCP connector on stdio: a thin discovery + proxy server
 * in the shape Vercel's next-devtools-mcp (https://github.com/vercel/next-devtools-mcp)
-* validated — credit due there for the architecture this connector follows.
-* It exposes two gateway tools —
+* validated; credit is due there for the architecture this connector follows.
+* It exposes two gateway tools:
 * `devframe_connect_list-instances` (discover running devframe instances via
 * the instance registry and list each one's MCP tools) and
 * `devframe_connect_call-tool` (invoke one tool on one instance over its
-* Streamable-HTTP endpoint) — and holds no domain knowledge of its own.
+* Streamable-HTTP endpoint), and holds no domain knowledge of its own.
 */
 async function startConnectServer(options = {}) {
 	const sdk = await importSdk();
@@ -128,7 +147,7 @@ async function index(sdk, options) {
 		try {
 			entry.mcp = {
 				url,
-				tools: await listInstanceTools(sdk, url)
+				tools: await listInstanceTools(sdk, url, resolveAuthToken(options.authToken, record))
 			};
 		} catch (error) {
 			entry.mcp = {
@@ -163,8 +182,8 @@ async function probePort(port, timeoutMs) {
 		startedAt: 0
 	};
 }
-async function listInstanceTools(sdk, url) {
-	return withInstanceClient(sdk, url, async (client) => {
+async function listInstanceTools(sdk, url, token) {
+	return withInstanceClient(sdk, url, token, async (client) => {
 		return (await client.listTools()).tools.map((tool) => ({
 			name: tool.name,
 			description: tool.description
@@ -180,7 +199,7 @@ async function call(sdk, options, args) {
 	const record = live.find((r) => r.port === args.port) ?? await probePort(args.port, options.timeoutMs);
 	if (!record) throw diagnostics.DF0050({ port: args.port });
 	if (!record.mcp) throw diagnostics.DF0051({ port: args.port });
-	return withInstanceClient(sdk, `${record.origin}${record.mcp.path}`, async (client) => {
+	return withInstanceClient(sdk, `${record.origin}${record.mcp.path}`, resolveAuthToken(options.authToken, record), async (client) => {
 		const result = await client.callTool({
 			name: args.tool,
 			arguments: args.args ?? {}
@@ -197,9 +216,8 @@ async function call(sdk, options, args) {
 		};
 	});
 }
-async function withInstanceClient(sdk, url, fn) {
-	const origin = new URL(url).origin;
-	const transport = new sdk.StreamableHTTPClientTransport(new URL(url), { requestInit: { headers: { origin } } });
+async function withInstanceClient(sdk, url, token, fn) {
+	const transport = new sdk.StreamableHTTPClientTransport(new URL(url), { requestInit: { headers: buildInstanceRequestHeaders(url, token) } });
 	const client = new sdk.Client({
 		name: "devframe-connect",
 		version: "0.0.0"
@@ -254,7 +272,7 @@ function keepAlive() {
 //#endregion
 //#region src/cli/main.ts
 /**
-* The `devframe` bin — the framework's own CLI, distinct from the per-app
+* The `devframe` bin is the framework's own CLI, distinct from the per-app
 * CLI shells authors build with `createCac(definition)`. It hosts the
 * app-independent commands; today that is `connect`, the MCP connector.
 */
@@ -264,7 +282,13 @@ async function runDevframeCli(argv = process.argv) {
 		await startConnectServer({
 			ports: parsePortsFlag(options.port),
 			instancesDir: options.instancesDir,
-			timeoutMs: options.timeout
+			timeoutMs: options.timeout,
+			/**
+			* The bearer for authenticated instance MCP routes comes from the
+			* environment, never a CLI flag: command-line arguments are visible to
+			* any process on the machine (`ps`, `/proc`), which would defeat it.
+			*/
+			authToken: process.env.DEVFRAME_MCP_AUTH_TOKEN
 		});
 		keepAlive();
 	});