feat(auth): magic-link pairing via one-time code in the URL

Let a host print a pairing link (`<origin>/?devframe_auth=<code>`) so opening
it pairs the browser automatically. `connectDevframe` reads the code, exchanges
it for a token, and strips the parameter from the URL before anything else;
the resulting bearer token is persisted, never written back to the URL.

Only the short-lived, single-use code rides the URL — never the bearer. The
behaviour is configurable via the `autoPairParam` client option (defaults to
`devframe_auth`, set `false` to disable).

Add the shared `DEVFRAME_AUTH_URL_PARAM` constant and a node `buildAuthPairingUrl`
helper for hosts to construct the link from the current code (devframe stays
headless, so the host prints its own banner). Document the flow and its
trusted-channel caveat in the security guide and skill.

Author: antfubot

docs/guide/client.md

@@ -89,6 +89,8 @@ const ok = await rpc.requestTrustWithCode('047204')
 
 The code is single-use, expires after five minutes, and is rotated after repeated wrong attempts, so re-display the current code if an exchange fails.
 
+To pair without typing, a host can print a link embedding the code (`buildAuthPairingUrl(origin)`); `connectDevframe` reads the `devframe_auth` query parameter, exchanges it, and strips it from the URL. Disable or rename it with the `autoPairParam` option.
+
 ### Re-using an existing token
 
 Authenticate with a token obtained elsewhere (e.g. another surface) without reloading:

docs/guide/security.md

@@ -31,6 +31,16 @@ The 6-digit code is single-use, expires after five minutes, is compared in const
 
 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.
 
+### Magic-link pairing
+
+To skip typing, a host can print a link that embeds the code and open the browser straight into a paired session. Build it from the current code with `buildAuthPairingUrl(origin)` (devframe stays headless, so the host prints its own banner):
+
+```
+Devtools ready — pair this browser: http://localhost:3000/?devframe_auth=123456
+```
+
+`connectDevframe` reads the `devframe_auth` parameter, exchanges it, and removes it from the URL before anything else (configurable via the `autoPairParam` client option). Only the short-lived, single-use **code** ever rides the URL — the resulting bearer token is stored, never written back to it. Because the link grants trust to whoever opens it within the code's lifetime, print it only to a trusted channel (the terminal), exactly as you would the bare code.
+
 ## 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.

packages/devframe/src/client/__tests__/auth-url.test.ts

@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { clearAuthCodeFromUrl, readAuthCodeFromUrl } from '../auth-url'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('auth-url helpers', () => {
+  it('reads the pairing code from the page URL query string', () => {
+    vi.stubGlobal('location', { search: '?devframe_auth=123456&x=1', href: 'http://localhost:3000/?devframe_auth=123456&x=1' })
+    expect(readAuthCodeFromUrl('devframe_auth')).toBe('123456')
+  })
+
+  it('returns undefined when the param is absent or empty', () => {
+    vi.stubGlobal('location', { search: '?x=1', href: 'http://localhost:3000/?x=1' })
+    expect(readAuthCodeFromUrl('devframe_auth')).toBeUndefined()
+  })
+
+  it('is safe when location is unavailable', () => {
+    vi.stubGlobal('location', undefined)
+    expect(readAuthCodeFromUrl('devframe_auth')).toBeUndefined()
+    expect(() => clearAuthCodeFromUrl('devframe_auth')).not.toThrow()
+  })
+
+  it('strips the pairing code from the URL via history.replaceState, keeping other params', () => {
+    const replaceState = vi.fn()
+    vi.stubGlobal('location', { search: '?devframe_auth=123456&x=1', href: 'http://localhost:3000/?devframe_auth=123456&x=1' })
+    vi.stubGlobal('history', { state: { a: 1 }, replaceState })
+
+    clearAuthCodeFromUrl('devframe_auth')
+
+    expect(replaceState).toHaveBeenCalledTimes(1)
+    const [state, , href] = replaceState.mock.calls[0]
+    expect(state).toEqual({ a: 1 })
+    expect(href).toBe('http://localhost:3000/?x=1')
+  })
+
+  it('does nothing when the param is not present in the URL', () => {
+    const replaceState = vi.fn()
+    vi.stubGlobal('location', { href: 'http://localhost:3000/?x=1' })
+    vi.stubGlobal('history', { state: null, replaceState })
+
+    clearAuthCodeFromUrl('devframe_auth')
+
+    expect(replaceState).not.toHaveBeenCalled()
+  })
+})

