fix(client): gate outbound calls behind the auth bootstrap handshake

connectDevframe()/getDevframeRpcClient() kicks off the auth bootstrap
(stored token, then the URL's magic-link OTP, then a native-prompt
fallback) without waiting for it, so it can return the client right
away. A caller's very first RPC calls — e.g. a component's onMount,
fired the instant connectDevframe() resolves — raced that still
in-flight sequence: the socket was already open, so the transport sent
them straight through, and the server rejected them with DF0036
because trust hadn't landed yet, even though the exact same call would
succeed a moment later once the handshake completed.

rpc.call/callOptional/callEvent now hold anything issued before the
first bootstrap attempt settles and release it (or fail fast, if the
handshake ultimately failed) once it does. This lives once in
devframe's client RPC core, so every plugin's standalone/hosted SPA
gets it automatically — no plugin-level changes needed.

Co-authored-by: opencode <noreply@opencode.ai>

Author: antfubot

docs/guide/client.md

@@ -80,6 +80,8 @@ if (!trusted) {
 }
 ```
 
+`connectDevframe()` kicks off that same handshake (stored token, then a magic-link OTP on the page URL, then — top-level pages only — a native prompt) the moment it resolves, without making the caller wait for it. `rpc.call` / `rpc.callOptional` / `rpc.callEvent` know about that in-flight handshake internally and hold anything issued before it settles, so application code can call a trusted method right away — e.g. in a component's `onMount` — without an explicit `ensureTrusted()` guard just to avoid a race. Reach for `ensureTrusted()` when you want to reflect the pending state in the UI (a spinner, a "waiting for auth" banner), not to make calls safe.
+
 ### Authenticating with a one-time code
 
 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:

docs/guide/security.md

@@ -24,6 +24,8 @@ Exactly one rule decides what an untrusted connection may call: **a method is re
 
 `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).
 
+On the client, `connectDevframe()` kicks off the handshake below without waiting for it, so a naive client could otherwise race it — sending a trusted call over the freshly-opened socket before the server has had a chance to answer `anonymous:devframe:auth`, hitting this exact gate. `rpc.call` / `rpc.callOptional` / `rpc.callEvent` hold anything issued while that first handshake is still in flight and release it once the handshake settles, so application code never has to special-case this window itself.
+
 ## 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.

packages/devframe/src/client/rpc-auth-gate.test.ts

