@dsh-plus/access-gate 0.1.0

package/src/client/i18n.ts

@@ -0,0 +1,103 @@
+/**
+ * 配置卡片文案（zh/en）。经 ctx.locale.register 注册、bind 取用，与官方卡片同机制。
+ * @module access-gate/client/i18n
+ */
+
+export const NS = 'dsh-plus-access-gate'
+
+export const zh: Record<string, string> = {
+  title: '访问控制',
+  description: 'Web 访问围栏：本机直连放行；远程按白名单 IP 或访问令牌放行，其余拦截到登录页。',
+  enabled: '启用访问围栏',
+  enabledHint: '关闭即完全旁路（等价插件缺席）；启用后远程流量需命中白名单或令牌。',
+  token: '访问令牌',
+  tokenHint: '留空表示保持已存令牌不变；清空并保存需先输入既有令牌确认。',
+  tokenSet: '已配置',
+  tokenUnset: '未配置',
+  allowedIps: '放行 IP 白名单',
+  allowedIpsHint:
+    '每行一个：精确 IP 或 CIDR（IPv4/IPv6 皆可），如 100.86.108.55 或 fd7a:115c:a1e0::/48。',
+  trustForwardedFor: '信任 x-forwarded-for 还原客户端 IP',
+  trustForwardedForHint:
+    '仅当入口代理强制覆盖该头时开启（tailscale serve 满足）；直连暴露场景必须关闭。',
+  cookieMaxAgeHours: '登录有效期（小时）',
+  cookieMaxAgeHoursHint: '令牌登录后 cookie 的有效期。',
+  loginFailLimit: '登录失败阈值',
+  loginFailLimitHint: '每个 IP 在冷却窗口内允许的失败次数，超出进入冷却。',
+  loginCooldownMs: '登录冷却（毫秒）',
+  loginCooldownMsHint: '失败达到阈值后的冷却时长。',
+  diagTitle: '当前页面诊断',
+  diagVerdict: '本页判定',
+  diagClientIp: '客户端 IP',
+  diagReason: '放行原因',
+  diagLocal: '本机直连',
+  diagAllowedIp: '白名单 IP',
+  diagToken: '令牌',
+  diagPass: '放行',
+  diagBlock: '拦截',
+  diagLogin: '登录页',
+  diagOff: '围栏未启用',
+  diagInvalid: '白名单存在无法解析的条目：',
+  warnFailClosed: '警告：已启用但令牌与白名单均为空——所有远程访问将被拒绝（含本页之外的设备）。',
+  save: '保存',
+  saving: '保存中…',
+  discard: '放弃',
+  unsaved: '未保存',
+  saveFailed: '保存失败，请检查填写内容。',
+  loading: '加载中…',
+  unavailable: '配置服务不可用。',
+  readOnly: '当前部署无 settings provider，配置为只读；请编辑 settings.yaml。',
+  expand: '展开',
+  collapse: '收起',
+  invalidNumber: '请输入有效数字',
+}
+
+export const en: Record<string, string> = {
+  title: 'Access Control',
+  description:
+    'Web access gate: loopback passes; remote traffic needs an allowlisted IP or the token, others hit the login page.',
+  enabled: 'Enable access gate',
+  enabledHint:
+    'Off means full bypass (as if absent); on, remote traffic must match the allowlist or the token.',
+  token: 'Access token',
+  tokenHint: 'Leave blank to keep the stored token; clearing requires typing the current one.',
+  tokenSet: 'Set',
+  tokenUnset: 'Not set',
+  allowedIps: 'Allowed IP allowlist',
+  allowedIpsHint:
+    'One per line: exact IP or CIDR (IPv4/IPv6), e.g. 100.86.108.55 or fd7a:115c:a1e0::/48.',
+  trustForwardedFor: 'Trust x-forwarded-for for client IP',
+  trustForwardedForHint:
+    'Enable only when the entry proxy overwrites that header (tailscale serve does); must be off for direct exposure.',
+  cookieMaxAgeHours: 'Login validity (hours)',
+  cookieMaxAgeHoursHint: 'Cookie lifetime after a token login.',
+  loginFailLimit: 'Login failure limit',
+  loginFailLimitHint: 'Failures per IP within the cooldown window before throttling.',
+  loginCooldownMs: 'Login cooldown (ms)',
+  loginCooldownMsHint: 'Cooldown duration after reaching the limit.',
+  diagTitle: 'This page',
+  diagVerdict: 'Verdict',
+  diagClientIp: 'Client IP',
+  diagReason: 'Reason',
+  diagLocal: 'loopback',
+  diagAllowedIp: 'allowlisted IP',
+  diagToken: 'token',
+  diagPass: 'pass',
+  diagBlock: 'blocked',
+  diagLogin: 'login page',
+  diagOff: 'gate disabled',
+  diagInvalid: 'Allowlist entries that failed to parse:',
+  warnFailClosed:
+    'Warning: enabled with no token and an empty allowlist — all remote access will be refused.',
+  save: 'Save',
+  saving: 'Saving…',
+  discard: 'Discard',
+  unsaved: 'Unsaved',
+  saveFailed: 'Save failed; please check the inputs.',
+  loading: 'Loading…',
+  unavailable: 'Settings service unavailable.',
+  readOnly: 'No settings provider in this deployment; read-only. Edit settings.yaml instead.',
+  expand: 'Expand',
+  collapse: 'Collapse',
+  invalidNumber: 'Enter a valid number',
+}

