@dsh-plus/access-gate 0.1.0

package/src/interceptor.ts

@@ -0,0 +1,215 @@
+/**
+ * 围栏拦截器：对 webServer 服务做结构性包装，覆盖全部 HTTP/WS 流量。
+ *
+ * 机制（dsh-host-webserver 无中间件机制，路由分发必经以下三个面）：
+ * 1. `match(pathname)` —— HTTP 分发总咽喉：patch 后**请求级**围栏判定——
+ *    放行则返回原 route（handler 外包一层，route 对象本体不动，webserver
+ *    拿到的是浅拷贝）；拒绝则返回内联拒绝 route（导航→登录页，其余→403；
+ *    连「未知路径」的探测面也一并收敛）。与路由注册时序完全无关。
+ * 2. `fallback` 字段 + `registerFallback` 方法 —— SPA index/静态资源：
+ *    在位包装已注册的 fallback（frontend-static 先于本插件），并 patch
+ *    方法兜底后续注册。
+ * 3. `upgrades` Map 各 route 的 handler + `registerUpgrade` 方法 —— WS 升级
+ *    双路径覆盖（先/后注册的条目都被拦截）。
+ *
+ * 结构守卫：安装前校验字段形状（match 为函数、upgrades 为 Map 等），
+ * 不符即 fail-loud 抛错（启动失败由 lifeboat 隔离止损，绝不静默 fail-open）。
+ * 恢复：所有 patch 与在位 handler 替换均登记 undo，dispose/HMR 时完全还原。
+ * @module access-gate/interceptor
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+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 { renderLoginPage } from './login-page.ts'
+import { GATE_ROUTE } from './routes.ts'
+
+type HttpHandler = (req: IncomingMessage, res: ServerResponse) => unknown
+type UpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => unknown
+type UpgradeRoute = { path: string; handler: UpgradeHandler }
+
+/** 围栏所需的最小 webServer 结构面（结构守卫的契约）。 */
+export interface GateWebServer {
+  match(pathname: string): unknown
+  upgrades: Map<string, UpgradeRoute>
+  fallback?: HttpHandler
+  registerFallback(handler: HttpHandler): unknown
+  registerUpgrade(route: UpgradeRoute): unknown
+  [key: string]: unknown
+}
+
+export interface InterceptorDeps {
+  config: () => AccessGateConfig
+  onBlock?: (message: string) => void
+}
+
+/** 是否围栏豁免路径（自有登录/状态端点）。 */
+export function isExemptPath(pathname: string): boolean {
+  return pathname === GATE_ROUTE || pathname.startsWith(`${GATE_ROUTE}/`)
+}
+
+function toGateRequest(req: IncomingMessage): GateRequest {
+  return {
+    url: req.url ?? '/',
+    method: req.method ?? 'GET',
+    headers: req.headers,
+    remoteAddress: req.socket?.remoteAddress,
+  }
+}
+
+/** WS 升级拒绝：按官方同款 403 原始响应后关闭。 */
+function rejectUpgrade(socket: Duplex, clientIp: string, log: (m: string) => void): void {
+  socket.end(
+    [
+      'HTTP/1.1 403 Forbidden',
+      'Connection: close',
+      'Content-Type: text/plain; charset=utf-8',
+      'Content-Length: 9',
+      '',
+      'forbidden',
+    ].join('\r\n'),
+  )
+  log(`blocked upgrade (${clientIp})`)
+}
+
+/** 单请求围栏判定；放行 true / 拒绝（已写响应）false。 */
+function passHttp(req: IncomingMessage, res: ServerResponse, deps: InterceptorDeps): boolean {
+  if (isExemptPath(new URL(req.url ?? '/', 'http://x').pathname)) return true
+  const decision = decideGate(toGateRequest(req), deps.config())
+  if (decision.verdict === 'pass') return true
+  const log = deps.onBlock ?? (() => {})
+  if (decision.verdict === 'login' && !res.headersSent) {
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
+    res.end(renderLoginPage())
+    log(`login page ${req.method ?? '?'} ${req.url ?? '?'}`)
+    return false
+  }
+  if (!res.headersSent) {
+    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
+    res.end('forbidden')
+  } else {
+    res.end()
+  }
+  log(`blocked ${req.method ?? '?'} ${req.url ?? '?'} (${decision.clientIp ?? 'unknown'})`)
+  return false
+}
+
+/** HTTP handler 包装体：先判定再派发。 */
+function gatedHttp(handler: HttpHandler, deps: InterceptorDeps): HttpHandler {
+  return async (req, res) => {
+    if (isExemptPath(new URL(req.url ?? '/', 'http://x').pathname)) return handler(req, res)
+    if (!passHttp(req, res, deps)) return
+    return handler(req, res)
+  }
+}
+
+/** WS 升级包装体：拒绝时不进协议协商。 */
+function gatedUpgrade(handler: UpgradeHandler, deps: InterceptorDeps): UpgradeHandler {
+  return (req, socket, head) => {
+    const decision = decideGate(toGateRequest(req), deps.config())
+    if (decision.verdict === 'pass') return handler(req, socket, head)
+    rejectUpgrade(socket, decision.clientIp ?? 'unknown', deps.onBlock ?? (() => {}))
+    return undefined
+  }
+}
+
+/**
+ * 安装围栏（结构包装 + fail-loud 守卫）。
+ * @returns 恢复函数（调用方登记进 ctx.effect）。
+ */
+export function installGateInterceptor(
+  ctx: Context,
+  server: GateWebServer,
+  deps: InterceptorDeps,
+): () => void {
+  assertGateStructure(server)
+  const restores: Array<{ undo(): void }> = []
+
+  // 1. match：HTTP 总咽喉——请求级判定；返回浅拷贝 route（handler 已包 gate），
+  //    原 route 对象与注册表不动，杜绝重复包装。
+  //    未命中任何路由时必须返回 undefined：webserver 的 handle() 据此转入
+  //    fallback 原生路径（fallback 已被第 2 步包装，SPA 语义完整保留）。
+  const originalMatch = server.match.bind(server)
+  const gatedMatch = (pathname: string): unknown => {
+    if (isExemptPath(pathname)) return originalMatch(pathname)
+    const config = deps.config()
+    if (!config.enabled) return originalMatch(pathname)
+    const route = originalMatch(pathname) as { handler: HttpHandler } | undefined
+    if (route === undefined) return undefined
+    return { ...route, handler: gatedHttp(route.handler, deps) }
+  }
+  server.match = gatedMatch as typeof server.match
+  restores.push({
+    undo: () => {
+      server.match = originalMatch as typeof server.match
+    },
+  })
+
+  // 2. fallback 在位包装 + registerFallback 兜底（浅拷贝 route 不覆盖
+  //    fallback 场景：webserver 对未命中请求直接调 this.fallback）。
+  const wrapFallback = (handler: HttpHandler): HttpHandler => gatedHttp(handler, deps)
+  const originalFallback = server.fallback
+  let fallbackReplaced = false
+  if (originalFallback !== undefined) {
+    server.fallback = wrapFallback(originalFallback) as typeof originalFallback
+    fallbackReplaced = true
+  }
+  const originalRegisterFallback = server.registerFallback.bind(server)
+  const patchedRegisterFallback = (handler: HttpHandler): unknown =>
+    originalRegisterFallback(wrapFallback(handler))
+  server.registerFallback = patchedRegisterFallback as typeof server.registerFallback
+  restores.push({
+    undo: () => {
+      server.registerFallback = originalRegisterFallback as typeof server.registerFallback
+      if (fallbackReplaced) server.fallback = originalFallback as typeof server.fallback
+    },
+  })
+
+  // 3. upgrades：在位包装已注册条目 + patch registerUpgrade（后续注册）。
+  const wrapped = new Map<UpgradeRoute, UpgradeHandler>()
+  const wrapUpgradeRoute = (route: UpgradeRoute): void => {
+    wrapped.set(route, route.handler)
+    route.handler = gatedUpgrade(route.handler, deps)
+  }
+  for (const route of server.upgrades.values()) wrapUpgradeRoute(route)
+  const originalRegisterUpgrade = server.registerUpgrade.bind(server)
+  const patchedRegisterUpgrade = (route: UpgradeRoute): unknown => {
+    const disposer = originalRegisterUpgrade(route)
+    // 未抛重复错即注册成功；在位包装（Map 值 === route 已证其已入表）。
+    if (server.upgrades.get(route.path) === route) wrapUpgradeRoute(route)
+    return disposer
+  }
+  server.registerUpgrade = patchedRegisterUpgrade as typeof server.registerUpgrade
+  restores.push({
+    undo: () => {
+      server.registerUpgrade = originalRegisterUpgrade as typeof server.registerUpgrade
+      for (const [route, handler] of wrapped) route.handler = handler
+      wrapped.clear()
+    },
+  })
+
+  const undo = (): void => {
+    for (let i = restores.length - 1; i >= 0; i -= 1) restores[i].undo()
+  }
+  void ctx
+  return undo
+}
+
+/** 结构守卫：字段形状不符即抛错（fail-loud）。 */
+export function assertGateStructure(server: GateWebServer): void {
+  if (typeof server.match !== 'function')
+    throw new Error('access-gate: webServer.match is not a function (upstream shape changed)')
+  if (!(server.upgrades instanceof Map))
+    throw new Error('access-gate: webServer.upgrades is not a Map (upstream shape changed)')
+  if (typeof server.registerFallback !== 'function')
+    throw new Error(
+      'access-gate: webServer.registerFallback is not a function (upstream shape changed)',
+    )
+  if (typeof server.registerUpgrade !== 'function')
+    throw new Error(
+      'access-gate: webServer.registerUpgrade is not a function (upstream shape changed)',
+    )
+}

