fix(starter): gate RPC auth by default instead of trusting every connection

`auth: false` was set on every real surface (the CLI's cli.auth, and both
Vite playgrounds) - each one auto-trusted any connection that could reach
its port, with no interactive handshake at all. That's the framework's
documented opt-out for a tool that's genuinely single-user and
loopback-only, not a sane starter default: a copy-pasted template should
teach the secure-by-default posture, not silently disable it everywhere.

Leave `auth` unset on `src/devframe.ts`'s `cli` and both playground
configs, so they fall through to devframe's interactive OTP gate (the
same default every hosted adapter already ships). A developer who wants
to skip the prompt for a one-off loopback session now reaches for the
CLI's existing `--no-auth` flag per invocation instead of a baked-in
opt-out.

The single playground's e2e suite still needs to drive the bridge
without solving an interactive code, so `playwright.config.ts`'s
`webServer.env` sets an explicit `DEVFRAME_E2E` flag that the playground
config checks to disable auth *only* for that automated run - a plain
`pnpm run play:single` stays gated. The unit test's own ephemeral,
loopback-only `initDevframe` instance keeps `auth: false` outright (it's
a private test fixture torn down in `afterAll`, not a listening surface
anyone else can reach) - now with a comment explaining why that one is
fine.

This PR was created with the help of an agent.

Author: antfubot

starter/README.md

@@ -17,6 +17,8 @@ pnpm run lint
 pnpm run typecheck
 ```
 
+`pnpm run dev` and both playgrounds gate by default: opening the printed URL walks you through devframe's interactive OTP handshake (a 6-digit code) before the SPA can call RPC. That's intentional - see the `auth` comments in `src/devframe.ts` and `playground/*/vite.config.ts` before reaching for `auth: false`, which trusts every connection that can reach the port. For a one-off loopback-only session, pass `--no-auth` to the CLI instead (`pnpm run dev -- --no-auth`).
+
 ## File map
 
 | Path | Purpose |

starter/playground/hub/vite.config.ts

@@ -36,8 +36,12 @@ export default defineConfig({
       devframes: [entry],
       // Use the default hub-ui, rebrand it to match the starter's accent color.
       ui: createUi({ branding: { primaryColor: '#10b981', productName: 'Devframe Starter' } }),
-      // Ungated localhost demo - skip the trust handshake.
-      auth: false,
+      // `auth` is left unset: gated by default (devframe's interactive
+      // OTP - a 6-digit code printed to the terminal, entered once in the
+      // reference UI's authorization view). `auth: false` would trust
+      // every connection that can reach this port instead; only reach for
+      // it on a tool that's genuinely single-user and loopback-only. See
+      // docs/guide/security.md.
     }),
   ],
 })

starter/playground/single/vite.config.ts

@@ -1,3 +1,4 @@
+import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { devframeViteBridge } from '@devframes/vite/single'
 import { defineConfig } from 'vite'
@@ -29,8 +30,15 @@ export default defineConfig({
   plugins: [
     devframeViteBridge(devframe, {
       base: devframe.basePath,
-      // Ungated localhost demo - skip the trust handshake.
-      auth: false,
+      // Gated by default (devframe's interactive OTP) when unset, same as
+      // `bin.mjs dev` - see the comment on `cli` in `src/devframe.ts`.
+      // `DEVFRAME_E2E` is set only by `playwright.config.ts`'s
+      // `webServer.env`, so the automated e2e suite can drive the bridge
+      // without solving the OTP prompt; a plain `pnpm run play:single`
+      // still gates. Don't widen this to a bare `auth: false` - that
+      // trusts every connection that can reach the port, not just this
+      // test harness. See docs/guide/security.md.
+      auth: process.env.DEVFRAME_E2E ? false : undefined,
     }),
   ],
 })

starter/playwright.config.ts

@@ -26,7 +26,14 @@ export default defineConfig({
   ],
   webServer: {
     command: 'pnpm run play:single',
-    env: { DEVFRAME_E2E_CWD: fixtureCwd },
+    env: {
+      DEVFRAME_E2E_CWD: fixtureCwd,
+      // Tells the bridge to skip the interactive OTP handshake - see the
+      // `auth` comment in `playground/single/vite.config.ts`. Real usage
+      // (a human running `pnpm run play:single`) never sets this and stays
+      // gated.
+      DEVFRAME_E2E: '1',
+    },
     // The SPA (this playground's own `index.html`) serves from Vite's root -
     // see `playground/single/vite.config.ts` for why it can't share the
     // RPC bridge's `/__devframe-starter/` base.

starter/src/devframe.ts

@@ -25,9 +25,15 @@ export default defineDevframe({
     command: 'devframe-starter',
     port: 7391,
     distDir,
-    // Single-user localhost demo - skip the trust handshake so the served
-    // SPA can call RPC without an OTP round-trip.
-    auth: false,
+    // `auth` is deliberately left unset: gated by default (devframe's
+    // interactive OTP handshake - a 6-digit code printed to the terminal
+    // that trusts the browser before it can call any RPC function).
+    // `auth: false` would trust *any* connection that can reach the port
+    // instead - see docs/guide/security.md before reaching for it. A
+    // developer who wants to skip the prompt for a one-off loopback-only
+    // session can pass `--no-auth` per run (`devframe-starter --no-auth`)
+    // rather than baking the opt-out into the definition.
+    //
     // Serve the agent (MCP) surface over the dev server's `/__mcp` route.
     mcp: true,
   },

starter/test/rpc.test.ts

@@ -37,6 +37,10 @@ describe('rpc functions', () => {
       // directly - an address-family mismatch that reads as a silent hang.
       host: '127.0.0.1',
       ws: { sidecar: true },
+      // Fine here (unlike the "real" surfaces in `src/devframe.ts` and
+      // `playground/`): this instance is a private, ephemeral test fixture
+      // - bound to loopback, torn down in `afterAll`, and never reachable
+      // by anything but this test process.
       auth: false,
     })
     await instance.ready