@dsh-plus/access-gate 0.2.4 → 0.3.1

package/src/cookie.ts

@@ -0,0 +1,208 @@
+/**
+ * 官方 browser-auth cookie 铸造（IP 信任自动登录的核心纯函数面）。
+ *
+ * 目标：对「IP 信任白名单来源」的未认证请求，在服务端自签与官方
+ * `?token=` 启动令牌交换产物等价的 `dsh-auth-*` cookie——写进响应后
+ * 浏览器落罐，后续 /api、WS 的官方 requestRejection() 自然通过，
+ * 用户全程无感、免启动 token。
+ *
+ * 契约（对 dsh 0.1.2-alpha.2 / 0.1.3-alpha.2 官方 client-connection
+ * browser-auth 逐行核实，见 docs/README.md「信任模型」）：
+ * - 签名密钥持久化于 $DSH_HOME/.credentials.yaml
+ *   （records → client-connection/browser-session → payload.secret，
+ *   base64url 无填充 32B；跨重启不变）；
+ * - cookie 名 = `dsh-auth-<base64url(sha256(authority))>`，
+ *   authority = 请求 Host 经 `new URL('http://'+host).host` 归一化
+ *   （host:port，含端口；与官方 requestAuthority() 同实现）；
+ * - cookie 值 = `v1.<base64url(payload-json)>.<base64url(hmac-sha256(secret, body))>`，
+ *   payload 键序固定 {"version":1,"authority":…,"issuedAt":ms,"expiresAt":ms}，
+ *   JSON.stringify 紧凑序列化；
+ * - 属性与官方 sessionCookie() 同款：Max-Age/Expires/Path=HttpOnly/SameSite=Strict；
+ * - 服务端校验 `expiresAt - issuedAt <= cookieMaxAgeDays`（默认 30 天）且
+ *   下界 1 天；本模块取官方默认 30 天。
+ *
+ * 本模块不 import 官方包：密钥从文件读取（dshctl auth.py 同款定向文本
+ * 解析），crypto 用 node: 内置。全部为纯函数/可注入，测试零网络零依赖。
+ * 安全：任何解析失败都返回明确错误（fail-loud / fail-safe），绝不产出
+ * 半成品 cookie。
+ * @module access-gate/cookie
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 官方 cookie 名前缀（client-connection browser-auth 常量）。 */
+export const COOKIE_PREFIX = 'dsh-auth-'
+/** payload version（官方 COOKIE_PAYLOAD_VERSION）。 */
+const PAYLOAD_VERSION = 1
+/** 密钥长度（官方 SECRET_BYTES）。 */
+const SECRET_BYTES = 32
+/** 自签 cookie 有效期：官方默认 cookieMaxAgeDays。 */
+export const COOKIE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000
+/** .credentials.yaml 中 browser-session 段名（AUTH_RECORD_KEY 的 id）。 */
+const SECRET_SECTION = 'client-connection/browser-session'
+/** payload 键序（官方 encodeCookie 的 JSON.stringify 紧凑序列化键序）。 */
+const PAYLOAD_KEYS = ['version', 'authority', 'issuedAt', 'expiresAt'] as const
+
+function base64url(data: Buffer): string {
+  return data.toString('base64url')
+}
+
+/** 取请求 authority（官方 requestAuthority 同款：Host → URL.host，host:port）。 */
+export function requestAuthority(headers: { host?: unknown }): string | undefined {
+  const host = headers.host
+  if (typeof host !== 'string' || host === '') return undefined
+  try {
+    return new URL(`http://${host}`).host
+  } catch {
+    return undefined
+  }
+}
+
+/** 官方 cookie 名（authority 绑定，同 requestAuthority 输出）。 */
+export function cookieName(authority: string): string {
+  return COOKIE_PREFIX + base64url(createHash('sha256').update(authority).digest())
+}
+
+/** 校验签名（官方 isAuthenticated/decodeCookie 同款防时序侧信道比较）。 */
+function validSignature(value: string, secret: Buffer): boolean {
+  const [version, body, encodedSignature] = value.split('.')
+  if (version !== 'v1' || body === undefined || encodedSignature === undefined) return false
+  const actual = Buffer.from(encodedSignature, 'base64url')
+  if (actual.byteLength === 0) return false
+  const expected = createHmac('sha256', secret).update(body).digest()
+  return actual.byteLength === expected.byteLength && timingSafeEqual(actual, expected)
+}
+
+/** 解码 cookie 载荷（返回 null = 值损坏/签名不符/字段缺失，语义与官方一致）。 */
+export function decodeCookiePayload(
+  value: string,
+  secret: Buffer,
+): { authority: string; issuedAt: number; expiresAt: number } | null {
+  if (!validSignature(value, secret)) return null
+  const body = value.split('.')[1]
+  if (body === undefined) return null
+  let decoded: unknown
+  try {
+    decoded = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'))
+  } catch {
+    return null
+  }
+  if (
+    typeof decoded !== 'object' ||
+    decoded === null ||
+    !('version' in decoded) ||
+    (decoded as { version?: unknown }).version !== PAYLOAD_VERSION ||
+    typeof (decoded as { authority?: unknown }).authority !== 'string' ||
+    !Number.isSafeInteger((decoded as { issuedAt?: unknown }).issuedAt) ||
+    !Number.isSafeInteger((decoded as { expiresAt?: unknown }).expiresAt)
+  ) {
+    return null
+  }
+  const { authority, issuedAt, expiresAt } = decoded as {
+    authority: string
+    issuedAt: number
+    expiresAt: number
+  }
+  const now = Date.now()
+  if (issuedAt > now || expiresAt <= now || expiresAt <= issuedAt) return null
+  if (expiresAt - issuedAt > COOKIE_MAX_AGE_MS) return null
+  return { authority, issuedAt, expiresAt }
+}
+
+/**
+ * 校验既有 cookie 是否（对给定 authority）有效——等价官方
+ * `browserAuth.isAuthenticated`（无 authority 匹配即 false）。
+ */
+export function isAuthenticatedCookie(
+  cookieHeader: string | undefined,
+  authority: string,
+  secret: Buffer,
+): boolean {
+  if (cookieHeader === undefined) return false
+  const name = cookieName(authority)
+  for (const segment of cookieHeader.split(';')) {
+    const at = segment.indexOf('=')
+    if (at === -1 || segment.slice(0, at).trim() !== name) continue
+    const payload = decodeCookiePayload(segment.slice(at + 1).trim(), secret)
+    if (payload === null) return false
+    return payload.authority === authority
+  }
+  return false
+}
+
+/** 定向解析 .credentials.yaml 中 browser-session 段（dshctl auth.py 同款）。 */
+export function readSigningSecretFromFile(credentialsYamlPath: string): Buffer {
+  let text: string
+  try {
+    text = readFileSync(credentialsYamlPath, 'utf8')
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw new Error(`read .credentials.yaml failed (${credentialsYamlPath}): ${detail}`)
+  }
+  let inSection = false
+  for (const line of text.split(/\r?\n/)) {
+    const stripped = line.trim()
+    if (stripped === '' || stripped.startsWith('#')) continue
+    const indent = line.length - line.replace(/^\s*/, '').length
+    if (indent <= 2) {
+      inSection = stripped === `${SECRET_SECTION}:`
+      continue
+    }
+    if (inSection) {
+      const match = /^secret:\s*(\S+)\s*$/.exec(stripped)
+      if (match !== null) {
+        const secret = Buffer.from(match[1] ?? '', 'base64url')
+        if (secret.byteLength !== SECRET_BYTES) {
+          throw new Error(
+            `browser-session secret has invalid length (${secret.byteLength}, want ${SECRET_BYTES})`,
+          )
+        }
+        return secret
+      }
+    }
+  }
+  throw new Error(`browser-session secret not found in ${credentialsYamlPath}`)
+}
+
+/** 官方 sessionCookie() 序列化（属性逐字同款；nowMs 注入保持纯函数可测）。 */
+export function serializeSessionCookie(
+  name: string,
+  value: string,
+  expiresAt: number,
+  nowMs: number,
+): string {
+  const maxAgeSeconds = Math.floor((expiresAt - nowMs) / 1000)
+  return (
+    `${name}=${value}; Max-Age=${String(maxAgeSeconds)}; Path=/; ` +
+    `Expires=${new Date(expiresAt).toUTCString()}; HttpOnly; SameSite=Strict`
+  )
+}
+
+/** 铸造官方同款 cookie（键序/序列化/属性全对齐），返回可直接写 Set-Cookie 的串。 */
+export function mintSessionCookie(secret: Buffer, authority: string, nowMs: number): string {
+  const expiresAt = nowMs + COOKIE_MAX_AGE_MS
+  const payload: Record<string, unknown> = { version: PAYLOAD_VERSION }
+  for (const key of PAYLOAD_KEYS) {
+    if (key === 'version') continue
+    payload[key] = key === 'authority' ? authority : key === 'issuedAt' ? nowMs : expiresAt
+  }
+  const body = base64url(Buffer.from(JSON.stringify(payload), 'utf8'))
+  const signature = base64url(createHmac('sha256', secret).update(body).digest())
+  return serializeSessionCookie(cookieName(authority), `v1.${body}.${signature}`, expiresAt, nowMs)
+}
+
+/** 拼接 DSH_HOME 下凭据文件路径（默认 home 与 $DSH_HOME 语义同官方 home-paths）。 */
+export function credentialsPath(dshHome: string): string {
+  return join(dshHome, '.credentials.yaml')
+}
+
+/** 完整铸造入口：读密钥 + 铸造；任何失败抛带上下文错误（调用方降级 fail-safe）。 */
+export function mintAutoLoginCookie(
+  credentialsYamlPath: string,
+  authority: string,
+  nowMs: number,
+): string {
+  const secret = readSigningSecretFromFile(credentialsYamlPath)
+  return mintSessionCookie(secret, authority, nowMs)
+}

