refactor(auth)!: rename OTP url param and expose client pairing utilities

Rename the magic-link query parameter from `devframe_auth` to `devframe_otp`
(and the constant to `DEVFRAME_OTP_URL_PARAM`) to distinguish it from the
bearer-token param `devframe_auth_token`.

Expose reusable client utilities from `devframe/client` so higher-level
integrations (e.g. Vite DevTools) can consume the URL OTP themselves:
`readOtpFromUrl`, `consumeOtpFromUrl` (read + strip), and `pairWithUrlOtp(rpc)`
(consume + exchange). `connectDevframe`'s built-in handling now reuses
`pairWithUrlOtp` and is opt-out via the renamed `otpParam: false` option.

Rename the node helper to `buildOtpPairingUrl` for consistency.

BREAKING CHANGE: `DEVFRAME_AUTH_URL_PARAM` → `DEVFRAME_OTP_URL_PARAM` (value
`devframe_otp`), `buildAuthPairingUrl` → `buildOtpPairingUrl`, and the
`connectDevframe` option `autoPairParam` → `otpParam`. All unreleased.

Author: antfubot

docs/guide/client.md

@@ -89,7 +89,7 @@ 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.
+To pair without typing, a host can print a link embedding the code (`buildOtpPairingUrl(origin)`); `connectDevframe` reads the `devframe_otp` query parameter, exchanges it, and strips it from the URL. Rename it with the `otpParam` option, or set `otpParam: false` and drive pairing yourself with the exposed `pairWithUrlOtp(rpc)` / `consumeOtpFromUrl()` utilities.
 
 ### Re-using an existing token
 

docs/guide/security.md