packages/devframe/src/client/auth-url.ts

@@ -0,0 +1,33 @@
+// Browser-only helpers for "magic link" pairing: a host can print a URL that
+// carries a one-time pairing code, and the client reads the code, exchanges it
+// for a token, and removes it from the address bar. Only the short-lived,
+// single-use code ever rides the URL — never the resulting bearer token.
+
+/**
+ * Read a one-time pairing code from the current page URL's query string.
+ * Returns `undefined` when the parameter is absent or unavailable.
+ */
+export function readAuthCodeFromUrl(param: string): string | undefined {
+  try {
+    return new URLSearchParams(globalThis.location?.search).get(param) || undefined
+  }
+  catch {
+    return undefined
+  }
+}
+
+/**
+ * Remove the pairing-code parameter from the address bar (and the current
+ * history entry) so the single-use code isn't left in the URL, browser
+ * history, or a `Referer` header.
+ */
+export function clearAuthCodeFromUrl(param: string): void {
+  try {
+    const url = new URL(globalThis.location!.href)
+    if (!url.searchParams.has(param))
+      return
+    url.searchParams.delete(param)
+    globalThis.history?.replaceState(globalThis.history.state, '', url.href)
+  }
+  catch {}
+}

packages/devframe/src/client/rpc.ts

@@ -4,10 +4,12 @@ import type { WsRpcChannelOptions } from 'devframe/rpc/transports/ws-client'
 import type { ConnectionMeta, DevframeRpcClientFunctions, DevframeRpcServerFunctions, EventEmitter, RpcSharedStateHost } from 'devframe/types'
 import type { RpcStreamingClientHost } from './rpc-streaming'
 import {
+  DEVFRAME_AUTH_URL_PARAM,
   DEVFRAME_CONNECTION_META_FILENAME,
 } from 'devframe/constants'
 import { RpcCacheManager, RpcFunctionsCollectorBase } from 'devframe/rpc'
 import { createEventEmitter } from 'devframe/utils/events'
+import { clearAuthCodeFromUrl, readAuthCodeFromUrl } from './auth-url'
 import { createRpcSharedStateClientHost } from './rpc-shared-state'
 import { createStaticRpcClientMode } from './rpc-static'
 import { createRpcStreamingClientHost } from './rpc-streaming'