package/src/ip.ts

@@ -0,0 +1,143 @@
+/**
+ * IP 与 CIDR 解析/匹配纯函数（IPv4 + IPv6，BigInt 位运算实现）。
+ * 零依赖、无副作用，node 半与测试共用；非法输入返回 null / false，绝不抛错。
+ *
+ * 表示约定：IP 一律归一化为「BigInt 数值 + 地址族位宽（32/128）」内部表示，
+ * IPv4 不映射进 IPv6 空间（tailscale 环境只会出现原生 v4/v6 字面量，
+ * 映射式 ::ffff:x.x.x.x 判等容易引入歧义，映射形式明确拒绝）。
+ * @module access-gate/ip
+ */
+
+/** 归一化 IP：数值 + 地址族位宽。 */
+export interface ParsedIp {
+  readonly value: bigint
+  readonly bits: 32 | 128
+}
+
+/** 解析 IPv4 十进制点分字面量；非法返回 null。 */
+function parseIpv4(text: string): bigint | null {
+  const parts = text.split('.')
+  if (parts.length !== 4) return null
+  let value = 0n
+  for (const part of parts) {
+    if (part.length === 0 || part.length > 3 || !/^\d+$/.test(part)) return null
+    const octet = Number(part)
+    if (octet > 255) return null
+    value = (value << 8n) | BigInt(octet)
+  }
+  return value
+}
+
+/** 把一个组（4 位十六进制）压入累积值；越界（>0xffff）返回 null。 */
+function pushGroup(value: bigint, group: string): bigint | null {
+  if (group.length === 0 || group.length > 4 || !/^[0-9a-fA-F]+$/.test(group)) return null
+  return (value << 16n) | BigInt(Number.parseInt(group, 16))
+}
+
+/**
+ * 解析 IPv6（含 `::` 压缩与 `::1.2.3.4` 形态的 v4 尾巴；拒绝 zone / 映射前缀）。
+ * 算法：按 `::` 切成左右两半 → 各自逐组展开（末组可为点分 v4，占 2 组）
+ * → 数值拼接，右半在低位，中间空洞补零。
+ */
+function parseIpv6(text: string): bigint | null {
+  if (text.includes('%') || text.startsWith('::ffff:')) return null
+  const gap = text.indexOf('::')
+  if (gap !== -1 && text.indexOf('::', gap + 1) !== -1) return null
+  const headText = gap === -1 ? text : text.slice(0, gap)
+  const tailText = gap === -1 ? '' : text.slice(gap + 2)
+
+  const expandHalf = (half: string, atStart: boolean): { value: bigint; groups: number } | null => {
+    if (half === '') return { value: 0n, groups: 0 }
+    const rawGroups = half.split(':')
+    if (rawGroups.some((group) => group === '')) return null
+    // v4 尾巴只允许出现在整串的最末一组。
+    const dotted = rawGroups.findIndex((group) => group.includes('.'))
+    if (dotted !== -1 && !(dotted === rawGroups.length - 1 && !atStart)) return null
+    let value = 0n
+    let groups = 0
+    for (const group of rawGroups) {
+      if (group.includes('.')) {
+        const v4 = parseIpv4(group)
+        if (v4 === null) return null
+        value = (value << 32n) | v4
+        groups += 2
+      } else {
+        const next = pushGroup(value, group)
+        if (next === null) return null
+        value = next
+        groups += 1
+      }
+    }
+    return { value, groups }
+  }
+
+  const head = expandHalf(headText, true)
+  const tail = expandHalf(tailText, false)
+  if (head === null || tail === null) return null
+  const total = head.groups + tail.groups
+  if (total > 8) return null
+  if (gap === -1 && total !== 8) return null
+  if (gap !== -1 && total >= 8) return null
+  // 右半在最低位，其后才是洞：head 左移「洞 + 右半」的组数。
+  const holeAndTail = BigInt(8 - head.groups) * 16n
+  return (head.value << holeAndTail) | tail.value
+}
+
+/** 解析任意 IP 字面量；非法返回 null。 */
+export function parseIp(text: string): ParsedIp | null {
+  const trimmed = text.trim()
+  if (trimmed.includes(':')) {
+    const value = parseIpv6(trimmed)
+    return value === null ? null : { value, bits: 128 }
+  }
+  const value = parseIpv4(trimmed)
+  return value === null ? null : { value, bits: 32 }
+}
+
+/** 归一化 CIDR；非法（IP 解析失败 / 前缀越界）返回 null。 */
+export function parseCidr(text: string): { ip: ParsedIp; prefix: number } | null {
+  const slash = text.indexOf('/')
+  if (slash === -1) return null
+  const ip = parseIp(text.slice(0, slash))
+  const prefixText = text.slice(slash + 1)
+  if (ip === null || !/^\d{1,3}$/.test(prefixText)) return null
+  const prefix = Number(prefixText)
+  if (prefix > ip.bits) return null
+  return { ip, prefix }
+}
+
+/** 同族且数值相等。 */
+export function ipEquals(a: ParsedIp, b: ParsedIp): boolean {
+  return a.bits === b.bits && a.value === b.value
+}
+
+/** 判断 IP 是否落入 CIDR；跨族（v4 vs v6）恒 false。 */
+export function ipInCidr(ip: ParsedIp, cidr: { ip: ParsedIp; prefix: number }): boolean {
+  if (ip.bits !== cidr.ip.bits) return false
+  const shift = BigInt(ip.bits - cidr.prefix)
+  return ip.value >> shift === cidr.ip.value >> shift
+}
+
+/** 解析白名单条目（精确 IP 或 CIDR）；返回可判定函数，非法条目返回 null。 */
+export function parseAllowEntry(text: string): ((ip: ParsedIp) => boolean) | null {
+  const trimmed = text.trim()
+  const cidr = parseCidr(trimmed)
+  if (cidr !== null) {
+    return (ip) => ipInCidr(ip, cidr)
+  }
+  const exact = parseIp(trimmed)
+  if (exact !== null) {
+    return (ip) => ipEquals(ip, exact)
+  }
+  return null
+}
+
+/** 判断 remoteAddress 是否 loopback（node 形态：`127.x.x.x` / `::1` / `::ffff:127.x.x.x`）。 */
+export function isLoopbackAddress(remoteAddress: string | undefined): boolean {
+  if (remoteAddress === undefined) return false
+  const bare = remoteAddress.startsWith('::ffff:') ? remoteAddress.slice(7) : remoteAddress
+  if (bare === '::1') return true
+  const parsed = parseIp(bare)
+  if (parsed === null || parsed.bits !== 32) return false
+  return parsed.value >= 0x7f000000n && parsed.value <= 0x7ffffffen
+}

