fix(client): clarify isolated connection defaults and auth flow

Author: dvcolomban

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

@@ -1,5 +1,6 @@
 import type {
   DevframeConnection,
+  SetupDevframeConnectionOptions,
 } from './index'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { setupDevframeConnection } from './index'
@@ -89,7 +90,7 @@ describe('isolated connection setup', () => {
     expect(readGlobal('__DEVFRAME_CONNECTION_META__')).toBe(storedConnection.connectionMeta)
   })
 
-  it.each([{}, { connection: { isolated: false } }])(
+  it.each([{}, { connection: {} }, { connection: { isolated: false } }])(
     'retains default cache discovery with %j',
     async (options) => {
       expect.assertions(5)
@@ -130,3 +131,33 @@ describe('isolated connection setup', () => {
     expect(parentWindow.__DEVFRAME_CONNECTION__).toBe(storedConnection)
   })
 })
+
+describe.each(['provided', 'fetched'] as const)('shared credentials with %s metadata', (metadataSource) => {
+  it.each([
+    { name: 'explicit token overrides metadata and storage', authToken: 'explicit-token', metadataToken: 'metadata-token', storedToken: 'stored-token', expectedToken: 'explicit-token' },
+    { name: 'metadata token overrides storage', authToken: undefined, metadataToken: 'metadata-token', storedToken: 'stored-token', expectedToken: 'metadata-token' },
+    { name: 'local storage supplies a missing token', authToken: undefined, metadataToken: undefined, storedToken: 'stored-token', expectedToken: 'stored-token' },
+    { name: 'window storage supplies a missing token', authToken: undefined, metadataToken: undefined, storedToken: null, expectedToken: 'window-token' },
+  ])('$name', async ({ authToken, metadataToken, storedToken, expectedToken }) => {
+    expect.assertions(4)
+    vi.stubGlobal('__DEVFRAME_CONNECTION__', undefined)
+    vi.stubGlobal('__DEVFRAME_CONNECTION_META__', undefined)
+    vi.stubGlobal('__DEVFRAME_CONNECTION_AUTH_TOKEN__', 'window-token')
+    getItem.mockReturnValue(storedToken)
+    const connectionMeta = { backend: 'static' as const, authToken: metadataToken }
+    const options: SetupDevframeConnectionOptions = {
+      baseURL: 'http://requested.example/',
+      authToken,
+    }
+    if (metadataSource === 'provided')
+      options.connectionMeta = connectionMeta
+    else
+      fetchMetadata.mockResolvedValue(Response.json(connectionMeta))
+
+    const connection = await setupDevframeConnection(options)
+    expect(connection.authToken).toBe(expectedToken)
+    expect(readGlobal('__DEVFRAME_CONNECTION__')).toStrictEqual(connection)
+    expect(setItem).toHaveBeenCalledExactlyOnceWith('__DEVFRAME_CONNECTION_AUTH_TOKEN__', expectedToken)
+    expect(fetchMetadata).toHaveBeenCalledTimes(metadataSource === 'fetched' ? 1 : 0)
+  })
+})

packages/devframe/src/client/connection.ts

@@ -30,7 +30,7 @@ export interface DevframeConnection {
 export interface SetupDevframeConnectionOptions {
   /** Reuse a prepared connection, or configure isolation before resolving its metadata. */
   connection?: DevframeConnection | {
-    isolated: boolean
+    isolated?: boolean
     connectionMeta?: never
     metaBaseUrl?: never
     authToken?: never
@@ -119,6 +119,7 @@ export async function setupDevframeConnection(
   options: SetupDevframeConnectionOptions = {},
 ): Promise<DevframeConnection> {
   const connection = await resolveDevframeConnection(options)
+  /** Apply token precedence once, regardless of how the connection metadata was resolved. */
   const authToken = options.authToken ?? connection.authToken ?? connection.connectionMeta.authToken
   const resolvedConnection = withAuthToken(
     connection,

packages/devframe/src/client/rpc.ts

@@ -427,15 +427,19 @@ export async function getDevframeRpcClient(
 
   /** Channel name kept for cross-tab interop with the Vite DevTools auth page. */
   let authChannel: BroadcastChannel | undefined
-  try {
-    authChannel = connection.isolated ? undefined : new BroadcastChannel('devframe-auth')
+  if (!connection.isolated) {
+    try {
+      authChannel = new BroadcastChannel('devframe-auth')
+    }
+    catch {}
   }
-  catch {}
 
   function updateAuthToken(token: string): void {
     connection = { ...connection, authToken: token }
-    if (!connection.isolated)
-      storeAuthToken(token)
+    if (connection.isolated)
+      return
+
+    storeAuthToken(token)
   }
 
   // Gate outbound calls behind the auth bootstrap below. Without it, a

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

@@ -127,7 +127,7 @@ export interface RpcStreamingClientHost {
 }
 export interface SetupDevframeConnectionOptions {
   connection?: DevframeConnection | {
-    isolated: boolean;
+    isolated?: boolean;
     connectionMeta?: never;
     metaBaseUrl?: never;
     authToken?: never;