fix(devframe): validate authentication link origins

Author: antfubot

docs/content/1.guide/14.security.md

@@ -67,6 +67,8 @@ Devtools ready — authenticate this browser: http://localhost:3000/#devframe_ot
 
 The code rides the URL **fragment** (`#devframe_otp=…`), which browsers never send to the server, keeping the single-use code out of access logs and `Referer` headers. `connectDevframe` reads it, exchanges it, and strips it from the URL. Because the link grants trust to whoever opens it within the code's lifetime, print it only to a trusted channel (the terminal).
 
+The link points at the **public origin**. A standalone dev server derives it from its own bound address; an owned listener uses that address regardless of any inbound `Host` header. A handler or middleware without an explicit `origin` derives one from a request only when the request's own origin is loopback or exactly matches an `allowedOrigins` entry — a raw inbound authority and forwarded headers are never trusted. Set `origin` explicitly for non-loopback handler deployments (behind a proxy, on a LAN, or on a public host) so the magic link always resolves to the address you intend.
+
 For your own auth UI, disable built-in handling with `otpParam: false`, then call `authenticateWithUrlOtp(rpc)` or `consumeOtpFromUrl()` from `devframe/client`.
 
 ## Practices for tools built on devframe

docs/content/2.adapters/1.initiate.md

@@ -129,7 +129,7 @@ Fetch handlers only hand over `Request`s, so the host framework binds the RPC so
 
 ## Auth
 
-The running devframe **gates by default**. The interactive OTP handler wires automatically, printing its code/magic-link banner once the public origin is known (the first request, or the `origin` option). Pass `auth: false` for single-user localhost, or a `DevframeAuthHandler` for a custom scheme.
+The running devframe **gates by default**. The interactive OTP handler wires automatically, printing its code/magic-link banner once the public origin is known — from the `origin` option, or derived from a request whose own origin is loopback or exactly matches an `allowedOrigins` entry. A non-loopback deployment (behind a proxy, on a LAN, on a public host) sets `origin` explicitly so the magic link resolves to the intended address; a raw inbound `Host` header and forwarded headers are never trusted. Pass `auth: false` for single-user localhost, or a `DevframeAuthHandler` for a custom scheme.
 
 ## Relation to the other adapters
 

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

@@ -352,6 +352,128 @@ describe('adapters/handler', () => {
     }
   })
 
