feat(auth)!: ready-made interactive auth handler with real enforcement

Implements the auth-side upstream proposals surfaced by the Vite DevTools
0.6 migration (devframes/devframe issues): a single pre-trust rule, a
packaged OTP auth handler, and an authenticated `startHttpAndWs`.

BREAKING CHANGE (wire-level, `@internal` methods): the two pre-auth
handshake methods are renamed to carry the `anonymous:` prefix so the
pre-trust gate has one rule to apply, not a hand-maintained allowlist:

  - `devframe:anonymous:auth` -> `anonymous:devframe:auth`
  - `devframe:auth:exchange` -> `anonymous:devframe:auth:exchange`

- `devframe/constants` exports `ANONYMOUS_RPC_PREFIX` / `isAnonymousRpcMethod`,
  the single source of truth for what's callable before trust.
- `devframe/recipes/interactive-auth`'s `createInteractiveAuth(ctx, options)`
  packages the OTP protocol devframe's primitives already implement
  (`exchangeTempAuthCode`, `verifyAuthToken`, `revokeAuthToken`,
  `getTempAuthCode`, `buildOtpAuthUrl`) into a `DevframeAuthHandler` —
  handshake RPC functions, the resolver gate, a connect-time trust hook
  that reads a bearer off the WS upgrade URL, and the code/link banner.
  The auth storage stays internal to the handler.
- `startHttpAndWs` accepts that handler (or a lower-level `authorize` /
  `onPeerConnect` pair) directly via `auth`, and now actually enforces
  it: an untrusted call to a non-`anonymous:` method throws `DF0036`.
  `StartedServer.connectionMeta()` returns the `__connection.json` shape
  a host would otherwise hand-roll.
- Client: adds a standalone `forgetAuthToken()` export (clear a persisted
  token) to pair with the new trusted-only `devframe:auth:revoke` server
  method for giving up the current session's token.
- Docs: rewrite the Security guide's auth-methods table for the new
  names and the ready-made handler, add the `DF0036` error page, and add
  an Interactive Auth helper page.

Also clarifies the terminals hub-aggregation model (`ctx.terminals` as
the single source of truth for sessions, the plugin as the PTY-capable
renderer that mirrors into it) in the terminals plugin docs, closing out
the last of the five proposals.

Generated with the help of an agent.

Author: antfubot

docs/.vitepress/config.ts

@@ -55,6 +55,7 @@ function helpersItems(prefix: string): DefaultTheme.NavItemWithLink[] {
     { text: 'Vite Bridge', link: `${prefix}/helpers/vite-bridge` },
     { text: 'Nuxt Module', link: `${prefix}/helpers/nuxt` },
     { text: 'Open Helpers', link: `${prefix}/helpers/open-helpers` },
+    { text: 'Interactive Auth', link: `${prefix}/helpers/interactive-auth` },
   ]
 }
 

docs/errors/DF0036.md