@@ -33,13 +33,15 @@ The bearer token is a secret. It travels to the server on the WebSocket URL (`?d
 
 ### 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):
+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 `buildOtpPairingUrl(origin)` (devframe stays headless, so the host prints its own banner):
 
 ```
-Devtools ready — pair this browser: http://localhost:3000/?devframe_auth=123456
+Devtools ready — pair this browser: http://localhost:3000/?devframe_otp=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.
+`connectDevframe` reads the `devframe_otp` parameter, exchanges it, and removes it from the URL before anything else. 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.
+
+Higher-level integrations can drive their own pairing UI instead: disable the built-in handling with the `otpParam: false` client option, then call the exposed `pairWithUrlOtp(rpc)` (consume the code from the URL and exchange it) or `consumeOtpFromUrl()` (read and strip the code) from `devframe/client`.
 
 ## Practices for tools built on devframe
 

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

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { consumeOtpFromUrl, pairWithUrlOtp, readOtpFromUrl } from '../otp'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('otp url helpers', () => {
+  it('reads the OTP from the page URL query string (default param)', () => {
+    vi.stubGlobal('location', { search: '?devframe_otp=123456&x=1', href: 'http://localhost:3000/?devframe_otp=123456&x=1' })
+    expect(readOtpFromUrl()).toBe('123456')
+  })
+
+  it('supports a custom param name', () => {
+    vi.stubGlobal('location', { search: '?code=999', href: 'http://localhost:3000/?code=999' })
+    expect(readOtpFromUrl('code')).toBe('999')
+  })
+
+  it('returns undefined when the param is absent and is safe without location', () => {
+    vi.stubGlobal('location', { search: '?x=1', href: 'http://localhost:3000/?x=1' })
+    expect(readOtpFromUrl()).toBeUndefined()
+    vi.stubGlobal('location', undefined)
+    expect(readOtpFromUrl()).toBeUndefined()
+    expect(() => consumeOtpFromUrl()).not.toThrow()
+  })
+
+  it('consume reads then strips the OTP via history.replaceState, keeping other params', () => {
+    const replaceState = vi.fn()
+    vi.stubGlobal('location', { search: '?devframe_otp=123456&x=1', href: 'http://localhost:3000/?devframe_otp=123456&x=1' })
+    vi.stubGlobal('history', { state: { a: 1 }, replaceState })
+
+    expect(consumeOtpFromUrl()).toBe('123456')
+    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 not touch the URL when no OTP is present', () => {
+    const replaceState = vi.fn()
+    vi.stubGlobal('location', { search: '?x=1', href: 'http://localhost:3000/?x=1' })
+    vi.stubGlobal('history', { state: null, replaceState })
+
+    expect(consumeOtpFromUrl()).toBeUndefined()
+    expect(replaceState).not.toHaveBeenCalled()
+  })
+})
+
+describe('pairWithUrlOtp', () => {
+  it('exchanges the OTP via the client and resolves true on success', async () => {
+    vi.stubGlobal('location', { search: '?devframe_otp=123456', href: 'http://localhost:3000/?devframe_otp=123456' })
+    vi.stubGlobal('history', { state: null, replaceState: vi.fn() })
+    const requestTrustWithCode = vi.fn().mockResolvedValue(true)
+
+    const ok = await pairWithUrlOtp({ isTrusted: false, requestTrustWithCode })
+
+    expect(requestTrustWithCode).toHaveBeenCalledWith('123456')
+    expect(ok).toBe(true)
+  })
+
+  it('returns false (and does not exchange) when no OTP is present', async () => {
+    vi.stubGlobal('location', { search: '', href: 'http://localhost:3000/' })
+    const requestTrustWithCode = vi.fn()
+
+    const ok = await pairWithUrlOtp({ isTrusted: false, requestTrustWithCode })
+
+    expect(requestTrustWithCode).not.toHaveBeenCalled()
+    expect(ok).toBe(false)
+  })
+
+  it('skips the exchange but still consumes the OTP when already trusted', async () => {
+    const replaceState = vi.fn()
+    vi.stubGlobal('location', { search: '?devframe_otp=123456', href: 'http://localhost:3000/?devframe_otp=123456' })
+    vi.stubGlobal('history', { state: null, replaceState })
+    const requestTrustWithCode = vi.fn()
+
+    const ok = await pairWithUrlOtp({ isTrusted: true, requestTrustWithCode })
+
+    expect(ok).toBe(true)
+    expect(requestTrustWithCode).not.toHaveBeenCalled()
+    expect(replaceState).toHaveBeenCalledTimes(1)
+  })
+})

packages/devframe/src/client/__tests__/otp.test.ts

@@ -1,5 +1,6 @@
 import { getDevframeRpcClient } from './rpc'
 
+export * from './otp'
 export * from './rpc'
 export * from './rpc-streaming'
 

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

@@ -0,0 +1,66 @@
+import type { DevframeRpcClient } from './rpc'
+import { DEVFRAME_OTP_URL_PARAM } from 'devframe/constants'
+
+// Browser-only helpers for "magic link" pairing: a host prints a URL carrying a
+// one-time pairing code (OTP), and the client reads it, exchanges it for a
+// token, and removes it from the address bar. Only the short-lived, single-use
+// OTP ever rides the URL — never the resulting bearer token.
+
+/**
+ * Read a one-time pairing code from the current page URL's query string,
+ * without side effects. Returns `undefined` when the parameter is absent.
+ */
+export function readOtpFromUrl(param: string = DEVFRAME_OTP_URL_PARAM): string | undefined {
+  try {
+    return new URLSearchParams(globalThis.location?.search).get(param) || undefined
+  }
+  catch {
+    return undefined
+  }
+}
+
+function stripParamFromUrl(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 {}
+}
+
+/**
+ * Read the one-time code from the page URL and remove it 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`. Returns the code, or `undefined` when
+ * absent.
+ */
+export function consumeOtpFromUrl(param: string = DEVFRAME_OTP_URL_PARAM): string | undefined {
+  const code = readOtpFromUrl(param)
+  if (code)
+    stripParamFromUrl(param)
+  return code
+}
+
+/**
+ * Consume a one-time code from the page URL (see {@link consumeOtpFromUrl}) and
+ * exchange it for a token via the client. Resolves `true` when the client is
+ * paired (already trusted, or the exchange succeeded), and `false` when no code
+ * is present or the exchange failed.
+ *
+ * Higher-level integrations (e.g. Vite DevTools) that want to drive their own
+ * pairing UI can disable `connectDevframe`'s built-in handling with
+ * `otpParam: false` and call this — or {@link consumeOtpFromUrl} — themselves.
+ */
+export async function pairWithUrlOtp(
+  rpc: Pick<DevframeRpcClient, 'isTrusted' | 'requestTrustWithCode'>,
+  options: { param?: string } = {},
+): Promise<boolean> {
+  const code = consumeOtpFromUrl(options.param ?? DEVFRAME_OTP_URL_PARAM)
+  if (!code)
+    return false
+  if (rpc.isTrusted)
+    return true
+  return rpc.requestTrustWithCode(code)
+}

packages/devframe/src/client/index.ts

@@ -4,12 +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,
+  DEVFRAME_OTP_URL_PARAM,
 } from 'devframe/constants'
 import { RpcCacheManager, RpcFunctionsCollectorBase } from 'devframe/rpc'
 import { createEventEmitter } from 'devframe/utils/events'