package/src/client/scope.ts

@@ -0,0 +1,53 @@
+/**
+ * 浏览器半 settingsScope/connection 的最小本地接口声明（notify-email 同款）。
+ * 只声明本插件用到的窄面，避免为构建期类型引入整条官方 client 依赖树；
+ * 运行时契约以官方 dsh-client-connection 的 settings RPC 面为准。
+ * @module access-gate/client/scope
+ */
+
+/** settings 命名空间 scope 的快照（官方 SettingsScopeSnapshot 的最小投影）。 */
+export interface ScopeSnapshot {
+  status: 'loading' | 'ready' | 'unavailable'
+  /** schema 解析后的配置值（secret 字段已脱敏剥除）。 */
+  value: unknown
+  /** 命名空间 revision，写操作 fencing 用；首次 Host 应答前为 undefined。 */
+  revision: number | undefined
+  /** Host 文档是否可写。 */
+  writable: boolean
+}
+
+/** settingsScope.bind({namespace}) 返回的控制器面（本插件由 api 直连实现）。 */
+export interface Scope {
+  getSnapshot(): ScopeSnapshot
+  subscribe(listener: () => void): () => void
+  load(): Promise<void>
+}
+
+/** connection api.settings 的 RPC 面（本插件用到的三个方法）。 */
+export interface SettingsApi {
+  describe(payload?: Record<string, never>): Promise<{
+    result: {
+      ok: boolean
+      value?: {
+        writable: boolean
+        namespaces: Array<{
+          ns: string
+          value: unknown
+          revision: number
+          secrets: Array<{ path: string[]; set: boolean }>
+        }>
+      }
+      error?: { message?: string }
+    }
+  }>
+  update(request: {
+    ns: string
+    patch: Record<string, unknown>
+    expectedRevision?: number
+  }): Promise<{ result: { ok: boolean; error?: { message?: string } } }>
+  replace(request: {
+    ns: string
+    section: Record<string, unknown>
+    expectedRevision?: number
+  }): Promise<{ result: { ok: boolean; error?: { message?: string } } }>
+}

package/src/client/styles.ts