@@ -0,0 +1,140 @@
+import type { ConnectionMeta } from 'devframe/types'
+import type { DevframeRpcClientMode } from './rpc'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// `getDevframeRpcClient` kicks off the auth bootstrap (`requestTrust`, then
+// the URL OTP, then a native-prompt fallback) without awaiting it, so it can
+// return the client immediately. The regression this guards is a caller's
+// very first `rpc.call(...)` — issued the moment `connectDevframe()` resolves
+// — racing that still-in-flight bootstrap: without a gate, the transport
+// sends the call over an already-open-but-not-yet-trusted socket and the
+// server rejects it with DF0036, even though the exact same call succeeds a
+// moment later once the handshake lands.
+//
+// Exercising this through a real WebSocket would mean hand-rolling birpc's
+// wire protocol, so instead this mocks `./rpc-ws` with a controllable fake
+// mode — a `requestTrust()` the test resolves on its own schedule, and a
+// `call` spy whose invocation timing is exactly what's under test.
+const fakeMode = vi.hoisted(() => {
+  const requestTrustGate = { resolve: undefined as ((value: boolean) => void) | undefined }
+  const call = vi.fn(async () => 'ok')
+  const callOptional = vi.fn(async () => 'ok')
+  const callEvent = vi.fn(async () => {})
+  return { requestTrustGate, call, callOptional, callEvent }
+})
+
+vi.mock('./rpc-ws', () => ({
+  createWsRpcClientMode: vi.fn((): DevframeRpcClientMode => ({
+    isTrusted: false,
+    status: 'connecting',
+    connectionError: null,
+    ensureTrusted: async () => true,
+    requestTrust: () => new Promise<boolean>((resolve) => {
+      fakeMode.requestTrustGate.resolve = resolve
+    }),
+    requestTrustWithToken: async () => true,
+    requestTrustWithCode: async () => null,
+    call: fakeMode.call as DevframeRpcClientMode['call'],
+    callOptional: fakeMode.callOptional as DevframeRpcClientMode['callOptional'],
+    callEvent: fakeMode.callEvent as DevframeRpcClientMode['callEvent'],
+  })),
+}))
+
+class FakeBroadcastChannel {
+  onmessage: ((e: any) => void) | null = null
+  postMessage(): void {}
+  close(): void {}
+}
+
+const connectionMeta: ConnectionMeta = { backend: 'websocket', websocket: { path: '__ws' } }
+
+describe('getDevframeRpcClient — auth bootstrap gates outbound calls', () => {
+  beforeEach(() => {
+    fakeMode.requestTrustGate.resolve = undefined
+    fakeMode.call.mockClear()
+    fakeMode.callOptional.mockClear()
+    fakeMode.callEvent.mockClear()
+    vi.stubGlobal('BroadcastChannel', FakeBroadcastChannel)
+    vi.stubGlobal('navigator', { userAgent: 'test' })
+    vi.stubGlobal('location', {
+      protocol: 'http:',
+      host: 'localhost:5173',
+      hostname: 'localhost',
+      href: 'http://localhost:5173/index.html',
+      origin: 'http://localhost:5173',
+    })
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('holds `call` until the in-flight bootstrap settles, instead of sending it early', async () => {
+    const { getDevframeRpcClient } = await import('./rpc')
+    const rpc = await getDevframeRpcClient({
+      connectionMeta,
+      otpParam: false,
+      simpleAuth: false,
+    })
+
+    // Fired the instant the client is available — mirrors a component's
+    // `onMount` calling a trusted method right after `connectDevframe()`.
+    const pending = rpc.call('test:probe' as any)
+    await Promise.resolve()
+    await Promise.resolve()
+    // The bootstrap's `requestTrust()` hasn't resolved yet — the call must
+    // not have reached the (mocked) transport.
+    expect(fakeMode.call).not.toHaveBeenCalled()
+
+    // The handshake lands.
+    fakeMode.requestTrustGate.resolve?.(true)
+
+    await expect(pending).resolves.toBe('ok')
+    expect(fakeMode.call).toHaveBeenCalledTimes(1)
+    expect(fakeMode.call).toHaveBeenCalledWith('test:probe')
+  })
+
+  it('holds `callOptional` and `callEvent` the same way', async () => {
+    const { getDevframeRpcClient } = await import('./rpc')
+    const rpc = await getDevframeRpcClient({
+      connectionMeta,
+      otpParam: false,
+      simpleAuth: false,
+    })
+
+    const pendingOptional = rpc.callOptional('test:optional' as any)
+    const pendingEvent = rpc.callEvent('test:event' as any)
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(fakeMode.callOptional).not.toHaveBeenCalled()
+    expect(fakeMode.callEvent).not.toHaveBeenCalled()
+
+    fakeMode.requestTrustGate.resolve?.(true)
+
+    await expect(pendingOptional).resolves.toBe('ok')
+    await pendingEvent
+    expect(fakeMode.callOptional).toHaveBeenCalledTimes(1)
+    expect(fakeMode.callEvent).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops gating once the first bootstrap attempt has settled', async () => {
+    const { getDevframeRpcClient } = await import('./rpc')
+    const rpc = await getDevframeRpcClient({
+      connectionMeta,
+      otpParam: false,
+      simpleAuth: false,
+    })
+
+    fakeMode.requestTrustGate.resolve?.(true)
+    // Let the bootstrap's own promise chain fully settle before the next
+    // call — a few microtask ticks cover `await mode.requestTrust()`
+    // resuming, `bootstrapAuth()` returning, and its `.then()` flipping
+    // `bootstrapAuthSettled`.
+    for (let i = 0; i < 5; i++)
+      await Promise.resolve()
+
+    await rpc.call('test:probe' as any)
+    // Sent straight through — no more waiting once bootstrap is over.
+    expect(fakeMode.call).toHaveBeenCalledTimes(1)
+  })
+})

packages/devframe/src/client/rpc.ts

@@ -408,6 +408,30 @@ export async function getDevframeRpcClient(
   }
   catch {}
 
+  // Gate outbound calls behind the auth bootstrap kicked off below (stored
+  // auth token, then the URL's magic-link OTP, then — standalone/top-level
+  // only — a native prompt). Without this, a caller's very first RPC calls
+  // (fired the moment `connectDevframe()` resolves — e.g. a component's
+  // `onMount`) race that still-in-flight sequence: the socket is open, so
+  // the transport happily sends them, and the server rejects them with
+  // DF0036 because trust hasn't landed yet — even though the exact same call
+  // would succeed a moment later. `bootstrapAuthPromise` is assigned once
+  // `bootstrapAuth()` is kicked off further down; these closures read the
+  // variable at call time, so the gate is live even though it's declared
+  // before that assignment happens. Once the first bootstrap attempt has
+  // settled (trusted, refused, or given up), `bootstrapAuthSettled` flips
+  // for good and every later call skips the gate entirely — this only ever
+  // holds the first wave of calls.
+  let bootstrapAuthPromise: Promise<void> | undefined
+  let bootstrapAuthSettled = false
+  function gateOnBootstrapAuth<F extends (...args: any[]) => any>(fn: F): F {
+    return ((...args: any[]) => {
+      if (bootstrapAuthSettled || !bootstrapAuthPromise)
+        return fn(...args)
+      return bootstrapAuthPromise.then(() => fn(...args))
+    }) as F
+  }
+
   const rpc: DevframeRpcClient = {
     events,
     get isTrusted() {
@@ -440,9 +464,9 @@ export async function getDevframeRpcClient(
       catch {}
       return true
     },
-    call: mode.call,
-    callEvent: mode.callEvent,
-    callOptional: mode.callOptional,
+    call: gateOnBootstrapAuth(mode.call),
+    callEvent: gateOnBootstrapAuth(mode.callEvent),
+    callOptional: gateOnBootstrapAuth(mode.callOptional),
     client: clientRpc,
     sharedState: undefined!,
     streaming: undefined!,
@@ -522,7 +546,14 @@ export async function getDevframeRpcClient(
       return
     await runSimpleAuthPrompt()
   }
-  void bootstrapAuth()
+  // Always resolves (never rejects) regardless of `bootstrapAuth`'s outcome —
+  // the gate only cares that the first attempt is *over*, not whether it
+  // succeeded; a rejection here must never leak into unrelated calls waiting
+  // on `bootstrapAuthPromise`.
+  bootstrapAuthPromise = bootstrapAuth().then(
+    () => { bootstrapAuthSettled = true },
+    () => { bootstrapAuthSettled = true },
+  )
 
   // Listen for auth updates from other tabs (e.g., the auth page, or another
   // tab that just completed a code exchange).