devframe 0.8.0 → 0.8.2

package/dist/{ws-server-D_Vjtums.d.mts → ws-server-uKQcClcJ.d.mts}

@@ -4,6 +4,7 @@ import { BirpcGroup, ChannelOptions } from "birpc";
 import { NodeAdapter } from "crossws/adapters/node";
 import { Server } from "node:http";
 import { Server as Server$1, ServerOptions } from "node:https";
+import { AddressInfo } from "node:net";
 //#region src/rpc/transports/ws-server.d.ts
 interface DevframeNodeRpcSessionMeta {
   id: number;
@@ -34,9 +35,12 @@ interface WsRpcTransportOptions {
    * this transport detaches the upgrade listener without closing the server.
    */
   server?: Server | Server$1;
-  /** Port for a newly-created standalone WS server. */
+  /**
+   * Port for the standalone WebSocket server. Defaults to `0`, which lets the
+   * operating system assign an available port.
+   */
   port?: number;
-  /** Host for a newly-created standalone WS server. Defaults to `localhost`. */
+  /** Host for the standalone WebSocket server. Defaults to `localhost`. */
   host?: string;
   /**
    * Restrict the WS endpoint to a single upgrade route (e.g. `/__devframe_ws`). When
@@ -62,7 +66,7 @@ interface WsRpcTransportOptions {
    * Pass `false` to disable origin checking entirely (not recommended).
    * Default: loopback-only.
    */
-  allowedOrigins?: readonly string[] | false;
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
   /**
    * RPC function definitions, used by the per-call wire serializer to
    * dispatch between strict-JSON and structured-clone encoding based
@@ -79,12 +83,37 @@ interface WsRpcTransportOptions {
   /** Override the default per-call deserializer. Most callers should leave this unset. */
   deserialize?: ChannelOptions['deserialize'];
 }
+interface CreateWsOriginRegistryOptions {
+  /** Origins allowed before any external viewers are registered. */
+  allowedOrigins?: readonly string[];
+  /** Additional validation to run after the registration token is verified. */
+  validateOrigin?: (origin: string) => boolean;
+}
+interface WsOriginRegistry {
+  /** Registration token to include in connection metadata. */
+  readonly token: string;
+  /** Read and register an origin from a connection bootstrap URL. */
+  registerFromUrl: (url: string) => string | undefined;
+  /** Check whether an origin is currently allowed. */
+  isAllowed: (origin: string | undefined) => boolean;
+}
+/**
+ * Create a live, token-protected origin allowlist for external browser
+ * viewers. Pass it to {@link WsRpcTransportOptions.allowedOrigins}, then use
+ * `registerFromUrl()` in the connection metadata handler to authorize a
+ * viewer without sharing a mutable array or disabling DNS-rebinding protection.
+ */
+declare function createWsOriginRegistry(options?: CreateWsOriginRegistryOptions): WsOriginRegistry;
 interface WsRpcTransport {
   /**
    * The crossws node adapter driving the socket — exposes the connected
    * `peers` and pub/sub. See https://crossws.h3.dev.
    */
   ws: NodeAdapter;
+  /** Resolves when the transport-owned server is listening. */
+  ready: Promise<void>;
+  /** Returns the bound address, or `null` when the server is not listening. */
+  address: () => AddressInfo | string | null;
   /** Remove the upgrade listener from a shared `server` (a no-op otherwise). */
   detach: () => void;
   /**
@@ -109,10 +138,10 @@ declare function isAllowedOrigin(origin: string | undefined, allowedOrigins: rea
  * `server` (sharing its port, optionally scoped to a `path`), or let this
  * helper create a standalone server from `port` / `host` / `https`.
  *
- * Returns the crossws node adapter plus `detach` (remove the upgrade
- * listener from a shared `server`) and `close` (full deterministic
- * teardown).
+ * Returns the crossws node adapter, standalone-server readiness/address
+ * accessors, `detach` (remove the upgrade listener from a shared `server`),
+ * and `close` (full deterministic teardown).
  */
 declare function attachWsRpcTransport<ClientFunctions extends object, ServerFunctions extends object>(rpcGroup: BirpcGroup<ClientFunctions, ServerFunctions, false>, options?: WsRpcTransportOptions): WsRpcTransport;
 //#endregion
-export { isAllowedOrigin as a, attachWsRpcTransport as i, WsRpcTransport as n, isLoopbackHostname as o, WsRpcTransportOptions as r, DevframeNodeRpcSessionMeta as t };
+export { WsRpcTransportOptions as a, isAllowedOrigin as c, WsRpcTransport as i, isLoopbackHostname as l, DevframeNodeRpcSessionMeta as n, attachWsRpcTransport as o, WsOriginRegistry as r, createWsOriginRegistry as s, CreateWsOriginRegistryOptions as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Framework for building generic devframes",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -115,7 +115,7 @@
     "ua-parser-modern": "^0.1.1",
     "valibot": "^1.4.2",
     "whenexpr": "^0.1.2",
-    "ws": "^8.21.1"
+    "ws": "^8.21.2"
   },
   "scripts": {
     "build": "tsdown",

package/skills/devframe/SKILL.md

@@ -569,10 +569,11 @@ RPC handlers run with the full privileges of the host process, so the boundary t
 - **`auth` defaults to `true`** — dev-mode connections must authenticate before calls are accepted. Devframe ships the node primitives (`exchangeTempAuthCode`, `verifyAuthToken` in `devframe/node/auth`); the host adapter (e.g. Vite DevTools) provides the interactive `devframe:anonymous:auth` + `devframe:auth:exchange` handlers and auth UI.
 - **`auth: false` trusts every reachable connection.** Use it only for single-user `localhost` tools. Never combine it with a non-loopback bind host, a tunnel, or a shared/CI environment. The default bind host is already `localhost`.
 - **Authentication** exchanges a 6-digit one-time code (shown in the developer's terminal) for a node-issued bearer token via `requestTrustWithCode(code)`. The code is single-use, expires in 5 min, compared in constant time, and rotates after repeated failures — show it only in the terminal, never over the network.
-- **Magic-link (optional):** print `buildOtpAuthUrl(origin)` — `<origin>/?devframe_otp=<code>`. `connectDevframe` reads the code, exchanges it, and strips it from the URL. Integrations can opt out (`otpParam: false`) and drive it via the exposed `authenticateWithUrlOtp(rpc)` / `consumeOtpFromUrl()` client utilities. Only the single-use code rides the URL, never the bearer; treat the printed link like the code itself. The standalone CLI's `--open` does this automatically via `DevframeAuthHandler.buildOpenUrl` — the launched tab already carries the OTP, no prompt needed.
+- **Magic-link (optional):** print `buildOtpAuthUrl(origin)` — `<origin>/#devframe_otp=<code>`. The code rides the URL **fragment**, which the browser never sends to the server, so it stays out of access logs and `Referer`. `connectDevframe` reads the code, exchanges it, and strips it from the URL. Integrations can opt out (`otpParam: false`) and drive it via the exposed `authenticateWithUrlOtp(rpc)` / `consumeOtpFromUrl()` client utilities. Only the single-use code rides the URL, never the bearer; treat the printed link like the code itself. The standalone CLI's `--open` does this automatically via `DevframeAuthHandler.buildOpenUrl` — the launched tab already carries the OTP, no prompt needed.
 - **Tokens are secrets.** The bearer token rides the WS URL (`?devframe_auth_token=…`) — serve over `wss://`/`https://` beyond loopback. Never log the token or code, never bake them into build output. Revoke via `revokeAuthToken(...)`; clients drop to untrusted on `devframe:auth:revoked`.
 - **Authorize handlers.** Any trusted client can call any registered function — validate inputs, and mark state-changing functions `type: 'destructive'` so MCP/agent clients prompt first.
-- **Origin-lock remote docks** (`originLock`) so a dock token is honored only from its expected origin.
+- **Origin-lock remote docks** (`originLock`, on by default) so a dock's session token is honored only on a connection whose `Origin` matches the dock — the connect-time gate enforces it.
+- **The MCP route requires an Origin.** The route-based MCP server (`cli.mcp`, `viteDevBridge`/Next handler `mcp`, `createMcpFetchHandler`) rejects `Origin`-less requests — a request must carry a loopback (or allow-listed) `Origin`, so it isn't reachable by an arbitrary local process. `devframe connect` sends each instance's own loopback origin automatically.
 
 See [Security](https://devfra.me/security) for the full reference.