@dsh-plus/access-gate 0.2.4 → 0.3.1

package/lib/index.js

@@ -1,5 +1,9 @@
 import { Service } from "@deepseek-ai/cordis";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
 import z from "@deepseek-ai/schemastery";
+import { createHash, createHmac } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 //#endregion
 //#region src/config.ts
 /**
@@ -19,9 +23,128 @@ const SETTINGS_NS = "dsh-plus-access-gate";
 const Config = z.object({
 	enabled: z.boolean().description("访问围栏总开关（false = 一切放行，等价插件缺席）").default(false),
 	allowedIps: z.array(z.string()).description("附加 IP 围栏：非空时仅白名单条目（精确 IP 或 CIDR，IPv4/IPv6 皆可）可通行与登录；空 = 不限制来源 IP（仅官方登录保护）").default([]),
-	trustForwardedFor: z.boolean().description("是否信任 x-forwarded-for 还原真实客户端 IP（仅当入口代理强制覆盖该头时开启；tailscale serve 满足）").default(true)
+	trustForwardedFor: z.boolean().description("是否信任 x-forwarded-for 还原真实客户端 IP（仅当入口代理强制覆盖该头时开启；tailscale serve 满足）").default(true),
+	autoLoginTrustedIps: z.boolean().description("IP 信任自动登录：来源命中 allowedIps 白名单且未认证时，服务端自动签发官方登录 cookie（免启动 token，仅对白名单来源生效）；默认关闭，需显式开启").default(false)
 });
 //#endregion
+//#region src/cookie.ts
+/**
+* 官方 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
+*/
+/** 官方 cookie 名前缀（client-connection browser-auth 常量）。 */
+const COOKIE_PREFIX = "dsh-auth-";
+/** payload version（官方 COOKIE_PAYLOAD_VERSION）。 */
+const PAYLOAD_VERSION = 1;
+/** 密钥长度（官方 SECRET_BYTES）。 */
+const SECRET_BYTES = 32;
+/** 自签 cookie 有效期：官方默认 cookieMaxAgeDays。 */
+const COOKIE_MAX_AGE_MS = 2592e6;
+/** .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"
+];
+function base64url(data) {
+	return data.toString("base64url");
+}
+/** 取请求 authority（官方 requestAuthority 同款：Host → URL.host，host:port）。 */
+function requestAuthority(headers) {
+	const host = headers.host;
+	if (typeof host !== "string" || host === "") return void 0;
+	try {
+		return new URL(`http://${host}`).host;
+	} catch {
+		return;
+	}
+}
+/** 官方 cookie 名（authority 绑定，同 requestAuthority 输出）。 */
+function cookieName(authority) {
+	return COOKIE_PREFIX + base64url(createHash("sha256").update(authority).digest());
+}
+/** 定向解析 .credentials.yaml 中 browser-session 段（dshctl auth.py 同款）。 */
+function readSigningSecretFromFile(credentialsYamlPath) {
+	let text;
+	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;
+		if (line.length - line.replace(/^\s*/, "").length <= 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 注入保持纯函数可测）。 */
+function serializeSessionCookie(name, value, expiresAt, nowMs) {
+	const maxAgeSeconds = Math.floor((expiresAt - nowMs) / 1e3);
+	return `${name}=${value}; Max-Age=${String(maxAgeSeconds)}; Path=/; Expires=${new Date(expiresAt).toUTCString()}; HttpOnly; SameSite=Strict`;
+}
+/** 铸造官方同款 cookie（键序/序列化/属性全对齐），返回可直接写 Set-Cookie 的串。 */
+function mintSessionCookie(secret, authority, nowMs) {
+	const expiresAt = nowMs + COOKIE_MAX_AGE_MS;
+	const payload = { 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）。 */
+function credentialsPath(dshHome) {
+	return join(dshHome, ".credentials.yaml");
+}
+/** 完整铸造入口：读密钥 + 铸造；任何失败抛带上下文错误（调用方降级 fail-safe）。 */
+function mintAutoLoginCookie(credentialsYamlPath, authority, nowMs) {
+	return mintSessionCookie(readSigningSecretFromFile(credentialsYamlPath), authority, nowMs);
+}
+//#endregion
 //#region src/ip.ts
 /** 解析 IPv4 十进制点分字面量；非法返回 null。 */
 function parseIpv4(text) {
@@ -176,8 +299,10 @@ function compileAllowlist(entries) {
 * 围栏判定（纯函数，无任何副作用与 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 也不
@@ -210,6 +335,12 @@ function decideGate(req, policy, officialAuthed) {
 			clientIp: clientIpText,
 			invalidEntries
 		};
+		if (policy.autoLoginTrustedIps && !officialAuthed) return {
+			verdict: "autologin",
+			clientIp: clientIpText,
+			reason: "trusted-ip",
+			invalidEntries
+		};
 	}
 	if (officialAuthed) return {
 		verdict: "pass",
@@ -267,7 +398,9 @@ function createGateRoutes(deps) {
 			officialAuthed: deps.officialAuth(req),
 			ipFenceActive: config.allowedIps.length > 0,
 			invalidEntries: decision.invalidEntries ?? [],
-			allowedCount: config.allowedIps.length
+			allowedCount: config.allowedIps.length,
+			autoLoginActive: config.autoLoginTrustedIps,
+			autoLoginReady: deps.autoLoginReady?.() ?? false
 		});
 	};
 	const handleLaunchUrl = (req, res) => {
@@ -440,12 +573,71 @@ function rejectUpgrade(socket, clientIp, log) {
 	].join("\r\n"));
 	log(`blocked upgrade (${clientIp})`);
 }
+/** IP 信任自动登录的引导页：已落官方 cookie，纯客户端跳回干净首页。 */
+function renderAutoLoginPage() {
+	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, res, deps) {
 	if (isExemptPath(new URL(req.url ?? "/", "http://x").pathname) || isTokenExchange(req)) return true;
 	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 !== void 0) {
+			if (isNavigationRequest(toGateRequest(req)) && !res.headersSent) {
+				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;
+			}
+			return true;
+		}
+		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",
@@ -469,12 +661,13 @@ function gatedHttp(handler, deps) {
 		return handler(req, res);
 	};
 }
-/** WS 升级包装体：拒绝时不进协议协商。 */
+/** WS 升级包装体：拒绝时不进协议协商；IP 信任自动登录（cookie 可铸）放行。 */
 function gatedUpgrade(handler, deps) {
 	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);
+		if (decision.verdict === "autologin" && deps.autoLoginCookie !== void 0 && deps.autoLoginCookie(req) !== null) return handler(req, socket, head);
 		rejectUpgrade(socket, decision.clientIp ?? "unknown", deps.onBlock ?? (() => {}));
 	};
 }