@@ -0,0 +1,74 @@
+/**
+ * 配置卡片样式：沿用官方 data-plugin / data-plugin-css 约定（HMR 据此卸载），
+ * 视觉对齐官方卡片（--dsw-alias-* 变量），不覆盖上游任何选择器。
+ * @module access-gate/client/styles
+ */
+
+export const PLUGIN_ID = '@dsh-plus/access-gate'
+export const STYLE_TAG_ID = `${PLUGIN_ID}/card.css`
+
+export const cardCss = `
+.dag-card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:12px;list-style:none;transition:border-color .16s,background .16s}
+.dag-card:hover{border-color:var(--dsw-alias-label-dimmed)}
+.dag-cardOpen{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}
+.dag-header{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;align-items:center;gap:12px;padding:14px 16px;display:flex}
+.dag-header:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}
+.dag-headText{flex-direction:column;flex:1;gap:4px;min-width:0;display:flex}
+.dag-name{color:var(--dsw-alias-label-primary);font-size:15px;font-weight:600;line-height:1.4}
+.dag-description{color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:1.5}
+.dag-chevron{color:var(--dsw-alias-label-tertiary);flex:none;transition:transform .16s;font-size:12px}
+.dag-chevronOpen{transform:rotate(180deg)}
+.dag-pending{white-space:nowrap;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary);border-radius:999px;flex:none;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}
+.dag-body{border-top:1px solid var(--dsw-alias-border-l2);margin:0 16px;padding-bottom:8px}
+.dag-field{flex-direction:column;gap:6px;padding:12px 0;display:flex}
+.dag-field+.dag-field{border-top:1px solid var(--dsw-alias-border-l2)}
+.dag-head{align-items:center;gap:8px;display:flex}
+.dag-label{min-width:0;color:var(--dsw-alias-label-primary);flex:1;font-size:13px;font-weight:500;line-height:1.5}
+.dag-badge{white-space:nowrap;border-radius:999px;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}
+.dag-badgeSet{background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary)}
+.dag-badgeUnset{color:var(--dsw-alias-label-tertiary)}
+.dag-input{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px}
+.dag-input:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}
+.dag-input:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}
+.dag-inputInvalid{border-color:var(--dsw-alias-label-error)}
+.dag-textarea{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:8px 12px;font-size:13px;line-height:1.6;min-height:96px;resize:vertical;font-family:var(--dsw-alias-font-mono,ui-monospace,monospace)}
+.dag-textarea:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}
+.dag-textarea:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}
+.dag-hint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:1.5}
+.dag-invalid{color:var(--dsw-alias-label-error);margin:0;font-size:12px;line-height:1.5}
+.dag-checkRow{align-items:center;gap:8px;display:flex;padding:6px 0}
+.dag-checkRow input{accent-color:var(--dsw-alias-brand-primary)}
+.dag-checkRow label{color:var(--dsw-alias-label-primary);font-size:13px;line-height:1.5;cursor:pointer}
+.dag-groupLabel{color:var(--dsw-alias-label-secondary);font-size:12px;font-weight:600;padding:12px 0 2px;margin:0}
+.dag-readOnly{color:var(--dsw-alias-label-tertiary);margin:12px 0 0;font-size:12px;line-height:1.5}
+.dag-footer{border-top:1px solid var(--dsw-alias-border-l2);justify-content:flex-end;align-items:center;gap:8px;padding:12px 0 4px;display:flex;flex-wrap:wrap}
+.dag-status{min-width:0;color:var(--dsw-alias-label-secondary);flex:1;margin:0;font-size:12px;line-height:1.5}
+.dag-statusError{color:var(--dsw-alias-label-error)}
+.dag-btn{appearance:none;font:inherit;cursor:pointer;border:1px solid #0000;border-radius:8px;padding:5px 14px;font-size:13px;line-height:1.5}
+.dag-btnGhost{border-color:var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);background:0 0}
+.dag-btnGhost:hover:not(:disabled){color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-dimmed)}
+.dag-btnPrimary{background:var(--dsh-plus-brand,#3d6dff);color:#fff}
+.dag-btn:disabled{opacity:.4;cursor:default}
+.dag-btn:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:1px}
+.dag-diag{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:10px 12px;margin:12px 0 0;flex-direction:column;gap:4px;display:flex}
+.dag-diagTitle{color:var(--dsw-alias-label-secondary);font-size:12px;font-weight:600;margin:0}
+.dag-diagRow{display:flex;gap:8px;font-size:12px;line-height:1.6}
+.dag-diagKey{color:var(--dsw-alias-label-tertiary);flex:none;min-width:72px}
+.dag-diagVal{color:var(--dsw-alias-label-primary);margin:0}
+.dag-diagWarn{color:var(--dsw-alias-label-error);border-color:var(--dsw-alias-label-error)}
+.dag-warn{color:var(--dsh-plus-warn,#c9503f);border:1px solid var(--dsh-plus-warn-border,rgba(201,80,63,.4));border-radius:8px;padding:8px 12px;margin:12px 0 0;font-size:12px;line-height:1.6}
+`
+
+/** 幂等注入样式标签；返回标签（已存在或环境无 document 时为 null）。 */
+export function injectStyle(): HTMLStyleElement | null {
+  if (typeof document === 'undefined') return null
+  if (document.querySelector(`style[data-plugin-css=${JSON.stringify(STYLE_TAG_ID)}]`) !== null) {
+    return null
+  }
+  const tag = document.createElement('style')
+  tag.dataset.plugin = PLUGIN_ID
+  tag.dataset.pluginCss = STYLE_TAG_ID
+  tag.textContent = cardCss
+  document.head.append(tag)
+  return tag
+}

