docs(auth): security guide + preserve URL-query token auth

Persist a token supplied to `connectDevframe({ authToken })` so a host that
bootstraps trust from its own page-URL query survives reconnects, matching the
previous always-persist behaviour. The transport still forwards the token via
the `?devframe_auth_token=` WS query param; add a test locking that in.

Add a "Security" guide page and a SKILL section covering the trust model and
secure-by-default practices for tools built on devframe: keep `auth` on,
restrict `auth: false` to single-user localhost, treat tokens as secrets,
serve over wss beyond loopback, authorize handlers, and origin-lock remote
docks.

Author: antfubot

docs/.vitepress/config.ts

@@ -27,6 +27,7 @@ function guideItems(prefix: string): DefaultTheme.NavItemWithLink[] {
     { text: 'When Clauses', link: `${prefix}/guide/when-clauses` },
     { text: 'Structured Diagnostics', link: `${prefix}/guide/diagnostics` },
     { text: 'Client', link: `${prefix}/guide/client` },
+    { text: 'Security', link: `${prefix}/guide/security` },
     { text: 'Standalone CLI', link: `${prefix}/guide/standalone-cli` },
     { text: 'Hub (multi-tool)', link: `${prefix}/guide/hub` },
     { text: 'Agent-Native (experimental)', link: `${prefix}/guide/agent-native` },

docs/guide/security.md

@@ -0,0 +1,41 @@
+---
+outline: deep
+---
+
+# Security
+
+Devframe tools are secure by default: connections bind to `localhost`, and dev-mode RPC requires a trust handshake before a browser is accepted. This page covers the trust model and the practices that keep a tool safe as it moves beyond a single developer's machine.
+
+## Trust model
+
+An RPC handler runs with the full privileges of the process hosting it — filesystem, child processes, network. A trusted connection can call any registered function, so the boundary that matters is *who is allowed to connect*.
+
+Two postures cover that boundary:
+
+- **Authenticated (default).** `auth` defaults to `true`. The browser pairs with the server before calls are accepted, and reconnects by presenting a node-issued bearer token. Devframe supplies the node-side primitives (`exchangeTempAuthCode`, `verifyAuthToken`); the host adapter — e.g. Vite DevTools — provides the interactive handler and pairing UI.
+- **Unauthenticated opt-out.** Setting `auth: false` starts the server with an auto-trust handshake. It exists for single-user tools talking to their own `localhost`, where a round-trip would only add friction.
+
+> [!WARNING]
+> `auth: false` trusts every connection that can reach the port. Only use it when the surface is reachable solely by the local developer. Never combine it with a non-loopback bind host, a tunnelled port, or a shared/CI environment.
+
+## Pairing and tokens
+
+Pairing exchanges a short code for a long token:
+
+1. The dev server shows a 6-digit one-time code in the developer's terminal.
+2. The developer types it into the browser, which calls `requestTrustWithCode(code)`.
+3. The server verifies the code, mints a high-entropy bearer token, records it as trusted, and returns it.
+4. The browser persists the token and presents it on reconnect; sibling tabs receive it over the `devframe-auth` channel.
+
+The 6-digit code is single-use, expires after five minutes, is compared in constant time, and rotates after repeated wrong attempts — which is what keeps a short code brute-force resistant. Show it only in a trusted channel (the terminal), never over the network.
+
+The bearer token is a secret. It travels to the server on the WebSocket URL (`?devframe_auth_token=…`), so serve over `wss://`/`https://` whenever the surface is reachable beyond loopback. Revoke a token with `revokeAuthToken(context, storage, token)`; affected clients drop to untrusted via the `devframe:auth:revoked` event.
+
+## Practices for tools built on devframe
+
+- **Stay on loopback.** The default bind host is `localhost`. Bind to a routable address only when you intend to, and require authentication when you do.
+- **Keep `auth: false` local.** Reach for it only for single-user localhost tools; leave the default in place anywhere a connection could originate elsewhere.
+- **Treat tokens as secrets.** Never log the bearer token or the pairing code, and never bake either into build output.
+- **Authorize every handler.** A registered function is callable by any trusted client. Validate inputs, and mark state-changing functions `type: 'destructive'` so MCP and agent clients prompt before invoking them.
+- **Origin-lock remote docks.** When a hub embeds a remote-UI dock, enable `originLock` so a dock token is only honored from its expected origin.
+- **Serve encrypted off-machine.** Use `https://`/`wss://` for any surface reachable beyond `localhost`.

packages/devframe/src/client/rpc.ts

@@ -238,6 +238,12 @@ export async function getDevframeRpcClient(
     rpc: undefined!,
   }
   const authToken = getStoredAuthToken(options.authToken)
+  // Persist a resolved token so one supplied out-of-band — e.g. a host that
+  // bootstraps trust by passing `authToken` (read from its own page URL query)
+  // — survives reconnects. The token is still sent to the server via the WS
+  // URL query param (`?devframe_auth_token=`) by the transport.
+  if (authToken)
+    persistAuthToken(authToken)
   const clientRpc: DevframeClientRpcHost = new RpcFunctionsCollectorBase<DevframeRpcClientFunctions, DevframeRpcContext>(context)
 
   async function fetchJsonFromBases(path: string): Promise<any> {

packages/devframe/src/rpc/transports/ws.test.ts

@@ -8,6 +8,35 @@ import { attachWsRpcTransport } from './ws-server'
 
 vi.stubGlobal('WebSocket', WebSocket)
 
+describe('ws auth token in URL', () => {
+  it('appends the auth token as a URL query param, url-encoded, and omits it when absent', () => {
+    const urls: string[] = []
+    class CapturingWS {
+      constructor(public url: string) {
+        urls.push(url)
+      }
+
+      addEventListener() {}
+      removeEventListener() {}
+      send() {}
+      readyState = 0
+    }
+
+    try {
+      vi.stubGlobal('WebSocket', CapturingWS)
+      createWsRpcChannel({ url: 'ws://127.0.0.1:1234' })
+      createWsRpcChannel({ url: 'ws://127.0.0.1:1234', authToken: 'a b/c+d' })
+
+      expect(urls[0]).toBe('ws://127.0.0.1:1234')
+      expect(urls[1]).toBe('ws://127.0.0.1:1234?devframe_auth_token=a%20b%2Fc%2Bd')
+    }
+    finally {
+      // Restore the real ws implementation for the connection tests below.
+      vi.stubGlobal('WebSocket', WebSocket)
+    }
+  })
+})
+
 describe('devframe rpc', () => {
   it('should work w/ ws transport', async () => {
     const PORT = 3333

skills/devframe/SKILL.md

@@ -478,6 +478,19 @@ Devframe re-exports a curated set of helpers under `devframe/utils/*`. They are
 
 For "open file in editor" + "reveal in finder", prefer the prebuilt `openHelpers` RPC recipe — it wires the two utilities into named RPC functions ready to register.
 
+## Security (secure by default)
+
+RPC handlers run with the full privileges of the host process, so the boundary that matters is who may connect. Keep that boundary tight:
+
+- **`auth` defaults to `true`** — dev-mode connections must pair 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 pairing UI.
+- **`auth: false` trusts every reachable connection.** Use it only for single-user `localhost` tools. Never pair it with a non-loopback bind host, a tunnel, or a shared/CI environment. The default bind host is already `localhost`.
+- **Pairing** 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.
+- **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.
+
+See [Security](https://devfra.me/security) for the full reference.
+
 ## Testing
 
 - Unit-test host classes with fake contexts.
@@ -497,6 +510,7 @@ Devframe-level pages (one-tool, portable surface):
 - [Structured Diagnostics](https://devfra.me/diagnostics) — coded errors via `ctx.diagnostics`, register custom codes
 - [Utilities](https://devfra.me/utilities) — bundled `devframe/utils/*` helpers (colors, hash, launchEditor, structured-clone, …)
 - [Client](https://devfra.me/client) — auth handshake, modes, discovery
+- [Security](https://devfra.me/security) — trust model, pairing, secure-by-default practices
 - [Agent-Native](https://devfra.me/agent-native) — agent field, tools/resources, MCP + Claude Desktop
 
 Host-specific extras (when mounting into Vite DevTools — other hosts have their own equivalents):