dsh-webui-oauth 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 本文件记录每个版本的**用户可见**变更。破坏性变更与升级动作单独标注。
 
+## 0.6.8
+
+修复 0.6.7 引入的回归：**登录成功后 `/api` 恒 401**。
+
+### 修复：/api 的 loopback 伪装在包装时被固化
+
+- **现象**：升级到 0.6.7 后可以正常登录、页面也能打开，但所有 `/api` 请求一律 401；
+  回退到 0.6.6 立即恢复。
+- **原因**：0.6.7 为了让新装的插件"注册即上闸门"，接管了 webServer 三张路由表的
+  `set`。这改变了包装时机——`/api` 可能在 `client-connection` 服务对本插件上下文
+  **尚不可见**时就被包装。旧代码在**包装那一刻**判定一次 `coreHasRequestGate`，
+  于是把"这是旧核心"永久固化下来，之后每个 `/api` 请求都走 loopback 伪装：
+  `Host` 被改写成 `127.0.0.1`、`Origin` 被删除。
+  而 alpha.2+ 核心的浏览器 Cookie **按 Host authority 绑定**，改写后查不到对应
+  Cookie，核心随即 401。登录与页面走的是 `/`，不经过这段伪装，所以"能登录、只有
+  `/api` 坏"。
+- **修复**：把判定改为**每次请求现查** `ctx.get('connection').requestRejection`，
+  不再在包装时定死。路由注册的先后顺序、服务就绪的时序都不再影响结果。
+  旧核心（始终没有 `requestRejection`）仍保留 loopback 伪装，行为不变。
+
+### 测试
+
+- `test/gate-default-deny.test.mjs` 新增 6 项：
+  - 安装时 `connection` 不可见、之后才就绪 → `/api` 的 `Host`/`Origin` 必须保持原样；
+  - 旧核心（始终无 `requestRejection`）→ 仍然改写 Host / 删除 Origin，确保修复没误伤。
+- 全量 17 个测试文件、444 项断言通过。
+
+## 0.6.7
+
+安全修复：路由闸门由**黑名单**改为**默认拒绝的白名单**。此前只包 `/api` 与
+`/plugins`，第三方插件注册的读接口完全裸奔。
+
+### 修复：未登录可读任意第三方插件的路由
+
+- **现象（实测）**：未登录、不带任何 Cookie，以下端点直接 200：
+  - `/dsh-550c-boot/update` —— 版本 / 镜像指纹
+  - `/dsh-any-background/font` —— 用户上传字体（12,079,480 B）
+  - `/dsh-any-background/wallpaper` —— 用户壁纸
+  与此同时写端点（`/font/upload` 等）因为走 connection RPC 通道反而 401。
+  即典型的「**写保护、读裸奔**」。
+- **原因**：webServer 的匹配顺序是「exact 优先，其次最长前缀」。闸门原来只包装
+  `/api` 与 `/plugins` 两条前缀，第三方插件注册的 `/dsh-any-background`、
+  `/dsh-550c-boot/update` 等比本插件的 `""` 前缀更具体，会抢在闸门之前命中，
+  于是完全绕过鉴权。黑名单永远追不上「下一个装上的插件」。
+- **修复**：改为**默认拒绝**。安装闸门时枚举并包装 webServer 上的**全部**路由：
+  - 所有 `exact` 路由 → 401（白名单/自管端点除外）
+  - 所有 `prefix` 路由 → 401（仅本插件自己的 `""` 传输闸门除外，它负责 302 到登录页）
+  - **所有** WebSocket upgrade → 一律拒绝（不再只认 `/api/remote.mux`）
+  - `fallback` 处理器 → 同样要求会话
+  - 并且接管 `exact/prefixes/upgrades` 三张路由表的 `set`，**注册那一刻就上闸门**，
+    消除「新装插件到下一次重扫（最长 10s）之间」的裸奔窗口。
+
+### 公开白名单（能匿名访问的全部路径）
+
+`/dsh-webui-oauth/login`、`/setup`、`/oidc/login`、`/oidc/callback`、
+`/oauth/callback`（账号平台 OAuth 回跳，自带 state 常量时间比对）。
+
+其余 `/dsh-webui-oauth/*` 端点（status / audit / configure / disable / logout /
+oidc/bind / oidc/unbind / oidc/logout）保持「各 handler 自己 checkRequest」，
+不套通用闸门，避免改变其 JSON 错误语义。
+
+### 新增：部署方可追加公开路径
+
+机器调用的端点（例如签名校验的 GitHub webhook）需要匿名可达。在 dsh settings 里声明：
+
+```yaml
+remote-web-ui:
+  publicPaths:
+    - /api/webhooks/github      # 精确路径
+    - /api/webhooks/*           # 前缀（结尾 /*）
+```
+
+未声明的路径一律拒绝。配置热更新后下一次扫描（≤10s）生效，无需重启。
+
+### 可观测性
+
+`/dsh-webui-oauth/status` 的 `gate` 现在回显实际保护范围，便于运维核对，
+而不是只看到一句「闸门已开」：
+
+```json
+{
+  "gate": {
+    "ok": true,
+    "mode": "deny-by-default",
+    "stats": {
+      "wrappedExact": 8, "wrappedPrefix": 8,
+      "wrappedUpgrade": 1, "wrappedFallback": 1,
+      "publicPaths": ["/dsh-webui-oauth/login", "..."],
+      "exemptSelfGated": ["/dsh-webui-oauth/status", "..."]
+    }
+  }
+}
+```
+
+### 升级注意
+
+- 升级后**第三方插件的所有路由默认需要登录**。如果某个端点确实要匿名可达
+  （webhook、回调），请按上面的 `publicPaths` 显式声明，否则会 401。
+- 登录页、OIDC 往返、应用根的行为不变；实测登录 → 进应用 → 各插件功能均正常。
+
+### 测试
+
+- 新增 `test/gate-default-deny.test.mjs`（53 项）：锁定默认拒绝、白名单例外、
+  晚注册路由无窗口期、upgrade 与 fallback 覆盖、`undo` 完全可逆。
+- 真实实例端到端验证（dsh + `dsh-550c-boot` + `dsh-any-background` + 本插件）：
+  匿名访问上述三个端点由 200 变为 **401**，登录后仍 200/404（正常业务语义）。
+- 全量 17 个测试文件、434 项断言通过。
+
 ## 0.6.6
 
 对 **OIDC 授权跳转**做一次全量验证（固定路径 / 反代 / 浏览器动态三路），

