feat(client): support isolated RPC connections

Author: dvcolomban

docs/content/8.references/5.browser-api.md

@@ -13,6 +13,7 @@ The options of `connectDevframe()` / `getDevframeRpcClient()`: [Client](/guide/c
 
 | Option | Description |
 |--------|-------------|
+| `isolateConnection` | `true` keeps endpoint discovery and credentials local to this RPC client. Skips shared window/localStorage caches and authentication broadcasts. Default `false`. |
 | `connection` | Connection prepared by `setupDevframeConnection()`. |
 | `baseURL` | Mount path to probe for `__connection.json` (array = fallback). Default `'./'` (relative to `document.baseURI`); use an absolute path (`'/__devframe/'`) from outside the SPA. |
 | `authToken` | Override the auth token (default: a locally-persisted id). |
@@ -23,6 +24,10 @@ The options of `connectDevframe()` / `getDevframeRpcClient()`: [Client](/guide/c
 | `connectionMeta` | Descriptor that skips the `__connection.json` fetch. |
 | `webmcp` | Mirror `agent`-flagged client RPC functions onto the page's WebMCP model context as tools; `false` opts out. Default `true` (applies only when the browser provides one). See [Agent-Native](/guide/agent-native#browser-side-tools-over-webmcp). |
 
+Use `isolateConnection: true` for an external viewer that manages independent endpoints or supplies its own credential persistence. Explicit `connection`, `connectionMeta`, `authToken` and `baseURL` inputs retain their precedence. Token and one-time-code authentication update the RPC client's `connection`; the caller can retain that descriptor for reconnection.
+
+The option applies separately to `setupDevframeConnection()` and `connectDevframe()`. When handing a prepared descriptor to another RPC client, pass `isolateConnection: true` again. URL code consumption and the authentication prompt remain controlled by `otpParam` and `simpleAuth`.
+
 ## RPC client events
 
 Emitted over `rpc.events`: [Events](/guide/client#events).

packages/devframe/src/client/connection-isolation.test.ts

@@ -0,0 +1,130 @@
+import type {
+  DevframeConnection,
+} from './index'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { setupDevframeConnection } from './index'
+
+const storedConnection: DevframeConnection = {
+  connectionMeta: { backend: 'static' },
+  metaBaseUrl: 'http://stored.example/__connection.json',
+  authToken: 'stored-token',
+}
+const explicitConnection: DevframeConnection = {
+  connectionMeta: { backend: 'static' },
+  metaBaseUrl: 'http://explicit.example/__connection.json',
+}
+const getItem = vi.fn<Storage['getItem']>()
+const setItem = vi.fn<Storage['setItem']>()
+const fetchMetadata = vi.fn<typeof fetch>()
+function readGlobal(name: string): unknown {
+  return Reflect.get(globalThis, name)
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubGlobal('window', globalThis)
+  vi.stubGlobal('parent', { window: globalThis })
+  vi.stubGlobal('location', new URL('http://viewer.example/index.html'))
+  vi.stubGlobal('localStorage', { getItem, setItem })
+  vi.stubGlobal('fetch', fetchMetadata)
+  vi.stubGlobal('__DEVFRAME_CONNECTION__', storedConnection)
+  vi.stubGlobal('__DEVFRAME_CONNECTION_META__', storedConnection.connectionMeta)
+  vi.stubGlobal('__DEVFRAME_CONNECTION_AUTH_TOKEN__', 'stored-token')
+  getItem.mockReturnValue('stored-token')
+  fetchMetadata.mockResolvedValue(Response.json({}))
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('isolated connection setup', () => {
+  it('does not discover or persist shared credentials for an explicit isolated connection', async () => {
+    expect.assertions(5)
+    const connection = await setupDevframeConnection({
+      connection: explicitConnection,
+      isolateConnection: true,
+    })
+    expect(connection).toBe(explicitConnection)
+    expect(connection.authToken).toBeUndefined()
+    expect(getItem).not.toHaveBeenCalled()
+    expect(setItem).not.toHaveBeenCalled()
+    expect(readGlobal('__DEVFRAME_CONNECTION__')).toBe(storedConnection)
+  })
+
+  it('fetches the requested base despite a different cached connection', async () => {
+    expect.assertions(6)
+    fetchMetadata.mockResolvedValue(
+      Response.json({ backend: 'static', authToken: 'metadata-token' }),
+    )
+    const connection = await setupDevframeConnection({
+      baseURL: 'http://requested.example/provider/',
+      isolateConnection: true,
+    })
+    expect(fetchMetadata).toHaveBeenCalledExactlyOnceWith(
+      'http://requested.example/provider/__connection.json',
+    )
+    expect(connection.metaBaseUrl).toBe('http://requested.example/provider/__connection.json')
+    expect(connection.authToken).toBe('metadata-token')
+    expect(getItem).not.toHaveBeenCalled()
+    expect(setItem).not.toHaveBeenCalled()
+    expect(readGlobal('__DEVFRAME_CONNECTION__')).toBe(storedConnection)
+  })
+
+  it('accepts explicit metadata and token without reading or writing shared caches', async () => {
+    expect.assertions(6)
+    const connection = await setupDevframeConnection({
+      connectionMeta: { backend: 'static', authToken: 'metadata-token' },
+      baseURL: 'http://requested.example/',
+      authToken: 'explicit-token',
+      isolateConnection: true,
+    })
+    expect(connection.authToken).toBe('explicit-token')
+    expect(connection.metaBaseUrl).toBe('http://requested.example/__connection.json')
+    expect(getItem).not.toHaveBeenCalled()
+    expect(setItem).not.toHaveBeenCalled()
+    expect(fetchMetadata).not.toHaveBeenCalled()
+    expect(readGlobal('__DEVFRAME_CONNECTION_META__')).toBe(storedConnection.connectionMeta)
+  })
+
+  it.each([{}, { isolateConnection: false }])(
+    'retains default cache discovery with %j',
+    async (options) => {
+      expect.assertions(5)
+      const connection = await setupDevframeConnection({
+        baseURL: 'http://ignored.example/',
+        ...options,
+      })
+      expect(connection).toBe(storedConnection)
+      expect(getItem).toHaveBeenCalled()
+      expect(fetchMetadata).not.toHaveBeenCalled()
+      expect(setItem).toHaveBeenCalledExactlyOnceWith(
+        '__DEVFRAME_CONNECTION_AUTH_TOKEN__',
+        'stored-token',
+      )
+      expect(readGlobal('__DEVFRAME_CONNECTION__')).toEqual(storedConnection)
+    },
+  )
+
+  it('ignores accessible-parent caches while retaining fetched metadata resolution', async () => {
+    expect.assertions(5)
+    vi.stubGlobal('__DEVFRAME_CONNECTION__', undefined)
+    vi.stubGlobal('__DEVFRAME_CONNECTION_META__', undefined)
+    vi.stubGlobal('__DEVFRAME_CONNECTION_AUTH_TOKEN__', undefined)
+    const parentWindow = {
+      __DEVFRAME_CONNECTION__: storedConnection,
+      __DEVFRAME_CONNECTION_AUTH_TOKEN__: 'parent-token',
+    }
+    vi.stubGlobal('parent', { window: parentWindow })
+    fetchMetadata.mockResolvedValue(Response.json({ backend: 'static', baseUrl: './nested/__connection.json' }))
+    const connection = await setupDevframeConnection({
+      baseURL: 'http://requested.example/',
+      isolateConnection: true,
+    })
+    expect(connection.metaBaseUrl).toBe('http://requested.example/nested/__connection.json')
+    expect(connection.authToken).toBeUndefined()
+    expect(getItem).not.toHaveBeenCalled()
+    expect(setItem).not.toHaveBeenCalled()
+    expect(parentWindow.__DEVFRAME_CONNECTION__).toBe(storedConnection)
+  })
+})

packages/devframe/src/client/connection.ts

@@ -26,6 +26,15 @@ export interface DevframeConnection {
 }
 
 export interface SetupDevframeConnectionOptions {
+  /**
+   * Keep connection discovery and credentials local to this RPC client.
+   * Skips shared window/localStorage reads and writes, and authentication
+   * broadcasts. Explicit connections, metadata and credentials still apply.
+   * Pass this option again when reusing a prepared connection.
+   *
+   * @default false
+   */
+  isolateConnection?: boolean
   /** Reuse a complete connection prepared in another viewer or JavaScript realm. */
   connection?: DevframeConnection
   /** Use a pre-known descriptor while deriving its source URL from `baseURL`. */
@@ -111,17 +120,27 @@ export function getDevframeConnection(): DevframeConnection | undefined {
 export async function setupDevframeConnection(
   options: SetupDevframeConnectionOptions = {},
 ): Promise<DevframeConnection> {
+  const isolateConnection = options.isolateConnection === true
+  function resolveAuthToken(authToken: string | undefined): string | undefined {
+    if (isolateConnection)
+      return authToken
+    return readStoredAuthToken(authToken)
+  }
+  function finishConnectionSetup(connection: DevframeConnection): DevframeConnection {
+    if (!isolateConnection)
+      storeConnection(connection)
+    return connection
+  }
   if (options.connection) {
     const connection = withAuthToken(
       options.connection,
-      readStoredAuthToken(
+      resolveAuthToken(
         options.authToken
         ?? options.connection.authToken
         ?? options.connection.connectionMeta.authToken,
       ),
     )
-    storeConnection(connection)
-    return connection
+    return finishConnectionSetup(connection)
   }
 
   const bases = Array.isArray(options.baseURL)
@@ -136,26 +155,24 @@ export async function setupDevframeConnection(
        * supplied descriptor resolves from the caller's explicit base.
        */
       metaBaseUrl: resolveMetaBaseUrl(bases[0] ?? './'),
-      authToken: readStoredAuthToken(
+      authToken: resolveAuthToken(
         options.authToken ?? options.connectionMeta.authToken,
       ),
     }
-    storeConnection(connection)
-    return connection
+    return finishConnectionSetup(connection)
   }
 
-  const existing = getDevframeConnection()
+  const existing = isolateConnection ? undefined : getDevframeConnection()
   if (existing) {
     const connection = withAuthToken(
       existing,
-      readStoredAuthToken(
+      resolveAuthToken(
         options.authToken
         ?? existing.authToken
         ?? existing.connectionMeta.authToken,
       ),
     )
-    storeConnection(connection)
-    return connection
+    return finishConnectionSetup(connection)
   }
 
   const errors: Error[] = []
@@ -179,12 +196,11 @@ export async function setupDevframeConnection(
         metaBaseUrl: connectionMeta.baseUrl
           ? new URL(connectionMeta.baseUrl, loadedFrom).href
           : loadedFrom,
-        authToken: readStoredAuthToken(
+        authToken: resolveAuthToken(
           options.authToken ?? connectionMeta.authToken,
         ),
       }
-      storeConnection(connection)
-      return connection
+      return finishConnectionSetup(connection)
     }
     catch (error) {
       errors.push(error as Error)

packages/devframe/src/client/rpc-connection-isolation.test.ts

@@ -0,0 +1,105 @@
+import type { DevframeConnection } from './connection'
+import { DEVFRAME_CONNECTION_KEY } from 'devframe/constants'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { getDevframeRpcClient } from './rpc'
+
+const transport = vi.hoisted(() => ({ close: vi.fn() }))
+
+vi.mock('devframe/rpc/transports/ws-client', () => ({
+  createWsRpcChannel: () => ({ post: vi.fn(), on: vi.fn(), close: transport.close }),
+}))
+vi.mock('devframe/rpc/client', () => ({
+  createRpcClient: () => ({
+    $callEvent: vi.fn(),
+    $call: async (method: string, input: { code?: string }) => {
+      if (method === 'anonymous:devframe:auth:exchange')
+        return { authToken: `issued-${input.code}` }
+      if (method === 'anonymous:devframe:auth')
+        return { isTrusted: true }
+      return {}
+    },
+  }),
+}))
+
+const sharedConnection: DevframeConnection = {
+  connectionMeta: { backend: 'websocket', websocket: { path: '__ws' } },
+  metaBaseUrl: 'http://shared.example/__connection.json',
+  authToken: 'shared-token',
+}
+const storage = { getItem: vi.fn(), setItem: vi.fn() }
+const closeChannel = vi.fn()
+const channel = vi.fn(class {
+  postMessage = vi.fn()
+  close = closeChannel
+})
+const options = { isolateConnection: true, otpParam: false, simpleAuth: false, webmcp: false } as const
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubGlobal('location', new URL('http://viewer.example/'))
+  vi.stubGlobal('navigator', { userAgent: 'test' })
+  vi.stubGlobal('localStorage', storage)
+  vi.stubGlobal('BroadcastChannel', channel)
+  vi.stubGlobal(DEVFRAME_CONNECTION_KEY, sharedConnection)
+  vi.stubGlobal('__DEVFRAME_CONNECTION_AUTH_TOKEN__', 'shared-token')
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+it('keeps independent authentication and reconnection local while closing transports', async () => {
+  expect.assertions(11)
+  const first = await getDevframeRpcClient({
+    ...options,
+    connection: { ...sharedConnection, metaBaseUrl: 'http://first.example/__connection.json', authToken: 'first-token' },
+  })
+  const second = await getDevframeRpcClient({
+    ...options,
+    connection: { ...sharedConnection, metaBaseUrl: 'http://second.example/__connection.json', authToken: 'second-token' },
+  })
+  try {
+    expect(await first.requestTrustWithCode('first-code')).toBe(true)
+    expect(first.connection.authToken).toBe('issued-first-code')
+    expect(second.connection.authToken).toBe('second-token')
+    const recreated = await getDevframeRpcClient({ ...options, connection: second.connection })
+    try {
+      expect(recreated.connection.metaBaseUrl).toBe('http://second.example/__connection.json')
+      expect(recreated.connection.authToken).toBe('second-token')
+      expect(await recreated.requestTrustWithToken('second-updated')).toBe(true)
+      expect(first.connection.authToken).toBe('issued-first-code')
+      expect(Reflect.get(globalThis, '__DEVFRAME_CONNECTION_AUTH_TOKEN__')).toBe('shared-token')
+      expect(storage.setItem).not.toHaveBeenCalled()
+      expect(channel).not.toHaveBeenCalled()
+    }
+    finally {
+      recreated.close?.()
+    }
+  }
+  finally {
+    first.close?.()
+    second.close?.()
+  }
+  expect(transport.close).toHaveBeenCalledTimes(3)
+})
+
+it.each([{}, { isolateConnection: false }])('preserves shared OTP persistence and broadcasts with %j', async (settings) => {
+  expect.assertions(6)
+  const rpcClient = await getDevframeRpcClient({
+    ...options,
+    isolateConnection: undefined,
+    ...settings,
+    connection: sharedConnection,
+  })
+  try {
+    expect(await rpcClient.requestTrustWithCode('shared-code')).toBe(true)
+    expect(rpcClient.connection.authToken).toBe('issued-shared-code')
+    expect(storage.setItem).toHaveBeenLastCalledWith('__DEVFRAME_CONNECTION_AUTH_TOKEN__', 'issued-shared-code')
+    expect(channel).toHaveBeenCalledExactlyOnceWith('devframe-auth')
+    expect(channel.mock.results[0]?.value.postMessage).toHaveBeenCalledExactlyOnceWith({ type: 'auth-update', authToken: 'issued-shared-code' })
+  }
+  finally {
+    rpcClient.close?.()
+  }
+  expect(closeChannel).toHaveBeenCalledOnce()
+})

packages/devframe/src/client/rpc.ts

@@ -330,6 +330,7 @@ export function resolveClientTransport(
 export async function getDevframeRpcClient(
   options: DevframeRpcClientOptions = {},
 ): Promise<DevframeRpcClient> {
+  const isolateConnection = options.isolateConnection === true
   // Default to a relative base: the SPA owns its mount path at runtime, so
   // connection meta and dump shards live alongside `index.html`. An embedded
   // surface inside a host page must pass an explicit `baseURL` - its
@@ -428,7 +429,8 @@ export async function getDevframeRpcClient(
   // Channel name kept for cross-tab interop with the Vite DevTools auth page.
   let authChannel: BroadcastChannel | undefined
   try {
-    authChannel = new BroadcastChannel('devframe-auth')
+    if (!isolateConnection)
+      authChannel = new BroadcastChannel('devframe-auth')
   }
   catch {}
 
@@ -485,18 +487,18 @@ export async function getDevframeRpcClient(
     ensureTrusted: mode.ensureTrusted,
     requestTrust: mode.requestTrust,
     requestTrustWithToken: async (token: string) => {
-      // Update stored token for future reconnections
-      storeAuthToken(token)
+      if (!isolateConnection)
+        storeAuthToken(token)
       connection = { ...connection, authToken: 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.
-      storeAuthToken(token)
+      /** Shared mode also persists the issued token for sibling tabs. */
+      if (!isolateConnection)
+        storeAuthToken(token)
       connection = { ...connection, authToken: token }
       try {
         authChannel?.postMessage({ type: 'auth-update', authToken: token })

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

@@ -125,6 +125,7 @@ export interface RpcStreamingClientHost {
   upload: <T = unknown>(_: string, _: string) => StreamSink<T>;
 }
 export interface SetupDevframeConnectionOptions {
+  isolateConnection?: boolean;
   connection?: DevframeConnection;
   connectionMeta?: ConnectionMeta;
   baseURL?: string | string[];