@@ -0,0 +1,41 @@
+---
+outline: deep
+---
+
+# DF0036: RPC Call Rejected — Not Authorized
+
+## Message
+
+> RPC call to "`{name}`" was rejected: the caller is not authorized.
+
+## Cause
+
+`startHttpAndWs` was configured with an `authorize` gate (either directly, or via a [`DevframeAuthHandler`](../guide/security) passed as `auth`) and the calling session hasn't satisfied it — the call is neither to an `anonymous:`-prefixed method (see `isAnonymousRpcMethod`) nor made by a trusted session.
+
+## Example
+
+```ts
+import { startHttpAndWs } from 'devframe/node'
+import { createInteractiveAuth } from 'devframe/recipes/interactive-auth'
+
+const auth = createInteractiveAuth(ctx)
+
+await startHttpAndWs({ context: ctx, port: 9999, auth })
+
+// A browser that hasn't completed the handshake yet can still reach the
+// handshake methods themselves…
+await client.call('anonymous:devframe:auth', { authToken: '', ua, origin })
+
+// …but any other method throws DF0036 until the handshake succeeds.
+await client.call('some-plugin:do-something') // ✗ throws DF0036
+```
+
+## Fix
+
+- Complete the auth handshake — call `anonymous:devframe:auth` with a previously-issued token, or `anonymous:devframe:auth:exchange` with a one-time code — before calling a trusted method.
+- Connect with a static/pre-shared token (`createInteractiveAuth`'s `clientAuthTokens` option) for CI or shared-machine setups that should skip the interactive prompt.
+- If you supplied a custom `authorize` function, verify it allows the method you expect — it receives the raw method name and the session's `meta` (`isTrusted`, `clientAuthToken`, …).
+
+## Source
+
+- [`packages/devframe/src/node/server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/server.ts) — `startHttpAndWs`'s resolver throws this when `authorize`/`auth.authorize` rejects a call.

docs/guide/hub.md

@@ -16,7 +16,7 @@ A hub-aware node context (`DevframeHubContext`) extends `DevframeNodeContext` wi
 | Subsystem | Surface | Purpose |
 |---|---|---|
 | `ctx.docks` | `register / update / values` | Multi-tool dock entries (iframes, launchers, json-render, custom-render) and groups that collapse them under one button. |
-| `ctx.terminals` | `register / startChildProcess` | Aggregate terminal sessions, stream output over a well-known channel. |
+| `ctx.terminals` | `register / startChildProcess` | Aggregate terminal sessions, stream output over a well-known channel. The single source of truth for "what sessions exist" — see [Terminals](/plugins/terminals#hub-aggregation) for how the terminals plugin renders and mirrors into it. |
 | `ctx.messages` | `add / update / remove / clear` | Server-side toast/notification queue (FIFO, capped at 1000). |
 | `ctx.commands` | `register / execute / list` | Hierarchical command palette with keybindings and `when` clauses. |
 

docs/guide/security.md

@@ -12,34 +12,57 @@ An RPC handler runs with the full privileges of the process hosting it — files
 
 Two postures cover that boundary:
 
-- **Authenticated (default).** `auth` defaults to `true`. The browser authenticates 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 authentication UI.
+- **Authenticated (default).** `auth` defaults to `true`. The browser authenticates with the server before calls are accepted, and reconnects by presenting a node-issued bearer token. `devframe/recipes/interactive-auth`'s `createInteractiveAuth` packages the whole protocol — handshake handlers, the resolver gate, connect-time trust, and the code/link banner — into a single `DevframeAuthHandler` you pass straight to `startHttpAndWs({ auth })`.
 - **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.
 
+## The pre-trust gate
+
+Exactly one rule decides what an untrusted connection may call: **a method is reachable before trust iff its name starts with `anonymous:`** (`isAnonymousRpcMethod`, from `devframe/constants`). There is no separate allowlist to keep in sync — the two handshake methods below carry the prefix precisely because they're the only ones an unauthenticated caller needs.
+
+`startHttpAndWs` enforces this itself once you give it something to enforce: pass `auth: authHandler` (its `.authorize` becomes the gate) or your own `authorize(methodName, session)` function. Every other call from an untrusted session throws [`DF0036`](../errors/DF0036).
+
 ## Authentication flow
 
 Authentication exchanges a short code for a long-lived token. A node mints and owns the token; the browser only ever sends the short code, and only over the open socket.
 
-1. A fresh client connects unauthenticated and calls `devframe:anonymous:auth` with its stored token (empty on first run). The server returns `{ isTrusted: false }`, so the trust gate stays open while the UI prompts for a code.
-2. The dev server shows a 6-digit one-time code in the developer's terminal.
-3. The developer enters it; the browser calls `requestTrustWithCode(code)` → `devframe:auth:exchange`.
+1. A fresh client connects unauthenticated and calls `anonymous:devframe:auth` with its stored token (empty on first run). The server returns `{ isTrusted: false }`, so the trust gate stays open while the UI prompts for a code.
+2. The dev server shows a 6-digit one-time code in the developer's terminal — call `auth.printBanner()` once the server is listening; devframe stays headless otherwise.
+3. The developer enters it; the browser calls `requestTrustWithCode(code)` → `anonymous:devframe:auth:exchange`.
 4. The server verifies the code, mints a high-entropy bearer token, records it as trusted, marks the session trusted, and returns the token.
-5. The browser persists the token and presents it on reconnect (`devframe:anonymous:auth` → `verifyAuthToken`); sibling tabs receive it over the `devframe-auth` channel and become trusted too.
+5. The browser persists the token and presents it on reconnect (`anonymous:devframe:auth` → `verifyAuthToken`, or as a `?devframe_auth_token=` query param the connect-time hook checks before the handshake even runs); sibling tabs receive it over the `devframe-auth` channel and become trusted too.
 
 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.
+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. A client can give up its own token by calling `devframe:auth:revoke` and then `forgetAuthToken()` locally; a host can revoke on a client's behalf with `revokeAuthToken(context, storage, token)`. Either way, affected clients drop to untrusted via the `devframe:auth:revoked` event.
+
+### The ready-made layer
+
+```ts
+import { startHttpAndWs } from 'devframe/node'
+import { createInteractiveAuth } from 'devframe/recipes/interactive-auth'
+
+const auth = createInteractiveAuth(ctx, {
+  clientAuthTokens: process.env.CI ? [process.env.DEVFRAME_CI_TOKEN!] : undefined,
+})
+
+const server = await startHttpAndWs({ context: ctx, port: 9999, auth })
+auth.printBanner()
+```
+
+`createInteractiveAuth` closes over the auth storage internally — nothing here reaches into `devframe/node/hub-internals`. Pass `clientAuthTokens` for CI/shared machines that should skip the interactive prompt entirely, or a custom `banner`/`serverUrl` to change how the code is presented.
 
 ### Auth methods
 
-Devframe owns the wire contract; the host adapter registers the handlers on top of the `devframe/node/auth` primitives (the standalone server registers a noop auto-trust handler when `auth: false`).
+Devframe owns the wire contract; `createInteractiveAuth` registers the handlers on top of the `devframe/node/auth` primitives (the standalone server registers a noop auto-trust handler when `auth: false`).
 
 | RPC method | Direction | Shape |
 |------------|-----------|-------|
-| `devframe:anonymous:auth` | client → server | `{ authToken, ua, origin }` → `{ isTrusted }` — re-authenticate a stored token |
-| `devframe:auth:exchange` | client → server | `{ code, ua, origin }` → `{ authToken \| null }` — exchange a one-time code for a token |
+| `anonymous:devframe:auth` | client → server | `{ authToken, ua, origin }` → `{ isTrusted }` — re-authenticate a stored token |
+| `anonymous:devframe:auth:exchange` | client → server | `{ code, ua, origin }` → `{ authToken \| null }` — exchange a one-time code for a token |
+| `devframe:auth:revoke` | client → server | — self-revoke: drop the caller's own token |
 | `devframe:auth:revoked` | server → client | event — the connection's token was revoked |
 
 Node primitives (`devframe/node/auth`):
@@ -52,7 +75,7 @@ Node primitives (`devframe/node/auth`):
 | `buildOtpAuthUrl(origin, code?)` | build a magic-link URL embedding the code |
 | `revokeAuthToken(context, storage, token)` | delete a token and disconnect any sessions using it |
 
-Client methods (`devframe/client`): `requestTrustWithCode(code)` (exchange a code), `requestTrustWithToken(token)` (re-authenticate a token), `ensureTrusted(timeout?)` / `isTrusted` (the trust gate).
+Client methods (`devframe/client`): `requestTrustWithCode(code)` (exchange a code), `requestTrustWithToken(token)` (re-authenticate a token), `forgetAuthToken()` (clear a persisted token — pair with a `devframe:auth:revoke` call to give up this browser's own token), `ensureTrusted(timeout?)` / `isTrusted` (the trust gate).
 
 ### Magic-link authentication
 

docs/helpers/index.md

@@ -12,5 +12,6 @@ Helpers are the optional, opt-in surface around the core `defineDevframe` API: s
 | [Vite Bridge](./vite-bridge) | `devframe/helpers/vite` | Vite plugin for mounting a devframe inside any Vite-based host (Astro, SolidStart, plain Vite). |
 | [Nuxt Module](./nuxt) | `@devframes/nuxt` | Nuxt module that wires a Nuxt SPA as a devframe client and serves the dev-time RPC bridge. |
 | [Open Helpers](./open-helpers) | `devframe/recipes/open-helpers` | Prebuilt RPC actions for "open in editor" and "reveal in Finder". |
+| [Interactive Auth](./interactive-auth) | `devframe/recipes/interactive-auth` | Ready-made OTP auth layer — handshake, resolver gate, connect-time trust, and the code/link banner. |
 
 Helpers vs. [adapters](/adapters/): an adapter takes a `DevframeDefinition` and deploys it as a runnable surface (CLI, dev server, static build, MCP server). A helper is a smaller piece — a Vite plugin, a Nuxt module, a recipe, a utility function — that you compose alongside an adapter.

docs/helpers/interactive-auth.md

@@ -0,0 +1,57 @@
+---
+outline: deep
+---
+
+# Interactive Auth
+
+A ready-made OTP auth layer over devframe's node-side primitives — the handshake RPC functions, the resolver gate, the connect-time trust hook, and the code/link banner — so a host doesn't re-implement the protocol on top of `exchangeTempAuthCode` / `verifyAuthToken` / `revokeAuthToken` itself.
+
+```ts
+import { startHttpAndWs } from 'devframe/node'
+import { createInteractiveAuth } from 'devframe/recipes/interactive-auth'
+
+const auth = createInteractiveAuth(ctx, {
+  clientAuthTokens: process.env.CI ? [process.env.DEVFRAME_CI_TOKEN!] : undefined,
+})
+
+const server = await startHttpAndWs({ context: ctx, port: 9999, auth })
+auth.printBanner()
+```
+
+Passing the layer as `auth` registers its `rpcFunctions`, wires its `authorize` as the resolver gate, and wires its `onConnect` on every new peer — see [Security](../guide/security) for the full authentication flow this implements.
+
+## `createInteractiveAuth(context, options?)`
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `clientAuthTokens` | `undefined` | Static, pre-shared bearer tokens that are always trusted — for CI runs or shared machines that should skip the interactive prompt. |
+| `banner` | a small boxed console message | Called with `{ code, url }` to present the current code. Devframe stays headless — nothing prints until you call `printBanner()`. |
+| `serverUrl` | `context.host.resolveOrigin()` | Base URL the magic link should point at. |
+
+Returns a `DevframeAuthHandler`:
+
+| Field | Purpose |
+|-------|---------|
+| `rpcFunctions` | `anonymous:devframe:auth` + `anonymous:devframe:auth:exchange` (the handshake) and `devframe:auth:revoke` (self-revoke) — register these on the RPC host if not passing the whole layer to `startHttpAndWs`. |
+| `authorize(methodName, session)` | The resolver gate: allows any `anonymous:`-prefixed method, otherwise requires `session.meta.isTrusted`. |
+| `onConnect(peer, session)` | Connect-time trust: reads a bearer off the peer's WS upgrade URL (`?devframe_auth_token=`) and trusts the session immediately when it's valid, before the client's own handshake call arrives. |
+| `printBanner()` | Prints the current code + magic-link URL. Safe to call repeatedly — it only prints once per code. |
+
+## Using the pieces directly
+
+Not using `startHttpAndWs`? Wire the same four pieces against your own transport:
+
+```ts
+const auth = createInteractiveAuth(ctx)
+auth.rpcFunctions.forEach(fn => ctx.rpc.register(fn))
+auth.printBanner()
+
+// in your resolver:
+if (!auth.authorize(methodName, session))
+  throw new Error('not authorized')
+
+// on each new WS peer:
+auth.onConnect(peer, session)
+```
+
+Nothing here reaches into `devframe/node/hub-internals` — the recipe closes over the auth storage internally.

docs/plugins/terminals.md

@@ -50,6 +50,12 @@ export default createTerminalsDevframe({
 })
 ```
 
+## Hub aggregation
+
+Mounted into a hub, the plugin owns PTY/child-process spawning and its own streaming channel (`devframes-plugin-terminals:output`) — that's what the panel renders. It also mirrors every session it spawns into `ctx.terminals` (the hub's aggregate registry, streaming on `devframe:terminals`) so other tools — a launcher dock, a custom panel — see the same session list without depending on the plugin's own types. A session started the other way, via `ctx.terminals.startChildProcess` / `startPtySession` directly (e.g. from a launcher dock), shows up in the terminals panel too — the plugin reads foreign hub sessions read-only and renders them alongside its own, subscribing to the hub's channel for their output.
+
+`ctx.terminals` is the source of truth for "what sessions exist"; the plugin is the panel that renders them and the one PTY-capable provider among possibly several session sources. The plugin never imports `@devframes/hub`'s types to stay mountable without a hub — it duck-types the minimal `register` / `update` / `events` shape it needs.
+
 ## Source
 
 [`plugins/terminals`](https://github.com/devframes/devframe/tree/main/plugins/terminals)

packages/devframe/package.json

@@ -31,6 +31,7 @@
     "./node": "./dist/node/index.mjs",
     "./node/auth": "./dist/node/auth.mjs",
     "./node/hub-internals": "./dist/node/hub-internals.mjs",
+    "./recipes/interactive-auth": "./dist/recipes/interactive-auth.mjs",
     "./recipes/open-helpers": "./dist/recipes/open-helpers.mjs",
     "./rpc": "./dist/rpc/index.mjs",
     "./rpc/client": "./dist/rpc/client.mjs",

packages/devframe/src/client/rpc-ws.ts

@@ -159,7 +159,7 @@ export function createWsRpcClientMode(
   async function requestTrustWithToken(token: string) {
     currentAuthToken = token
 
-    const result = await serverRpc.$call('devframe:anonymous:auth', {
+    const result = await serverRpc.$call('anonymous:devframe:auth', {
       authToken: token,
       ua: describeUA(),
       origin: location.origin,
@@ -175,7 +175,7 @@ export function createWsRpcClientMode(
   }
 
   async function requestTrustWithCode(code: string): Promise<string | null> {
-    const result = await serverRpc.$call('devframe:auth:exchange', {
+    const result = await serverRpc.$call('anonymous:devframe:auth:exchange', {
       code,
       ua: describeUA(),
       origin: location.origin,

packages/devframe/src/client/rpc.ts

@@ -193,6 +193,24 @@ function persistAuthToken(token: string): void {
   ;(globalThis as any)[CONNECTION_AUTH_TOKEN_KEY] = token
 }
 
+/**
+ * Clear any persisted devframe bearer token from this browser — the
+ * counterpart to `persistAuthToken`. For integrations that manage their own
+ * auth UI and just need to forget a token locally, e.g. after a sign-out
+ * action, or after calling the server's `devframe:auth:revoke` to give up
+ * the current session's token.
+ */
+export function forgetAuthToken(): void {
+  try {
+    localStorage.removeItem(CONNECTION_AUTH_TOKEN_KEY)
+  }
+  catch {}
+  try {
+    delete (globalThis as any)[CONNECTION_AUTH_TOKEN_KEY]
+  }
+  catch {}
+}
+
 function findConnectionMetaFromWindows(): ConnectionMeta | undefined {
   const getters = [
     () => (window as any)?.[CONNECTION_META_KEY],