package/src/decision.ts

@@ -22,6 +22,7 @@ import { isLoopbackAddress, parseAllowEntry, parseIp } from './ip.ts'
 /** 围栏判定结果。 */
 export type GateVerdict =
   | 'pass' /** 放行（本机直连 / 官方 cookie 有效） */
+  | 'autologin' /** IP 信任自动登录：白名单来源未认证 → 由拦截器落官方 cookie 后放行 */
   | 'block' /** 拒绝：非导航请求或 IP 围栏拦截 → 403 */
   | 'token-page' /** 拒绝：浏览器导航请求 → token 输入页 */
 
@@ -30,8 +31,8 @@ export interface GateDecision {
   verdict: GateVerdict
   /** 还原出的客户端 IP（有 XFF 或非 loopback 直连时存在）。 */
   clientIp?: string
-  /** 放行原因（诊断/日志用）：local / cookie。 */
-  reason?: 'local' | 'cookie'
+  /** 放行原因（诊断/日志用）：local / cookie / trusted-ip。 */
+  reason?: 'local' | 'cookie' | 'trusted-ip'
   /** 无效白名单条目（卡片诊断用，判定时忽略它们）。 */
   invalidEntries?: string[]
 }
@@ -78,8 +79,10 @@ export function compileAllowlist(entries: readonly string[]): CompiledAllowlist
  * 围栏判定（纯函数，无任何副作用与 IO）。
  * 逻辑次序：豁免路径由调用方前置处理；enabled=false 直通；确定有效来源
  * （受信 XFF 优先，否则 remoteAddress）；来源为 loopback 直连 → 放行；
