Skip to content

feat: dsh web admin relay (security.adminRelay) — remote browsers open the bili panel (#3373) - #3486

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-17_panel-admin-relay
Oct 17, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-17_panel-admin-relay

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #3373.

What this fixes

Headless host runs dsh web; a browser on another machine reaches it through a reverse proxy, opens Settings → bili, and the panel iframe points at http://127.0.0.1:18787 — connection failed (#3373). With this PR the host itself relays the /__bili/ admin surface through its own entry origin, so the whole panel round-trips same-origin with the entry the browser already reached. No 0.0.0.0 bind, no socat, no extra port.

How

Config surface (per AGENTS §3)

Security note (also in the docs)

/__bili/ is the full admin surface — config editing and credential writes, not a read-only dashboard. Enabling the relay means whoever can reach the host web entry can reach all of that. The docs call this out: protect the entry (auth / reverse proxy) first.

Tests

  • tests/dsh-admin-relay.test.ts (new): fail-closed 404 with a bound proxy; 503 unbound; full GET+POST forwarding against a real local stub — method/url/body byte-exact, browser Origin/Cookie/Referer verified absent at the proxy, fetch-derived loopback Host, header/status/body passthrough, streaming; 502 unreachable.
  • tests/dsh-settings-ui.test.ts: relay-mode probe binds same-origin; prefix-gateway fallback resolves through the base-relative form (https://dsh.example/app/dsh/…); existing tests updated for the second route + hermetic BILI_CONFIG_FILE.
  • Source-text assertions updated for API_ROOT (web-storage-banner, issue2861).
  • Local: typecheck clean, build clean, targeted suites green (dsh-settings-ui 14, dsh-admin-relay 4, web set 112, config guards 32). Full-suite verdict: CI test lanes on this head.

No kernel/ or pi-subagents/ changes. No version bump.

…n the bili panel through the host entry (#3373)

Headless hosts run 'dsh web' behind a reverse proxy; the settings panel
iframe pointed at http://127.0.0.1:18787 and failed for every remote
browser. The host now relays the /__bili/ admin surface through its own
entry origin, gated by a fail-closed security.adminRelay (file-only):

- dsh plugin registers a /__bili prefix route forwarding to the loopback
  proxy; the relayed hop is a local non-browser client (loopback source +
  Host, no Origin/Cookie/Referer forwarded) so the #1538 admin gate and
  its DNS-rebinding protection are untouched. Off by default: route
  answers 404, unbound proxy 503, unreachable proxy 502.
- /bili/origin (and the index-inject snapshot) reports {relay:true} when
  enabled, so the panel UI builds same-origin URLs; the panel API root
  derives itself from the page path, fixing prefix gateways (/app/dsh/…)
  as a side effect; the origin probe caches the winning form (base-relative
  fallback first described in #3373-C1).
- Docs: security section in CONFIGURATION.md + zh; config-reference seed.
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-17_panel-admin-relay (e9f7b24)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.4129-pr.3486.b64348c

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr3486.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重:不重复。 这是 #3373(+已并入的 #3424)的唯一实现 PR,无并行同类工作。相邻项均不同向:#3343/#3350 是管理面收紧族(伪造回环身份拦截),本 PR 是显式 opt-in 放宽(宿主自身中继,闸门零改动);#1538 是被复用的既有闸门行为,不是重复项。

开始独立审查。已拉取分支 2026-10-17_panel-admin-relay(单 commit e490dbe,13 文件 +639/-62)。审查顺序:① 原 issue 方向核对 → ② 触碰路径的既有行为清单与回归判定 → ③ 代码与安全面精读(重点:中继头剥离是否让管理面闸门零改动成立、路径/方法/大小边界、fail-closed 默认逐字不变)→ ④ 测试有效性 → ⑤ diff 整洁度。定向本地验证(dsh-admin-relay / dsh-settings-ui / web 套件 / typecheck)随后跑,全量回归以 CI 为准。完整八问结论稍后在本线程给出。

…ordering, effect disposer

- contain the relay to the declared /__bili surface: reject decoded ".." segments (literal and %2e-encoded; fetch() normalizes both) with 400 before any upstream hop; an unchecked "/__bili/.." would otherwise land on sibling paths of the loopback proxy (#3486 review F1)
- present 404 admin-relay-disabled before the 503 not-running state when the gate is off (fail-closed beats state disclosure; #3486 review F3)
- restore the combined route disposer as the inject-effect cleanup so dsh disposes both panel routes on each re-run, matching master's effect contract; re-tighten the dsh-settings-ui assertion that had softened to dead code (#3486 review F2)
- type the method/url extraction through locals so the typeof guard actually narrows (new strict usages exposed string|undefined)
- regression tests: traversal rejected with zero upstream hops, gate-off+unbound 404 ordering, 413 oversized body with no upstream hop
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

独立审核完成(查重结论见上一条)。审核中发现 3 个问题,已按「小问题直接修」在本分支修掉并推送:commit e9f7b24ba(已确认 PR head 更新,CI 正在该 head 上跑)。

① 是什么问题:headless dsh web 部署下,面板 iframe 指向 http://127.0.0.1:18787,远程浏览器打不开(#3373);根因是 /bili/origin 恒报 loopback + admin gate 只认 loopback 源地址。本 PR 按你在 #3373 拍板的方向实现 host-side relay:dsh 入口注册 /__bili 前缀路由转发到本地代理,浏览器只走同源。方向正确——同时消掉了 socat/nginx 伪造头的绕行方案,并顺带解决 #3424 的前缀网关问题(C1–C5)。

② 什么原因导致的:功能类 issue,非缺陷修复。

③ 影响范围与严重程度:仅影响显式开启 security.adminRelay: true 的用户(默认 false、file-only、无 env)。关闭时既有行为字节级不变(逐行核对过)。开启后 bili 完整 admin surface(配置编辑、凭据写入)对能到达 dsh web 入口的任何人可达——这是功能固有代价,CONFIGURATION en/zh 与 website 文档均已写明。

④ 怎么修复的:13 个文件全量逐行审完。关键核验:

  • admin gate(src/server/admin.ts)零改动:relay hop 到达时是「本地非浏览器客户端」形态(loopback 源地址 + fetch 派生的 loopback Host + Origin/Cookie/Referer 已剥离),原样通过 fix: accept SSH-forwarded local port in admin origin gate (#1536) #1538 gate ✓;attach 模式(register.base 非 loopback)会被远端代理自己的 gate 拒绝,fail-closed ✓
  • 请求头剥离清单充分(connection 族/hop-by-hop/浏览器身份头齐全);CSRF 面:JSON 请求触发 preflight(无 ACAO),无超出 opt-in 范围的升级
  • 发现并已修(F1,安全):fetch() 会规范化 dot segment——node 实测字面 .. 与 %2e%2e 都被规范化,/__bili/../__acp/sessions 会落到 loopback 代理的 /__acp/* 兄弟路径,超出声明的 relay surface。现在转发前拒绝解码后含 .. 段的路径(400,零上游 hop);query/hash 不参与解码,a..b 这类 session id 不受影响
  • 发现并已修(F3,状态泄露):gate 关 + 代理未启动时原顺序先回 503,泄露「有代理」状态;改为 404 fail-closed 优先
  • 发现并已修(F2,effect 生命周期回归):inject-effect 函数体从返回 disposer 变成返回 undefined,dsh 重跑 effect 时旧路由不再被 dispose、累积残留;恢复两路由合并 disposer,并把 dsh-settings-ui.test.ts 里被软化成死代码的断言恢复为硬断言(disposer 类型 + disposed 计数)
  • 非阻塞小注(未改):AbortSignal.timeout(120s) 是整个交换的超时,超长流式响应(如超大 raw log 下载)可能被截断;Authorization 不在剥离清单(无害——bili 忽略它)

⑤ 是否有回归问题:审过的既有行为及结论——off 态 /bili/origin 与 index-inject snapshot 字节级一致(保持);admin gate(零改动,保持);probe/embed-preflight 消费者对空 base 的字符串拼接兼容(保持);effect 清理契约(F2 已恢复);行为变更披露:默认 off 时 dsh web 对 /__bili* 的未知路径响应体从 dsh 自己的处理变为 bili JSON {"error":"admin relay disabled"}(两者都是 404,dsh 在 /__bili 下无已知内容,低危但如实列出)。无其他无意回归。

⑥ 是否破坏缓存:不涉及——不触碰压缩缓存/重试/游标/去重键。

⑦ 是否改了设计方向:不涉及——完全按 owner 在 #3373 拍板的 relay 架构执行,无新增架构决策。

⑧ 是否引入新配置:是——顶层 security.adminRelay(bool,默认 false,file-only),即你在 #3373 指定的安全相关顶层字段,是该 block 第一个 knob;CONFIGURATION en/zh + website config-reference 已同步。

测试有效性:新增测试有牙——fail-closed 404(带已绑定代理)、503 未绑定、GET+POST 字节精确转发、浏览器头剥离实证(上游 stub 看不到 Origin/Cookie/Referer)、流式透传、502;我补的 3 条:traversal 400 且零上游 hop、gate-off+unbound 的 404 优先级、413 超大 body 零上游 hop。本地定向验证:dsh-admin-relay + dsh-settings-ui + web-storage-banner + issue2861 + config-surface-guard 共 49/49 通过,tests/web-* 全集 100/100 通过,typecheck/build 干净。全量判定以推送 head 上的 CI 为准。

结论:可合入——等 CI 绿即可。分支落后 master 若干提交但 GitHub 判 mergeable,可直接合(需要的话 rebase 一下也行)。合并留给你:#3486

@ranxianglei
ranxianglei merged commit fabb7f6 into master Oct 17, 2026
43 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.522-master.fabb7f6 (rolling master tag).

npm install -g billion-context@0.0.522-master.fabb7f6  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant