devframe 0.9.8 → 0.9.9

package/dist/{_shared-BM3PdYli.mjs → _shared-C08SdQRl.mjs}

@@ -36,12 +36,23 @@ async function resolveDevServerPort(def, options = {}) {
 	return getPort(portOptions);
 }
 /**
-* Normalize the `cli.mcp` / `mcp` option (`boolean | McpRouteOptions`) into
-* concrete options, or `undefined` when the MCP route is disabled.
+* Normalize the `mcp` option (`boolean | McpRouteOptions`) into a
+* fully-resolved config, or `undefined` when the MCP route is disabled.
+*
+* An enabled route trusts same-machine callers by default: the authorization
+* resolves to origin-only (`false`) unless the object config opts into a
+* bearer/callback identity check. An empty-string bearer is treated as no
+* bearer (origin-only) rather than a usable credential.
 */
 function resolveMcpConfig(mcp) {
 	if (!mcp) return void 0;
-	return mcp === true ? {} : mcp;
+	if (mcp === true) return { authorization: false };
+	const authorization = typeof mcp.authorization === "string" && mcp.authorization.length === 0 ? false : mcp.authorization ?? false;
+	return {
+		...mcp.path !== void 0 ? { path: mcp.path } : {},
+		...mcp.allowedOrigins !== void 0 ? { allowedOrigins: mcp.allowedOrigins } : {},
+		authorization
+	};
 }
 /**
 * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
@@ -65,4 +76,4 @@ function resolveMcpConnectionMeta(def, mcp, port) {
 	} : { path: route };
 }
 //#endregion
-export { resolveMcpConnectionMeta as i, resolveBasePath as n, resolveDevServerPort as r, normalizeBasePath as t };
+export { resolveMcpConnectionMeta as a, resolveMcpConfig as i, resolveBasePath as n, resolveDevServerPort as r, normalizeBasePath as t };

package/dist/{_shared-mtXpcJIv.d.mts → _shared-CK3czkH4.d.mts}

@@ -1,4 +1,4 @@
-import { F as DevframeDefinition, G as McpRouteOptions, I as DevframeDeploymentKind, t as ConnectionMeta } from "./context-CLF4-8Pp.mjs";
+import { F as DevframeDefinition, G as McpAuthorization, I as DevframeDeploymentKind, K as McpRouteOptions, t as ConnectionMeta } from "./context-4AIVRLYF.mjs";
 //#region src/adapters/_shared.d.ts
 /**
  * Resolve the mount base path for a devframe's SPA. Hosted adapters
@@ -24,6 +24,29 @@ interface ResolveDevServerPortOptions {
  * before starting the server.
  */
 declare function resolveDevServerPort(def: DevframeDefinition, options?: ResolveDevServerPortOptions): Promise<number>;
+/**
+ * A fully-resolved MCP route configuration: the concrete authorization policy
+ * (never the `mcp: true` shorthand), plus the optional route path and origin
+ * allow-list. Every route mount consumes this shape.
+ */
+interface ResolvedMcpConfig {
+  /** Route segment, relative to the base. Default resolved by the caller. */
+  path?: string;
+  /** Origin allow-list, or `false` to disable the origin gate. */
+  allowedOrigins?: readonly string[] | false;
+  /** The resolved identity policy: a bearer token, callback, or `false`. */
+  authorization: McpAuthorization;
+}
+/**
+ * Normalize the `mcp` option (`boolean | McpRouteOptions`) into a
+ * fully-resolved config, or `undefined` when the MCP route is disabled.
+ *
+ * An enabled route trusts same-machine callers by default: the authorization
+ * resolves to origin-only (`false`) unless the object config opts into a
+ * bearer/callback identity check. An empty-string bearer is treated as no
+ * bearer (origin-only) rather than a usable credential.
+ */
+declare function resolveMcpConfig(mcp: boolean | McpRouteOptions | undefined): ResolvedMcpConfig | undefined;
 /**
  * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
  * server started with the given `mcp` option (falling back to `def.cli?.mcp`,
@@ -38,4 +61,4 @@ declare function resolveDevServerPort(def: DevframeDefinition, options?: Resolve
  */
 declare function resolveMcpConnectionMeta(def: DevframeDefinition, mcp: boolean | McpRouteOptions | undefined, port?: number): ConnectionMeta['mcp'];
 //#endregion