package/src/config.ts

@@ -0,0 +1,61 @@
+/**
+ * 配置单一事实源：cordis 行级 Config（组合默认值，dev/prod patch 层可覆盖）
+ * 与 settings namespace（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）
+ * 共用同一 schemastery schema（notify-email 同款约定）。
+ * token 标记 secret 角色：任何读取通道不得回传明文。
+ * @module access-gate/config
+ */
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from '@deepseek-ai/schemastery'
+
+import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
+
+/** settings 命名空间；webui 配置卡片与插件运行期读取同一份（字面量见 ./ns.ts）。 */
+export const SETTINGS_NS = settingsNamespace(NS_LITERAL)
+
+export const Config = z.object({
+  enabled: z
+    .boolean()
+    .description('访问围栏总开关（false = 一切放行，等价插件缺席）')
+    .default(false),
+  token: z
+    .string()
+    .role('secret')
+    .description('访问令牌；空字符串 = token 通道关闭。经登录页输入后以 HttpOnly cookie 持有')
+    .default(''),
+  allowedIps: z
+    .array(z.string())
+    .description('放行 IP 白名单：精确 IP 或 CIDR（IPv4/IPv6 皆可）')
+    .default([]),
+  trustForwardedFor: z
+    .boolean()
+    .description(
+      '是否信任 x-forwarded-for 还原真实客户端 IP（仅当入口代理强制覆盖该头时开启；tailscale serve 满足）',
+    )
+    .default(true),
+  cookieMaxAgeHours: z
+    .natural()
+    .max(24 * 365)
+    .description('登录 cookie 有效期（小时）')
+    .default(720),
+  loginFailLimit: z
+    .natural()
+    .description('登录失败节流阈值（每 IP 冷却窗口内允许的失败次数）')
+    .default(10),
+  loginCooldownMs: z.natural().description('登录失败节流冷却毫秒数').default(60000),
+})
+
+export type AccessGateConfig = Schemastery.TypeT<typeof Config>
+
+/** 判定所需的最小配置视图（测试与决策函数共用窄面）。 */
+export interface GatePolicy {
+  readonly enabled: boolean
+  readonly token: string
+  readonly allowedIps: readonly string[]
+  readonly trustForwardedFor: boolean
+}
+
+/** 远程放行通道是否全部关闭（enabled 且无 token 且白名单空 = 拒绝一切远程）。 */
+export function isFailClosed(policy: GatePolicy): boolean {
+  return policy.enabled && policy.token === '' && policy.allowedIps.length === 0
+}

package/src/decision.ts

