feat(auth)!: node-issued one-time-code token exchange

Pivot the pairing flow from "client mints a token, node approves it" to a
node-issued exchange: the dev server shows a 6-digit code, the browser submits
it, and the node mints and returns the bearer token. The token now travels
down only after the code is verified, and the node owns token generation.

Node side (`devframe/node/auth`): drop the pending-promise machinery
(`PendingAuthRequest`, `setPendingAuth`, `getPendingAuth`, `abortPendingAuth`,
`consumeTempAuthToken`) in favour of two synchronous primitives —
`exchangeTempAuthCode` (verify code → mint + store + trust + return token) and
`verifyAuthToken` (re-auth a stored token on reconnect). The code keeps its
TTL, constant-time compare, and attempt-cap guards.

Client side: stop self-issuing a token. A fresh client connects unpaired and
calls the new `requestTrustWithCode(code)` to exchange the code for a token,
which is persisted and broadcast to sibling tabs. `requestTrustWithToken`
remains for re-auth. The client still announces on connect so the standalone
`auth: false` noop keeps auto-trusting.

The auth wire methods (`devframe:anonymous:auth`, `devframe:auth:exchange`,
`devframe:auth:revoked`) are now declared in the RPC contract types.

BREAKING CHANGE: `devframe/node/auth` no longer exports `PendingAuthRequest`,
`setPendingAuth`, `getPendingAuth`, `abortPendingAuth`, or
`consumeTempAuthToken`. Host adapters register a `devframe:auth:exchange`
handler built on `exchangeTempAuthCode`, and an `devframe:anonymous:auth`
handler built on `verifyAuthToken`, instead of the pending-request dance.

Author: antfubot

docs/guide/client.md

@@ -66,7 +66,7 @@ The client picks a mode automatically from the backend field. Mode-specific code
 
 ## Trust & auth (WebSocket mode)
 
-Dev-mode connections require trust before the server accepts calls. The client handles this automatically: on first connect it submits the locally-stored auth token, and `ensureTrusted()` resolves once the server accepts.
+Dev-mode connections become trusted by pairing. A client that has paired before presents its stored token automatically on reconnect, and `ensureTrusted()` resolves once the server accepts it:
 
 ```ts
 const rpc = await connectDevframe()
@@ -75,21 +75,31 @@ const rpc = await connectDevframe()
 const trusted = await rpc.ensureTrusted()
 
 if (!trusted) {
-  console.warn('Auth denied')
+  console.warn('Not paired yet')
 }
 ```
 
-### Replacing the token
+### Pairing with a one-time code
 