@@ -551,6 +744,8 @@ const inject = ["webServer", "connection"];
 /** 围栏服务：持有当前配置读取器（settings 用户层热更新经 setSource 注入）。 */
 var AccessGateService = class extends Service {
 	current;
+	/** 官方 browser-auth 签名密钥（惰性读取缓存；读取失败 = null，autoLogin fail-safe 降级）。 */
+	signingSecret;
 	constructor(ctx, config) {
 		super(ctx, "accessGate");
 		this.current = () => config;
@@ -564,15 +759,30 @@ var AccessGateService = class extends Service {
 		});
 		const logger = ctx.logger("access-gate");
 		const officialAuth = (req) => ctx.connection.requestRejection({ headers: req.headers }) === void 0;
+		const secretOf = () => this.readSigningSecret(logger);
+		const autoLoginCookie = (req) => {
+			const secret = secretOf();
+			const authority = requestAuthority(req.headers);
+			if (secret === null || authority === void 0) 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;
+			}
+		};
 		registerGateRoutes(ctx, {
 			config: () => this.current(),
 			officialAuth,
 			authenticatedUrl: (baseUrl) => ctx.connection.authenticatedUrl(baseUrl),
+			autoLoginReady: () => this.autoLoginSecretReady(logger),
 			onError: (message) => logger.warn(message)
 		});
 		const undo = installGateInterceptor(ctx, ctx.webServer, {
 			config: () => this.current(),
 			officialAuth,
+			autoLoginCookie,
 			onBlock: (message) => logger.info(message)
 		});
 		ctx.effect(() => undo, "access-gate: interceptor");
@@ -581,6 +791,22 @@ var AccessGateService = class extends Service {
 	policy() {
 		return this.current();
 	}
+	/** 官方签名密钥（惰性缓存；失败返回 null 并记录，autoLogin 降级 fail-safe）。 */
+	readSigningSecret(logger) {
+		if (this.signingSecret !== void 0) 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) {
+		return this.readSigningSecret(logger) !== null;
+	}
 };
 function apply(ctx, config) {
 	ctx.plugin(AccessGateService, config);