package/src/login-page.ts

@@ -0,0 +1,77 @@
+/**
+ * 登录页：围栏拦截浏览器导航请求时返回的内联 HTML。
+ * 自包含（无外部静态资源依赖）、中文、vanilla JS——输入 token → 调
+ * /dsh-plus/gate/login → 成功后 reload 放行。
+ * @module access-gate/login-page
+ */
+
+export function renderLoginPage(): string {
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>访问校验</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, 360px); padding: 32px 28px; border-radius: 14px;
+    background: #1e2128; border: 1px solid #2e323c; box-shadow: 0 8px 32px rgba(0,0,0,.4);
+    box-sizing: border-box;
+  }
+  h1 { margin: 0 0 6px; font-size: 20px; font-weight: 600; }
+  p { margin: 0 0 22px; font-size: 13px; color: #9aa1ad; line-height: 1.6; }
+  input {
+    width: 100%; box-sizing: border-box; padding: 10px 12px; border-radius: 8px;
+    border: 1px solid #3a3f4b; background: #16181d; color: #e6e8ec; font-size: 15px;
+    outline: none;
+  }
+  input:focus { border-color: #5b8cff; }
+  button {
+    width: 100%; margin-top: 14px; padding: 10px 0; border: 0; border-radius: 8px;
+    background: #3d6dff; color: #fff; font-size: 15px; font-weight: 600; cursor: pointer;
+  }
+  button:disabled { opacity: .6; cursor: default; }
+  .msg { min-height: 18px; margin-top: 12px; font-size: 13px; text-align: center; }
+  .err { color: #ff7a76; }
+  .ok { color: #63d17c; }
+</style>
+</head>
+<body>
+  <form class="card" id="form">
+    <h1>此页面受访问控制保护</h1>
+    <p>当前网络不在放行名单内。输入访问令牌以继续；或使用名单内的设备/网络访问。</p>
+    <input id="token" type="password" placeholder="访问令牌" autocomplete="off" autofocus>
+    <button id="btn" type="submit">继续访问</button>
+    <div class="msg" id="msg"></div>
+  </form>
+<script>
+  var form = document.getElementById('form');
+  var input = document.getElementById('token');
+  var btn = document.getElementById('btn');
+  var msg = document.getElementById('msg');
+  form.addEventListener('submit', function (event) {
+    event.preventDefault();
+    var token = input.value;
+    if (!token) { msg.className = 'msg err'; msg.textContent = '请输入访问令牌'; return; }
+    btn.disabled = true;
+    msg.className = 'msg'; msg.textContent = '校验中…';
+    fetch('/dsh-plus/gate/login', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token: token })
+    }).then(function (res) {
+      if (res.ok) { msg.className = 'msg ok'; msg.textContent = '校验通过，正在进入…'; location.reload(); }
+      else if (res.status === 429) { msg.className = 'msg err'; msg.textContent = '失败次数过多，请稍后再试'; btn.disabled = false; }
+      else { msg.className = 'msg err'; msg.textContent = '令牌无效'; btn.disabled = false; }
+    }).catch(function () { msg.className = 'msg err'; msg.textContent = '网络错误，请重试'; btn.disabled = false; });
+  });
+</script>
+</body>
+</html>`
+}

package/src/ns.ts

@@ -0,0 +1,7 @@
+/**
+ * settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
+ * 服务端经 settingsNamespace() 品牌化后使用（config.ts），浏览器半将其作为
+ * settings.plugin.item keyed 槽位的 key —— 同一字面量两处共用，防止漂移。
+ * @module access-gate/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-access-gate'

package/src/routes.ts

@@ -0,0 +1,201 @@
+/**
+ * 自有 HTTP 端点（/dsh-plus/gate 前缀，围栏豁免路径）：
+ * - POST /dsh-plus/gate/login  — token 换 cookie（HttpOnly + SameSite=Strict）
+ * - GET  /dsh-plus/gate/status — 当前客户端判定状态（登录页与卡片诊断）
+ *
+ * 登录失败节流：按客户端 IP 记录失败次数与冷却截止（惰性清理，无定时器）。
+ * handler 工厂与路由注册分离，测试直接驱动 handler（禁起真实服务器）。
+ * @module access-gate/routes
+ */
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+
+import type { AccessGateConfig } from './config.ts'
+import { decideGate } from './decision.ts'
+
+export const GATE_ROUTE = '/dsh-plus/gate'
+
+/** 节流状态（纯数据结构，可注入 clock 测试）。 */
+export interface ThrottleState {
+  fails: Map<string, { count: number; until: number }>
+}
+
+export function createThrottleState(): ThrottleState {
+  return { fails: new Map() }
+}
+
+export interface RouteDeps {
+  config: () => AccessGateConfig
+  /** 客户端 IP 还原（与围栏同一规则）；缺省时从请求自身推导。 */
+  resolveClientIp?: (req: IncomingMessage) => string | undefined
+  throttle?: ThrottleState
+  clock?: () => number
+  onError?: (message: string) => void
+}
+
+function sendJson(
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+  headers?: Record<string, string>,
+): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...headers })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+/** 解析 JSON body；非对象或解析失败返回 null。 */
+async function readJson(req: IncomingMessage): Promise<Record<string, unknown> | null> {
+  if (!req.headers['content-type']?.includes('application/json')) return null
+  try {
+    const parsed: unknown = JSON.parse(await readBody(req))
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null
+  } catch {
+    return null
+  }
+}
+
+/** 默认客户端 IP 还原：XFF 最左优先，否则 socket 地址。 */
+function clientIpOf(req: IncomingMessage): string | undefined {
+  const forwarded = req.headers['x-forwarded-for']
+  if (typeof forwarded === 'string' && forwarded.trim() !== '') {
+    const first = forwarded.split(',')[0]?.trim()
+    if (first) return first
+  }
+  const remote = req.socket?.remoteAddress
+  if (remote === undefined || remote === '') return undefined
+  return remote.startsWith('::ffff:') ? remote.slice(7) : remote
+}
+
+/** 是否处于冷却期；冷却期满的条目惰性清除（计数中条目保留）。 */
+function throttled(state: ThrottleState, ip: string, now: number): boolean {
+  const entry = state.fails.get(ip)
+  if (entry === undefined) return false
+  if (entry.until > now) return true
+  if (entry.until > 0) state.fails.delete(ip)
+  return false
+}
+
+/** 记一次失败；达到阈值则进入冷却。 */
+function recordFailure(
+  state: ThrottleState,
+  ip: string,
+  limit: number,
+  cooldownMs: number,
+  now: number,
+): void {
+  const entry = state.fails.get(ip) ?? { count: 0, until: 0 }
+  entry.count += 1
+  if (entry.count >= limit) {
+    entry.until = now + cooldownMs
+    entry.count = 0
+  }
+  state.fails.set(ip, entry)
+}
+
+export function createGateRoutes(
+  deps: RouteDeps,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  const throttle = deps.throttle ?? createThrottleState()
+  const clock = deps.clock ?? Date.now
+  const resolveIp = deps.resolveClientIp ?? clientIpOf
+
+  const handleLogin = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const config = deps.config()
+    const body = await readJson(req)
+    if (body === undefined || body === null || typeof body.token !== 'string') {
+      sendJson(res, 400, { error: 'invalid json body' })
+      return
+    }
+    const ip = resolveIp(req) ?? 'unknown'
+    const now = clock()
+    if (throttled(throttle, ip, now)) {
+      sendJson(res, 429, { error: 'too many attempts' })
+      return
+    }
+    const ok = verifyToken(body.token, config.token)
+    if (!ok) {
+      recordFailure(throttle, ip, config.loginFailLimit, config.loginCooldownMs, now)
+      sendJson(res, 403, { error: 'invalid token' })
+      return
+    }
+    throttle.fails.delete(ip)
+    const maxAge = config.cookieMaxAgeHours * 3600
+    const cookie = `dsh_gate=${body.token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAge}`
+    sendJson(res, 200, { ok: true }, { 'set-cookie': cookie })
+  }
+
+  const handleStatus = (req: IncomingMessage, res: ServerResponse): void => {
+    const config = deps.config()
+    const decision = decideGate(
+      {
+        url: req.url ?? '/',
+        method: req.method ?? 'GET',
+        headers: req.headers,
+        remoteAddress: req.socket?.remoteAddress,
+      },
+      config,
+    )
+    sendJson(res, 200, {
+      enabled: config.enabled,
+      verdict: decision.verdict,
+      clientIp: decision.clientIp ?? null,
+      reason: decision.reason ?? null,
+      invalidEntries: decision.invalidEntries ?? [],
+      tokenConfigured: config.token !== '',
+      allowedCount: config.allowedIps.length,
+    })
+  }
+
+  return async (req, res) => {
+    try {
+      const sub = new URL(req.url ?? '/', 'http://localhost').pathname.slice(GATE_ROUTE.length)
+      const method = req.method ?? 'GET'
+      if (sub === '/login') {
+        if (method !== 'POST') return sendJson(res, 405, { error: 'POST only' })
+        return await handleLogin(req, res)
+      }
+      if (sub === '/status') {
+        if (method !== 'GET') return sendJson(res, 405, { error: 'GET only' })
+        return handleStatus(req, res)
+      }
+      sendJson(res, 404, { error: 'unknown endpoint' })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      deps.onError?.(`gate api failed: ${message}`)
+      if (!res.headersSent) sendJson(res, 500, { error: message })
+      else res.end()
+    }
+  }
+}
+
+/** token 校验（sha256 + 常时比较）；空 token 通道关闭恒 false。 */
+function verifyToken(candidate: string, expected: string): boolean {
+  if (candidate === '' || expected === '') return false
+  const a = createHash('sha256').update(candidate).digest()
+  const b = createHash('sha256').update(expected).digest()
+  return timingSafeEqual(a, b)
+}
+
+/** 注册路由（webServer 缺失时由调用方保证不调用）。 */
+export function registerGateRoutes(ctx: Context, deps: RouteDeps): void {
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: GATE_ROUTE,
+    handler: createGateRoutes(deps),
+  })
+}