-export { resolveMcpConnectionMeta as a, resolveDevServerPort as i, normalizeBasePath as n, resolveBasePath as r, ResolveDevServerPortOptions as t };
+export { resolveDevServerPort as a, resolveBasePath as i, ResolvedMcpConfig as n, resolveMcpConfig as o, normalizeBasePath as r, resolveMcpConnectionMeta as s, ResolveDevServerPortOptions as t };

package/dist/adapters/build.d.mts

@@ -1,14 +1,14 @@
-import { F as DevframeDefinition, V as DevframeSnapshotRpcEntry, o as DevframeNodeContext } from "../context-CLF4-8Pp.mjs";
-import { o as StaticAssetsSource } from "../remote-assets-B13_vRkJ.mjs";
+import { F as DevframeDefinition, V as DevframeSnapshotRpcEntry, o as DevframeNodeContext } from "../context-4AIVRLYF.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-eBvSKZMS.mjs";
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {
   /** Output directory. Defaults to `dist-static`. */
   outDir?: string;
   /**
-   * Override the SPA dist to copy into `outDir` — a local directory or a
+   * Override the SPA dist to copy into `outDir`: a local directory or a
    * remote-assets declaration (materialized in full at build time). When
    * omitted the adapter reads `devframe.clientAssets` (or the deprecated
-   * `devframe.cli?.distDir`) — authors typically set this once on the
+   * `devframe.cli?.distDir`); authors typically set this once on the
    * definition itself.
    */
   distDir?: StaticAssetsSource;
@@ -21,7 +21,7 @@ interface CreateBuildOptions {
   /**
    * Proceed even when the definition declares `capabilities.build: false`.
    * `createCac` already skips registering the `build` subcommand for such
-   * a definition — this only matters for a caller invoking `createBuild`
+   * a definition; this only matters for a caller invoking `createBuild`
    * directly, bypassing the CLI.
    */
   force?: boolean;
@@ -34,7 +34,7 @@ interface CreateBuildOptions {
  *   - Write `<outDir>/__connection.json` (`{ backend: 'static' }`) and the
  *     sharded RPC dump under `<outDir>/__rpc-dump/` so the deployed SPA
  *     discovers both via relative paths from `document.baseURI`. The
- *     output is mount-path agnostic — the same bundle works at `/`,
+ *     output is mount-path agnostic, so the same bundle works at `/`,
  *     `/devframe/`, or any base, no rewriting required.
  */
 declare function createBuild(d: DevframeDefinition, options?: CreateBuildOptions): Promise<void>;

package/dist/adapters/build.mjs

@@ -1,13 +1,13 @@
-import { s as colors } from "../nostics-CzECRXpE.mjs";
-import { n as strictJsonStringify } from "../serialization-BGzEwAdr.mjs";
-import { t as resolveClientAssets } from "../client-assets-C7SXgTWY.mjs";
+import { s as colors } from "../nostics-D0PvLZsn.mjs";
+import { n as strictJsonStringify } from "../serialization-DTZnPQ1-.mjs";
+import { t as resolveClientAssets } from "../client-assets-DNdhagGm.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
-import { t as collectStaticRpcDump } from "../static-DV_qUSRS.mjs";
+import { t as collectStaticRpcDump } from "../static-DZ8P2Kn7.mjs";
 import { n as structuredCloneStringify } from "../structured-clone-CbAV5rFI.mjs";
-import { t as diagnostics } from "../diagnostics-BXWW3VK-.mjs";
-import { t as createHostContext } from "../context-omlma_1n.mjs";
-import { t as resolveStaticAssetsSource } from "../remote-assets-DezQmPQU.mjs";
-import { t as createH3DevframeHost } from "../host-h3-fRbF9yor.mjs";
+import { t as diagnostics } from "../diagnostics-BMfN8mb1.mjs";
+import { t as createHostContext } from "../context-CwPUinjn.mjs";
+import { t as resolveStaticAssetsSource } from "../remote-assets-BIFWOlBW.mjs";
+import { t as createH3DevframeHost } from "../host-h3-BJ4siyz7.mjs";
 import process from "node:process";
 import { dirname, resolve } from "pathe";
 import { existsSync } from "node:fs";
@@ -21,7 +21,7 @@ import fs$1 from "node:fs/promises";
 *   - Write `<outDir>/__connection.json` (`{ backend: 'static' }`) and the
 *     sharded RPC dump under `<outDir>/__rpc-dump/` so the deployed SPA
 *     discovers both via relative paths from `document.baseURI`. The
-*     output is mount-path agnostic — the same bundle works at `/`,
+*     output is mount-path agnostic, so the same bundle works at `/`,
 *     `/devframe/`, or any base, no rewriting required.
 */
 async function createBuild(d, options = {}) {
@@ -35,14 +35,7 @@ async function createBuild(d, options = {}) {
 		origin: "http://localhost",
 		appName: d.id
 	});
-	const resolved = resolveStaticAssetsSource(distSource, host.getStorageDir("project"), d.importMetaUrl);
-	if (typeof resolved === "string") {
-		console.log(colors.cyan`[devframe] copying SPA from ${resolved} -> ${outDir}`);
-		await fs$1.cp(resolved, outDir, { recursive: true });
-	} else {
-		console.log(colors.cyan`[devframe] materializing SPA from ${resolved.assets.package}@${resolved.assets.version} -> ${outDir}`);
-		await resolved.materialize(outDir);
-	}
+	await materializeSpa(resolveStaticAssetsSource(distSource, host.getStorageDir("project"), d.importMetaUrl), outDir);
 	const ctx = await createHostContext({
 		cwd: process.cwd(),
 		mode: "build",
@@ -54,23 +47,40 @@ async function createBuild(d, options = {}) {
 	await d.setup(ctx);
 	applySnapshotRpc(ctx, d.rpc?.snapshot);
 	await fs$1.mkdir(resolve(outDir, DEVFRAME_RPC_DUMP_DIRNAME), { recursive: true });
+	await writeConnectionMeta(ctx, outDir);
+	console.log(colors.cyan`[devframe] writing RPC dump to ${resolve(outDir, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME)}`);
+	const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx);
+	await writeDumpFiles(dump, outDir, options.pretty ? 2 : void 0);
+	await fs$1.writeFile(resolve(outDir, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME), JSON.stringify(dump.manifest, null, 2), "utf-8");
+	console.log(colors.green`[devframe] built "${d.id}" -> ${outDir}`);
+}
+/** Copy a local SPA dist, or materialize a remote assets source, into `outDir`. */
+async function materializeSpa(resolved, outDir) {
+	if (typeof resolved === "string") {
+		console.log(colors.cyan`[devframe] copying SPA from ${resolved} -> ${outDir}`);
+		await fs$1.cp(resolved, outDir, { recursive: true });
+		return;
+	}
+	console.log(colors.cyan`[devframe] materializing SPA from ${resolved.assets.package}@${resolved.assets.version} -> ${outDir}`);
+	await resolved.materialize(outDir);
+}
+/** Write `__connection.json` with the JSON-serializable method allow-list. */
+async function writeConnectionMeta(ctx, outDir) {
 	const jsonSerializableMethods = [];
 	for (const def of ctx.rpc.definitions.values()) if (def.jsonSerializable === true) jsonSerializableMethods.push(def.name);
 	await fs$1.writeFile(resolve(outDir, DEVFRAME_CONNECTION_META_FILENAME), JSON.stringify({
 		backend: "static",
 		jsonSerializableMethods
 	}, null, 2), "utf-8");
-	console.log(colors.cyan`[devframe] writing RPC dump to ${resolve(outDir, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME)}`);
-	const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx);
-	const indent = options.pretty ? 2 : void 0;
+}
+/** Encode and write each sharded RPC dump file under `outDir`. */
+async function writeDumpFiles(dump, outDir, indent) {
 	for (const [filepath, file] of Object.entries(dump.files)) {
 		const fullpath = resolve(outDir, filepath);
 		await fs$1.mkdir(dirname(fullpath), { recursive: true });
 		const text = file.serialization === "structured-clone" ? structuredCloneStringify(file.data) : strictJsonStringify(file.data, file.fnName);
 		await fs$1.writeFile(fullpath, file.serialization === "json" && indent != null ? JSON.stringify(JSON.parse(text), null, indent) : text, "utf-8");
 	}
-	await fs$1.writeFile(resolve(outDir, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME), JSON.stringify(dump.manifest, null, 2), "utf-8");
-	console.log(colors.green`[devframe] built "${d.id}" -> ${outDir}`);
 }
 /**
 * Attach a `dump` to each {@link DevframeRpcOptions.snapshot} target so the

package/dist/adapters/cac.d.mts

@@ -1,10 +1,25 @@
-import { Dt as parseCliFlags, Et as defineCliFlags, F as DevframeDefinition, Tt as InferCliFlags, wt as CliFlagsSchema } from "../context-CLF4-8Pp.mjs";
+import { Dt as defineCliFlags, Et as InferCliFlags, F as DevframeDefinition, K as McpRouteOptions, Ot as parseCliFlags, Tt as CliFlagsSchema } from "../context-4AIVRLYF.mjs";
 import { CAC } from "cac";
 import { H3 } from "h3";
 //#region src/adapters/cac.d.ts
 interface CreateCacOptions {
   /** Default port for `dev` (default: 9999). */
   defaultPort?: number;
+  /**
+   * Expose a route-based MCP server alongside the dev server, speaking the
+   * MCP Streamable-HTTP transport at `<base>__mcp`. Whether to expose MCP is
+   * a hosting decision made at the CLI assembly stage, so it lives here rather
+   * than on the definition.
+   *
+   * - `false` / omitted (default): no MCP route is mounted.
+   * - `true`: mount at the default `__mcp` route with the loopback origin gate.
+   * - {@link McpRouteOptions}: customise the route path, origin allow-list, and
+   *   opt into an identity check.
+   *
+   * The `--mcp` / `--no-mcp` flags override this per run. Falls back to the
+   * definition's deprecated `cli.mcp` when unset.
+   */
+  mcp?: boolean | McpRouteOptions;
   /**
    * Final CAC hook invoked after devframe's built-in subcommands and
    * after the definition's `cli.configure`. Use this to add app-level

package/dist/adapters/cac.mjs

@@ -1,13 +1,13 @@
-import { s as colors } from "../nostics-CzECRXpE.mjs";
-import { r as resolveDevServerPort } from "../_shared-BM3PdYli.mjs";
-import { a as importRuntimeModule } from "../instance-shell-CpVW4zG0.mjs";
+import { s as colors } from "../nostics-D0PvLZsn.mjs";
+import { r as resolveDevServerPort } from "../_shared-C08SdQRl.mjs";
+import { a as importRuntimeModule } from "../instance-shell-cdVETpfz.mjs";
 import { createBuild } from "./build.mjs";
-import { t as createDevServer } from "../dev-CzkPCJwi.mjs";
+import { t as createDevServer } from "../dev-Eqq5PX0k.mjs";
 import process from "node:process";
 import cac$1 from "cac";
 //#region src/adapters/flags.ts
 /**
-* Identity helper that preserves the literal schema-map type — use this
+* Identity helper that preserves the literal schema-map type; use this
 * so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
 *
 * ```ts
@@ -110,7 +110,7 @@ function createCac(d, options = {}) {
 			host,
 			defaultPort
 		});
-		const mcp = flags.mcp;
+		const mcp = flags.mcp ?? options.mcp;
 		await createDevServer(d, {
 			host,
 			port,
@@ -129,6 +129,7 @@ function createCac(d, options = {}) {
 		const { createMcpServer } = await importRuntimeModule("devframe/adapters/mcp");
 		await createMcpServer(d, {
 			transport: "stdio",
+			/** Deliberately go to stderr: stdout is the MCP transport. */
 			onReady: ({ transport }) => {
 				console.error(`[devframe] "${d.id}" MCP server ready (${transport})`);
 			}
@@ -150,7 +151,7 @@ function resolveTypedFlags(d, raw) {
 	if (!d.cli?.flags) return raw;
 	const { flags, issues } = parseCliFlags(d.cli.flags, raw);
 	if (issues?.length) {
-		for (const issue of issues) console.error(colors.red`[devframe] invalid flag — ${issue}`);
+		for (const issue of issues) console.error(colors.red`[devframe] invalid flag: ${issue}`);
 		process.exit(1);
 	}
 	return flags;

package/dist/adapters/dev.d.mts

@@ -1,8 +1,8 @@
-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, s as DevframeNodeRpcSession } from "../context-CLF4-8Pp.mjs";
-import { o as StaticAssetsSource } from "../remote-assets-B13_vRkJ.mjs";
-import { c as StartedServer } from "../instance-shell-Tcp5hGoq.mjs";
-import { a as resolveMcpConnectionMeta, i as resolveDevServerPort, t as ResolveDevServerPortOptions } from "../_shared-mtXpcJIv.mjs";
+import { c as DevframeNodeRpcSessionMeta, l as DevframeRpcConnection, n as WsOriginRegistry } from "../ws-server-D2nv68Hg.mjs";
+import { F as DevframeDefinition, K as McpRouteOptions, U as DevframeSseOptions, W as DevframeWsOptions, s as DevframeNodeRpcSession, wt as DevframeAuthHandler } from "../context-4AIVRLYF.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-eBvSKZMS.mjs";
+import { c as StartedServer } from "../instance-shell-7Z52PE4_.mjs";
+import { a as resolveDevServerPort, s as resolveMcpConnectionMeta, t as ResolveDevServerPortOptions } from "../_shared-CK3czkH4.mjs";
 import { H3 } from "h3";
 //#region src/adapters/dev.d.ts
 interface CreateDevServerOptions {
@@ -23,7 +23,7 @@ interface CreateDevServerOptions {
   /**
    * Override the definition's `clientAssets` (or deprecated `cli.distDir`).
    * When neither this option nor the definition's client assets are set, the
-   * dev server runs in **bridge mode** — only `__connection.json` and the WS
+   * dev server runs in **bridge mode**: only `__connection.json` and the WS
    * endpoint are mounted; the SPA is expected to be hosted elsewhere (e.g. by
    * a parent Vite/Nuxt dev server via `devframeViteBridge` from
    * `@devframes/vite`).
@@ -37,7 +37,7 @@ interface CreateDevServerOptions {
   /**
    * Override how the browser reaches the RPC WebSocket (`def.cli?.ws`).
    * See {@link DevframeWsOptions}: same-server route (default), a dedicated
-   * port, or a remote origin. Pass `false` to serve no WebSocket at all —
+   * port, or a remote origin. Pass `false` to serve no WebSocket at all;
    * clients connect over the SSE endpoint instead (`backend: 'sse'`).
    */
   ws?: DevframeWsOptions | false;
@@ -49,7 +49,7 @@ interface CreateDevServerOptions {
    */
   allowedOrigins?: readonly string[] | WsOriginRegistry | false;
   /**
-   * Override the SSE RPC endpoint control (`def.cli?.sse`) — enabled by
+   * Override the SSE RPC endpoint control (`def.cli?.sse`), enabled by
    * default at `<base>__sse`. Pass `false` to disable, or a
    * {@link DevframeSseOptions} to rename the route.
    */
@@ -71,7 +71,7 @@ interface CreateDevServerOptions {
   /**
    * Override how authentication resolves, taking precedence over
    * `def.cli?.auth`. Pass `false` to skip the gate entirely (the standard
-   * choice for a **hosted** deployment where the host manages auth — see
+   * choice for a **hosted** deployment where the host manages auth; see
    * {@link devframeViteBridge} from `@devframes/vite`); a {@link DevframeAuthHandler} to install a custom
    * scheme; or `true` to force devframe's interactive OTP gate on. When
    * omitted, auth resolves from `flags.auth` / `def.cli?.auth` (the standalone
@@ -99,7 +99,7 @@ interface CreateDevServerOptions {
   onPeerDisconnect?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
   /**
    * Called once the WS server is bound. Devframe stays headless
-   * otherwise — wire this if you want a startup banner.
+   * otherwise, so wire this if you want a startup banner.
    */
   onReady?: (info: {
     origin: string;
@@ -108,20 +108,20 @@ interface CreateDevServerOptions {
   }) => void | Promise<void>;
   /**
    * Proceed even when the definition declares `capabilities.dev: false`.
-   * `createDevServer` otherwise refuses such a definition (`DF0058`) — this
+   * `createDevServer` otherwise refuses such a definition (`DF0058`); this
    * only matters for a caller invoking it directly, bypassing the CLI.
    */
   force?: boolean;
 }
 /**
- * Start a devframe dev server for a {@link DevframeDefinition} —
+ * Start a devframe dev server for a {@link DevframeDefinition}:
  * h3 + WebSocket RPC + (optionally) the author's SPA mounted at the
  * resolved base path.
  *
  * When `distDir` is omitted (and the definition's client assets are unset) the
  * server runs in **bridge mode**: only `__connection.json` and the WS
  * endpoint are mounted, with no SPA mount. The SPA is expected to be
- * hosted elsewhere (e.g. by a parent Vite/Nuxt dev server) — see
+ * hosted elsewhere (e.g. by a parent Vite/Nuxt dev server); see
  * `devframeViteBridge` from `@devframes/vite`.
  *
  * Returns the underlying {@link StartedServer} handle so callers can

package/dist/adapters/dev.mjs

@@ -1,3 +1,3 @@
-import { i as resolveMcpConnectionMeta, r as resolveDevServerPort } from "../_shared-BM3PdYli.mjs";
-import { t as createDevServer } from "../dev-CzkPCJwi.mjs";
+import { a as resolveMcpConnectionMeta, r as resolveDevServerPort } from "../_shared-C08SdQRl.mjs";
+import { t as createDevServer } from "../dev-Eqq5PX0k.mjs";
 export { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/embedded.d.mts

@@ -1,4 +1,4 @@
-import { F as DevframeDefinition, o as DevframeNodeContext } from "../context-CLF4-8Pp.mjs";
+import { F as DevframeDefinition, o as DevframeNodeContext } from "../context-4AIVRLYF.mjs";
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {
   /** Target context the devframe is registered into. Required. */

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, K as McpRouteOptions, U as DevframeSseOptions, W as DevframeWsOptions, o as DevframeNodeContext, s as DevframeNodeRpcSession, t as ConnectionMeta, wt as DevframeAuthHandler, xt as DevframeStorageScope } from "../context-4AIVRLYF.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-eBvSKZMS.mjs";
+import { c as StartedServer, f as DevframeInstanceRecord } from "../instance-shell-7Z52PE4_.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,7 +67,7 @@ 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;
   /**
@@ -78,10 +78,12 @@ interface InitDevframeOptions {
   mcp?: boolean | McpRouteOptions;
   /**
    * 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 +106,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 +140,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 +160,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 +177,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 +206,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 +214,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-Eqq5PX0k.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-4AIVRLYF.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