@@ -0,0 +1,137 @@
+/**
+ * 围栏判定核心：`decideGate` 纯函数。
+ *
+ * 信任模型（决策记录详见 docs/README.md）：
+ * - dsh web 仅绑 127.0.0.1，远程流量必经 tailscale serve → dsh-proxy 两跳，
+ *   serve 会**覆盖**（而非追加）x-forwarded-for，客户端无法伪造；
+ * - 能直发 loopback 或伪造 XFF 的只有本机进程——与 dsh 官方 /api 围栏的
+ *   loopback 信任边界一致，本机直连视为可信管理通道；
+ * - 因此 XFF 存在且 trustForwardedFor=true 时取最左条目为真实客户端 IP。
+ *
+ * token 比较使用 sha256 摘要 + timingSafeEqual 常时比较。
+ * @module access-gate/decision
+ */
+import { createHash, timingSafeEqual } from 'node:crypto'
+
+import type { GatePolicy } from './config.ts'
+import { isLoopbackAddress, parseAllowEntry, parseIp } from './ip.ts'
+
+export const GATE_COOKIE = 'dsh_gate'
+
+/** 围栏判定结果。 */
+export type GateVerdict =
+  | 'pass' /** 放行（本机直连 / 白名单 IP / 有效 token） */
+  | 'block' /** 拒绝：API / WebSocket 等非导航请求 → 403 */
+  | 'login' /** 拒绝：浏览器导航请求 → 登录页 */
+
+/** 判定输出。 */
+export interface GateDecision {
+  verdict: GateVerdict
+  /** 还原出的客户端 IP（有 XFF 或非 loopback 直连时存在）。 */
+  clientIp?: string
+  /** 放行原因（诊断/日志用）：local / allowed-ip / token。 */
+  reason?: 'local' | 'allowed-ip' | 'token'
+  /** 无效白名单条目（卡片诊断用，判定时忽略它们）。 */
+  invalidEntries?: string[]
+}
+
+/** 判定输入的请求事实（headers 小写键，node:http 原生形态）。 */
+export interface GateRequest {
+  readonly url: string
+  readonly method: string
+  readonly headers: Record<string, unknown>
+  readonly remoteAddress?: string
+}
+
+/** sha256 摘要为定长 32 字节，常时比较的前提。 */
+function tokenMatches(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)
+}
+
+/** 从 cookie 头解析指定名字的值（手写最小解析，零依赖）。 */
+export function readCookie(headers: Record<string, unknown>, name: string): string | undefined {
+  const raw = headers.cookie
+  if (typeof raw !== 'string') return undefined
+  for (const part of raw.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    if (part.slice(0, eq).trim() === name) {
+      const value = part.slice(eq + 1).trim()
+      return value === '' ? undefined : value
+    }
+  }
+  return undefined
+}
+
+/** 取 XFF 最左条目（serve 单跳覆盖语义下即真实客户端 IP）。 */
+function forwardedIp(headers: Record<string, unknown>): string | undefined {
+  const raw = headers['x-forwarded-for']
+  if (typeof raw !== 'string' || raw.trim() === '') return undefined
+  const first = raw.split(',')[0]?.trim() ?? ''
+  return first === '' ? undefined : first
+}
+
+/** 浏览器导航请求判定：GET + accept 含 text/html（需要返回登录页而非 403）。 */
+export function isNavigationRequest(req: GateRequest): boolean {
+  if (req.method !== 'GET' && req.method !== 'HEAD') return false
+  const accept = req.headers.accept
+  return typeof accept === 'string' && accept.includes('text/html')
+}
+
+/** 预解析白名单（含非法条目收集），每次判定复用。 */
+export interface CompiledAllowlist {
+  match: (ip: { value: bigint; bits: 32 | 128 }) => boolean
+  invalid: string[]
+}
+
+export function compileAllowlist(entries: readonly string[]): CompiledAllowlist {
+  const matchers = entries.flatMap((entry) => {
+    const matcher = parseAllowEntry(entry)
+    return matcher === null ? [] : [matcher]
+  })
+  const invalid = entries.filter((entry) => parseAllowEntry(entry) === null)
+  return { match: (ip) => matchers.some((matcher) => matcher(ip)), invalid }
+}
+
+/**
+ * 围栏判定（纯函数，除 token 哈希外无任何副作用与 IO）。
+ * 逻辑次序：豁免路径由调用方前置处理；enabled=false 直通；确定有效来源
+ * （受信 XFF 优先，否则 remoteAddress）；来源为 loopback 直连 → 放行；
+ * 否则按白名单/token 判定；无来源 → fail-closed。
+ *
+ * loopback 语义：XFF 被信任时，存在 XFF 即代表请求经代理（serve→proxy→dsh
+ * 全链 loopback，真实客户端只在 XFF 里）——remoteAddress 是 loopback 也不
+ * 放行，必须按 XFF 判定；XFF 不被信任时，来源就是 remoteAddress，
+ * loopback 即本机直连 → 放行（防锁死兜底优先）。
+ */
+export function decideGate(req: GateRequest, policy: GatePolicy): GateDecision {
+  if (!policy.enabled) return { verdict: 'pass', reason: 'local' }
+
+  const forwarded = forwardedIp(req.headers)
+  const trustedForwarded = policy.trustForwardedFor ? forwarded : undefined
+  const clientIpText = trustedForwarded ?? req.remoteAddress
+  if (clientIpText === undefined) {
+    return { verdict: 'block', reason: undefined }
+  }
+  if (trustedForwarded === undefined && isLoopbackAddress(req.remoteAddress)) {
+    return { verdict: 'pass', reason: 'local' }
+  }
+
+  const allowlist = compileAllowlist(policy.allowedIps)
+  const clientIp = parseIp(clientIpText)
+  const allowedByIp = clientIp !== null && allowlist.match(clientIp)
+  const cookieToken = readCookie(req.headers, GATE_COOKIE)
+  const allowedByToken = cookieToken !== undefined && tokenMatches(cookieToken, policy.token)
+
+  const decision: GateDecision = {
+    verdict: allowedByIp || allowedByToken ? 'pass' : isNavigationRequest(req) ? 'login' : 'block',
+    clientIp: clientIpText,
+  }
+  if (allowedByToken) decision.reason = 'token'
+  else if (allowedByIp) decision.reason = 'allowed-ip'
+  if (allowlist.invalid.length > 0) decision.invalidEntries = allowlist.invalid
+  return decision
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+/**
+ * dsh 插件：访问围栏（access-gate）。
+ *
+ * 为 dsh web 的全部 HTTP/WebSocket 流量提供访问安全校验与访问控制：
+ * - 本机直连（loopback 且无 x-forwarded-for）永久放行——管理通道，防锁死；
+ * - 远程流量按 tailscale serve 注入的 x-forwarded-for 还原真实客户端 IP，
+ *   命中白名单（精确 IP / CIDR，v4+v6）即放行；
+ * - 或持有效 token（登录页换取 HttpOnly cookie）放行；
+ * - 其余：浏览器导航返回登录页，API / WS 一律 403 / 拒绝升级。
+ *
+ * 配置：settings 命名空间 dsh-plus-access-gate（webui 配置卡片同一份，
+ * 热生效）；enabled=false 时完全旁路（等价插件缺席）。
+ * 安全边界：结构守卫 fail-loud（upstream 形状变化 → 启动失败 → lifeboat
+ * 隔离止损，绝不静默 fail-open）。
+ * @module @dsh-plus/access-gate
+ */
+import { type Context, Service } from '@deepseek-ai/cordis'
+import { installSettingsSection } from '@deepseek-ai/dsh-settings'
+
+import { type AccessGateConfig, Config, SETTINGS_NS } from './config.ts'
+import { type GateWebServer, installGateInterceptor } from './interceptor.ts'
+import { registerGateRoutes } from './routes.ts'
+
+export const name = 'dsh-plus-access-gate'
+
+export const inject = ['webServer'] as const
+
+export { Config }
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    accessGate: AccessGateService
+  }
+}
+
+/** 围栏服务：持有当前配置读取器（settings 用户层热更新经 setSource 注入）。 */
+export class AccessGateService extends Service {
+  private current: () => AccessGateConfig
+
+  constructor(ctx: Context, config: AccessGateConfig) {
+    super(ctx, 'accessGate')
+    this.current = () => config
+    installSettingsSection(ctx, SETTINGS_NS, Config, config, {
+      setSource: (source) => {
+        this.current = source
+      },
+      onChange: () => {},
+    })
+    const logger = ctx.logger('access-gate')
+
+    // 自有端点（/dsh-plus/gate/*，围栏豁免路径）。
+    registerGateRoutes(ctx, {
+      config: () => this.current(),
+      onError: (message) => logger.warn(message),
+    })
+
+    // 结构包装：全部 HTTP/WS 流量的围栏。
+    const undo = installGateInterceptor(ctx, ctx.webServer as unknown as GateWebServer, {
+      config: () => this.current(),
+      onBlock: (message) => logger.info(message),
+    })
+    ctx.effect(() => undo, 'access-gate: interceptor')
+  }
+
+  /** 当前生效配置（诊断用）。 */
+  policy(): AccessGateConfig {
+    return this.current()
+  }
+}
+
+export function apply(ctx: Context, config: AccessGateConfig): void {
+  ctx.plugin(AccessGateService, config)
+}