@@ -36,6 +38,13 @@ export interface DevframeRpcClientOptions {
    * The auth token to use for the client
    */
   authToken?: string
+  /**
+   * Query-param name on the page URL carrying a one-time pairing code for
+   * "magic link" auth (e.g. a link the dev server prints). When present, the
+   * client exchanges the code for a token and removes the parameter from the
+   * URL. Set `false` to disable. Default: `'devframe_auth'`.
+   */
+  autoPairParam?: string | false
   wsOptions?: Partial<WsRpcChannelOptions>
   rpcOptions?: Partial<BirpcOptions<DevframeRpcServerFunctions, DevframeRpcClientFunctions, boolean>>
   cacheOptions?: boolean | Partial<RpcCacheOptions>
@@ -352,6 +361,19 @@ export async function getDevframeRpcClient(
   context.rpc = rpc
   void mode.requestTrust()
 
+  // Magic-link pairing: if the page URL carries a one-time code, exchange it
+  // and strip it from the URL. The code is single-use and short-lived; the
+  // resulting bearer token is persisted (never written back to the URL).
+  const autoPairParam = options.autoPairParam ?? DEVFRAME_AUTH_URL_PARAM
+  if (autoPairParam) {
+    const code = readAuthCodeFromUrl(autoPairParam)
+    if (code) {
+      clearAuthCodeFromUrl(autoPairParam)
+      if (!rpc.isTrusted)
+        void rpc.requestTrustWithCode(code)
+    }
+  }
+
   // Listen for auth updates from other tabs (e.g., the auth page, or another
   // tab that just completed a code exchange).
   if (authChannel) {

packages/devframe/src/constants.ts

@@ -15,3 +15,12 @@ export const DEVFRAME_RPC_DUMP_DIRNAME = '__rpc-dump'
  * `@vitejs/devtools-kit`) injected into remote-UI iframe dock URLs.
  */
 export const REMOTE_CONNECTION_KEY = 'devframe-remote-connection'
+
+/**
+ * Page-URL query parameter carrying a one-time pairing code for "magic link"
+ * auth. A host can print a link like `<origin>/?devframe_auth=<code>`; the
+ * client reads the code, exchanges it for a token, and strips the parameter
+ * from the URL. See `buildAuthPairingUrl` (node) and `connectDevframe`'s
+ * `autoPairParam` option (client).
+ */
+export const DEVFRAME_AUTH_URL_PARAM = 'devframe_auth'

packages/devframe/src/node/auth/state.ts

@@ -1,6 +1,7 @@
 import type { DevframeNodeRpcSession } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { InternalAnonymousAuthStorage } from '../hub-internals/context'
+import { DEVFRAME_AUTH_URL_PARAM } from 'devframe/constants'
 import { randomDigits, randomToken, timingSafeEqual } from 'devframe/utils/crypto-token'
 
 /** Number of decimal digits in a human-typed one-time pairing code. */
@@ -42,6 +43,18 @@ export function refreshTempAuthToken(): string {
   return tempAuthCode
 }
 
+/**
+ * Build a "magic link" pairing URL that embeds a one-time code as a query
+ * parameter. Opening it lets the client pair without typing — print it on
+ * startup (devframe stays headless, so the host prints its own banner).
+ * Defaults to the current code; the link is subject to the same TTL.
+ */
+export function buildAuthPairingUrl(baseUrl: string, code: string = tempAuthCode): string {
+  const url = new URL(baseUrl)
+  url.searchParams.set(DEVFRAME_AUTH_URL_PARAM, code)
+  return url.href
+}
+
 /**
  * Re-authenticate a connection that presents a previously-issued bearer token.
  * Returns `true` and marks the session trusted when the token is known.

skills/devframe/SKILL.md

@@ -485,6 +485,7 @@ RPC handlers run with the full privileges of the host process, so the boundary t
 - **`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.
+- **Magic-link (optional):** print `buildAuthPairingUrl(origin)` — `<origin>/?devframe_auth=<code>`. `connectDevframe` reads the code, exchanges it, and strips it from the URL (`autoPairParam` to disable/rename). Only the single-use code rides the URL, never the bearer; treat the printed link like the code itself.
 - **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.

tests/__snapshots__/tsnapi/devframe/client.snapshot.d.ts

@@ -32,6 +32,7 @@ export interface DevframeRpcClientOptions {
   connectionMeta?: ConnectionMeta;
   baseURL?: string | string[];
   authToken?: string;
+  autoPairParam?: string | false;
   wsOptions?: Partial<WsRpcChannelOptions>;
   rpcOptions?: Partial<BirpcOptions<DevframeRpcServerFunctions, DevframeRpcClientFunctions, boolean>>;
   cacheOptions?: boolean | Partial<RpcCacheOptions>;

tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts

@@ -2,6 +2,7 @@
  * Generated by tsnapi — public API snapshot of `devframe/constants`
  */
 // #region Variables
+export declare const DEVFRAME_AUTH_URL_PARAM: string;
 export declare const DEVFRAME_CONNECTION_META_FILENAME: string;
 export declare const DEVFRAME_DIRNAME: string;
 export declare const DEVFRAME_DOCK_IMPORTS_FILENAME: string;