dsh-remote-access
DSH Web 插件，为本地 DSH 提供局域网访问、Tailscale 私有远程入口和可选 Cloudflare Tunnel 公网入口。Tunnel-only 是匿名公网传输，不提供用户身份认证。
设计
局域网客户端 ── HTTPS:3081 ──► Caddy ──┬─ 所有页面/API/WS ─► API Gateway:3083 ─► DSH:3080
└─ /ca.crt（兼容下载路径）
Tailscale ── Serve/Funnel ──► Caddy:3082 ──┬─ 所有页面/API/WS ─► API Gateway:3083 ─► DSH:3080
└─ 无身份/无凭据请求拒绝
cloudflared ── Tunnel ──► CloudflareIngress:127.0.0.1:3084
└─ Host/Origin (+ optional JWT) ─► API Gateway:3083 ─► DSH:3080
DSH 原始服务只监听 127.0.0.1:3080。远程流量不得绕过 API Gateway；网关统一处理 Host、Origin、WebSocket、API 策略和上游 loopback 规范化。配置、证书和运行状态保存在 DSH 数据目录。
访问模式
| 模式 | 入口 | 认证 | API 策略 |
|---|
| 本机 | 127.0.0.1:3080 | DSH 自身 | 完整权限 |
| LAN trusted-lan | https://<LAN_IP>:3081 | 用户明确选择无认证 | lan |
| LAN protected-lan | https://<LAN_IP>:3081 | Basic Auth | lan |
| Tailscale Serve | Tailscale 域名 | tailnet policy，可选 Basic Auth | serve |
| Tailscale Funnel | 公网 Tailscale 域名 | 强制 Basic Auth | funnel，仅基础 API |
| Cloudflare Tunnel | 外部 cloudflared → 插件 loopback 适配器 | 推荐 Tunnel Basic Auth；也可显式匿名或可选 Access | cloudflare |
LAN、Serve、Funnel 各自使用 API 白名单，默认只开放会话、消息、模型列表、技能列表等基础功能。设置、凭据、主机文件和模型探测等接口默认关闭。API 方法白名单不是工具能力沙箱，获得 session.prompt 的远程主体仍应视为拥有完整 DSH 控制权。LAN 可通过 lanAllowedCidrs 或本机“配置来源网段”操作进一步限制来源网段；配置了该字段后，Caddy 会拒绝不在列表中的来源，包括 /ca.crt。留空表示不增加来源 CIDR 限制，仍由绑定地址、系统防火墙和网络边界负责隔离。
设置页可以按访问模式勾选 API、配置 Basic Auth，并为 LAN / Serve 开启“允许全部 API”或“可信远程设置”；Cloudflare Tunnel Basic Auth 也在“访问控制”中单独开关。两项高权限能力不适用于 Funnel；插件自身的写操作只接受精确的本机 Host + Origin 请求，不再使用注入到页面中的 action token。状态 GET 在没有 Origin 时也只接受精确 loopback Host，以兼容浏览器同源轮询。
设置页为 Caddy 开放的每个监听端口提供独立开关：LAN HTTPS 端口与 Tailscale loopback 端口可单独关闭，Cloudflare 适配器端口也单独控制。关闭端口会从生成的 Caddyfile 中移除对应 site（或停止 Cloudflare loopback 适配器），并由 Caddy --watch 热应用，不需要停止整个反代进程；关闭最后一个 Caddy 端口时插件才会停止 Caddy。端口开关保存在 v2 状态中，重启后仍保持关闭，避免“忘关”。
风险操作（关闭 Basic Auth、切换匿名 Tunnel、开放匿名端口、重置共享凭据、保存高权限 API 策略）会先弹出确认/取消确认框；未配置访问凭据时开启 Basic Auth 会弹出只读提示并引导生成凭据。非风险操作不弹成功提示，失败仍会用窄弹窗提示。刷新按钮位于页面右上角，更新时间显示在刷新按钮左侧。提示/确认弹窗使用更高层级，不会被 API 白名单等二级窗口遮挡。访问控制卡也有凭据状态条，可直接看到共享凭据、Tunnel 凭据和 Funnel 保护是否已配置。页面左上角不再显示操作小字。
每种访问方式下方有状态条：绿点表示运行/可达，红点表示异常或配置冲突，灰点表示未运行/未启用。访问地址旁提供二维码图标；二维码由客户端内置编码器生成 SVG，不会把地址发送到外部服务。编码器按规范写入格式信息、按块交织 RS 纠错码字，并在符号四周绘制 4 模块静区；test/qr-code.test.js 用独立实现的解码器对每个样例断言符号能解回原地址。
新版 DSH 由 client-connection 自己认证浏览器页面：dsh web 打印的地址带有进程级 launch token，兑换后得到 30 天有效的 HttpOnly 会话 Cookie，之后 index 和 /api 都必须携带它。插件不把这个 token 交给远程客户端，而是由本机设置页为每个入口签发一次性登录地址（/remote-access.enroll?ticket=...，5 分钟有效、只能使用一次、并且只能从签发它的入口兑换）：目标设备扫码或打开后，插件在 DSH 进程内用真实 token 完成兑换，并先用该 Cookie 向 DSH 确认一次，然后才把 303 与会话 Cookie 交给浏览器。真正的 token 不会出现在远程 URL、二维码、浏览器历史、状态文件或日志里。
地址行的二维码图标就是登录入口：宿主支持时会签发一次性登录二维码，目标设备扫码后即完成登录，之后在 Cookie 有效期内直接访问普通地址即可；只有老版本 DSH（没有会话门）才回退为普通地址二维码。地址右侧的复制按钮仍然复制普通地址。设置页访问控制卡新增「本浏览器 DSH 会话」状态条，便于确认当前设备是否已登录。
安装
dsh plugin --profile web add @greenonion/dsh-remote-access
手动安装：
git clone <repo-url> dsh-remote-access
cd dsh-remote-access
node install.js
安装后重启 DSH，在“设置 → 远程访问”中操作 Caddy、LAN 策略和 API 策略。Tailscale 登录、Serve/Funnel 和自启动由系统客户端管理，插件只读检测状态并展示命令，不执行 tailscale up/down。设置页会额外显示 Serve 路由是否未配置、已指向插件 loopback 入口、指向其他目标或暂时无法确认；发现外部路由时不会覆盖它。Cloudflare Tunnel 卡片只控制插件自己的 loopback 适配器；Tunnel、DNS、Access Application 和策略仍由 cloudflared/Cloudflare 控制。
LAN TLS 默认使用 lanTlsMode: auto：能找到 OpenSSL 时保持旧版本地 CA 兼容路径；Windows 找不到 openssl.exe 时自动改用 Caddy tls internal，不会再因为 spawnSync openssl ENOENT 阻止启动。也可显式指定 openssl（兼容/严格模式）或 caddy-internal（完全不依赖 OpenSSL）。
Cloudflare Tunnel loopback 适配器
Tunnel 和 Access 是两套独立能力。本项目的公网访问主路径是 Cloudflare Tunnel；适配器默认关闭，启用时需要配置 HTTPS externalOrigins，并让外部 cloudflared 的 ingress 只指向 http://127.0.0.1:3084。推荐在设置页“访问控制”打开 Tunnel Basic Auth；对应配置为 cloudflare-tunnel-basic：
cloudflare:
enabled: true
authMode: cloudflare-tunnel-basic
listenHost: 127.0.0.1
listenPort: 3084
externalOrigins:
- https://dsh.example.com
upstreamTimeoutMs: 120000
upstreamConnectTimeoutMs: 10000
cloudflare-tunnel-basic 会复用“访问控制”中生成的 Basic Auth 凭据，同时保护 HTTP 和事件 WebSocket；密码只在生成响应中显示一次。cloudflare-tunnel 是显式匿名模式：请求以无用户身份 principal 进入插件，API 被网关强制限制为只读集合（agentPreset.list、host.describe、llm.models、session.list 等），事件流、allApis 和可信远程设置均不可用。需要更多接口时必须先开启 Tunnel Basic Auth 或改用 Access。
已有 Basic Auth 只保存 Caddy bcrypt 时，首次打开 Tunnel Basic Auth 需要重新点击一次“生成 / 重置访问凭据”，以创建本地校验值；重置会同时轮换 LAN、Serve、Funnel 和 Tunnel Basic Auth 使用的共享凭据。
首次配置可写入 profile config；已有 v2 状态中保存过 Cloudflare 选项后，状态文件优先，需从本机设置页/setCloudflare action 修改。仅有默认的空 disabled 状态不会覆盖 profile 中的显式 Cloudflare 配置。
设置页显示的 Cloudflare 地址来自 cloudflare.externalOrigins，不是从 cloudflared 自动发现的公网 hostname。请把这里配置成 Cloudflare/cloudflared 实际暴露的 HTTPS origin；本机设置页可以点击“配置公网地址”修改，每行一个 origin。保存后会更新 Host/Origin 白名单；若适配器正在运行会自动重启适配器。远程页面不会显示这些 origin。
插件不启动或停止 cloudflared，也不写入 Tunnel/DNS/Access 配置。Tunnel Basic Auth 模式先验证本地 Basic Auth，再通过 HTTPS externalOrigins、Host/Origin、请求体大小和上游超时边界进入 API Gateway；匿名模式不验证 Access JWT。上游 HTTP 无活动超时可配置为 100–600000 毫秒（默认 120 秒），WebSocket 连接握手超时可配置为 100–120000 毫秒（默认 10 秒），超时会 fail closed。适配器只监听 loopback，外部公网暴露、域名和 Cloudflare policy 由用户自行决定。
如需使用 Access，可将 authMode 改为 cloudflare-access，再配置 HTTPS issuer 与 Access audience；该模式保留用于兼容和纵深防御，但不属于 Tunnel-only 的默认验收范围。
外部 E2E 只读诊断
安装包附带 scripts/edge-diagnostics.mjs。它只执行 HTTPS GET、tailscale status、tailscale serve status 和 tailscale funnel status，不会登录、创建、修改或停止任何 Tunnel/Serve/Funnel。Tunnel-only 探测不需要 JWT；只有选择可选 Access 模式时才通过环境变量传入短期 JWT，结果会去除 query、响应体、Serve target 和凭据：
$env:DSH_REMOTE_URL = 'https://dsh.example.com/api/session.list'
node scripts/edge-diagnostics.mjs --tailscale --json
只检查本机 Tailscale 状态时无需公网 URL：
node scripts/edge-diagnostics.mjs --tailscale --json
诊断结果会区分 edge-login-required、edge-challenge、origin-auth-required、origin-unavailable、origin-ok 等状态。没有测试账号或公网入口时，也可以只运行 --tailscale，不会产生外部副作用。
公网链路较慢时可用 --timeout-ms 10000 调整单次探测超时（范围 100–30000 毫秒）；超出范围会直接拒绝，不会发起请求。
运行环境
- Node.js
>=20
- Caddy
2.8+
- OpenSSL（可选；
lanTlsMode: auto 未找到时使用 Caddy internal CA，显式 openssl 模式才要求它；Windows 可通过 OPENSSL_BIN 指定 openssl.exe 的绝对路径）
- Tailscale（使用 Serve / Funnel 时需要）
核心功能支持 Linux、macOS 和 Windows；证书安装提示使用 mDNS 检测，在 Linux 和 macOS 上启用。默认端口为 LAN 3081、Tailscale 3082、API Gateway 3083、Cloudflare loopback 3084，可在 cordis.patch.yml 中调整。
如果新版 DSH profile 同时启用了 dsh-pocket，它默认也会监听 3081。插件不会停止或覆盖该 listener；启动前会检测到端口冲突并 fail closed，在页面和 action 响应中提示用户为其中一个组件选择空闲端口。测试/迁移时可把 dsh-pocket 改到例如 3091，再让本插件继续使用 3081。
运行时目录默认为 ~/.dsh/dsh-remote-access/，可用 DSH_HOME 更改，主要包含动态生成的 Caddyfile、证书、认证信息和运行日志。POSIX 使用 0700/0600；Windows 会关闭继承并用当前用户 SID + SYSTEM 的显式 DACL 保护目录、配置、认证信息和私钥。Caddy internal CA 的根证书路径由插件独立的 XDG_DATA_HOME 管理，不会读取用户全局 Caddy 数据。
LAN TLS 选择
lanTlsMode 可在 cordis.patch.yml 的插件配置中设置：
auto（默认）：探测 OpenSSL；探测失败时回退 caddy-internal。openssl：只使用旧版本地 CA 生成器；缺少 OpenSSL 时返回可操作的 OPENSSL_BIN 诊断。caddy-internal：由 Caddy 生成本机 CA 和叶证书，不调用 OpenSSL。Caddy 可能在首次启动时将本机根证书安装到当前 Windows 用户的信任存储；如果不希望有这个系统级副作用，请使用 openssl 模式并手动安装 /ca.crt。
安全边界
-
远程请求先经过 Caddy 和 API Gateway，未知 API 默认拒绝；页面、API 和 WebSocket 不再旁路到 DSH，本机 loopback 保留 DSH 完整权限。
-
API Gateway 的 loopback hop 使用每次进程启动生成的未持久化共享密钥；仅伪造 X-DSH-Access-Mode 的本机请求不会被当作受信入口，密钥不会出现在状态、日志或 DSH 上游。
-
网关转发前会移除客户端提供的 Forwarded、X-Forwarded-*、CF-*、Tailscale-*、X-DSH-* 和 Authorization 身份头，并重写上游 Host/Origin。
-
网关按入口模式判权：投递到 /api/<method> 的 POST、GET、HEAD 都按该入口的 API 白名单判定（DSH 插件的文件流、deliverables、会话日志导出走 GET/HEAD），事件流仍由 events 开关单独控制；未在白名单中的方法返回 403，并说明是哪个入口缺少哪个方法。插件注册的嵌套路由（例如 /api/session/uploadFileBinary 附件上传）没有可列入白名单的方法名，只有显式打开「允许全部 API」的入口才会放行。
-
显式开启「允许全部 API」的入口按可信入口处理：除白名单方法外，还放行插件自带的路由（例如 dsh-better-sidebar 的 /sidebar/api、/sidebar/upload、/sidebar/file）及其 WebSocket（/sidebar/ws/*）。这些路由自带 Host/Origin 与凭据围栏，网关转发时仍会把 Host/Origin 重写为 loopback，因此围栏看到的是本机请求；未开启 ALL 的入口只放行 GET/HEAD 文档请求、白名单方法和已知实时流路径。
-
实时状态流走 WebSocket：新版 DSH 用单条 /api/remote.mux 承载全部远程流（旧版为 /api/events.*），网关按该入口的 events 开关放行，显式开启「允许全部 API」的入口也放行插件自定义的 /api/* 流；Cloudflare 适配器同样转发这些路径。
-
网关在内存保留最近 20 条拒绝记录（状态码、方法、路径、入口、原因），只在本机设置页访问控制卡展示最新 3 条，远程状态视图不下发；用于区分页面能打开但接口 403，是入口不匹配还是白名单缺少方法。
-
Cloudflare 适配器在网关之前完成 Tunnel Host/Origin 边界；Tunnel Basic Auth 请求先验证插件凭据，匿名 Tunnel 请求使用无用户身份的 transport principal，Access 模式额外验证 JWT。三种模式都只把受控 mode/subject 摘要放在适配器到网关的 loopback hop，JWT、CF-* 和客户端身份头不会到达 DSH。
-
LAN trusted-lan 可以不启用 Basic Auth，但同网段设备拥有完整控制权；公网入口默认应使用强认证。若显式选择 Cloudflare Tunnel-only，则它是匿名公网传输，必须依赖 API allowlist 和外部网络策略，不能视为身份认证。
-
Tailscale 生命周期由用户和系统客户端管理；插件不关闭用户已有的 Tailscale 连接或修改全局 Serve 配置。
-
Caddy 使用插件独立的配置和 PID；关闭时只停止插件创建或确认属于插件的 Caddy 资源。
-
Caddy 以 --watch 运行，只监视插件私有目录中经过校验、原子替换的 Caddyfile；不开放 Caddy admin API。端口开关通过重写 Caddyfile 由 Caddy 热应用。
-
Caddy 仍只保存 bcrypt hash；Tunnel Basic Auth 另保存不可逆的 scrypt 派生校验值，不保存明文密码。/ca.crt 用于设备安装本地 CA，保持免认证访问。
-
DSH 浏览器会话凭据（进程级 launch token 与权威绑定的会话 Cookie）只在本机流转：本地设置页签发的一次性 ticket 只存在于插件进程内存，单次使用、5 分钟过期、绑定入口模式，且从不写入状态文件或日志；远程客户端最终只拿到 DSH 自己下发的会话 Cookie。
开发状态
已完成第一批安全基础：
-
删除页面 action token。
-
新版 DSH 浏览器会话改为一次性 ticket 兑换：launch token 不进入远程 URL、二维码或日志。
-
管理接口增加精确 loopback Host/Origin 校验。
-
API POST 和 WebSocket 增加跨站 Origin 拒绝。
-
入口身份头不会转发到 DSH。
-
v2 网关为 LAN、Tailscale、Funnel 和 Cloudflare 入口生成统一的进程内 Principal；身份上下文不进入 DSH 上游、状态文件或日志。
-
LAN ingress adapter 只允许私有/链路本地地址，拒绝公网或通配绑定；显式 CIDR 限制由 Caddy 在入口处执行。
-
页面/API/WS 统一经过 API Gateway。
-
LAN 配置迁移为 trusted-lan / protected-lan。
-
Cloudflare Tunnel loopback 适配器已接入：固定 loopback 监听、Tunnel Basic Auth/显式匿名 Tunnel/可选 Access JWT 模式、Origin allowlist、HTTP/WS 代理、请求体限制和远程状态脱敏；Tunnel/DNS/Access 生命周期仍由外部 cloudflared 管理。
-
Cloudflare 适配器的上游 HTTP/WS 超时已经进入 profile/state/status 模型，设置页会显示当前值；非法值会回退到安全默认值，运行中的适配器配置变更会先停止旧 listener 再应用。
-
匿名 Cloudflare Tunnel 的 API 被网关强制为只读集合；事件流、allApis 和可信远程设置必须启用 Tunnel Basic Auth 或 Access 后才可用。设置页风险操作统一改为确认弹窗。
-
兼容新版 DSH client-modules：客户端 bundle 使用 npm 包名 @greenonion/dsh-remote-access 作为 ModuleLoader 注册 ID。
v2 已开始落地：state-store.js 负责 schema v2 入口状态、0.1.x 平面状态迁移、迁移前备份以及临时文件 + fsync + 原子替换；运行时已接入该状态层，识别到旧状态后会自动备份并转换，非法 JSON 不会被覆盖。当前切片不改变现有监听器拓扑，Tailscale/Cloudflare 状态只保留配置且不会被旧运行时自动启用。
正在开发：真实 tailnet/Cloudflare 外部入口和 cloudflared 故障恢复验证。Windows ACL、Caddy internal 无 OpenSSL LAN 路径、Tailscale 只读入口适配器、Cloudflare loopback 适配器已接入运行时状态和设置页；本地 Tunnel-only HTTP/WSS 与 RSA JWT → Cloudflare verifier → adapter → API Gateway 链路已覆盖。当前测试套件在受支持环境中全部通过。
License
MIT