-import { clearAuthCodeFromUrl, readAuthCodeFromUrl } from './auth-url'
+import { pairWithUrlOtp } from './otp'
 import { createRpcSharedStateClientHost } from './rpc-shared-state'
 import { createStaticRpcClientMode } from './rpc-static'
 import { createRpcStreamingClientHost } from './rpc-streaming'
@@ -39,12 +39,13 @@ export interface DevframeRpcClientOptions {
    */
   authToken?: string
   /**
-   * Query-param name on the page URL carrying a one-time pairing code for
+   * Query-param name on the page URL carrying a one-time pairing code (OTP) 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'`.
+   * URL. Set `false` to disable — e.g. integrations that drive their own
+   * pairing via `pairWithUrlOtp`. Default: `'devframe_otp'`.
    */
-  autoPairParam?: string | false
+  otpParam?: string | false
   wsOptions?: Partial<WsRpcChannelOptions>
   rpcOptions?: Partial<BirpcOptions<DevframeRpcServerFunctions, DevframeRpcClientFunctions, boolean>>
   cacheOptions?: boolean | Partial<RpcCacheOptions>
@@ -364,15 +365,11 @@ export async function getDevframeRpcClient(
   // 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)
-    }
-  }
+  // Integrations that drive their own pairing UI opt out with `otpParam: false`
+  // and call `pairWithUrlOtp` / `consumeOtpFromUrl` directly.
+  const otpParam = options.otpParam ?? DEVFRAME_OTP_URL_PARAM
+  if (otpParam)
+    void pairWithUrlOtp(rpc, { param: otpParam })
 
   // Listen for auth updates from other tabs (e.g., the auth page, or another
   // tab that just completed a code exchange).

packages/devframe/src/client/otp.ts

@@ -17,10 +17,10 @@ export const DEVFRAME_RPC_DUMP_DIRNAME = '__rpc-dump'
 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
+ * Page-URL query parameter carrying a one-time pairing code (OTP) for "magic
+ * link" auth. A host can print a link like `<origin>/?devframe_otp=<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).
+ * from the URL. See `buildOtpPairingUrl` (node) and the `pairWithUrlOtp` /
+ * `consumeOtpFromUrl` client utilities (or `connectDevframe`'s `otpParam`).
  */
-export const DEVFRAME_AUTH_URL_PARAM = 'devframe_auth'
+export const DEVFRAME_OTP_URL_PARAM = 'devframe_otp'

packages/devframe/src/client/rpc.ts

@@ -1,7 +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 { DEVFRAME_OTP_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. */
@@ -44,14 +44,14 @@ export function refreshTempAuthToken(): string {
 }
 
 /**
- * Build a "magic link" pairing URL that embeds a one-time code as a query
+ * Build a "magic link" pairing URL that embeds a one-time code (OTP) 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 {
+export function buildOtpPairingUrl(baseUrl: string, code: string = tempAuthCode): string {
   const url = new URL(baseUrl)
-  url.searchParams.set(DEVFRAME_AUTH_URL_PARAM, code)
+  url.searchParams.set(DEVFRAME_OTP_URL_PARAM, code)
   return url.href
 }