+  it('a hostile first request never becomes the OTP-link origin; a later loopback one does', async () => {
+    const wsPort = await getPort({ port: 18180, host: '127.0.0.1' })
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const devtools = initDevframe(defineTestDef('handler-poison'), { base: '/__handler-poison/', host: '127.0.0.1', ws: { port: wsPort } })
+
+    try {
+      await devtools.ready
+      // A first request forging a non-loopback Host must not print, adopt, or
+      // register that authority as the magic-link origin.
+      await devtools.handler(new Request('http://evil.example.com/__handler-poison/__connection.json', {
+        headers: { host: 'evil.example.com' },
+      }))
+      expect(spy).not.toHaveBeenCalled()
+
+      // A later loopback request is trusted, adopted, and prints exactly one
+      // link pointing at that origin — the rejected candidate never locked it
+      // out.
+      await devtools.handler(new Request('http://localhost:4321/__handler-poison/__connection.json'))
+      expect(spy).toHaveBeenCalledTimes(1)
+      const link = String(spy.mock.calls[0])
+      expect(link).toContain('http://localhost:4321/#')
+      expect(link).not.toContain('evil.example.com')
+      // The credential rides the fragment; assert only its presence.
+      expect(link).toContain('#devframe_otp=')
+
+      // The first-valid origin is pinned: a second loopback request neither
+      // re-prints nor moves it.
+      await devtools.handler(new Request('http://127.0.0.1:9999/__handler-poison/__connection.json'))
+      expect(spy).toHaveBeenCalledTimes(1)
+    }
+    finally {
+      spy.mockRestore()
+      await devtools.close()
+    }
+  })
+
+  it('adopts an exactly allow-listed non-loopback origin, but rejects a prefix/suffix near-match', async () => {
+    const wsPort = await getPort({ port: 18181, host: '127.0.0.1' })
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const devtools = initDevframe(defineTestDef('handler-allow'), {
+      base: '/__handler-allow/',
+      host: '127.0.0.1',
+      ws: { port: wsPort },
+      allowedOrigins: ['https://tools.example.com'],
+    })
+
+    try {
+      await devtools.ready
+      // Only prefix/suffix-matches the allow-list entry — never adopted.
+      await devtools.handler(new Request('https://tools.example.com.evil.com/__handler-allow/__connection.json', {
+        headers: { host: 'tools.example.com.evil.com' },
+      }))
+      await devtools.handler(new Request('https://evil.tools.example.com/__handler-allow/__connection.json', {
+        headers: { host: 'evil.tools.example.com' },
+      }))
+      expect(spy).not.toHaveBeenCalled()
+
+      // The exact allow-listed origin is adopted.
+      await devtools.handler(new Request('https://tools.example.com/__handler-allow/__connection.json', {
+        headers: { host: 'tools.example.com' },
+      }))
+      expect(spy).toHaveBeenCalledTimes(1)
+      expect(String(spy.mock.calls[0])).toContain('https://tools.example.com/#')
+    }
+    finally {
+      spy.mockRestore()
+      await devtools.close()
+    }
+  })
+
+  it('an explicit origin wins regardless of the inbound Host', async () => {
+    const wsPort = await getPort({ port: 18182, host: '127.0.0.1' })
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const devtools = initDevframe(defineTestDef('handler-pinned'), {
+      base: '/__handler-pinned/',
+      host: '127.0.0.1',
+      ws: { port: wsPort },
+      origin: 'https://pinned.example.com',
+    })
+
+    try {
+      await devtools.ready
+      // A pinned origin needs no request: the banner points at it from the
+      // start, ignoring whatever Host a request forges.
+      expect(spy).toHaveBeenCalledTimes(1)
+      expect(String(spy.mock.calls[0])).toContain('https://pinned.example.com/#')
+
+      await devtools.handler(new Request('http://evil.example.com/__handler-pinned/__connection.json', {
+        headers: { host: 'evil.example.com' },
+      }))
+      expect(spy).toHaveBeenCalledTimes(1)
+      expect(String(spy.mock.calls[0])).toContain('https://pinned.example.com/#')
+      expect(String(spy.mock.calls[0])).not.toContain('evil.example.com')
+    }
+    finally {
+      spy.mockRestore()
+      await devtools.close()
+    }
+  })
+
+  it('canonicalizes the protocol and default port of an adopted origin', async () => {
+    const wsPort = await getPort({ port: 18183, host: '127.0.0.1' })
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const devtools = initDevframe(defineTestDef('handler-canon'), { base: '/__handler-canon/', host: '127.0.0.1', ws: { port: wsPort } })
+
+    try {
+      await devtools.ready
+      // An explicit :80 default port canonicalizes away in the advertised
+      // origin, so the link carries no redundant port.
+      await devtools.handler(new Request('http://localhost:80/__handler-canon/__connection.json', {
+        headers: { host: 'localhost:80' },
+      }))
+      expect(spy).toHaveBeenCalledTimes(1)
+      expect(String(spy.mock.calls[0])).toContain('http://localhost/#')
+      expect(String(spy.mock.calls[0])).not.toContain('localhost:80')
+    }
+    finally {
+      spy.mockRestore()
+      await devtools.close()
+    }
+  })
+
   it('bridge mode: without a distDir only meta + WS are served', async () => {
     const wsPort = await getPort({ port: 18160, host: '127.0.0.1' })
     const devtools = initDevframe(defineTestDef('handler-bridge'), { base: '/__handler-bridge/', auth: false, ws: { port: wsPort } })

packages/devframe/src/adapters/initiate.ts

@@ -95,10 +95,12 @@ export interface InitDevframeOptions {
   mcp?: boolean | McpRouteOptions
   /**
    * Public origin the host app is reachable at (e.g. `http://localhost:3000`),
-   * or a getter for hosts that resolve it late. When omitted (or the getter
-   * returns a falsy value), it is derived lazily from the first request the
-   * handler serves — used for the auth banner's magic link and absolute dock
-   * URLs.
+   * or a getter for hosts that resolve it late. Backs the auth banner's magic
+   * link and absolute dock URLs. When omitted (or the getter returns a falsy
+   * value), it is derived from a served request — but only when that request's
+   * own origin is loopback or exactly matches an `allowedOrigins` entry; a raw
+   * inbound `Host`/URL authority and forwarded headers are never adopted. Set
+   * this explicitly for a non-loopback deployment (proxy, LAN, public host).
    */
   origin?: string | (() => string)
   /**

packages/devframe/src/node/instance-shell.ts

@@ -552,9 +552,11 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
   // listener) — derive it from the first request and let the auth banner
   // wait for it, unless the caller pinned one (as a string or a getter).
   let derivedOrigin: string | undefined
+  function explicitOrigin(): string | undefined {
+    return typeof options.origin === 'function' ? options.origin() : options.origin
+  }
   function currentOrigin(): string | undefined {
-    const explicit = typeof options.origin === 'function' ? options.origin() : options.origin
-    return explicit || derivedOrigin
+    return explicitOrigin() || derivedOrigin
   }
   let authHandler: DevframeAuthHandler | undefined
   let bannerPrinted = false
@@ -602,8 +604,78 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
     }).catch(() => {})
   }
 
-  function noteOrigin(origin: string): void {
-    derivedOrigin ??= origin
+  // `isLoopbackHostname` lives in the WS transport module (whose top-level
+  // `crossws` import instance-shell keeps out of its own static graph), so it
+  // is pulled in lazily and cached the first time a candidate needs checking.
+  // An explicit or already-derived origin short-circuits before this loads, so
+  // the common cases (a pinned dev-server origin, every request after the
+  // first valid one) never touch the transport module.
+  let loopbackCheck: ((hostname: string) => boolean) | undefined
+  async function ensureLoopbackCheck(): Promise<(hostname: string) => boolean> {
+    if (!loopbackCheck) {
+      const mod = await import('devframe/rpc/transports/ws-server')
+      loopbackCheck = mod.isLoopbackHostname
+    }
+    return loopbackCheck
+  }
+
+  /**
+   * Canonicalize a request-derived origin candidate and decide whether it may
+   * back the advertised origin. That origin becomes the destination of the OTP
+   * magic link, so a raw inbound authority is never trusted: a candidate is
+   * adopted only when its parsed hostname is loopback, or when its canonical
+   * origin exactly matches a configured `allowedOrigins` entry. A dynamic
+   * `WsOriginRegistry` or a disabled gate (`false`) offers no static list to
+   * match, so non-loopback adoption stays off there — those deployments supply
+   * an explicit `origin`. Returns the canonical origin, or `undefined` to
+   * reject (credentials, a path, a query, a fragment, a malformed port, a
+   * non-HTTP(S) scheme, or an untrusted host). Forwarded headers are never
+   * consulted.
+   */
+  function validateOriginCandidate(
+    candidate: string,
+    isLoopback: (hostname: string) => boolean,
+  ): string | undefined {
+    let url: URL
+    try {
+      url = new URL(candidate)
+    }
+    catch {
+      return undefined
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+      return undefined
+    // A canonical origin carries no credentials, path, query, or fragment; any
+    // of these means the candidate was a full or poisoned URL, not a bare
+    // authority safe to advertise.
+    if (url.username || url.password || url.search || url.hash)
+      return undefined
+    if (url.pathname !== '/' && url.pathname !== '')
+      return undefined
+    const canonical = url.origin
+    if (canonical === 'null')
+      return undefined
+    if (isLoopback(url.hostname))
+      return canonical
+    const allowed = options.allowedOrigins
+    if (Array.isArray(allowed) && allowed.includes(canonical))
+      return canonical
+    return undefined
+  }
+
+  /**
+   * Consider a request-derived origin candidate. Keeps the first-valid-origin
+   * behavior: an invalid candidate is ignored without setting `derivedOrigin`,
+   * so it neither prints a banner nor registers a poisoned origin, and a later
+   * valid candidate can still be adopted. Silent by design — a diagnostic here
+   * would let an unauthenticated request amplify log noise.
+   */
+  async function noteOrigin(candidate: string): Promise<void> {
+    if (derivedOrigin === undefined && !explicitOrigin()) {
+      const accepted = validateOriginCandidate(candidate, await ensureLoopbackCheck())
+      if (accepted !== undefined)
+        derivedOrigin = accepted
+    }
     maybePrintBanner()
     maybeRegister()
   }
@@ -854,7 +926,7 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
 
   async function handleRequest(request: Request): Promise<Response> {
     await initPromise
-    noteOrigin(new URL(request.url).origin)
+    await noteOrigin(new URL(request.url).origin)
     const response = await app.fetch(request)
     // Normalize a miss to a bare 404: an unmounted path falls through to
     // h3's default JSON-error handler, but for an asset host a body-less
@@ -885,7 +957,7 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
         const host = req.headers.host
         if (host) {
           const encrypted = (req.socket as { encrypted?: boolean }).encrypted
-          noteOrigin(`${encrypted ? 'https' : 'http'}://${host}`)
+          await noteOrigin(`${encrypted ? 'https' : 'http'}://${host}`)
         }
         if (!nodeHandler) {
           const { toNodeHandler } = await import('h3/node')

plans/README.md

@@ -11,7 +11,7 @@ Generated by the improve skill on 2026-09-01 at commit `2d978f84`. Execute in th
 | 003 | Enforce shared-state exposure policy on direct MCP reads | P1 | S | 002 | TODO |
 | 004 | Contain remote asset materialization | P1 | S | - | TODO |
 | 005 | Block Data Inspector prototype-chain writes | P1 | S | - | TODO |
-| 006 | Validate request-derived authentication-link origins | P1 | M | - | TODO |
+| 006 | Validate request-derived authentication-link origins | P1 | M | - | DONE |
 | 007 | Reject pre-existing symlink escapes from filesystem roots | P2 | M | - | TODO |
 
 Status values: TODO | IN PROGRESS | DONE | BLOCKED (with reason) | REJECTED (with rationale)