- * 白名单非空时作附加 IP 围栏，不命中即拒；官方 cookie 有效 → 放行；
- * 否则导航 → token 输入页，非导航 → 403；无来源 → fail-closed。
+ * 白名单非空时作附加 IP 围栏，不命中即拒；autoLoginTrustedIps=true 且
+ * 白名单命中但官方未认证 → autologin（拦截器负责落官方 cookie）；
+ * 官方 cookie 有效 → 放行；否则导航 → token 输入页，非导航 → 403；
+ * 无来源 → fail-closed。
  *
  * loopback 语义：XFF 被信任时，存在 XFF 即代表请求经代理（serve→proxy→dsh
  * 全链 loopback，真实客户端只在 XFF 里）——remoteAddress 是 loopback 也不
@@ -116,6 +119,11 @@ export function decideGate(
     if (clientIp === null || !allowlist.match(clientIp)) {
       return { verdict: 'block', clientIp: clientIpText, invalidEntries }
     }
+    // IP 信任自动登录：白名单命中 + 未认证 → 拦截器落官方 cookie 后放行
+    // （仅当显式开启且白名单非空；已认证走下方 cookie 正常路径）。
+    if (policy.autoLoginTrustedIps && !officialAuthed) {
+      return { verdict: 'autologin', clientIp: clientIpText, reason: 'trusted-ip', invalidEntries }
+    }
   }
 
   if (officialAuthed) {

package/src/index.ts

@@ -7,6 +7,8 @@
  *   本插件不再持有自有 token/cookie；
  * - 本机直连（loopback 且无 x-forwarded-for）gate 层永久放行——管理通道；
  * - allowedIps 为可选附加 IP 围栏（XFF 还原，精确 IP / CIDR，v4+v6）；
+ * - autoLoginTrustedIps=true 时，白名单来源未认证请求自动铸造官方登录
+ *   cookie（免启动 token，仅对白名单来源生效；密钥读取失败自动降级）；
  * - 未认证的浏览器导航 → token 输入页（粘贴启动令牌走官方交换，**PWA 内
  *   同路径可用**——恢复官方 start_url 无法携带 token 导致的 PWA 死结）；
  *   未认证的 API / WS / 静态资产 → 403 / 拒绝升级；
@@ -19,7 +21,8 @@
  * 配置：settings 命名空间 dsh-plus-access-gate（webui 配置卡片同一份，
  * 热生效）；enabled=false 时完全旁路（等价插件缺席）。
  * 安全边界：结构守卫 fail-loud（upstream 形状变化 → 启动失败 → lifeboat
- * 隔离止损，绝不静默 fail-open）。
+ * 隔离止损，绝不静默 fail-open）；autoLogin 依赖官方签名密钥，读取失败
+ * 自动降级为不自动登录（fail-safe）。
  * @module @dsh-plus/access-gate
  */
 
@@ -27,9 +30,16 @@ import type { IncomingMessage } from 'node:http'
 import { type Context, Service } from '@deepseek-ai/cordis'
 // HostConnectionHandle 的 Context 声明合并（connection 服务类型来源）。
 import type {} from '@deepseek-ai/dsh-client-connection'
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
 import type {} from '@deepseek-ai/dsh-settings'
 
 import { type AccessGateConfig, Config, SETTINGS_NS } from './config.ts'
+import {
+  credentialsPath,
+  mintAutoLoginCookie,
+  readSigningSecretFromFile,
+  requestAuthority,
+} from './cookie.ts'
 import { type GateWebServer, installGateInterceptor } from './interceptor.ts'
 import { registerGateRoutes } from './routes.ts'
 
@@ -48,6 +58,8 @@ declare module '@deepseek-ai/cordis' {
 /** 围栏服务：持有当前配置读取器（settings 用户层热更新经 setSource 注入）。 */
 export class AccessGateService extends Service {
   private current: () => AccessGateConfig
+  /** 官方 browser-auth 签名密钥（惰性读取缓存；读取失败 = null，autoLogin fail-safe 降级）。 */
+  private signingSecret: Buffer | null | undefined
 
   constructor(ctx: Context, config: AccessGateConfig) {
     super(ctx, 'accessGate')
@@ -68,11 +80,31 @@ export class AccessGateService extends Service {
     const officialAuth = (req: IncomingMessage): boolean =>
       ctx.connection.requestRejection({ headers: req.headers }) === undefined
 
+    // 官方 browser-auth 签名密钥（.credentials.yaml）：与官方 cookie 同源，
+    // 供 IP 信任自动登录铸造等价 cookie。惰性读取并缓存；失败记一次 warn 并
+    // 降级（autoLogin 不生效），围栏本身不受影响。
+    const secretOf = (): Buffer | null => this.readSigningSecret(logger)
+    // IP 信任自动登录的 cookie 铸造器（判定 autologin 时调用；不可铸返回 null，
+    // 拦截器据此回退 token 输入页/403，绝不 fail-open）。
+    const autoLoginCookie = (req: IncomingMessage): string | null => {
+      const secret = secretOf()
+      const authority = requestAuthority(req.headers)
+      if (secret === null || authority === undefined) return null
+      try {
+        return mintAutoLoginCookie(credentialsPath(dshHomePath()), authority, Date.now())
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn(`auto-login cookie mint failed: ${message}`)
+        return null
+      }
+    }
+
     // 自有端点（/dsh-plus/gate/*，围栏豁免路径）。
     registerGateRoutes(ctx, {
       config: () => this.current(),
       officialAuth,
       authenticatedUrl: (baseUrl) => ctx.connection.authenticatedUrl(baseUrl),
+      autoLoginReady: () => this.autoLoginSecretReady(logger),
       onError: (message) => logger.warn(message),
     })
 
@@ -80,6 +112,7 @@ export class AccessGateService extends Service {
     const undo = installGateInterceptor(ctx, ctx.webServer as unknown as GateWebServer, {
       config: () => this.current(),
       officialAuth,
+      autoLoginCookie,
       onBlock: (message) => logger.info(message),
     })
     ctx.effect(() => undo, 'access-gate: interceptor')
@@ -89,6 +122,24 @@ export class AccessGateService extends Service {
   policy(): AccessGateConfig {
     return this.current()
   }
+
+  /** 官方签名密钥（惰性缓存；失败返回 null 并记录，autoLogin 降级 fail-safe）。 */
+  private readSigningSecret(logger: { warn(message: string): void }): Buffer | null {
+    if (this.signingSecret !== undefined) return this.signingSecret
+    try {
+      this.signingSecret = readSigningSecretFromFile(credentialsPath(dshHomePath()))
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      logger.warn(`auto-login disabled: ${message}`)
+      this.signingSecret = null
+    }
+    return this.signingSecret
+  }
+
+  /** IP 信任自动登录可用性（诊断用）：签名密钥可读即为可用。 */
+  autoLoginSecretReady(logger: { warn(message: string): void }): boolean {
+    return this.readSigningSecret(logger) !== null
+  }
 }
 
 export function apply(ctx: Context, config: AccessGateConfig): void {

package/src/interceptor.ts

@@ -29,7 +29,7 @@ import type { Duplex } from 'node:stream'
 import type { Context } from '@deepseek-ai/cordis'
 
 import type { AccessGateConfig } from './config.ts'
-import { decideGate, type GateRequest } from './decision.ts'
+import { decideGate, type GateRequest, isNavigationRequest } from './decision.ts'
 import { GATE_ROUTE } from './routes.ts'
 import { renderTokenPage } from './token-page.ts'
 
@@ -51,6 +51,12 @@ export interface InterceptorDeps {
   config: () => AccessGateConfig
   /** 官方 browser-auth 校验（委托 connection.requestRejection；含官方 Host 围栏）。 */
   officialAuth: (req: IncomingMessage) => boolean
+  /**
+   * IP 信任自动登录的 cookie 铸造器：返回可直接写 Set-Cookie 的官方同款
+   * cookie 串；无法铸造（密钥缺失/authority 不可得等）返回 null（fail-safe，
+   * 调用方回退普通未认证路径）。仅在判定 autologin 时被调用。
+   */
+  autoLoginCookie?: (req: IncomingMessage) => string | null
   onBlock?: (message: string) => void
 }
 
@@ -95,6 +101,41 @@ function rejectUpgrade(socket: Duplex, clientIp: string, log: (m: string) => voi
   log(`blocked upgrade (${clientIp})`)
 }
 
+/** IP 信任自动登录的引导页：已落官方 cookie，纯客户端跳回干净首页。 */
+function renderAutoLoginPage(): string {
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>正在进入 - DeepSeek Harness</title>
+<style>
+  :root { color-scheme: dark; }
+  body {
+    margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+    background: #16181d; color: #e6e8ec;
+    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "PingFang SC", "Noto Sans CJK SC", sans-serif;
+  }
+  .card { width: min(92vw, 420px); padding: 32px 28px; border-radius: 14px; text-align: center;
+    background: #1e2128; border: 1px solid #2e323c; box-shadow: 0 8px 32px rgba(0,0,0,.4); box-sizing: border-box; }
+  .dot { display: inline-block; width: 10px; height: 10px; border-radius: 50%; background: #3d6dff; margin: 0 2px; animation: b 1s infinite ease-in-out; }
+  .dot:nth-child(2) { animation-delay: .15s; } .dot:nth-child(3) { animation-delay: .3s; }
+  @keyframes b { 0%,80%,100% { opacity:.25; transform:scale(.8); } 40% { opacity:1; transform:scale(1); } }
+  h1 { margin: 0 0 8px; font-size: 18px; font-weight: 600; }
+  p { margin: 0; font-size: 13px; color: #9aa1ad; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <h1><span class="dot"></span><span class="dot"></span><span class="dot"></span></h1>
+    <h1>已自动登录</h1>
+    <p>正在进入…（本设备已在信任名单，无需手动登录）</p>
+  </div>
+<script>location.replace('/')</script>
+</body>
+</html>`
+}
+
 /** 单请求围栏判定；放行 true / 拒绝（已写响应）false。 */
 function passHttp(req: IncomingMessage, res: ServerResponse, deps: InterceptorDeps): boolean {
   const url = new URL(req.url ?? '/', 'http://x')
@@ -102,6 +143,35 @@ function passHttp(req: IncomingMessage, res: ServerResponse, deps: InterceptorDe
   const decision = decideGate(toGateRequest(req), deps.config(), deps.officialAuth(req))
   if (decision.verdict === 'pass') return true
   const log = deps.onBlock ?? (() => {})
+  if (decision.verdict === 'autologin') {
+    const cookie = deps.autoLoginCookie?.(req)
+    if (cookie !== null && cookie !== undefined) {
+      if (isNavigationRequest(toGateRequest(req)) && !res.headersSent) {
+        // 导航：落官方 cookie + 引导页跳回干净首页（浏览器后续请求自动携带）。
+        res.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'cache-control': 'no-store',
+          'set-cookie': cookie,
+        })
+        res.end(renderAutoLoginPage())
+        log(`auto-login ${req.method ?? '?'} ${req.url ?? '?'} (${decision.clientIp ?? 'unknown'})`)
+        return false
+      }
+      // 非导航（API/静态资产）：cookie 可铸即放行——浏览器正常流程先导航落罐，
+      // 直呼请求由官方 requestRejection 按其携带的 cookie 判定。
+      return true
+    }
+    // 铸造失败（fail-safe）：导航回退 token 输入页，非导航落入下方 403。
+    log(`auto-login skipped: cookie unavailable (${decision.clientIp ?? 'unknown'})`)
+    if (isNavigationRequest(toGateRequest(req)) && !res.headersSent) {
+      res.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8',
+        'cache-control': 'no-store',
+      })
+      res.end(renderTokenPage())
+      return false
+    }
+  }
   if (decision.verdict === 'token-page' && !res.headersSent) {
     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
     res.end(renderTokenPage())
@@ -126,13 +196,22 @@ function gatedHttp(handler: HttpHandler, deps: InterceptorDeps): HttpHandler {
   }
 }
 
-/** WS 升级包装体：拒绝时不进协议协商。 */
+/** WS 升级包装体：拒绝时不进协议协商；IP 信任自动登录（cookie 可铸）放行。 */
 function gatedUpgrade(handler: UpgradeHandler, deps: InterceptorDeps): UpgradeHandler {
   return (req, socket, head) => {
     if (isExemptPath(new URL(req.url ?? '/', 'http://x').pathname))
       return handler(req, socket, head)
     const decision = decideGate(toGateRequest(req), deps.config(), deps.officialAuth(req))
     if (decision.verdict === 'pass') return handler(req, socket, head)
+    // IP 信任自动登录：cookie 可铸时放行（浏览器 WebSocket 会带此前导航落罐的
+    // cookie；官方 requestRejection 由连接携带的 cookie 通过）。
+    if (
+      decision.verdict === 'autologin' &&
+      deps.autoLoginCookie !== undefined &&
+      deps.autoLoginCookie(req) !== null
+    ) {
+      return handler(req, socket, head)
+    }
     rejectUpgrade(socket, decision.clientIp ?? 'unknown', deps.onBlock ?? (() => {}))
     return undefined
   }

package/src/routes.ts

@@ -28,6 +28,8 @@ export interface RouteDeps {
   authenticatedUrl: (baseUrl: string) => string
   /** 客户端 IP 还原（与围栏同一规则）；缺省时从请求自身推导。 */
   resolveClientIp?: (req: IncomingMessage) => string | undefined
+  /** IP 信任自动登录可用性（签名密钥可读）；缺省视为不可用（诊断展示）。 */
+  autoLoginReady?: () => boolean
   onError?: (message: string) => void
 }
 
@@ -83,6 +85,8 @@ export function createGateRoutes(
       ipFenceActive: config.allowedIps.length > 0,
       invalidEntries: decision.invalidEntries ?? [],
       allowedCount: config.allowedIps.length,
+      autoLoginActive: config.autoLoginTrustedIps,
+      autoLoginReady: deps.autoLoginReady?.() ?? false,
     })
   }