-For tokens supplied from a different source (e.g. copy-pasted from CLI output), swap one in without reloading:
+A fresh client holds no token. The dev server prints a 6-digit one-time code; pass it to `requestTrustWithCode` to exchange it for a node-issued token. The token is persisted for future reconnections and shared with sibling tabs, which become trusted without re-entering the code:
 
 ```ts
-const ok = await rpc.requestTrustWithToken('another-token')
+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.
+
+### Re-using an existing token
+
+Authenticate with a token obtained elsewhere (e.g. another surface) without reloading:
+
+```ts
+const ok = await rpc.requestTrustWithToken('a1b2c3…')
 ```
 
 ### Broadcast-channel sync
 
-`connectDevframe` listens on a shared `BroadcastChannel` (named `devframe-auth` for cross-tab handshake interop with Vite DevTools' auth page) for `auth-update` messages. When an auth page in another tab announces a new token, every open client requests trust with it automatically — no reload required.
+`connectDevframe` listens on a shared `BroadcastChannel` (named `devframe-auth` for cross-tab handshake interop with Vite DevTools' auth page) for `auth-update` messages. When another tab completes a pairing — or an auth page announces a token — every open client trusts it automatically, no reload required.
 
 ## Calling functions
 

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

@@ -16,6 +16,8 @@ export async function createStaticRpcClientMode(
     isTrusted: true,
     requestTrust: async () => true,
     requestTrustWithToken: async () => true,
+    // Static backends are always trusted, so there's nothing to exchange.
+    requestTrustWithCode: async () => null,
     ensureTrusted: async () => true,
     call: (...args: any): any => staticCaller.call(
       args[0] as string,

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

@@ -6,7 +6,7 @@ import { promiseWithResolver } from 'devframe/utils/promise'
 import { parseUA } from 'ua-parser-modern'
 
 export interface CreateWsRpcClientModeOptions {
-  authToken: string
+  authToken?: string
   connectionMeta: ConnectionMeta
   events: EventEmitter<RpcClientEvents>
   clientRpc: DevframeClientRpcHost
@@ -69,37 +69,63 @@ export function createWsRpcClientMode(
     },
   })
 
-  let currentAuthToken = authToken
-
-  async function requestTrustWithToken(token: string) {
-    currentAuthToken = token
+  let currentAuthToken: string | undefined = authToken
 
+  function describeUA(): string {
     const info = parseUA(navigator.userAgent)
-    const ua = [
+    return [
       info.browser.name,
       info.browser.version,
       '|',
       info.os.name,
       info.os.version,
       info.device.type,
     ].filter(i => i).join(' ')
+  }
+
+  async function requestTrustWithToken(token: string) {
+    currentAuthToken = token
 
     const result = await serverRpc.$call('devframe:anonymous:auth', {
       authToken: token,
-      ua,
+      ua: describeUA(),
       origin: location.origin,
     })
 
     isTrusted = result.isTrusted
-    trustedPromise.resolve(isTrusted)
+    // Only settle the trust gate on success; on failure the client can still
+    // pair via `requestTrustWithCode`, so leave `ensureTrusted` waiting.
+    if (isTrusted)
+      trustedPromise.resolve(true)
     events.emit('rpc:is-trusted:updated', isTrusted)
     return result.isTrusted
   }
 
+  async function requestTrustWithCode(code: string): Promise<string | null> {
+    const result = await serverRpc.$call('devframe:auth:exchange', {
+      code,
+      ua: describeUA(),
+      origin: location.origin,
+    })
+
+    const token = result?.authToken ?? null
+    if (token) {
+      currentAuthToken = token
+      isTrusted = true
+      trustedPromise.resolve(true)
+      events.emit('rpc:is-trusted:updated', true)
+    }
+    return token
+  }
+
   async function requestTrust() {
     if (isTrusted)
       return true
-    return requestTrustWithToken(currentAuthToken)
+    // Always announce on connect. The standalone (`auth: false`) noop handler
+    // auto-trusts regardless of token; the host adapter looks the token up and
+    // returns `false` for an unpaired client (empty/unknown token), which then
+    // pairs via `requestTrustWithCode`. The trust gate stays open until then.
+    return requestTrustWithToken(currentAuthToken ?? '')
   }
 
   async function ensureTrusted(timeout = 60_000): Promise<boolean> {
@@ -129,6 +155,7 @@ export function createWsRpcClientMode(
     },
     requestTrust,
     requestTrustWithToken,
+    requestTrustWithCode,
     ensureTrusted,
     call: (...args: any): any => {
       return serverRpc.$call(

packages/devframe/src/client/rpc.ts

@@ -7,7 +7,6 @@ import {
   DEVFRAME_CONNECTION_META_FILENAME,
 } from 'devframe/constants'
 import { RpcCacheManager, RpcFunctionsCollectorBase } from 'devframe/rpc'
-import { randomToken } from 'devframe/utils/crypto-token'
 import { createEventEmitter } from 'devframe/utils/events'
 import { createRpcSharedStateClientHost } from './rpc-shared-state'
 import { createStaticRpcClientMode } from './rpc-static'
@@ -75,11 +74,18 @@ export interface DevframeRpcClient {
   requestTrust: () => Promise<boolean>
 
   /**
-   * Request trust from the server using a specific auth token.
+   * Request trust from the server using a previously-issued auth token.
    * Updates the stored token and re-requests trust without reloading the page.
    */
   requestTrustWithToken: (token: string) => Promise<boolean>
 
+  /**
+   * Pair this client by exchanging a one-time code (shown by the dev server)
+   * for a node-issued auth token. On success the token is persisted for future
+   * reconnections and shared with sibling tabs. Resolves `true` when paired.
+   */
+  requestTrustWithCode: (code: string) => Promise<boolean>
+
   /**
    * Call a RPC function on the server
    */
@@ -118,37 +124,45 @@ export interface DevframeRpcClientMode {
   ensureTrusted: DevframeRpcClient['ensureTrusted']
   requestTrust: DevframeRpcClient['requestTrust']
   requestTrustWithToken: DevframeRpcClient['requestTrustWithToken']
+  /**
+   * Exchange a one-time code for a node-issued token. Resolves the minted
+   * token on success (for the caller to persist), or `null` on failure.
+   */
+  requestTrustWithCode: (code: string) => Promise<string | null>
   call: DevframeRpcClient['call']
   callEvent: DevframeRpcClient['callEvent']
   callOptional: DevframeRpcClient['callOptional']
 }
 
-function getConnectionAuthTokenFromWindows(userAuthToken?: string): string {
+function getStoredAuthToken(userAuthToken?: string): string | undefined {
   const getters = [
     () => userAuthToken,
-    () => localStorage.getItem(CONNECTION_AUTH_TOKEN_KEY),
+    () => localStorage.getItem(CONNECTION_AUTH_TOKEN_KEY) ?? undefined,
     () => (window as any)?.[CONNECTION_AUTH_TOKEN_KEY],
     () => (globalThis as any)?.[CONNECTION_AUTH_TOKEN_KEY],
     () => (parent.window as any)?.[CONNECTION_AUTH_TOKEN_KEY],
   ]
 
-  let value: string | undefined
-
   for (const getter of getters) {
     try {
-      value = getter()
+      const value = getter()
       if (value)
-        break
+        return value
     }
     catch {}
   }
 
-  if (!value)
-    value = randomToken()
+  // No token yet — the client is unpaired and must exchange a one-time code
+  // (see `requestTrustWithCode`) to obtain a node-issued token.
+  return undefined
+}
 
-  localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, value)
-  ;(globalThis as any)[CONNECTION_AUTH_TOKEN_KEY] = value
-  return value
+function persistAuthToken(token: string): void {
+  try {
+    localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, token)
+  }
+  catch {}
+  ;(globalThis as any)[CONNECTION_AUTH_TOKEN_KEY] = token
 }
 
 function findConnectionMetaFromWindows(): ConnectionMeta | undefined {
@@ -223,7 +237,7 @@ export async function getDevframeRpcClient(
   const context: DevframeRpcContext = {
     rpc: undefined!,
   }
-  const authToken = getConnectionAuthTokenFromWindows(options.authToken)
+  const authToken = getStoredAuthToken(options.authToken)
   const clientRpc: DevframeClientRpcHost = new RpcFunctionsCollectorBase<DevframeRpcClientFunctions, DevframeRpcContext>(context)
 
   async function fetchJsonFromBases(path: string): Promise<any> {
@@ -283,6 +297,13 @@ export async function getDevframeRpcClient(
         wsOptions: options.wsOptions,
       })
 
+  // Channel name kept for cross-tab interop with the Vite DevTools auth page.
+  let authChannel: BroadcastChannel | undefined
+  try {
+    authChannel = new BroadcastChannel('devframe-auth')
+  }
+  catch {}
+
   const rpc: DevframeRpcClient = {
     events,
     get isTrusted() {
@@ -293,10 +314,22 @@ export async function getDevframeRpcClient(
     requestTrust: mode.requestTrust,
     requestTrustWithToken: async (token: string) => {
       // Update stored token for future reconnections
-      localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, token)
-      ;(globalThis as any)[CONNECTION_AUTH_TOKEN_KEY] = token
+      persistAuthToken(token)
       return mode.requestTrustWithToken(token)
     },
+    requestTrustWithCode: async (code: string) => {
+      const token = await mode.requestTrustWithCode(code)
+      if (!token)
+        return false
+      // Persist the node-issued token and share it with sibling tabs so they
+      // become trusted without re-entering the code.
+      persistAuthToken(token)
+      try {
+        authChannel?.postMessage({ type: 'auth-update', authToken: token })
+      }
+      catch {}
+      return true
+    },
     call: mode.call,
     callEvent: mode.callEvent,
     callOptional: mode.callOptional,
@@ -313,17 +346,15 @@ export async function getDevframeRpcClient(
   context.rpc = rpc
   void mode.requestTrust()
 
-  // Listen for auth updates from other tabs (e.g., auth URL page).
-  // Channel name kept for cross-tab interop with the Vite DevTools auth page.
-  try {
-    const bc = new BroadcastChannel('devframe-auth')
-    bc.onmessage = (event) => {
+  // Listen for auth updates from other tabs (e.g., the auth page, or another
+  // tab that just completed a code exchange).
+  if (authChannel) {
+    authChannel.onmessage = (event) => {
       if (event.data?.type === 'auth-update' && event.data.authToken) {
         rpc.requestTrustWithToken(event.data.authToken)
       }
     }
   }
-  catch {}
 
   return rpc
 }