@dsh-plus/access-gate 0.1.0

package/lib/index.js

@@ -0,0 +1,663 @@
+import { Service } from "@deepseek-ai/cordis";
+import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
+import { createHash, timingSafeEqual } from "node:crypto";
+//#endregion
+//#region src/config.ts
+/**
+* 配置单一事实源：cordis 行级 Config（组合默认值，dev/prod patch 层可覆盖）
+* 与 settings namespace（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）
+* 共用同一 schemastery schema（notify-email 同款约定）。
+* token 标记 secret 角色：任何读取通道不得回传明文。
+* @module access-gate/config
+*/
+/** settings 命名空间；webui 配置卡片与插件运行期读取同一份（字面量见 ./ns.ts）。 */
+const SETTINGS_NS = settingsNamespace("dsh-plus-access-gate");
+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(8760).description("登录 cookie 有效期（小时）").default(720),
+	loginFailLimit: z.natural().description("登录失败节流阈值（每 IP 冷却窗口内允许的失败次数）").default(10),
+	loginCooldownMs: z.natural().description("登录失败节流冷却毫秒数").default(6e4)
+});
+//#endregion
+//#region src/ip.ts
+/** 解析 IPv4 十进制点分字面量；非法返回 null。 */
+function parseIpv4(text) {
+	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, group) {
+	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) {
+	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, atStart) => {
+		if (half === "") return {
+			value: 0n,
+			groups: 0
+		};
+		const rawGroups = half.split(":");
+		if (rawGroups.some((group) => group === "")) return null;
+		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;
+	const holeAndTail = BigInt(8 - head.groups) * 16n;
+	return head.value << holeAndTail | tail.value;
+}
+/** 解析任意 IP 字面量；非法返回 null。 */
+function parseIp(text) {
+	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。 */
+function parseCidr(text) {
+	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
+	};
+}
+/** 同族且数值相等。 */
+function ipEquals(a, b) {
+	return a.bits === b.bits && a.value === b.value;
+}
+/** 判断 IP 是否落入 CIDR；跨族（v4 vs v6）恒 false。 */
+function ipInCidr(ip, cidr) {
+	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。 */
+function parseAllowEntry(text) {
+	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`）。 */
+function isLoopbackAddress(remoteAddress) {
+	if (remoteAddress === void 0) 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 >= 2130706432n && parsed.value <= 2147483646n;
+}
+//#endregion
+//#region src/decision.ts
+/**
+* 围栏判定核心：`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
+*/
+const GATE_COOKIE = "dsh_gate";
+/** sha256 摘要为定长 32 字节，常时比较的前提。 */
+function tokenMatches(candidate, expected) {
+	if (candidate === "" || expected === "") return false;
+	const a = createHash("sha256").update(candidate).digest();
+	const b = createHash("sha256").update(expected).digest();
+	return timingSafeEqual(a, b);
+}
+/** 从 cookie 头解析指定名字的值（手写最小解析，零依赖）。 */
+function readCookie(headers, name) {
+	const raw = headers.cookie;
+	if (typeof raw !== "string") return void 0;
+	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 === "" ? void 0 : value;
+		}
+	}
+}
+/** 取 XFF 最左条目（serve 单跳覆盖语义下即真实客户端 IP）。 */
+function forwardedIp(headers) {
+	const raw = headers["x-forwarded-for"];
+	if (typeof raw !== "string" || raw.trim() === "") return void 0;
+	const first = raw.split(",")[0]?.trim() ?? "";
+	return first === "" ? void 0 : first;
+}
+/** 浏览器导航请求判定：GET + accept 含 text/html（需要返回登录页而非 403）。 */
+function isNavigationRequest(req) {
+	if (req.method !== "GET" && req.method !== "HEAD") return false;
+	const accept = req.headers.accept;
+	return typeof accept === "string" && accept.includes("text/html");
+}
+function compileAllowlist(entries) {
+	const matchers = entries.flatMap((entry) => {
+		const matcher = parseAllowEntry(entry);
+		return matcher === null ? [] : [matcher];
+	});
+	return {
+		match: (ip) => matchers.some((matcher) => matcher(ip)),
+		invalid: entries.filter((entry) => parseAllowEntry(entry) === null)
+	};
+}
+/**
+* 围栏判定（纯函数，除 token 哈希外无任何副作用与 IO）。
+* 逻辑次序：豁免路径由调用方前置处理；enabled=false 直通；确定有效来源
+* （受信 XFF 优先，否则 remoteAddress）；来源为 loopback 直连 → 放行；
+* 否则按白名单/token 判定；无来源 → fail-closed。
+*
+* loopback 语义：XFF 被信任时，存在 XFF 即代表请求经代理（serve→proxy→dsh
+* 全链 loopback，真实客户端只在 XFF 里）——remoteAddress 是 loopback 也不
+* 放行，必须按 XFF 判定；XFF 不被信任时，来源就是 remoteAddress，
+* loopback 即本机直连 → 放行（防锁死兜底优先）。
+*/
+function decideGate(req, policy) {
+	if (!policy.enabled) return {
+		verdict: "pass",
+		reason: "local"
+	};
+	const forwarded = forwardedIp(req.headers);
+	const trustedForwarded = policy.trustForwardedFor ? forwarded : void 0;
+	const clientIpText = trustedForwarded ?? req.remoteAddress;
+	if (clientIpText === void 0) return {
+		verdict: "block",
+		reason: void 0
+	};
+	if (trustedForwarded === void 0 && 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 !== void 0 && tokenMatches(cookieToken, policy.token);
+	const decision = {
+		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;
+}
+//#endregion
+//#region src/login-page.ts
+/**
+* 登录页：围栏拦截浏览器导航请求时返回的内联 HTML。
+* 自包含（无外部静态资源依赖）、中文、vanilla JS——输入 token → 调
+* /dsh-plus/gate/login → 成功后 reload 放行。
+* @module access-gate/login-page
+*/
+function renderLoginPage() {
+	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>`;
+}
+//#endregion
+//#region src/routes.ts
+/**
+* 自有 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
+*/
+const GATE_ROUTE = "/dsh-plus/gate";
+function createThrottleState() {
+	return { fails: /* @__PURE__ */ new Map() };
+}
+function sendJson(res, status, body, headers) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		...headers
+	});
+	res.end(JSON.stringify(body));
+}
+function readBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		req.on("error", reject);
+	});
+}
+/** 解析 JSON body；非对象或解析失败返回 null。 */
+async function readJson(req) {
+	if (!req.headers["content-type"]?.includes("application/json")) return null;
+	try {
+		const parsed = JSON.parse(await readBody(req));
+		return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/** 默认客户端 IP 还原：XFF 最左优先，否则 socket 地址。 */
+function clientIpOf(req) {
+	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 === void 0 || remote === "") return void 0;
+	return remote.startsWith("::ffff:") ? remote.slice(7) : remote;
+}
+/** 是否处于冷却期；冷却期满的条目惰性清除（计数中条目保留）。 */
+function throttled(state, ip, now) {
+	const entry = state.fails.get(ip);
+	if (entry === void 0) return false;
+	if (entry.until > now) return true;
+	if (entry.until > 0) state.fails.delete(ip);
+	return false;
+}
+/** 记一次失败；达到阈值则进入冷却。 */
+function recordFailure(state, ip, limit, cooldownMs, now) {
+	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);
+}
+function createGateRoutes(deps) {
+	const throttle = deps.throttle ?? createThrottleState();
+	const clock = deps.clock ?? Date.now;
+	const resolveIp = deps.resolveClientIp ?? clientIpOf;
+	const handleLogin = async (req, res) => {
+		const config = deps.config();
+		const body = await readJson(req);
+		if (body === void 0 || 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;
+		}
+		if (!verifyToken(body.token, config.token)) {
+			recordFailure(throttle, ip, config.loginFailLimit, config.loginCooldownMs, now);
+			sendJson(res, 403, { error: "invalid token" });
+			return;
+		}
+		throttle.fails.delete(ip);
+		const maxAge = config.cookieMaxAgeHours * 3600;
+		sendJson(res, 200, { ok: true }, { "set-cookie": `dsh_gate=${body.token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAge}` });
+	};
+	const handleStatus = (req, res) => {
+		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(14);
+			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, expected) {
+	if (candidate === "" || expected === "") return false;
+	const a = createHash("sha256").update(candidate).digest();
+	const b = createHash("sha256").update(expected).digest();
+	return timingSafeEqual(a, b);
+}
+/** 注册路由（webServer 缺失时由调用方保证不调用）。 */
+function registerGateRoutes(ctx, deps) {
+	ctx.webServer.register({
+		kind: "prefix",
+		path: GATE_ROUTE,
+		handler: createGateRoutes(deps)
+	});
+}
+//#endregion
+//#region src/interceptor.ts
+/** 是否围栏豁免路径（自有登录/状态端点）。 */
+function isExemptPath(pathname) {
+	return pathname === "/dsh-plus/gate" || pathname.startsWith(`/dsh-plus/gate/`);
+}
+function toGateRequest(req) {
+	return {
+		url: req.url ?? "/",
+		method: req.method ?? "GET",
+		headers: req.headers,
+		remoteAddress: req.socket?.remoteAddress
+	};
+}
+/** WS 升级拒绝：按官方同款 403 原始响应后关闭。 */
+function rejectUpgrade(socket, clientIp, log) {
+	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, res, deps) {
+	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, deps) {
+	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, deps) {
+	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 ?? (() => {}));
+	};
+}
+/**
+* 安装围栏（结构包装 + fail-loud 守卫）。
+* @returns 恢复函数（调用方登记进 ctx.effect）。
+*/
+function installGateInterceptor(ctx, server, deps) {
+	assertGateStructure(server);
+	const restores = [];
+	const originalMatch = server.match.bind(server);
+	const gatedMatch = (pathname) => {
+		if (isExemptPath(pathname)) return originalMatch(pathname);
+		if (!deps.config().enabled) return originalMatch(pathname);
+		const route = originalMatch(pathname);
+		if (route === void 0) return void 0;
+		return {
+			...route,
+			handler: gatedHttp(route.handler, deps)
+		};
+	};
+	server.match = gatedMatch;
+	restores.push({ undo: () => {
+		server.match = originalMatch;
+	} });
+	const wrapFallback = (handler) => gatedHttp(handler, deps);
+	const originalFallback = server.fallback;
+	let fallbackReplaced = false;
+	if (originalFallback !== void 0) {
+		server.fallback = wrapFallback(originalFallback);
+		fallbackReplaced = true;
+	}
+	const originalRegisterFallback = server.registerFallback.bind(server);
+	const patchedRegisterFallback = (handler) => originalRegisterFallback(wrapFallback(handler));
+	server.registerFallback = patchedRegisterFallback;
+	restores.push({ undo: () => {
+		server.registerFallback = originalRegisterFallback;
+		if (fallbackReplaced) server.fallback = originalFallback;
+	} });
+	const wrapped = /* @__PURE__ */ new Map();
+	const wrapUpgradeRoute = (route) => {
+		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) => {
+		const disposer = originalRegisterUpgrade(route);
+		if (server.upgrades.get(route.path) === route) wrapUpgradeRoute(route);
+		return disposer;
+	};
+	server.registerUpgrade = patchedRegisterUpgrade;
+	restores.push({ undo: () => {
+		server.registerUpgrade = originalRegisterUpgrade;
+		for (const [route, handler] of wrapped) route.handler = handler;
+		wrapped.clear();
+	} });
+	const undo = () => {
+		for (let i = restores.length - 1; i >= 0; i -= 1) restores[i].undo();
+	};
+	return undo;
+}
+/** 结构守卫：字段形状不符即抛错（fail-loud）。 */
+function assertGateStructure(server) {
+	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)");
+}
+//#endregion
+//#region src/index.ts
+/**
+* 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
+*/
+const name = "dsh-plus-access-gate";
+const inject = ["webServer"];
+/** 围栏服务：持有当前配置读取器（settings 用户层热更新经 setSource 注入）。 */
+var AccessGateService = class extends Service {
+	current;
+	constructor(ctx, config) {
+		super(ctx, "accessGate");
+		this.current = () => config;
+		installSettingsSection(ctx, SETTINGS_NS, Config, config, {
+			setSource: (source) => {
+				this.current = source;
+			},
+			onChange: () => {}
+		});
+		const logger = ctx.logger("access-gate");
+		registerGateRoutes(ctx, {
+			config: () => this.current(),
+			onError: (message) => logger.warn(message)
+		});
+		const undo = installGateInterceptor(ctx, ctx.webServer, {
+			config: () => this.current(),
+			onBlock: (message) => logger.info(message)
+		});
+		ctx.effect(() => undo, "access-gate: interceptor");
+	}
+	/** 当前生效配置（诊断用）。 */
+	policy() {
+		return this.current();
+	}
+};
+function apply(ctx, config) {
+	ctx.plugin(AccessGateService, config);
+}
+//#endregion
+export { AccessGateService, Config, apply, inject, name };