refactor(devframe): extract origin utils into devframe/utils/origin

Address review: move isLoopbackHostname/isAllowedOrigin out of the
crossws-carrying ws-server transport into a dependency-free
devframe/utils/origin, and group the auth-link origin validation
(validateOriginCandidate) alongside them. instance-shell now imports the
validator statically instead of dynamically importing the whole transport
module. ws-server re-exports both predicates to keep its public API path
intact; sse-server and the MCP fetch gate import the check from the util
directly.

Author: antfubot

packages/devframe/package.json

@@ -56,6 +56,7 @@
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
     "./utils/nostics": "./dist/utils/nostics.mjs",
     "./utils/open": "./dist/utils/open.mjs",
+    "./utils/origin": "./dist/utils/origin.mjs",
     "./utils/remote-assets": "./dist/utils/remote-assets.mjs",
     "./utils/simple-schema": "./dist/utils/simple-schema.mjs",
     "./utils/serve-static": "./dist/utils/serve-static.mjs",

packages/devframe/src/adapters/mcp/fetch.ts

@@ -1,6 +1,6 @@
 import type { DevframeNodeContext } from 'devframe/types'
 import { createMcpHandler } from '@modelcontextprotocol/server'
-import { isAllowedOrigin } from 'devframe/rpc/transports/ws-server'
+import { isAllowedOrigin } from 'devframe/utils/origin'
 import { bridgeListChanged, buildMcpServerFromContext } from './build-server'
 
 export interface CreateMcpFetchHandlerOptions {

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

@@ -14,6 +14,7 @@ import type { DevframeInstanceRecord, DevframeInstanceRegistration } from './ins
 import type { ContextRpcServer } from './rpc-core'
 import { createServer } from 'node:http'
 import process from 'node:process'
+import { validateOriginCandidate } from 'devframe/utils/origin'
 import { defineHandler, H3 as H3App, toNodeHandler } from 'h3'
 import { joinURL, withLeadingSlash, withoutLeadingSlash, withoutTrailingSlash } from 'ufo'
 import { DEVFRAME_SSE_ROUTE, DEVFRAME_WS_ROUTE } from '../constants'
@@ -604,75 +605,25 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
     }).catch(() => {})
   }
 