package/README.en.md

@@ -84,9 +84,15 @@ Authentication is enforced in four layers, all implemented by **wrapping the web
 | WebUI resources (index.html, /assets/*, SPA routes) | Plugin registers a `prefix ''` catch-all route; after session validation it hands off to frontend-static | 302 → login page |
 | Plugin bundles (/plugins/*) | Wraps the `/plugins` prefix route handler at runtime | 401 |
 | /api RPC surface | Wraps the `/api` prefix route handler at runtime | 401 |
-| WebSocket (`/api/remote.mux`; legacy cores `/api/events.mux`, `/api/events.host`) | Wraps the upgrade route handlers at runtime | 401 upgrade rejected |
+| **Any third-party plugin route** (exact / prefix) | Deny by default: every registered route is enumerated and wrapped, and each route table's `set` is intercepted so new routes are gated at registration time | 401 |
+| WebSocket (**all** upgrade routes) | Every upgrade handler is wrapped at runtime | 401 upgrade rejected |
+| fallback (requests claimed by no named route) | The fallback handler is wrapped too | 401 |
 
-- **No core patching**: a DSH upgrade never overwrites patches and never leaves `/api` exposed after an upgrade. Every startup re-wraps the route tables, with a 2s→10s rescan loop that catches late-registered routes. **On v0.1.2-alpha.2+ the event-stream WebSocket lives at `/api/remote.mux` (registered by dsh-api-gateway); the candidate list adapts automatically, so the plugin no longer falsely reports "upgrade route missing".**
+> **Since 0.6.7 the gate is a deny-by-default allowlist.** Previously only `/api` and `/plugins` were wrapped, but the webServer matches "exact first, then longest prefix" — a third-party route such as `/dsh-any-background/font` or `/dsh-550c-boot/update` is more specific than this plugin's `""` prefix and therefore won the match, bypassing the gate entirely (measured: anonymous requests read user fonts, wallpapers and image fingerprints with 200, while write endpoints returned 401 because they go through the RPC channel — "write-protected, read-naked"). A denylist can never keep up with the next plugin you install; a default-deny allowlist cannot miss.
+>
+> **The complete anonymous allowlist**: `/dsh-webui-oauth/login`, `/setup`, `/oidc/login`, `/oidc/callback`, `/oauth/callback`. Operators can extend it via `remote-web-ui.publicPaths` (see below).
+
+- **No core patching**: a DSH upgrade never overwrites patches and never leaves `/api` exposed after an upgrade. Every startup re-wraps the route tables, with a 2s→10s rescan loop that catches late-registered routes; the `set` methods of `exact/prefixes/upgrades` are also intercepted, so **a newly registered route is gated the moment it is registered** — there is no longer a window between "plugin installed" and "next rescan". **On v0.1.2-alpha.2+ the event-stream WebSocket lives at `/api/remote.mux` (registered by dsh-api-gateway); the candidate list adapts automatically, so the plugin no longer falsely reports "upgrade route missing".**
 - **Fail-closed**: if the expected routes are missing (DSH internals changed so wrapping can't apply), `setup`/`configure` **refuse to enable authentication** and the problem is reported both in the host log and on the settings page — better unusable than "login enabled with an unprotected /api".
 - **Cooperation with the core's own browser auth (v0.1.2-alpha.2+)**: that core version ships launch-token exchange with an origin-bound signed cookie (`dsh-auth-*`) guarding `/` and `/api`. After a successful plugin login the browser is automatically sent to the core's token-bearing root URL so the core cookie exchange runs too; `/api` requests pass through **unchanged** after the plugin session check (no more Host/Origin rewrite, which would break the core's cookie/Host binding). Both gates apply: a browser must hold the plugin session cookie **and** the core cookie.
 - **Privileged methods behind a reverse proxy / LAN (legacy cores ≤ alpha.1)**: after the session check the plugin hands authenticated requests to the core in a "loopback shape", so the core's **loopback-pinned privileged methods** (settings/credentials/agentPreset/llm.discoverModels) work in proxied deployments — the session-cookie gate is a strictly stronger identity proof than the Host-header heuristic it replaces.
@@ -100,6 +106,14 @@ Authentication is enforced in four layers, all implemented by **wrapping the web
   ```
   - `trustBrowserOrigin` defaults to `true` when omitted (legacy behavior); an explicit `false` makes both sites **ignore** the browser-influenced origin and use `publicBaseUrl`. With no `publicBaseUrl` either, the token redirect falls back to the request Host / loopback, and OIDC fails closed with an error.
   - The old `oidc.trustBrowserOrigin` is still accepted: when the settings section does not set the switch explicitly, it is used as the fallback, so existing deployments migrate smoothly.
+  - **Extra public paths (0.6.7, the companion switch for deny-by-default)**: endpoints called by machines that cannot carry a browser session (GitHub webhooks, third-party OAuth callbacks) must be declared explicitly, otherwise the gate answers 401. Same settings section:
+    ```yaml
+    remote-web-ui:
+      publicPaths:
+        - /api/webhooks/github     # exact match
+        - /api/webhooks/*          # prefix match (only a trailing /*)
+    ```
+    Only absolute paths starting with `/` and free of whitespace/control characters are accepted; anything undeclared is denied. Changes take effect on the next scan (≤10s) without a restart. **The built-in allowlist contains only the five paths required for login / the OIDC round trip** — do not add business endpoints unless they verify a signature or state themselves.
   - **Host-rewriting reverse proxies**: when the proxy rewrites `Host` to a loopback address (`127.0.0.1:3080`, `::1`, `localhost`, `0.0.0.0`) and sends nothing else, the plugin **cannot** recover the browser-side address from the request, so it treats the address as proxy-rewritten and uses the configured `publicBaseUrl` directly (the legacy "declare the public address in settings.yaml" advice was ineffective in that shape, because `publicBaseUrl` was only trusted on an exact Host match). If the proxy can send the original host, `X-Forwarded-Host` (or RFC 7239 `Forwarded: host=`) is preferred over the request Host for building the redirect.
 - **Optional OIDC SSO (0.4.0; identity binding required since 0.6.0)**: standards-based authorization-code + PKCE with a **confidential client (client_secret required)**, security-benchmarked against Logto. **Configuring OIDC does not mean anyone can log in**: you must first bind one IdP identity. Until then OIDC login is refused outright and the login page hides the SSO button (see the next bullet). Once bound, the login page shows an "SSO single sign-on" button; after IdP authentication the plugin creates a local session keyed by the IdP `sub` (reusing the session TTL and persistence).
 - **OIDC identity binding / unbinding (0.6.0)**: binding = log in with the local account, then click "绑定 OIDC 身份" under **Settings → Authentication → OIDC identity binding** and complete one IdP authorization; the verified `sub` is stored in the credentials file (`boundSub`), and **only that identity** can then log in via SSO. Unbinding = click "解除绑定" (current password required); once cleared, SSO login immediately reverts to "refuse everything". The settings page only ever shows a masked sub (e.g. `su*****ce`). A credentials file without `boundSub` counts as unbound, so upgrading never opens access. The **redirect_uri base is set by `oidc.redirectBase`**; by default the browser is trusted (it trusts the front-end `location.origin` — under a host-rewriting reverse proxy the browser's public address is correct), ****constrained by the unifed switch above****; when disabled only the configured `redirectBase` is used; if neither is available it fails closed with an error. id_token signatures support **RSA (RS256/384/512, PS256/384/512), EC (ES256/384/512) and EdDSA (Ed25519)**, with iss/aud/exp/iat/nbf/nonce and JWKS(kid) validation (see "Signature algorithm support" below). Logout is the simple variant: it clears the local session only.

package/README.md

@@ -84,9 +84,15 @@ DSH WebUI 身份认证插件（持久化插件）。在「设置 → 身份认
 | WebUI 资源（index.html、/assets/*、SPA 路由） | 插件注册 `prefix ''` 兜底路由，校验会话后转交 frontend-static | 302 → 登录页 |
 | 插件 bundle（/plugins/*） | 运行时包装 `/plugins` 前缀路由 handler | 401 |
 | /api RPC 接口 | 运行时包装 `/api` 前缀路由 handler | 401 |
-| WebSocket（`/api/remote.mux`；旧核心 `/api/events.mux`、`/api/events.host`） | 运行时包装 upgrade 路由 handler | 401 拒绝升级 |
+| **第三方插件的任意路由**（exact / prefix） | 默认拒绝：安装时枚举并包装**全部**路由，且接管路由表 `set` 在注册瞬间上闸门 | 401 |
+| WebSocket（**所有** upgrade 路由） | 运行时包装每个 upgrade handler | 401 拒绝升级 |
+| fallback（未被具名路由认领的请求） | 运行时包装 fallback handler | 401 |
 
-- **不修改核心包**：dsh 升级不会覆盖补丁、不会产生「升级后 /api 裸奔」的窗口。插件每次启动对路由表重做包装，并用 2s→10s 重扫捕获晚注册路由。**v0.1.2-alpha.2 及更新核心的事件流 WebSocket 位于 `/api/remote.mux`（由 dsh-api-gateway 注册），候选列表自动适配，不再误报「upgrade 路由缺失」。**
+> **0.6.7 起为「默认拒绝」白名单模型。** 此前只包 `/api` 与 `/plugins`，而 webServer 按「exact 优先、其次最长前缀」匹配——第三方插件注册的 `/dsh-any-background/font`、`/dsh-550c-boot/update` 等更具体的路由会抢在本插件的 `""` 前缀之前命中，完全绕过鉴权（实测未登录即 200 读出用户字体、壁纸与镜像指纹，而写端点因走 RPC 通道反而 401）。黑名单追不上新装的插件，白名单不会漏。
+>
+> **能匿名访问的完整清单**：`/dsh-webui-oauth/login`、`/setup`、`/oidc/login`、`/oidc/callback`、`/oauth/callback`。部署方可用 `remote-web-ui.publicPaths` 追加（见下）。
+
+- **不修改核心包**：dsh 升级不会覆盖补丁、不会产生「升级后 /api 裸奔」的窗口。插件每次启动对路由表重做包装，并用 2s→10s 重扫捕获晚注册路由；同时对 `exact/prefixes/upgrades` 三张表接管 `set`，**新路由注册的那一刻就上闸门**，不再有「装好插件到下一次重扫之间」的裸奔窗口。**v0.1.2-alpha.2 及更新核心的事件流 WebSocket 位于 `/api/remote.mux`（由 dsh-api-gateway 注册），候选列表自动适配，不再误报「upgrade 路由缺失」。**
 - **fail-closed**：若预期路由缺失（dsh 内部结构变化导致包装不上），`setup`/`configure` 会**拒绝启用认证**，并在宿主日志与设置页同时报错——宁可不可用，不可「开了登录却裸奔 /api」。
 - **与核心自带浏览器认证（v0.1.2-alpha.2+）协作**：该版本核心自带 launch-token 交换的签名 Cookie（`dsh-auth-*`）认证 `/` 与 `/api`。插件登录成功后自动把浏览器引导到核心的带 token 根 URL 完成核心 Cookie 交换；`/api` 请求在插件会话校验后**原样转交**给核心（不再改写 Host/Origin，避免破坏核心 Cookie 与 Host 绑定）。两者叠加：浏览器须同时持有插件会话 Cookie 与核心 Cookie。
 - **反代/局域网旧核心下的特权方法**（≤alpha.1）：已认证请求由插件在会话校验后以「回环形状」转交核心，使核心中**回环钉死的特权方法**（settings/credentials/agentPreset/llm.discoverModels）在反代部署下可用——会话 Cookie 闸门是比 Host 启发式更强的身份证明。
@@ -111,6 +117,16 @@ DSH WebUI 身份认证插件（持久化插件）。在「设置 → 身份认
 
   第 2 行是**动态跳转不可用时的兜底**，不是第二个开关：Host 被改写成回环时，服务端从请求里**拿不到**任何浏览器侧地址，开关即使开着也没有可用值，只能回退 `publicBaseUrl`（该值来自 `settings.yaml`，运维可控、非攻击者可控，不构成开放重定向）。
 
+- **追加公开路径（0.6.7，默认拒绝的配套开关）**：机器调用、无法携带浏览器会话的端点（GitHub webhook、第三方 OAuth 回跳等）必须显式声明，否则会被闸门 401。同一 settings 段：
+  ```yaml
+  remote-web-ui:
+    publicPaths:
+      - /api/webhooks/github     # 精确匹配
+      - /api/webhooks/*          # 前缀匹配（只认结尾的 /*）
+  ```
+  仅接受以 `/` 开头、不含空白与控制字符的绝对路径；未声明的路径一律拒绝。配置热更新后下一次扫描（≤10s）生效，无需重启。**内置白名单只有登录/OIDC 往返所必需的五条**，业务端点不应加进去，除非它自身已做签名/state 校验。
+
+
   **端口规则**：端口**只来自被选中那一方的字面**，不做任何补全。
   - 动态路径：端口取自 Host / 原始主机头。不带端口就不带（浏览器按 scheme 推 443）。
   - 绝对路径：端口取自 `publicBaseUrl`。**CDN 仅在 443 对外时应写不带端口**（`https://dsh.example.com`）；写成 `:8443` 会让浏览器去撞 8443。

package/index.js

@@ -127,11 +127,25 @@
  * and the scrypt credential format originate from Yuuz12/dsh-webui-auth
  * (MIT). This fork keeps the on-disk formats compatible where possible.
  *
- * Routes protected (all via runtime wrapping of the webServer service):
- *   - prefix ""    : SPA resources (302 to login page)
- *   - prefix "/plugins": client plugin bundles (302 to login page)
- *   - prefix "/api"     : RPC surface (401)
- *   - upgrades /api/remote.mux (+ legacy /api/events.mux, /api/events.host): (reject upgrade)
+ * Route gating (0.6.7+) — DENY BY DEFAULT, allowlist by exception:
+ *   Every route registered on the webServer is wrapped at registration time:
+ *     - all exact routes        -> 401 unless public / self-gated (below)
+ *     - all prefix routes       -> 401 unless the root "" prefix (ours) or public
+ *     - all upgrade (WebSocket) -> upgrade rejected with 401
+ *     - the fallback handler    -> 401 unless authenticated
+ *   Public allowlist (the minimum needed to log in):
+ *     /dsh-webui-oauth/login, /setup, /oidc/login, /oidc/callback, /oauth/callback
+ *   Self-gated (each handler calls checkRequest itself): the remaining
+ *     /dsh-webui-oauth/* endpoints.
+ *   Additional operator-declared public paths: settings remote-web-ui.publicPaths
+ *     (e.g. a signature-verified webhook ingress).
+ *
+ *   Why this replaced the old denylist: any third-party plugin could register a
+ *   more specific prefix/exact route (e.g. /dsh-any-background/font,
+ *   /dsh-550c-boot/update) that won the longest-prefix match and bypassed the
+ *   gate entirely — reads were anonymous while writes (over the connection RPC
+ *   channel) were 401: "write-protected, read-naked". A denylist can never keep
+ *   up with newly installed plugins; a default-deny allowlist cannot miss.
  *
  * Sessions: server-side, persisted across restarts (H3), carried by an
  * HttpOnly cookie `dsh_wua_session`; changing the password revokes every
@@ -200,7 +214,7 @@ async function dummyVerify(password) {
 }
 
 // 供测试与工具脚本使用（Cordis 加载时只消费 name/inject/apply，多余导出无副作用）
-export { hashPassword, verifyPassword, auditLog, readAuditEntries, resolveDataDirFrom, DATA_DIR, resolveRedirectScheme, postLoginRedirect, readOidcConfig, writeOidcConfig, configPath, oidcConfigPath, sendJson, makeOidcStateStore, makeDiscoveryCache }
+export { hashPassword, verifyPassword, auditLog, readAuditEntries, resolveDataDirFrom, DATA_DIR, resolveRedirectScheme, postLoginRedirect, readOidcConfig, writeOidcConfig, configPath, oidcConfigPath, sendJson, makeOidcStateStore, makeDiscoveryCache, installRouteGate, PUBLIC_EXACT_PATHS, SELF_GATED_EXACT_PATHS }
 
 // ---------------- 数据目录与文件 ----------------
 
@@ -1014,9 +1028,105 @@ f.addEventListener('submit', function (ev) {
 const API_PREFIX = '/api'
 const PLUGINS_PREFIX = '/plugins'
 // alpha.2 起事件流 WebSocket 由 dsh-api-gateway 的 /api/remote.mux 承载；
-// 旧的 events.mux/events.host 已删除。候选列表按"存在即包装"，兼容新旧核心。
+// 旧的 events.mux/events.host 已删除。候选列表仅用于"核心事件流是否就位"的
+// fail-closed 判断；实际包装已改为**所有** upgrade 路由（见 installRouteGate）。
 const UPGRADE_CANDIDATES = ['/api/remote.mux', '/api/events.mux', '/api/events.host']
 
+// ---------------- 路由白名单（默认拒绝） ----------------
+//
+// 0.6.7 起，闸门由「只包 /api 与 /plugins 的黑名单」改为「默认拒绝一切、
+// 只放行白名单」的白名单模型。
+//
+// 为什么必须改：webServer 的匹配顺序是「exact 优先，其次最长前缀」。任何第三方
+// 插件都可以注册自己的 prefix/exact 路由（实测：/dsh-any-background/font、
+// /dsh-550c-boot/update），它们比本插件的 "" 前缀更具体，会抢在闸门之前命中，
+// 于是完全绕过鉴权——读接口 200 裸奔、写接口因为走 connection RPC 通道反而 401，
+// 形成典型的"写保护、读裸奔"。黑名单永远追不上新装的插件，白名单不会漏。
+//
+// 公开（允许匿名）的**精确路径**。只放行登录/OIDC 往返所必需的最小集合：
+// 少一条登录就进不去，多一条就可能泄露数据。新增请写进 remote-web-ui.publicPaths，
+// 不要直接改这里——部署差异不该进代码。
+const PUBLIC_EXACT_PATHS = new Set([
+  '/dsh-webui-oauth/login',        // 登录页 GET + 提交 POST
+  '/dsh-webui-oauth/setup',        // 首次初始化（由 setup token 把关）
+  '/dsh-webui-oauth/oidc/login',   // SSO 发起（未绑定时内部拒绝）
+  '/dsh-webui-oauth/oidc/callback',// IdP 回跳（state + PKCE + 验签把关）
+  '/oauth/callback',               // 账号平台的 OAuth 回跳（state 常量时间比对）
+])
+
+// 本插件自己注册的端点：内部**逐个**自带 checkRequest（公开的那几个按设计放行）。
+// 与 PUBLIC_EXACT_PATHS 分开列，是为了让"为什么不套通用闸门"有明确理由；
+// 也避免用 startsWith('/dsh-webui-oauth/') 这种宽豁免——那会让第三方注册的
+// /dsh-webui-oauth/xxx 搭便车。
+const SELF_GATED_EXACT_PATHS = new Set([
+  '/dsh-webui-oauth/login',
+  '/dsh-webui-oauth/setup',
+  '/dsh-webui-oauth/logout',
+  '/dsh-webui-oauth/status',
+  '/dsh-webui-oauth/audit',
+  '/dsh-webui-oauth/configure',
+  '/dsh-webui-oauth/disable',
+  '/dsh-webui-oauth/oidc/login',
+  '/dsh-webui-oauth/oidc/bind',
+  '/dsh-webui-oauth/oidc/unbind',
+  '/dsh-webui-oauth/oidc/callback',
+  '/dsh-webui-oauth/oidc/logout',
+])
+
+/**
+ * 读取部署方追加的公开路径（settings 的 remote-web-ui.publicPaths）。
+ *
+ * 形如 ['/api/webhooks/github'] 或 ['/api/webhooks/*']（结尾 /* 表示前缀）。
+ * 只接受以 / 开头、无空白与控制字符的绝对路径——避免把配置写成任意匹配。
+ *
+ * @param ctx 插件上下文
+ * @returns {string[]} 清洗后的模式列表
+ */
+function extraPublicPaths(ctx) {
+  const out = []
+  try {
+    const settings = ctx && typeof ctx.get === 'function' ? ctx.get('settings') : undefined
+    const section = settings && typeof settings.get === 'function'
+      ? settings.get(PUBLIC_BASE_NAMESPACE)
+      : undefined
+    const raw = section && section.publicPaths
+    if (!Array.isArray(raw)) return out
+    for (const item of raw) {
+      if (typeof item !== 'string') continue
+      const p = item.trim()
+      if (!p.startsWith('/')) continue
+      if (/[\x00-\x1f\x7f\s]/.test(p)) continue
+      out.push(p)
+    }
+  } catch (e) { /* 配置不可读时按"没有额外放行"处理（更严格） */ }
+  return out
+}
+
+/**
+ * 判断路径是否命中公开模式。
+ * 模式以 '/*' 结尾表示前缀匹配（'/api/webhooks/*' 命中 '/api/webhooks/x' 与
+ * '/api/webhooks'），否则要求精确相等。
+ *
+ * @param path 请求/路由路径
+ * @param patterns 公开模式列表
+ * @returns {boolean}
+ */
+export function matchesPublicPath(path, patterns) {
+  const p = String(path || '')
+  for (const raw of patterns || []) {
+    const pat = String(raw || '')
+    if (!pat) continue
+    if (pat.endsWith('/*')) {
+      const base = pat.slice(0, -1)      // 保留结尾的 '/'
+      if (p === pat.slice(0, -2)) return true
+      if (p.startsWith(base)) return true
+    } else if (p === pat) {
+      return true
+    }
+  }
+  return false
+}
+
 function rejectUpgrade401(socket) {
   try {
     socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 13\r\n\r\nunauthorized\n')
@@ -1090,26 +1200,35 @@ function installRouteGate(ctx, checkRequest, log) {
   const undos = []
   let undone = false
 
+  // alpha.2 起核心自带 Connection 浏览器认证（BrowserAuth + trusted-host fence）：
+  // /api handler 内建 requestRejection，且 browser cookie 按 Host authority 绑定 ——
+  // 再改写 Host/Origin 会破坏 cookie 匹配。仅旧核心（无 connection.requestRejection）
+  // 需要 loopback 伪装来通过 PRIVILEGED_METHODS fence。
+  //
+  // 【必须按请求判定，不能在包装时判定一次】。0.6.7 引入了"注册瞬间上闸门"
+  // （接管路由表的 set），这使得 /api 可能在 client-connection 服务尚未对本站
+  // 上下文可见时就被包装。若此时把 coreHasRequestGate 固化为 false，
+  // useDeputy 就永久为 true：之后每个 /api 请求都被改写成回环 Host，
+  // 而核心的 authority 绑定 Cookie 随之失配 —— 表现为"登录成功后 /api 恒 401"。
+  // 这是 0.6.7 的回归，改为每次请求现查即可消除对服务就绪时序的依赖。
+  const coreHasRequestGate = () => {
+    try {
+      const connection = ctx.get('connection')
+      return !!(connection && typeof connection.requestRejection === 'function')
+    } catch (e) {
+      return false
+    }
+  }
   const wrapHttp = (route, opts) => {
     const original = route.handler
     const loopbackDeputy = !!(opts && opts.loopbackDeputy)
-    // alpha.2 起核心自带 Connection 浏览器认证（BrowserAuth + trusted-host fence）：
-    // /api handler 内建 requestRejection，且 browser cookie 按 Host authority 绑定 ——
-    // 再改写 Host/Origin 会破坏 cookie 匹配。仅旧核心（无 connection.requestRejection）
-    // 需要 loopback 伪装来通过 PRIVILEGED_METHODS fence。
-    let coreHasRequestGate = false
-    try {
-      const connection = ctx.get('connection')
-      coreHasRequestGate = !!(connection && typeof connection.requestRejection === 'function')
-    } catch (e) { coreHasRequestGate = false }
-    const useDeputy = loopbackDeputy && !coreHasRequestGate
     const wrapped = async (req, res) => {
       if (!checkRequest(req)) {
         res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' })
         res.end('unauthorized')
         return
       }
-      if (useDeputy) {
+      if (loopbackDeputy && !coreHasRequestGate()) {
         // Authenticated + this is the /api surface on a legacy core: present the request
         // to the core as loopback so PRIVILEGED_METHODS' strict fence (settings.*,
         // credentials.*, agentPreset.*, llm.discoverModels) admits it. Our session gate
@@ -1141,31 +1260,170 @@ function installRouteGate(ctx, checkRequest, log) {
     return () => { route.handler = original }
   }
 
-  // 已包装的路由打标记，避免重复包装
-  const wrapped = new WeakSet()
-  const PROTECTED_PREFIXES = [API_PREFIX, PLUGINS_PREFIX]
+  // 已包装的路由 → { kind, path, undo }。
+  // 用 Map 而不是 WeakSet，是为了支持"配置热更新后把已包的路由解包"：
+  // publicPaths 追加某路径后，该路径若之前已被包装，需要在下一次扫描时撤销，
+  // 否则文档里说的"无需重启生效"就不成立。
+  const wrappedRoutes = new Map()
+
+  // 部署方追加的公开路径（settings.remote-web-ui.publicPaths）。
+  // 每次扫描重读一次：配置热更新后无需重启即可生效。
+  let publicPatterns = extraPublicPaths(ctx)
+
+  // 当前生效的闸门策略快照，供 status 端点回显（便于运维核对"到底放行了什么"）。
+  // 计数在读取时从 wrappedRoutes 现算，避免 counters 与实际状态漂移；
+  // 豁免项用 Set 去重（scanOnce 每 2 秒跑一次，数组会无限增长）。
+  const stats = { publicPaths: new Set(), exemptPrefixes: new Set(), exemptSelfGated: new Set() }
+  let fallbackWrapped = false
+
+  /** 是否为公开路径：内置最小集合 + 部署方追加的模式。 */
+  const isPublicPath = (path) => PUBLIC_EXACT_PATHS.has(path) || matchesPublicPath(path, publicPatterns)
+
+  /** 精确路径/前缀是否属于本插件自管或已声明公开。 */
+  const isExemptHttp = (path, kind) => {
+    if (isPublicPath(path)) return true
+    if (kind === 'exact' && SELF_GATED_EXACT_PATHS.has(path)) return true
+    // 空前缀是本插件自己的传输层闸门（未登录时 302 到登录页）。
+    // 它不能套通用闸门，否则登录页永远打不开（401 死循环）。
+    if (kind === 'prefix' && path === '') return true
+    return false
+  }
+
+  /**
+   * 包一条 HTTP 路由（若它不在白名单里）。
+   * @returns {boolean} 本次是否真的包装了
+   */
+  const wrapRoute = (route, kind) => {
+    if (!route || typeof route !== 'object' || wrappedRoutes.has(route)) return false
+    if (typeof route.handler !== 'function') return false
+    const path = typeof route.path === 'string' ? route.path : ''
+    if (isExemptHttp(path, kind)) {
+      if (kind === 'prefix' && path === '') stats.exemptPrefixes.add('(root)')
+      else if (kind === 'exact' && !isPublicPath(path)) stats.exemptSelfGated.add(path)
+      return false
+    }
+    const undoFn = wrapHttp(route, { loopbackDeputy: kind === 'prefix' && path === API_PREFIX })
+    wrappedRoutes.set(route, { kind, path, undo: undoFn })
+    undos.push(undoFn)
+    log('wrapped ' + kind + ' route ' + (path === '' ? '(root)' : path))
+    return true
+  }
+
+  /** 包一条 upgrade 路由（WebSocket）。默认拒绝，不做白名单。 */
+  const wrapUpgradeRoute = (route) => {
+    if (!route || typeof route !== 'object' || wrappedRoutes.has(route)) return false
+    if (typeof route.handler !== 'function') return false
+    const undoFn = wrapUpgrade(route)
+    wrappedRoutes.set(route, { kind: 'upgrade', path: route.path || '', undo: undoFn })
+    undos.push(undoFn)
+    log('wrapped upgrade route ' + (route.path || '(unnamed)'))
+    return true
+  }
+
+  // ---------------- fallback 也要包 ----------------
+  // fallback 是"未被任何具名路由认领"的兜底处理器。它同样可能被第三方插件占据，
+  // 若不管，攻击者只要找到一个不存在的路径就可能落到未鉴权的 fallback 上。
+  const wrappedFallbacks = new WeakSet()
+  const gateFallback = (handler) => {
+    if (typeof handler !== 'function' || wrappedFallbacks.has(handler)) return handler
+    const original = handler
+    const gated = async (req, res) => {
+      if (!checkRequest(req)) {
+        res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' })
+        res.end('unauthorized')
+        return
+      }
+      return original(req, res)
+    }
+    wrappedFallbacks.add(gated)
+    fallbackWrapped = true
+    log('wrapped fallback handler')
+    return gated
+  }
+
+  // 已经就位的 fallback：直接替换属性（保留原函数以便 undo）。
+  const wrapExistingFallback = () => {
+    const current = ws.fallback
+    if (typeof current !== 'function') return
+    if (wrappedFallbacks.has(current)) return
+    if (current.__dshWuaGated === true) return
+    const gated = gateFallback(current)
+    if (gated === current) return
+    gated.__dshWuaGated = true
+    ws.fallback = gated
+    undos.push(() => { if (ws.fallback === gated) ws.fallback = current })
+  }
+
+  // ---------------- 注册时即拦截（消除重扫窗口） ----------------
+  // 仅靠周期重扫会有最长 2s（降频后 10s）的"新路由尚未包装"窗口：插件热加载
+  // 后立刻被匿名访问就能漏过去。因此直接接管 Map#set，在注册的那一刻包装。
+  const interceptMapSet = (map, kind) => {
+    if (!map || typeof map.set !== 'function') return
+    const originalSet = map.set
+    map.set = function patchedSet (key, value) {
+      try { wrapRoute(value, kind) } catch (e) { /* 包装失败不阻断注册，靠重扫兜底 */ }
+      return originalSet.call(this, key, value)
+    }
+    undos.push(() => { map.set = originalSet })
+  }
+  interceptMapSet(ws.exact, 'exact')
+  interceptMapSet(ws.prefixes, 'prefix')
+
+  // upgrade 表同理：新注册的 WebSocket 路由也要在注册那一刻就上闸门。
+  if (ws.upgrades && typeof ws.upgrades.set === 'function') {
+    const originalUpgradeSet = ws.upgrades.set
+    ws.upgrades.set = function patchedUpgradeSet (key, value) {
+      try { wrapUpgradeRoute(value) } catch (e) { /* 靠重扫兜底 */ }
+      return originalUpgradeSet.call(this, key, value)
+    }
+    undos.push(() => { ws.upgrades.set = originalUpgradeSet })
+  }
+
+  // registerFallback 走的是属性赋值而非 Map，单独接管。
+  if (typeof ws.registerFallback === 'function') {
+    const originalRegisterFallback = ws.registerFallback
+    ws.registerFallback = function patchedRegisterFallback (handler) {
+      return originalRegisterFallback.call(this, gateFallback(handler))
+    }
+    undos.push(() => { ws.registerFallback = originalRegisterFallback })
+  }
+
   const scanOnce = () => {
     if (undone) return
-    for (const pfx of PROTECTED_PREFIXES) {
-      const route = ws.prefixes.get(pfx)
-      if (route !== undefined && !wrapped.has(route)) {
-        wrapped.add(route)
-        undos.push(wrapHttp(route, { loopbackDeputy: pfx === API_PREFIX }))
-        problems.delete(`prefix route "${pfx}" not registered yet`)
-        log(`wrapped prefix route ${pfx}`)
-      } else if (route === undefined) {
-        problems.add(`prefix route "${pfx}" not registered yet`)
-      }
+    publicPatterns = extraPublicPaths(ctx)
+    stats.publicPaths = new Set([...PUBLIC_EXACT_PATHS, ...publicPatterns])
+
+    // 配置热更新可能**新增**公开路径：已包装的对应路由必须解包，否则"无需重启
+    // 生效"是假的。只处理 HTTP 路由（upgrade 不做白名单）。
+    for (const [route, rec] of [...wrappedRoutes]) {
+      if (rec.kind === 'upgrade') continue
+      if (!isExemptHttp(rec.path, rec.kind)) continue
+      try { rec.undo() } catch (e) { /* ignore */ }
+      wrappedRoutes.delete(route)
+      log('unwrapped ' + rec.kind + ' route ' + (rec.path || '(root)') + ' (now public)')
     }
-    // alpha.2 起仅存在 /api/remote.mux（由 api-gateway 注册）；旧核心仍用
-    // events.mux/events.host。候选列表兼容两代：已注册的全部包装，其余不计问题。
-    for (const path of UPGRADE_CANDIDATES) {
-      const r = ws.upgrades.get(path)
-      if (r !== undefined && !wrapped.has(r)) {
-        wrapped.add(r)
-        undos.push(wrapUpgrade(r))
-        log(`wrapped upgrade route ${path}`)
-      }
+    // 快照一遍再遍历：包装过程中不改 Map，但注册可能并发发生（单线程下安全，
+    // 仍显式取快照以免迭代语义依赖实现细节）。
+    const exactEntries = ws.exact && typeof ws.exact.forEach === 'function' ? [...ws.exact] : []
+    for (const [, route] of exactEntries) wrapRoute(route, 'exact')
+
+    const prefixEntries = ws.prefixes && typeof ws.prefixes.forEach === 'function' ? [...ws.prefixes] : []
+    for (const [, route] of prefixEntries) wrapRoute(route, 'prefix')
+
+    // 所有 WebSocket upgrade 一律包装（不再只认 /api/remote.mux）：
+    // 第三方插件注册的 upgrade 同样可能暴露未鉴权的双向通道。
+    const upgradeEntries = ws.upgrades && typeof ws.upgrades.forEach === 'function' ? [...ws.upgrades] : []
+    for (const [, route] of upgradeEntries) wrapUpgradeRoute(route)
+
+    wrapExistingFallback()
+
+    // fail-closed 的判据：核心的 /api 与 /plugins 必须就位，否则说明路由形状
+    // 变了，"已启用"可能意味着裸奔。这里只保留这两条（以及事件流 upgrade），
+    // 不再把"只包了这两个"当成保护范围。
+    for (const pfx of [API_PREFIX, PLUGINS_PREFIX]) {
+      const route = ws.prefixes.get(pfx)
+      if (route === undefined) problems.add(`prefix route "${pfx}" not registered yet`)
+      else problems.delete(`prefix route "${pfx}" not registered yet`)
     }
     if (UPGRADE_CANDIDATES.every((path) => ws.upgrades.get(path) === undefined)) {
       problems.add('no upgrade route registered yet (looked for ' + UPGRADE_CANDIDATES.join(', ') + ')')
@@ -1208,7 +1466,33 @@ function installRouteGate(ctx, checkRequest, log) {
     undone = true
     for (const u of undos.splice(0).reverse()) { try { u() } catch (e) { /* ignore */ } }
   }
-  return { ok: () => problems.size === 0, problems: () => [...problems], undo }
+  return {
+    ok: () => problems.size === 0,
+    problems: () => [...problems],
+    // 供 status 端点回显：让运维能直接看到"包了几条、放行了什么"，
+    // 而不是只能相信"闸门开着"这句话。
+    stats: () => {
+      // 现算而非累加：解包/重包后计数不会漂移。
+      let exact = 0, prefix = 0, upgrade = 0
+      for (const rec of wrappedRoutes.values()) {
+        if (rec.kind === 'exact') exact += 1
+        else if (rec.kind === 'prefix') prefix += 1
+        else if (rec.kind === 'upgrade') upgrade += 1
+      }
+      return {
+        wrappedExact: exact,
+        wrappedPrefix: prefix,
+        wrappedUpgrade: upgrade,
+        wrappedFallback: fallbackWrapped ? 1 : 0,
+        publicPaths: [...stats.publicPaths].sort(),
+        exemptPrefixes: [...stats.exemptPrefixes].sort(),
+        exemptSelfGated: [...stats.exemptSelfGated].sort(),
+      }
+    },
+    // 立即重扫一次（配置变更后测试/运维可直接触发，不必等 2s 定时器）。
+    refresh: () => { scanOnce(); return { ok: problems.size === 0, problems: [...problems] } },
+    undo,
+  }
 }
 
 // ---------------- DSH 外观偏好 ----------------
@@ -2247,7 +2531,13 @@ export async function apply(ctx) {
           username: enabled ? creds.username : null,
           ttl: ttlOf(creds),
           sessionsPersisted: sessions.ok,
-          gate: { ok: gate.ok(), problems: gate.problems().slice(0, 3) },
+          gate: {
+            ok: gate.ok(),
+            problems: gate.problems().slice(0, 3),
+            mode: 'deny-by-default',
+            // 让运维能核对"到底包了哪些、放行了哪些"，而不是只看一句"闸门已开"。
+            stats: gate.stats(),
+          },
           trustedOrigin: (() => {
             try {
               const pol = trustedOriginPolicy(ctx, oidcCfg)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-webui-oauth",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "test": "node test/redirect-scheme.test.mjs && node test/proxy-host.test.mjs && node test/trusted-origin.test.mjs && node test/oidc.test.mjs && node test/oidc-state-ttl.test.mjs && node test/set-cookie-multi.test.mjs && node test/oidc-integration.test.mjs && node test/oidc-config-store.test.mjs && node test/adopt-data-dir.test.mjs && node test/oidc-ec.test.mjs && node test/jwks-refresh.test.mjs && node test/oidc-bind.test.mjs && node test/client-bundle-id.test.mjs && node test/client-prefill.test.mjs && node test/displace-original.test.mjs && node test/oidc-redirect-matrix.test.mjs"
+    "test": "node test/redirect-scheme.test.mjs && node test/proxy-host.test.mjs && node test/trusted-origin.test.mjs && node test/oidc.test.mjs && node test/oidc-state-ttl.test.mjs && node test/set-cookie-multi.test.mjs && node test/oidc-integration.test.mjs && node test/oidc-config-store.test.mjs && node test/adopt-data-dir.test.mjs && node test/oidc-ec.test.mjs && node test/jwks-refresh.test.mjs && node test/oidc-bind.test.mjs && node test/client-bundle-id.test.mjs && node test/client-prefill.test.mjs && node test/displace-original.test.mjs && node test/oidc-redirect-matrix.test.mjs && node test/gate-default-deny.test.mjs"
   },
   "exports": {
     ".": "./index.js",