feat(cli): enable auth by default and auto-authorize --open via OTP

Every built-in plugin's standalone CLI now gates the dev server behind
devframe's interactive OTP handshake by default (code-server, git,
inspect, messages, terminals, data-inspector previously opted out;
og/a11y already defaulted on). Each plugin keeps an `auth` option to
opt back out for single-user/CI use.

To keep that gate from adding friction, `--open` now asks the resolved
auth handler to rewrite the launched URL — the interactive handler
embeds the current OTP (via buildOtpAuthUrl), so the opened tab
authenticates automatically instead of prompting for a code.

Adds DevframeAuthHandler.buildOpenUrl (optional) as the seam, wires it
through maybeOpenBrowser in the dev adapter, and updates docs/skill
guidance + tsnapi snapshots accordingly.

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

Author: antfubot

docs/adapters/cac.md

@@ -75,8 +75,7 @@ defineDevframe({
     portRange: [7777, 9000], // passed through to get-port-please
     random: false, // passed through to get-port-please
     host: '127.0.0.1', // default host; --host overrides
-    open: true, // auto-open the browser on dev start
-    auth: false, // skip the trust handshake (single-user localhost)
+    open: true, // auto-open the browser on dev start; embeds the current OTP so the tab lands authenticated
     configure(cli) { // contribute capability flags/commands
       cli.option('--config <file>', 'Custom config file')
         .option('--no-files', 'Skip file matching')

docs/guide/devframe-definition.md

@@ -185,8 +185,7 @@ defineDevframe({
     portRange: [9876, 10000], // forwarded to get-port-please
     random: false, // forwarded to get-port-please
     host: 'localhost', // default host; --host overrides
-    open: true, // auto-open the browser on dev start
-    auth: false, // skip the trust handshake (single-user localhost)
+    open: true, // auto-open the browser on dev start; embeds the current OTP so the tab lands authenticated
     configure(cli) { // contribute capability flags/commands
       cli
         .option('--my-flag <value>', 'Tool-specific flag')
@@ -208,7 +207,7 @@ defineDevframe({
 | `portRange` | `[number, number]` | Port scan range, passed through to `get-port-please`. |
 | `random` | `boolean` | Prefer a random open port. |
 | `host` | `string` | Default bind host. |
-| `open` | `boolean \| string` | `true` opens the origin, a string opens a specific path, `false` disables. Matches the `--open` / `--no-open` flags. |
+| `open` | `boolean \| string` | `true` opens the origin, a string opens a specific path, `false` disables. Matches the `--open` / `--no-open` flags. When `auth` is on, the opened URL embeds the current OTP so the tab authenticates automatically. |
 | `auth` | `boolean` | Disable the WS trust flow when the tool is localhost-only and single-user. Default `true`. |
 | `configure` | `(cli: CAC) => void` | Contribute capability flags/commands. Runs before `createCac`'s `configureCli` option so the final tool author always has the last word. |
 

docs/guide/security.md

@@ -79,7 +79,7 @@ Client methods (`devframe/client`): `requestTrustWithCode(code)` (exchange a cod
 
 ### Magic-link authentication
 
-To skip typing, a host can print a link that embeds the code and open the browser straight into an authenticated session. Build it from the current code with `buildOtpAuthUrl(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 an authenticated session. The standalone CLI (`createCac` / `createDevServer`) does this automatically for `--open`: when the server is auth-gated, the browser it launches already carries the current code, so the tab lands authenticated with no prompt at all. Build the link yourself from the current code with `buildOtpAuthUrl(origin)` (devframe stays headless, so the host prints its own banner):
 
 ```
 Devtools ready — authenticate this browser: http://localhost:3000/?devframe_otp=123456

docs/guide/standalone-cli.md

@@ -43,8 +43,7 @@ const devframe = defineDevframe({
     distDir,
     port: 7777,
     portRange: [7777, 9000],
-    open: true,
-    auth: false, // single-user localhost — skip the trust handshake
+    open: true, // auth defaults to on; `--open` embeds the current OTP so the tab lands authenticated
     configure(cli) {
       cli
         .option('--config <file>', 'Config file path')

packages/devframe/src/adapters/__tests__/dev.test.ts

@@ -4,13 +4,18 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { createRpcClient } from 'devframe/rpc/client'
 import { createWsRpcChannel } from 'devframe/rpc/transports/ws-client'
+import { open } from 'devframe/utils/open'
 import { getPort } from 'get-port-please'
 import { describe, expect, it, vi } from 'vitest'
 import { WebSocket } from 'ws'
 import { getTempAuthCode } from '../../node/auth/state'
 import { defineDevframe } from '../../types/devframe'
 import { createDevServer, resolveDevServerPort } from '../dev'
 
+// `--open` is exercised directly (asserting the URL handed to the OS opener)
+// rather than actually launching a browser in CI.
+vi.mock('devframe/utils/open', () => ({ open: vi.fn(async () => {}) }))
+
 function connectWsClient(host: string, port: number, authToken?: string) {
   return createRpcClient<DevframeRpcServerFunctions, DevframeRpcClientFunctions>(
     {} as DevframeRpcClientFunctions,
@@ -323,6 +328,62 @@ describe('adapters/dev', () => {
     }
   })
 
+  it('`--open` embeds the current OTP so the opened tab authenticates automatically', async () => {
+    const devframe = defineDevframe({
+      id: 'devframe-auth-open',
+      name: 'Auth Open',
+      version: '0.0.0',
+      packageName: 'devframe-test',
+      homepage: 'https://example.test',
+      description: 'Test devframe.',
+      setup: () => {},
+    })
+    const host = '127.0.0.1'
+    const port = await getPort({ port: 19415, host })
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const mockedOpen = vi.mocked(open)
+    mockedOpen.mockClear()
+    const code = getTempAuthCode()
+    const handle = await createDevServer(devframe, { host, port, openBrowser: true })
+
+    try {
+      expect(mockedOpen).toHaveBeenCalledTimes(1)
+      const [target] = mockedOpen.mock.calls[0]
+      expect(target).toBe(`http://localhost:${port}/?devframe_otp=${code}`)
+    }
+    finally {
+      spy.mockRestore()
+      await handle.close()
+    }
+  })
+
+  it('`--open` opens the plain origin when `auth: false` (no handler to embed a code)', async () => {
+    const devframe = defineDevframe({
+      id: 'devframe-auth-open-off',
+      name: 'Auth Open Off',
+      version: '0.0.0',
+      packageName: 'devframe-test',
+      homepage: 'https://example.test',
+      description: 'Test devframe.',
+      cli: { auth: false },
+      setup: () => {},
+    })
+    const host = '127.0.0.1'
+    const port = await getPort({ port: 19416, host })
+    const mockedOpen = vi.mocked(open)
+    mockedOpen.mockClear()
+    const handle = await createDevServer(devframe, { host, port, openBrowser: true })
+
+    try {
+      expect(mockedOpen).toHaveBeenCalledTimes(1)
+      const [target] = mockedOpen.mock.calls[0]
+      expect(target).toBe(`http://localhost:${port}/`)
+    }
+    finally {
+      await handle.close()
+    }
+  })
+
   it('opts out with `auth: false`: the server auto-trusts and skips the gate', async () => {
     const devframe = defineDevframe({
       id: 'devframe-auth-off',

packages/devframe/src/adapters/dev.ts

@@ -241,7 +241,7 @@ export async function createDevServer(
       // so the code is on screen by the time a browser lands on the page.
       authHandler?.printBanner()
       await options.onReady?.(info)
-      await maybeOpenBrowser(def, flags, `${info.origin}${basePath}`, options.openBrowser)
+      await maybeOpenBrowser(def, flags, `${info.origin}${basePath}`, options.openBrowser, authHandler)
     },
   })
 
@@ -303,6 +303,7 @@ async function maybeOpenBrowser(
   flags: Record<string, unknown>,
   origin: string,
   override: boolean | string | undefined,
+  authHandler: DevframeAuthHandler | undefined,
 ): Promise<void> {
   const flagsOpen = flags.open as boolean | string | undefined
   const cliOpen = def.cli?.open
@@ -314,8 +315,12 @@ async function maybeOpenBrowser(
   const target = typeof resolved === 'string'
     ? withBase(resolved, origin)
     : origin
+  // When the server is auth-gated, let the handler embed a one-time
+  // credential (e.g. the OTP query param) in the opened URL so the tab
+  // lands already authorized instead of prompting the user.
+  const authorizedTarget = authHandler?.buildOpenUrl?.(target) ?? target
   try {
-    await open(target)
+    await open(authorizedTarget)
   }
   catch {
     // Failing to launch a browser shouldn't break the dev server.

packages/devframe/src/node/auth/handler.ts

@@ -40,4 +40,13 @@ export interface DevframeAuthHandler {
    * call repeatedly; it only prints once per code.
    */
   printBanner: () => void
+  /**
+   * Rewrite a URL the CLI is about to open in the browser (`--open`) so the
+   * tab lands already authenticated — e.g. appending the current OTP as a
+   * query param. Called with the fully-resolved target URL; return it
+   * unchanged to opt out. Optional: a handler that doesn't need this (e.g.
+   * one gated by a pre-shared bearer token instead of an interactive code)
+   * can omit it and the URL opens as-is.
+   */
+  buildOpenUrl?: (url: string) => string
 }

packages/devframe/src/recipes/interactive-auth.ts

@@ -166,10 +166,15 @@ export function createInteractiveAuth(
     verifyAuthToken(token, session, storage)
   }
 
+  function buildOpenUrl(url: string): string {
+    return buildOtpAuthUrl(url)
+  }
+
   return {
     rpcFunctions: [anonymousAuth, anonymousAuthExchange, revoke],
     authorize,
     onConnect: onConnect as DevframeAuthHandler['onConnect'],
     printBanner,
+    buildOpenUrl,
   }
 }

plugins/code-server/src/index.ts

@@ -55,10 +55,10 @@ export function createCodeServerDevframe(options: CodeServerOptions = {}): Devfr
       portRange: options.portRange,
       random: options.random,
       distDir: existsSync(resolvedDist) ? resolvedDist : undefined,
-      // Single-user localhost tool: auto-trust the connection so the launcher's
-      // shared-state subscription and the auth handoff work without a manual
-      // round-trip. Hosted adapters supply their own auth layer.
-      auth: false,
+      // Gate the standalone launcher by default; `maybeOpenBrowser` folds the
+      // current OTP into the `--open` URL so the tab lands already trusted.
+      // Hosted adapters supply their own auth layer and ignore this.
+      auth: options.auth ?? true,
     },
     spa: { loader: 'none' },
     async setup(ctx) {

plugins/code-server/src/types.ts

@@ -174,6 +174,13 @@ export interface CodeServerOptions {
   portRange?: [number, number]
   /** Prefer a random port for the launcher SPA. */
   random?: boolean
+  /**
+   * Require the trust handshake on the standalone launcher server. Enabled
+   * by default — `--open` embeds the current OTP in the opened URL, so the
+   * tab authenticates automatically without extra prompts. Hosted adapters
+   * manage their own auth and ignore this.
+   */
+  auth?: boolean
 }
 
 /** Options for `mode: 'tunnel'`. */