-  // `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.
+   * Consider a request-derived origin candidate for the advertised public
+   * origin (which backs the OTP magic link). Delegates the trust decision to
+   * {@link validateOriginCandidate}: only a loopback host or an exact
+   * `allowedOrigins` match is adopted, so a raw inbound `Host`/URL authority
+   * never redirects the credential-bearing link. A dynamic `WsOriginRegistry`
+   * or a disabled gate offers no static list, so it passes none and only
+   * loopback candidates qualify.
+   *
+   * 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> {
+  function noteOrigin(candidate: string): void {
     if (derivedOrigin === undefined && !explicitOrigin()) {
-      const accepted = validateOriginCandidate(candidate, await ensureLoopbackCheck())
+      const allowed = options.allowedOrigins
+      const accepted = validateOriginCandidate(candidate, Array.isArray(allowed) ? allowed : undefined)
       if (accepted !== undefined)
         derivedOrigin = accepted
     }
@@ -926,7 +877,7 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
 
   async function handleRequest(request: Request): Promise<Response> {
     await initPromise
-    await noteOrigin(new URL(request.url).origin)
+    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
@@ -957,7 +908,7 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
         const host = req.headers.host
         if (host) {
           const encrypted = (req.socket as { encrypted?: boolean }).encrypted
-          await noteOrigin(`${encrypted ? 'https' : 'http'}://${host}`)
+          noteOrigin(`${encrypted ? 'https' : 'http'}://${host}`)
         }
         if (!nodeHandler) {
           const { toNodeHandler } = await import('h3/node')

packages/devframe/src/rpc/transports/sse-server.ts

@@ -3,9 +3,9 @@ import type { RpcFunctionDefinitionAny } from '../types'
 import type { DevframeNodeRpcSessionMeta, DevframeRpcConnection } from './session'
 import type { WsOriginRegistry } from './ws-server'
 import { DEVFRAME_SSE_SESSION_HEADER } from 'devframe/constants'
+import { isAllowedOrigin } from 'devframe/utils/origin'
 import { createRpcWireCodec, peekRpcWireFrame } from '../wire-codec'
 import { createRpcSessionMeta } from './session'
-import { isAllowedOrigin } from './ws-server'
 
 export interface SseRpcTransportOptions {
   /**

packages/devframe/src/rpc/transports/ws-server.ts

@@ -13,6 +13,7 @@ import { createServer as createHttpsServer } from 'node:https'
 import crossws from 'crossws/adapters/node'
 import { DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM } from 'devframe/constants'
 import { randomToken, timingSafeEqual } from 'devframe/utils/crypto-token'
+import { isAllowedOrigin } from 'devframe/utils/origin'
 import { createRpcWireCodec } from '../wire-codec'
 import { createRpcSessionMeta } from './session'
 
@@ -226,62 +227,13 @@ function pathMatches(a: string, b: string): boolean {
   return strip(a) === strip(b)
 }
 
-/**
- * Whether `hostname` names a loopback host: `localhost` (or any `*.localhost`
- * subdomain), the IPv6 loopback `::1`, or an IPv4 literal inside the
- * `127.0.0.0/8` loopback block.
- *
- * The IPv4 case is matched **structurally** — the whole hostname must be a
- * canonical dotted-decimal IPv4 literal whose first octet is `127`. A bare
- * `startsWith('127.')` prefix check would also accept an attacker-controlled
- * DNS name that merely *begins* with `127.` (`127.attacker.example`,
- * `127.0.0.1.attacker.example`), letting a cross-origin browser page defeat
- * the loopback origin gate that guards the RPC/MCP surface (a DNS-rebinding /
- * cross-site WebSocket-hijacking bypass). Requiring a real IPv4 literal keeps
- * genuine loopback addresses (`127.0.0.1`, `127.5.5.5`) allowed while rejecting
- * those DNS names.
- */
-export function isLoopbackHostname(hostname: string): boolean {
-  const h = hostname.replace(/^\[|\]$/g, '') // strip IPv6 brackets
-  if (h === 'localhost' || h.endsWith('.localhost') || h === '::1')
-    return true
-  return isLoopbackIPv4(h)
-}
-
-/** A canonical dotted-decimal IPv4 literal in `127.0.0.0/8`. */
-function isLoopbackIPv4(hostname: string): boolean {
-  const octets = hostname.split('.')
-  if (octets.length !== 4 || !octets.every(isDecimalOctet))
-    return false
-  return Number(octets[0]) === 127
-}
-
-/** A single canonical IPv4 octet: 1–3 digits, no leading zero, value 0–255. */
-function isDecimalOctet(part: string): boolean {
-  if (!/^\d{1,3}$/.test(part) || (part.length > 1 && part[0] === '0'))
-    return false
-  return Number(part) <= 255
-}
-
-/**
- * Default origin policy for a localhost dev tool: allow requests with no
- * `Origin` header (native, non-browser clients), allow any loopback origin
- * (so cross-port localhost dev setups keep working), and allow explicitly
- * configured origins. Everything else — a real remote page in the dev's
- * browser — is rejected.
- */
-export function isAllowedOrigin(origin: string | undefined, allowedOrigins: readonly string[]): boolean {
-  if (!origin)
-    return true
-  if (allowedOrigins.includes(origin))
-    return true
-  try {
-    return isLoopbackHostname(new URL(origin).hostname)
-  }
-  catch {
-    return false
-  }
-}
+// The loopback / origin predicates live in the dependency-free
+// `devframe/utils/origin` module so consumers that only need one check (e.g.
+// the instance shell's auth-link origin validation) don't import this whole
+// `crossws`-carrying transport. Re-exported here to keep the historical
+// `devframe/rpc/transports/ws-server` import path for `isAllowedOrigin` /
+// `isLoopbackHostname` intact.
+export { isAllowedOrigin, isLoopbackHostname } from 'devframe/utils/origin'
 
 function isWsOriginRegistry(
   value: readonly string[] | WsOriginRegistry | false | undefined,

packages/devframe/src/utils/origin.ts

@@ -0,0 +1,113 @@
+/**
+ * Origin and hostname predicates shared by the RPC transports (the WS upgrade,
+ * SSE, and MCP origin gates) and the instance shell's authentication-link
+ * origin validation. Kept dependency-free and runtime-agnostic so any consumer
+ * can pull in a single check without dragging in a transport's `crossws`
+ * import.
+ */
+
+/**
+ * Whether `hostname` names a loopback host: `localhost` (or any `*.localhost`
+ * subdomain), the IPv6 loopback `::1`, or an IPv4 literal inside the
+ * `127.0.0.0/8` loopback block.
+ *
+ * The IPv4 case is matched **structurally** — the whole hostname must be a
+ * canonical dotted-decimal IPv4 literal whose first octet is `127`. A bare
+ * `startsWith('127.')` prefix check would also accept an attacker-controlled
+ * DNS name that merely *begins* with `127.` (`127.attacker.example`,
+ * `127.0.0.1.attacker.example`), letting a cross-origin browser page defeat
+ * the loopback origin gate that guards the RPC/MCP surface (a DNS-rebinding /
+ * cross-site WebSocket-hijacking bypass). Requiring a real IPv4 literal keeps
+ * genuine loopback addresses (`127.0.0.1`, `127.5.5.5`) allowed while rejecting
+ * those DNS names.
+ */
+export function isLoopbackHostname(hostname: string): boolean {
+  const h = hostname.replace(/^\[|\]$/g, '') // strip IPv6 brackets
+  if (h === 'localhost' || h.endsWith('.localhost') || h === '::1')
+    return true
+  return isLoopbackIPv4(h)
+}
+
+/** A canonical dotted-decimal IPv4 literal in `127.0.0.0/8`. */
+function isLoopbackIPv4(hostname: string): boolean {
+  const octets = hostname.split('.')
+  if (octets.length !== 4 || !octets.every(isDecimalOctet))
+    return false
+  return Number(octets[0]) === 127
+}
+
+/** A single canonical IPv4 octet: 1–3 digits, no leading zero, value 0–255. */
+function isDecimalOctet(part: string): boolean {
+  if (!/^\d{1,3}$/.test(part) || (part.length > 1 && part[0] === '0'))
+    return false
+  return Number(part) <= 255
+}
+
+/**
+ * Default origin policy for a localhost dev tool: allow requests with no
+ * `Origin` header (native, non-browser clients), allow any loopback origin
+ * (so cross-port localhost dev setups keep working), and allow explicitly
+ * configured origins. Everything else — a real remote page in the dev's
+ * browser — is rejected.
+ */
+export function isAllowedOrigin(origin: string | undefined, allowedOrigins: readonly string[]): boolean {
+  if (!origin)
+    return true
+  if (allowedOrigins.includes(origin))
+    return true
+  try {
+    return isLoopbackHostname(new URL(origin).hostname)
+  }
+  catch {
+    return false
+  }
+}
+
+/**
+ * Canonicalize a request-derived origin candidate and decide whether it may
+ * back a devframe's advertised public 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 an `allowedOrigins` entry. A
+ * caller with no static allow-list (a dynamic registry or a disabled gate)
+ * passes none, so non-loopback adoption stays off — those deployments supply
+ * an explicit origin instead.
+ *
+ * Unlike {@link isAllowedOrigin} — which accepts any origin-shaped string —
+ * this rejects a candidate carrying credentials, a path, a query, a fragment,
+ * a malformed port, or a non-HTTP(S) scheme, and returns the **canonical**
+ * origin (default ports and casing normalized) rather than a boolean, so the
+ * value that ends up in the magic link is always canonical. Forwarded headers
+ * are never consulted.
+ *
+ * @returns the canonical origin to adopt, or `undefined` to reject.
+ */
+export function validateOriginCandidate(
+  candidate: string,
+  allowedOrigins?: readonly string[],
+): 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 (isLoopbackHostname(url.hostname))
+    return canonical
+  if (allowedOrigins?.includes(canonical))
+    return canonical
+  return undefined
+}

packages/devframe/test/runtime-agnostic.test.ts

@@ -14,6 +14,7 @@ const AGNOSTIC_ENTRIES = [
   'utils/events.mjs',
   'utils/hash.mjs',
   'utils/nanoid.mjs',
+  'utils/origin.mjs',
   'utils/shared-state.mjs',
   'utils/streaming-channel.mjs',
   'utils/structured-clone.mjs',

packages/devframe/tsdown.config.ts

@@ -78,6 +78,7 @@ const clientEntries = {
   'utils/events': 'src/utils/events.ts',
   'utils/hash': 'src/utils/hash.ts',
   'utils/nanoid': 'src/utils/nanoid.ts',
+  'utils/origin': 'src/utils/origin.ts',
   'utils/simple-schema': 'src/utils/simple-schema.ts',
   'utils/shared-state': 'src/utils/shared-state.ts',
   'utils/streaming-channel': 'src/utils/streaming-channel.ts',
@@ -159,6 +160,7 @@ export default defineConfig([
             resolve(distDir, 'utils/events.mjs'),
             resolve(distDir, 'utils/hash.mjs'),
             resolve(distDir, 'utils/nanoid.mjs'),
+            resolve(distDir, 'utils/origin.mjs'),
             resolve(distDir, 'utils/simple-schema.mjs'),
             resolve(distDir, 'utils/shared-state.mjs'),
             resolve(distDir, 'utils/streaming-channel.mjs'),

tsconfig.base.json

@@ -85,6 +85,9 @@
       "devframe/utils/open": [
         "./packages/devframe/src/utils/open.ts"
       ],
+      "devframe/utils/origin": [
+        "./packages/devframe/src/utils/origin.ts"
+      ],
       "devframe/utils/remote-assets": [
         "./packages/devframe/src/utils/remote-assets.ts"
       ],