dsh-auth-remote 0.1.3 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/CHANGELOG.zh-CN.md +14 -0
- package/CONTRIBUTING.md +2 -0
- package/CONTRIBUTING.zh-CN.md +2 -0
- package/README.md +16 -10
- package/README.zh-CN.md +16 -10
- package/cordis.patch.yml +4 -5
- package/dist/client.js +2 -2
- package/dist/client.js.map +2 -2
- package/dist/index.js +280 -87
- package/dist/index.js.map +4 -4
- package/dist/types/adapters/dsh/browser-auth.d.ts +3 -0
- package/dist/types/adapters/dsh/browser-auth.d.ts.map +1 -1
- package/dist/types/adapters/dsh/public-url.d.ts +10 -0
- package/dist/types/adapters/dsh/public-url.d.ts.map +1 -0
- package/dist/types/adapters/dsh/readiness.d.ts +2 -3
- package/dist/types/adapters/dsh/readiness.d.ts.map +1 -1
- package/dist/types/adapters/dsh/runtime-capabilities.d.ts +46 -0
- package/dist/types/adapters/dsh/runtime-capabilities.d.ts.map +1 -0
- package/dist/types/adapters/dsh/startup-urls.d.ts +2 -2
- package/dist/types/adapters/dsh/startup-urls.d.ts.map +1 -1
- package/dist/types/adapters/dsh/webserver.d.ts +8 -2
- package/dist/types/adapters/dsh/webserver.d.ts.map +1 -1
- package/dist/types/config.d.ts +48 -14
- package/dist/types/config.d.ts.map +1 -1
- package/dist/types/http/gate.d.ts +1 -2
- package/dist/types/http/gate.d.ts.map +1 -1
- package/dist/types/index.d.ts +6 -2
- package/dist/types/index.d.ts.map +1 -1
- package/docs/deployment.md +83 -38
- package/docs/deployment.zh-CN.md +84 -39
- package/docs/development.md +11 -5
- package/docs/development.zh-CN.md +11 -5
- package/docs/legacy-compatibility.md +115 -0
- package/docs/releasing.md +7 -5
- package/docs/releasing.zh-CN.md +7 -5
- package/docs/reverse-proxy.md +7 -5
- package/docs/reverse-proxy.zh-CN.md +7 -5
- package/examples/web-profile-auth-remote.patch.yml +7 -3
- package/package.json +19 -10
package/docs/deployment.zh-CN.md
CHANGED
|
@@ -2,9 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[English](deployment.md)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
下面的 npm 步骤使用插件 `0.1.3`。升级已有安装前,请参阅[兼容说明](../README.zh-CN.md#dsh-兼容性);源码构建参见[开发指南](development.zh-CN.md)。
|
|
5
|
+
本指南使用 DSH `0.2.1-alpha.2` 和默认 `~/.dsh` 数据目录。其他五版能力见[兼容矩阵](../README.zh-CN.md#dsh-兼容性),隔离源码构建见[开发指南](development.zh-CN.md)。域名、代理网络和服务管理器由部署者选择。
|
|
8
6
|
|
|
9
7
|
## 从 npm 最小化安装
|
|
10
8
|
|
|
@@ -12,28 +10,23 @@
|
|
|
12
10
|
|
|
13
11
|
```sh
|
|
14
12
|
dsh --version
|
|
15
|
-
dsh plugin --profile web add dsh-auth-remote@0.1.
|
|
13
|
+
dsh plugin --profile web add dsh-auth-remote@0.1.6
|
|
16
14
|
dsh plugin --profile web list
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
确认 `dsh --version` 输出 `0.2.0-rc.2`,且列表中有 `dsh-auth-remote@0.1.3`。bundle 提供认证监听,默认 `allowedOrigins: []`,因此只准入字面回环主机。最小安装无需修改 profile 补丁。在一个终端启动 DSH:
|
|
20
|
-
|
|
21
|
-
```sh
|
|
22
15
|
dsh web --no-open --port 13090
|
|
23
16
|
```
|
|
24
17
|
|
|
25
|
-
|
|
18
|
+
核对所选 DSH 版本和插件列表。默认 IPv4 HTTP 回环监听不需要 profile 补丁。在另一终端确认 `/auth-remote/ready` 返回 `"plugin":"dsh-auth-remote"`、`"protocolVersion":1` 和 `"ready":true`,随后初始化账号:
|
|
26
19
|
|
|
27
20
|
```sh
|
|
28
21
|
curl -fsS http://127.0.0.1:13090/auth-remote/ready
|
|
29
22
|
dsh plugin --profile web exec dsh-auth-remote init --lang zh
|
|
30
23
|
```
|
|
31
24
|
|
|
32
|
-
|
|
25
|
+
打开打印的 `http://127.0.0.1:13090/` 根地址。匿名导航跳转登录页,匿名业务 API 被拒绝。bundle 关闭原生 token URL 输出和自动打开浏览器;开发、测试 home 与账号 profile 分开。
|
|
33
26
|
|
|
34
|
-
##
|
|
27
|
+
## 公开入口完整配置
|
|
35
28
|
|
|
36
|
-
|
|
29
|
+
HTTPS 代理入口可把以下条目合并到 `~/.dsh/profiles/web/cordis.patch.yml`,保留无关模型和插件条目。可复用的 [profile 示例](../examples/web-profile-auth-remote.patch.yml)使用相同配置:
|
|
37
30
|
|
|
38
31
|
```yaml
|
|
39
32
|
- id: webserver
|
|
@@ -41,50 +34,102 @@ dsh plugin --profile web exec dsh-auth-remote init --lang zh
|
|
|
41
34
|
|
|
42
35
|
- id: auth-remote
|
|
43
36
|
config:
|
|
44
|
-
|
|
37
|
+
publicUrl: https://dsh.example.com/
|
|
38
|
+
host: 127.0.0.1
|
|
39
|
+
port: 13090
|
|
45
40
|
requireTotp: true
|
|
46
41
|
sessionHours: 168
|
|
47
42
|
preserveOriginPaths: []
|
|
48
43
|
```
|
|
49
44
|
|
|
50
|
-
在 profile
|
|
45
|
+
在 profile 和代理中一致地替换公网主机名。示例在外部 TLS 后使用私有 HTTP 监听。`publicUrl` 选择浏览器入口,不会配置代理、证书或监听协议。建议独立禁用 `webserver`;认证 bundle 正常加载时已自行禁用该条目。卸载插件并恢复原生监听时,移除独立禁用条目。
|
|
46
|
+
|
|
47
|
+
后应用的 DSH patch 条目会整段替换插件 `config`,因此该条目必须保留全部预期认证配置。home 级 patch 若也定义 `auth-remote`,开放入口前用 `dsh --profile web --dump-config` 核对最终组合。
|
|
48
|
+
|
|
49
|
+
## 配置优先级与路径基准
|
|
50
|
+
|
|
51
|
+
以下字段均直接位于 `auth-remote.config`,没有别名或嵌套 TLS 对象。
|
|
52
|
+
|
|
53
|
+
| 字段 | 生效值 |
|
|
54
|
+
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| `publicUrl` | alpha.1/2 的 CLI `--public-url` 整项替换文件 URL;否则依次为文件、旧单项迁移、实际监听根地址。仅接受绝对 HTTP(S) 根 URL,可带末尾斜杠,不能带凭据、子路径、查询或片段。 |
|
|
56
|
+
| `host` | CLI `--host`、文件、默认 `127.0.0.1`。要求具体 IPv4 字面量;alpha.2 还接受具体 IPv6,包含 mapped 格式。拒绝 DNS 名称和通配绑定。 |
|
|
57
|
+
| `port` | CLI `--port`、文件、默认 `3080`,与 host 分别覆盖。`0` 在真实非零端口绑定后才生成入口。 |
|
|
58
|
+
| `tlsCert`、`tlsKey` | 仅 alpha.2。两个文件字段必须成对,CLI `--tls-cert`/`--tls-key` 也必须成对。CLI 整组替换文件组,不混合来源、不读取未采用的文件证书路径。省略 TLS 即 HTTP。 |
|
|
59
|
+
| `requireTotp` | 默认 `true`。设为 `false` 时未绑定账号可跳过;已绑定账号仍需第二因素。 |
|
|
60
|
+
| `sessionHours` | 默认固定 168 小时。缩短会收紧已有会话,放宽不会复活过期会话。 |
|
|
61
|
+
| `preserveOriginPaths` | 可选的规范路径段前缀,默认 `[]`。匹配路径在认证后保留已验证公网 Host 和已有 Origin;最终公开来源自动配置原生 Connection 信任。 |
|
|
62
|
+
|
|
63
|
+
**特别注意 TLS 路径:**文件中的相对值以所选 profile 目录为基准,即其 `cordis.patch.yml` 所在目录;CLI 的相对路径以进程启动 cwd 为基准。两者均不以 bundle 或其他 overlay 目录为基准。绝对路径保持绝对。
|
|
64
|
+
|
|
65
|
+
alpha.2 的覆盖示例 `dsh web --no-open --host ::1 --port 0 --public-url https://dsh.example.com/` 分别替换文件 host、port 和 URL。监听绑定真实空闲端口,显式公开根地址保持不变;代理须到达该实际端口。仅覆盖端口时,省略 `--host` 即保留文件 host。
|
|
66
|
+
|
|
67
|
+
例如文件 `tlsCert: ./tls/dsh.crt` 始终指 `~/.dsh/profiles/web/tls/dsh.crt`,从其他目录启动也不变。以下命令则使用 `./launch-workdir/tls/dsh.crt` 和对应私钥:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
cd ./launch-workdir
|
|
71
|
+
dsh web --no-open --tls-cert ./tls/dsh.crt --tls-key ./tls/dsh.key
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
只给一个 CLI 参数会失败,即使文件提供另一半也不混用。证书/私钥缺失、不可读、空内容、PEM 无效或不匹配时启动失败,不回退 HTTP,并释放监听、管理 socket 和存储资源。证书须对浏览器主机名有效;TLS 由官方监听处理。
|
|
75
|
+
|
|
76
|
+
CLI 公开 URL 覆盖仅在 alpha.1/2 可用。旧 DSH 对该未知参数报错,需使用插件文件字段;旧版也明确拒绝原生 IPv6/TLS。旧版 Web 提示和 `DSH_WEB_URL` 保留原生固定 IPv4 回环 URL 加实际端口,插件准入和公开地址输出仍取生效配置。
|
|
77
|
+
|
|
78
|
+
## 原生 HTTPS 与 IPv6
|
|
79
|
+
|
|
80
|
+
alpha.2 的 IPv6 回环 HTTPS 可合并以下完整认证条目,使用自己的证书和私钥:
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
- id: auth-remote
|
|
84
|
+
config:
|
|
85
|
+
host: ::1
|
|
86
|
+
port: 8443
|
|
87
|
+
tlsCert: ./tls/dsh.crt
|
|
88
|
+
tlsKey: ./tls/dsh.key
|
|
89
|
+
requireTotp: true
|
|
90
|
+
sessionHours: 168
|
|
91
|
+
preserveOriginPaths: []
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
用 `dsh web --no-open` 启动,派生根地址为 `https://[::1]:8443/`。IPv6 URL authority 需要方括号。省略 TLS 字段时,也可用 `dsh web --no-open --host ::1 --port 13090` 提供 IPv6 HTTP。具体非回环文档地址如 `192.0.2.10`、`2001:db8::10` 必须替换为主机实际拥有的地址;绑定网卡不限制客户端来源 IP,来源限制由网络策略实施。
|
|
95
|
+
|
|
96
|
+
拒绝 `0.0.0.0`、`::` 和 mapped IPv4 通配绑定。scope/zone 为绑定选择网卡,不能进入便携公开 URL;冗余回环 scope 会归一化,非回环 scoped bind 需要显式便携 `publicUrl`,例如 `https://dsh.example.com/`。
|
|
51
97
|
|
|
52
|
-
##
|
|
98
|
+
## 迁移旧 allowedOrigins
|
|
53
99
|
|
|
54
|
-
|
|
55
|
-
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
56
|
-
| `webserver: disabled` | 建议在 profile 中独立禁用原生监听;认证 bundle 正常加载时会自行禁用。 |
|
|
57
|
-
| `dsh web --port` | 设置认证监听端口;示例使用 `127.0.0.1:13090`。插件读取 DSH web startup,无需在插件配置中重复填写监听参数。 |
|
|
58
|
-
| `allowedOrigins` | 精确列出 HTTP(S) 来源,含非默认端口。示例为 `https://dsh.example.com`。空列表只允许字面回环;没有通配、转发头推断或 CORS 回退。 |
|
|
59
|
-
| `requireTotp` | 默认 `true`。设为 `false` 时未绑定账号可以跳过;已绑定账号仍需第二因素。 |
|
|
60
|
-
| `sessionHours` | 默认固定 168 小时。缩短会收紧已有会话,放宽不会复活过期会话。 |
|
|
61
|
-
| `preserveOriginPaths` | 可选的路径段前缀,让已验证的公网 Host 和请求中已有的 Origin 传给 DSH。默认 `[]` 把已认证请求改写到内部 authority;bundle 会为保留路径配置 Connection。 |
|
|
100
|
+
旧字段支持属于插件迁移契约,与 DSH 版本支持范围独立。每次激活只告警一次,在内存转换,不改写 profile 或账号状态。
|
|
62
101
|
|
|
63
|
-
|
|
102
|
+
| 旧输入 | 升级行为 |
|
|
103
|
+
| --------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
104
|
+
| 未提供字段 | 未提供 `publicUrl` 时,根据实际监听生成唯一根地址。 |
|
|
105
|
+
| `allowedOrigins: []` | 告警,派生实际监听根地址。 |
|
|
106
|
+
| 一个根 URL | 告警,将该根地址作为 `publicUrl`。 |
|
|
107
|
+
| 两项及以上,包含重复值 | 失败;人工选择唯一公开入口,用 `publicUrl` 替换数组。 |
|
|
108
|
+
| 任意显式 `allowedOrigins` 与文件或 CLI `publicUrl` 共存,含空数组或相同 URL | 失败;使用新字段前删除旧字段。 |
|
|
64
109
|
|
|
65
|
-
|
|
110
|
+
升级前备份旧 patch。单项替换为 `publicUrl: https://dsh.example.com/`;空数组删除即可保留派生行为。旧多来源安装必须主动选择一个规范入口,在流量到达受保护上游前把其他浏览器主机名导向该入口。回退 0.1.5 时恢复其兼容的旧配置备份;新字段不属于 0.1.5 契约。
|
|
66
111
|
|
|
67
|
-
|
|
112
|
+
## 来源与桥接契约
|
|
68
113
|
|
|
69
|
-
|
|
114
|
+
准入为唯一生效公开来源加字面回环 authority;URL 根路径不支持部署前缀。请求须有唯一合法 Host,修改请求和 WebSocket 升级须有匹配 Origin;跨站或不匹配 Fetch Metadata 被拒绝。替换后旧公开来源不再登记。`Forwarded`、`X-Forwarded-*` 不决定准入或 Cookie Secure;CLI `--trusted-host` 只配置原生 Connection,不扩大外层策略。
|
|
70
115
|
|
|
71
|
-
|
|
116
|
+
插件 Cookie 跟随已验证外部来源,限主机、HttpOnly、SameSite,HTTPS 设置 Secure。原生桥接凭据仅保留服务端,跟随原生监听协议;公开 HTTP 代理接入原生 HTTPS 时,其原生 Cookie audience/Secure 仍按 HTTPS。浏览器 Cookie 不通过端口隔离。
|
|
72
117
|
|
|
73
|
-
|
|
118
|
+
标准 `/api` 路由在 `preserveOriginPaths: []` 下即可工作,无需列 `/api`。仅在下游需要原始公网 Host 时加入前缀;Origin 仅在请求已有时透传,保留路径预检所选公开 authority。无需单独 Connection 条目或额外 trusted-host 参数。alpha.2 普通路径使用归一化原生 bind authority,旧 Connection 保留内部 HTTP 回环桥接;两类路径均需完整会话。撤销、Connection 丢失或存储故障会关闭活跃上传、流和升级连接,撤回业务准入。ready 不表示账号已初始化。
|
|
74
119
|
|
|
75
|
-
##
|
|
120
|
+
## 启动并验证公开入口
|
|
76
121
|
|
|
77
|
-
1. 核对 Linux、Node.js 24
|
|
78
|
-
2.
|
|
79
|
-
3.
|
|
80
|
-
4.
|
|
122
|
+
1. 核对 Linux、Node.js 24+、精确兼容 DSH 版本及目标 profile/包;测试开发数据独立。
|
|
123
|
+
2. 合并一个完整 profile 配置,需要代理时建立私有可达上游,参见[代理指南](reverse-proxy.zh-CN.md)。
|
|
124
|
+
3. 启动 DSH。HTTP 上游示例检查 `curl -fsS -H 'Host: dsh.example.com' http://127.0.0.1:13090/auth-remote/ready`,要求预期插件/协议和 `ready: true`。
|
|
125
|
+
4. 核对匿名 HTML 跳转和 API 拒绝,再本地初始化、登录、绑定 TOTP、保存备用码。经所选入口测试官方设置、工作区、预览、上传、SSE/WebSocket 和撤销。
|
|
81
126
|
|
|
82
|
-
|
|
127
|
+
启动打印实际协议、地址、端口及一个不同的公开根地址,相同 URL 去重,不含 token 或登录路径。ready 和匿名拒绝检查通过前保持入口私有;插件、TLS、状态或 Connection 初始化失败时业务须不可用。
|
|
83
128
|
|
|
84
129
|
## 备份、恢复与变更
|
|
85
130
|
|
|
86
|
-
停止 DSH
|
|
131
|
+
停止 DSH 并确认释放 profile 锁,再复制 `~/.dsh/profiles/web/auth-remote/auth-state.json`。副本目录权限 0700、文件权限 0600;它含密码哈希、TOTP 密钥、备用码哈希和会话。不要复制写入中的临时文件、覆盖运行中持锁状态或提交 Git;同时备份对应 profile patch 和包/锁文件。
|
|
87
132
|
|
|
88
|
-
恢复时先停止 DSH
|
|
133
|
+
恢复时先停止 DSH,检查 schema/包兼容,以私有属主/权限恢复,再核对 ready 和 CLI `status --json`。本地 `reset-password`、`reset-totp`、`revoke-sessions` 均撤销会话。管理响应丢失后结果不明,先查状态再执行下一次修改。
|
|
89
134
|
|
|
90
|
-
|
|
135
|
+
外部入口变更时,替换唯一 `publicUrl`、更新代理并重启 DSH。检查新入口与旧非回环入口的拒绝,包含 Cookie、重定向、上传和长连接。不要在插件中临时配置两个来源。
|
package/docs/development.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[简体中文](development.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
Development and the full test suite use Linux (`/proc` is required for the profile lock), Node.js 24+, pnpm 12.5.1, and DSH `0.2.
|
|
5
|
+
Development and the full test suite use Linux (`/proc` is required for the profile lock), Node.js 24+, pnpm 12.5.1, and DSH `0.2.1-alpha.2`. Browser tests use Playwright-managed Chromium and a Node HTTP/HTTPS forwarder.
|
|
6
6
|
|
|
7
7
|
## Set up and check a checkout
|
|
8
8
|
|
|
@@ -14,7 +14,7 @@ pnpm pack:local
|
|
|
14
14
|
pnpm smoke
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
`pnpm check` runs type checking, formatting, build, package/deployment/document checks, then unit, integration, CLI, and browser tests. `pnpm pack:local` writes `artifacts/dsh-auth-remote-0.1.
|
|
17
|
+
`pnpm check` runs type checking, formatting, build, package/deployment/document checks, then unit, integration, CLI, and browser tests. `pnpm pack:local` writes `artifacts/dsh-auth-remote-0.1.6.tgz` after static checks; it does not publish. `pnpm smoke` installs that archive into an isolated DSH home, starts the pinned DSH runtime briefly, checks readiness, anonymous redirection/denial and an online CLI status, then stops it.
|
|
18
18
|
|
|
19
19
|
## Use the isolated development profile
|
|
20
20
|
|
|
@@ -29,7 +29,7 @@ The scripts manage only `.dev/runtime-<version>` and `.dev/dsh-home` under this
|
|
|
29
29
|
For direct inspection, use the same isolated home explicitly:
|
|
30
30
|
|
|
31
31
|
```sh
|
|
32
|
-
DSH_HOME="$PWD/.dev/dsh-home" "$PWD/.dev/runtime-0.2.
|
|
32
|
+
DSH_HOME="$PWD/.dev/dsh-home" "$PWD/.dev/runtime-0.2.1-alpha.2/node_modules/.bin/dsh" plugin --profile web exec dsh-auth-remote status --json
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
The development home contains test account data. Keep it private and do not commit or copy it into a deployment profile.
|
|
@@ -38,13 +38,15 @@ The development home contains test account data. Keep it private and do not comm
|
|
|
38
38
|
|
|
39
39
|
`pnpm test:unit` covers the auth state machine, TOTP, backup codes, origin policy, translations, storage durability and lock recovery. `pnpm test:integration` exercises real HTTP/WebSocket sockets, native readiness, cookies, origin decisions and revocation. `pnpm test:cli` builds the real archive and tests interactive and noninteractive commands against isolated profiles and Unix sockets. `pnpm test:browser` boots the selected DSH version with temporary profiles and verifies the login and Security UI, native settings, workspace, upload/preview, SSE, WebSocket and an HTTPS forwarding chain.
|
|
40
40
|
|
|
41
|
-
Browser network traffic uses a Node HTTP/HTTPS forwarder. The dedicated self-signed certificate and key under `tests/fixtures/tls/` are test fixtures only; they are never packaged or deployment credentials. Chat uses a local model stub. No real third-party authorization or paid model request is exercised. The default browser is Playwright Chromium; `DSH_TEST_BROWSER` can select a local browser executable, and `DSH_TEST_BIN` can select another binary only if it reports the exact selected version (default `0.2.
|
|
41
|
+
Browser network traffic uses a Node HTTP/HTTPS forwarder. The dedicated self-signed certificate and key under `tests/fixtures/tls/` are test fixtures only; they are never packaged or deployment credentials. Chat uses a local model stub. No real third-party authorization or paid model request is exercised. The default browser is Playwright Chromium; `DSH_TEST_BROWSER` can select a local browser executable, and `DSH_TEST_BIN` can select another binary only if it reports the exact selected version (default `0.2.1-alpha.2`).
|
|
42
42
|
|
|
43
43
|
The DSH test runtime lives in `.cache/test-runtime/<version>` and is pinned separately from the source dependencies. Host services and React remain external to the client bundle. The [deployment guide](deployment.md) describes profile and backup rules.
|
|
44
44
|
|
|
45
|
+
Before changing compatibility declarations or adaptations, read the [legacy compatibility inventory](legacy-compatibility.md) (Chinese maintenance document). Check runtime admission, test targets, CI and user claims together; remove exclusive runtime code and tests in the same change when its applicable versions leave support. Old plugin configuration follows its own migration policy. Keep shared security checks and update the inventory with exact-version evidence.
|
|
46
|
+
|
|
45
47
|
## Cross-version verification
|
|
46
48
|
|
|
47
|
-
The default test target is DSH `0.2.
|
|
49
|
+
The default test target is DSH `0.2.1-alpha.2`. Set `DSH_TEST_VERSION` to `0.1.7-rc.1`, `0.1.7-rc.2`, `0.2.0-rc.1`, `0.2.0-rc.2`, `0.2.1-alpha.1`, or `0.2.1-alpha.2`; test runtimes live separately under `.cache/test-runtime/<version>` and development runtimes under `.dev/runtime-<version>`. `DSH_TEST_BIN` must report the exact selected version. CI runs CLI, installation smoke and browser tests for all six versions. Development types and integration tests use the pinned alpha.2 packages. The source checkout test guide (`tests/README.md`) describes real Loader/model URL checks and native IPv6/TLS positive or unsupported-capability assertions; unavailable native test transport fails instead of skipping.
|
|
48
50
|
|
|
49
51
|
```sh
|
|
50
52
|
DSH_TEST_VERSION=0.1.7-rc.1 pnpm test:cli
|
|
@@ -53,6 +55,10 @@ DSH_TEST_VERSION=0.1.7-rc.2 pnpm test:cli
|
|
|
53
55
|
DSH_TEST_VERSION=0.1.7-rc.2 pnpm test:browser
|
|
54
56
|
DSH_TEST_VERSION=0.2.0-rc.1 pnpm test:cli
|
|
55
57
|
DSH_TEST_VERSION=0.2.0-rc.1 pnpm test:browser
|
|
58
|
+
DSH_TEST_VERSION=0.2.0-rc.2 pnpm test:cli
|
|
59
|
+
DSH_TEST_VERSION=0.2.0-rc.2 pnpm test:browser
|
|
60
|
+
DSH_TEST_VERSION=0.2.1-alpha.1 pnpm test:cli
|
|
61
|
+
DSH_TEST_VERSION=0.2.1-alpha.1 pnpm test:browser
|
|
56
62
|
pnpm test:cli
|
|
57
63
|
pnpm test:browser
|
|
58
64
|
```
|
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
[English](development.md)
|
|
4
4
|
|
|
5
|
-
开发和完整测试需要 Linux(profile 锁依赖 `/proc`)、Node.js 24+、pnpm 12.5.1,以及 DSH `0.2.
|
|
5
|
+
开发和完整测试需要 Linux(profile 锁依赖 `/proc`)、Node.js 24+、pnpm 12.5.1,以及 DSH `0.2.1-alpha.2`。浏览器测试使用 Playwright 管理的 Chromium 和 Node HTTP/HTTPS 转发器。
|
|
6
|
+
|
|
7
|
+
兼容声明或适配变更前,先阅读 [Legacy 兼容维护清单](legacy-compatibility.md)。共同复核运行时准入、测试目标、CI 和用户声明;适用版本退出支持集合时同次清理专属运行时代码及测试。旧插件配置按自身迁移策略退役,保留共享安全逻辑并用精确版本证据更新清单。
|
|
6
8
|
|
|
7
9
|
## 准备和检查源码检出
|
|
8
10
|
|
|
@@ -14,7 +16,7 @@ pnpm pack:local
|
|
|
14
16
|
pnpm smoke
|
|
15
17
|
```
|
|
16
18
|
|
|
17
|
-
`pnpm check` 依次执行类型、格式、构建、包/部署/文档检查,以及单元、集成、CLI 和浏览器测试。`pnpm pack:local` 在静态检查后写出 `artifacts/dsh-auth-remote-0.1.
|
|
19
|
+
`pnpm check` 依次执行类型、格式、构建、包/部署/文档检查,以及单元、集成、CLI 和浏览器测试。`pnpm pack:local` 在静态检查后写出 `artifacts/dsh-auth-remote-0.1.6.tgz`,不会发布。`pnpm smoke` 将包安装到隔离 DSH_HOME,短暂启动固定版本的 DSH,验证就绪、匿名重定向/拒绝和在线 CLI 状态,然后停止。
|
|
18
20
|
|
|
19
21
|
## 使用隔离开发 profile
|
|
20
22
|
|
|
@@ -29,7 +31,7 @@ pnpm dev:start
|
|
|
29
31
|
直接查看状态时显式使用同一隔离 home:
|
|
30
32
|
|
|
31
33
|
```sh
|
|
32
|
-
DSH_HOME="$PWD/.dev/dsh-home" "$PWD/.dev/runtime-0.2.
|
|
34
|
+
DSH_HOME="$PWD/.dev/dsh-home" "$PWD/.dev/runtime-0.2.1-alpha.2/node_modules/.bin/dsh" plugin --profile web exec dsh-auth-remote status --json
|
|
33
35
|
```
|
|
34
36
|
|
|
35
37
|
开发 home 可能含测试账号数据,须保持私有,不要提交或复制到部署 profile。
|
|
@@ -38,13 +40,13 @@ DSH_HOME="$PWD/.dev/dsh-home" "$PWD/.dev/runtime-0.2.0-rc.2/node_modules/.bin/ds
|
|
|
38
40
|
|
|
39
41
|
`pnpm test:unit` 覆盖认证状态机、TOTP、备用码、来源策略、翻译、存储持久性和锁恢复。`pnpm test:integration` 使用真实 HTTP/WebSocket socket 验证原生就绪、Cookie、来源判定与撤销。`pnpm test:cli` 构建真实压缩包,并用隔离 profile/Unix socket 验证交互与非交互命令。`pnpm test:browser` 用临时 profile 启动所选的 DSH 版本,验证登录、安全页、原生设置、工作区、上传/预览、SSE、WebSocket 和 HTTPS 转发链。
|
|
40
42
|
|
|
41
|
-
浏览器网络链路使用 Node HTTP/HTTPS 转发器。`tests/fixtures/tls/` 下的专用自签证书与私钥仅为测试夹具,不进入安装包,也不是部署凭证。聊天使用本地模型替身;不执行真实第三方授权或付费模型请求。默认浏览器为 Playwright Chromium;`DSH_TEST_BROWSER` 可选择本地浏览器程序,`DSH_TEST_BIN` 仅在报告所选精确版本(默认 `0.2.
|
|
43
|
+
浏览器网络链路使用 Node HTTP/HTTPS 转发器。`tests/fixtures/tls/` 下的专用自签证书与私钥仅为测试夹具,不进入安装包,也不是部署凭证。聊天使用本地模型替身;不执行真实第三方授权或付费模型请求。默认浏览器为 Playwright Chromium;`DSH_TEST_BROWSER` 可选择本地浏览器程序,`DSH_TEST_BIN` 仅在报告所选精确版本(默认 `0.2.1-alpha.2`)时可替换 DSH 二进制。
|
|
42
44
|
|
|
43
45
|
DSH 测试运行时位于 `.cache/test-runtime/<version>`,与源码依赖分别固定。宿主服务和 React 不打入客户端 bundle。[部署指南](deployment.zh-CN.md)说明 profile 与备份规则。
|
|
44
46
|
|
|
45
47
|
## 跨版本验证
|
|
46
48
|
|
|
47
|
-
默认测试 DSH `0.2.
|
|
49
|
+
默认测试 DSH `0.2.1-alpha.2`;`DSH_TEST_VERSION` 可选择 `0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1` 或 `0.2.1-alpha.2`,测试运行时分别位于 `.cache/test-runtime/<version>`,开发运行时位于 `.dev/runtime-<version>`。`DSH_TEST_BIN` 必须报告所选的精确版本。CI 对六版分别运行 CLI、安装冒烟和浏览器测试。开发类型和集成测试使用锁定的 alpha.2 包。源码检出目录的测试指南(`tests/README.zh-CN.md`)说明真实 Loader/模型地址核对,以及原生 IPv6/TLS 正向或不支持能力的断言;原生测试传输不可用时失败,不跳过。
|
|
48
50
|
|
|
49
51
|
```sh
|
|
50
52
|
DSH_TEST_VERSION=0.1.7-rc.1 pnpm test:cli
|
|
@@ -53,6 +55,10 @@ DSH_TEST_VERSION=0.1.7-rc.2 pnpm test:cli
|
|
|
53
55
|
DSH_TEST_VERSION=0.1.7-rc.2 pnpm test:browser
|
|
54
56
|
DSH_TEST_VERSION=0.2.0-rc.1 pnpm test:cli
|
|
55
57
|
DSH_TEST_VERSION=0.2.0-rc.1 pnpm test:browser
|
|
58
|
+
DSH_TEST_VERSION=0.2.0-rc.2 pnpm test:cli
|
|
59
|
+
DSH_TEST_VERSION=0.2.0-rc.2 pnpm test:browser
|
|
60
|
+
DSH_TEST_VERSION=0.2.1-alpha.1 pnpm test:cli
|
|
61
|
+
DSH_TEST_VERSION=0.2.1-alpha.1 pnpm test:browser
|
|
56
62
|
pnpm test:cli
|
|
57
63
|
pnpm test:browser
|
|
58
64
|
```
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Legacy 兼容维护清单
|
|
2
|
+
|
|
3
|
+
本清单是人工及本地 AI 修改兼容声明前的唯一维护入口,最后复核日期为 2026-10-10。用户配置指南仍使用中英文版本;不复制英文状态清单,不增加脚本或 CI 门禁。
|
|
4
|
+
|
|
5
|
+
## 复核与退役规则
|
|
6
|
+
|
|
7
|
+
修改 `package.json` 的 peers 或 `dsh.compatibility`、运行时准入范围、测试支持列表、CI 矩阵或用户兼容声明前,逐条读取本清单并检查新支持集合。
|
|
8
|
+
|
|
9
|
+
- `dsh-runtime`:适用版本与新支持集合仍有交集则保留;交集为空时,在修改声明的同一次变更删除专属实现、专属测试并更新清单和指南,不延后清理。共同安全校验和共享测试不属于删除范围。
|
|
10
|
+
- `plugin-contract`:按插件自身的迁移政策退役;DSH 支持范围收缩不触发退役。旧 `allowedOrigins` 单项和空数组兼容在 0.1.6 保留,只有未来明确结束旧配置支持时才能删除。
|
|
11
|
+
- 证据不足时保留实现,登记缺口和待复核版本,不编造退役阈值。未来版本的准入不等于经过兼容验证。
|
|
12
|
+
|
|
13
|
+
当前声明和测试目标为 `0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`;默认运行时为 alpha.2。声明和针对性验证不单独证明开发完成,交付须有同一最终产物的六版 CLI/browser/smoke 矩阵与审计确认。本清单维护长期适用范围和退役条件,具体交付证据由执行记录保存。
|
|
14
|
+
|
|
15
|
+
本次证据沿安装目录中的 DSH 包 → WebApp 包 → 实际依赖包解析,核对 manifest 精确版本;从测试目录直接解析子包可能误用仓库或祖先目录的其他版本。下列上游位置均指对应精确版本的安装包,不使用浮动主分支。
|
|
16
|
+
|
|
17
|
+
## DSH-HOST-001:旧监听 host/schema 适配
|
|
18
|
+
|
|
19
|
+
| 字段 | 内容 |
|
|
20
|
+
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
21
|
+
| 类型 / 生效状态 | `dsh-runtime` / 现存生效 |
|
|
22
|
+
| 适用 DSH | 前五版保留具体 IPv4/schema 适配;alpha.2 原生具体 IP 分支已接入 |
|
|
23
|
+
| 原因 | 五版 WebServer.Config 仅列 `127.0.0.1` 和 `0.0.0.0`;插件允许具体 IPv4,拒绝通配和非 IPv4,构造函数直接传递监听值 |
|
|
24
|
+
| 代码 / 上游证据 | `src/config.ts`、`src/adapters/dsh/webserver.ts`;对应包 `@deepseek-ai/dsh-host-webserver/lib/index.js` 的 Config 和 server.listen |
|
|
25
|
+
| 实现位置 | `src/adapters/dsh/runtime-capabilities.ts` 的旧具体 IPv4 分支及现代原生 Config 校验;生产入口在构造时使用统一 `resolveStartupConfig`,已删除过渡 resolver;GuardedWebServer 接收统一 NativeListenerConfig |
|
|
26
|
+
| 关联测试 | `tests/integration/dsh-adapter.test.ts`、`tests/integration/http-gate.test.ts`;`tests/unit/config.test.ts` 六版能力输入表;六个精确安装包 schema/能力已分别核对 |
|
|
27
|
+
| 客观退役条件 | 所有需要旧 schema 适配的 DSH 均退出支持集合,且精确包证据确认剩余版本具有原生具体 IP 校验 |
|
|
28
|
+
| 删除 / 调整范围 | 仅旧 IPv4/schema 分支与专属拒绝测试;保留通配拒绝、端口检查、身份/API 校验及共同门禁测试 |
|
|
29
|
+
| 最后复核依据 | 2026-10-10,前五版精确 schema 证据保留;alpha.2 真实 IPv4、IPv6、mapped/scoped loopback 和非回环 IPv4 监听通过;无可绑定的非回环 IPv6 接口,仅核对原生 schema 与策略,不据此扩大实测声明 |
|
|
30
|
+
|
|
31
|
+
## DSH-PROTOCOL-001:旧原生 HTTP 协议假设
|
|
32
|
+
|
|
33
|
+
| 字段 | 内容 |
|
|
34
|
+
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
35
|
+
| 类型 / 生效状态 | `dsh-runtime` / 旧版 HTTP 和回环 authority 回退保留;现代原生协议/地址桥接已接入 |
|
|
36
|
+
| 适用 DSH | 前五版没有 TLS/原生绑定 authority 识别;alpha.2 使用原生 protocol 和地址归一化 |
|
|
37
|
+
| 原因 | 前五版 startup 没有 TLS 配置且 Connection 不认识具体非回环 bind,继续使用服务端 HTTP/127.0.0.1 桥接;监听和公开 URL 仍为实际具体 IPv4。现代分支支持 IPv6/HTTPS |
|
|
38
|
+
| 代码 / 上游证据 | `src/adapters/dsh/readiness.ts`、`src/adapters/dsh/browser-auth.ts`、`src/adapters/dsh/startup-urls.ts`、`src/http/gate.ts`;对应 WebApp `lib/startup.js` |
|
|
39
|
+
| 实现位置 | `listenerProtocol`、`listenerTransport` 集中旧 HTTP/回环回退;现代回环使用原生 normalizeBindAddress/isLoopbackHost,非回环保留 Connection 绑定 authority 的 WHATWG IPv6 形式并去掉 zone;定稿 nativeAuthority/nativeOrigin 供 readiness 和 gate 共用;browser-auth 校验 token URL 协议和 Cookie Secure。外层 Cookie 按公开来源,原生 Cookie 按监听协议 |
|
|
40
|
+
| 关联测试 | `tests/integration/native-transport.test.ts`、`tests/browser/native-transport.spec.ts`、`tests/unit/config.test.ts`、既有 dsh-adapter / proxy-chain;包括旧非回环实际包、旧能力拒绝、两种协议方向代理和流撤销 |
|
|
41
|
+
| 客观退役条件 | 所有不提供原生监听协议能力的 DSH 均退出支持集合 |
|
|
42
|
+
| 删除 / 调整范围 | 仅能力适配器内旧 HTTP/回环回退与专属能力测试;保留 HTTP 正向、双向代理、Cookie 和撤销安全回归 |
|
|
43
|
+
| 最后复核依据 | 2026-10-10,rc.1 / alpha.1 真实包非回环绑定曾在统一改写真实 host 后无法激活;恢复旧回环桥接后可认证访问原生设置 API。alpha.2 真实 HTTPS/IPv6 MFA、Host 设置和 CLI 撤销通过;整分支审查发现非回环 mapped IPv6 经 WebServer 归一化后与 Connection 的绑定比较不一致,新增 HTTP/HTTPS、preserveOriginPaths 空数组的实际监听回归。完整六版产物证据由 CLI/browser/smoke 矩阵核对 |
|
|
44
|
+
|
|
45
|
+
## DSH-PUBLIC-001:旧宿主公开地址投影边界
|
|
46
|
+
|
|
47
|
+
| 字段 | 内容 |
|
|
48
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
49
|
+
| 类型 / 生效状态 | `dsh-runtime` / 上游能力差异现存;能力解析及插件投影已实现,三个能力组真实包验证通过 |
|
|
50
|
+
| 适用 DSH | 前四版无原生 publicUrl;alpha.1 支持,alpha.2 精确包已核实支持 |
|
|
51
|
+
| 原因 | 前四版没有 `--public-url`,提示和 `DSH_WEB_URL` 保持原生固定 `127.0.0.1` + 实际端口(无末尾斜杠)的行为;不能为旧宿主补造原生 CLI 参数 |
|
|
52
|
+
| 代码 / 上游证据 | [cordis.patch.yml](../cordis.patch.yml)、`src/adapters/dsh/startup-urls.ts`;对应 WebApp `lib/startup.js` 和 `lib/index.js` |
|
|
53
|
+
| 实现位置 | bundle 在 webStartup/webServer 可用后读取 `webServer.publicUrl` 只读属性,alpha.1/2 原生消费最终入口,旧版保留原生提示行为 |
|
|
54
|
+
| 关联测试 | `tests/browser/deployment-profile.spec.ts` 和 `startup-compatibility.spec.ts`;profile 根目录只读 startup-observer 调用原生 systemPrompt.assemble 和 shellEnv.collect,核对 Web 提示与 DSH_WEB_URL,同一最终地址且无 token;三个能力组真实包验证 |
|
|
55
|
+
| 客观退役条件 | 所有缺少原生 publicUrl 的 DSH 均退出支持集合 |
|
|
56
|
+
| 删除 / 调整范围 | 仅旧版能力分支、原生提示差异和不支持 CLI 参数的专属测试;保留插件唯一入口、来源准入与启动输出测试 |
|
|
57
|
+
| 最后复核依据 | 2026-10-09,四版精确 startup 无 publicUrl,alpha.1 有该字段;不得伪造旧版支持 |
|
|
58
|
+
|
|
59
|
+
## DSH-THEME-001:旧主题 token fallback
|
|
60
|
+
|
|
61
|
+
| 字段 | 内容 |
|
|
62
|
+
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
63
|
+
| 类型 / 生效状态 | `dsh-runtime` / 现存生效 |
|
|
64
|
+
| 适用 DSH | `0.1.7-rc.1` 缺少 radius-md、radius-lg、focus-ring-color;其他五个已声明版本已提供 |
|
|
65
|
+
| 原因 | Security 样式需在最旧支持版本保持圆角和键盘焦点可见性 |
|
|
66
|
+
| 代码 / 上游证据 | `src/client/settings/style.css`;精确 `@deepseek-ai/dsh-client-ui-theme/lib` 中 CSS token 定义 |
|
|
67
|
+
| 实现位置 | `var(--dsw-radius-md, ...)`、`var(--dsw-radius-lg, 16px)`、focus-ring 的 business-primary fallback |
|
|
68
|
+
| 关联测试 | `tests/browser/dsh-bootstrap.spec.ts` 的主题与布局;各版本截图人工复核 |
|
|
69
|
+
| 客观退役条件 | `0.1.7-rc.1` 退出支持集合,并确认其余支持版本都有上述 token |
|
|
70
|
+
| 删除 / 调整范围 | 仅上述 var 的 fallback 参数和专属旧主题说明;保留宿主动态主题、布局与共享视觉回归 |
|
|
71
|
+
| 最后复核依据 | 2026-10-09,五版精确 theme 包 CSS 搜索:rc.1 缺少,rc.2 起均存在;alpha.2 精确 theme 包三个 lib JS 文件的 token 定义均存在 |
|
|
72
|
+
|
|
73
|
+
## DSH-TEST-001:旧宿主 onboarding 交互
|
|
74
|
+
|
|
75
|
+
| 字段 | 内容 |
|
|
76
|
+
| --------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| 类型 / 生效状态 | `dsh-runtime` / 现存生效,精确适用范围有证据缺口 |
|
|
78
|
+
| 适用 DSH | 六版共享测试 helper;具体 notice 名称、首次保存重载与设置页关闭行为的版本范围待真实 UI 复核 |
|
|
79
|
+
| 原因 | 宿主启动 notice/API Key 提示可能延迟出现;首次保存可能重载页面并关闭设置 |
|
|
80
|
+
| 代码 / 上游证据 | `tests/helpers/runtime.ts` 的注释和实际交互;不能只由源码字符串推定 UI 生命周期 |
|
|
81
|
+
| 实现位置 | `completeApiKeyPrompt`、`clickThroughDshPrompts` 中 notice 名称与 reopen 处理 |
|
|
82
|
+
| 关联测试 | `tests/browser/dsh-bootstrap.spec.ts`、`tests/browser/dsh-gate.spec.ts` |
|
|
83
|
+
| 客观退役条件 | 真实 UI 复核得到精确适用版本后,交集为空才能删除专属交互;证据缺口未补齐时不得退役 |
|
|
84
|
+
| 删除 / 调整范围 | 仅经证明确属旧宿主的 notice/reload 分支;通用异步 UI 重试、主题持久化等待和浏览器 fallback 不自动归类为 legacy |
|
|
85
|
+
| 最后复核依据 | 2026-10-10,六版完整浏览器矩阵均使用共享 helper 并通过;各项 notice/reload 适配的精确适用范围仍须独立 UI 复核 |
|
|
86
|
+
|
|
87
|
+
## PLUGIN-CONFIG-001:旧 allowedOrigins 配置迁移
|
|
88
|
+
|
|
89
|
+
| 字段 | 内容 |
|
|
90
|
+
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
91
|
+
| 类型 / 生效状态 | `plugin-contract` / 旧数组配置现存;0.1.6 内存迁移及监听后单入口定稿已生效 |
|
|
92
|
+
| 适用契约 | 0.1.5 的顶层 `allowedOrigins`;与 DSH 版本集合无关 |
|
|
93
|
+
| 原因 | 0.1.6 迁移到唯一顶层 `publicUrl`,保留旧单项和空数组输入,不改写 profile |
|
|
94
|
+
| 代码 / 上游证据 | `src/config.ts`、[cordis.patch.yml](../cordis.patch.yml);插件自身配置契约 |
|
|
95
|
+
| 实现位置 | schema 用 undefined union 取消 Schemastery 数组默认值;bundle 无旧数组默认;`resolveStartupConfig` 检查显式互斥并内存转换,`finalizeAuthConfig` 用实际 port 生成唯一策略,旧 resolver 已删除 |
|
|
96
|
+
| 关联测试 | `tests/unit/origin-policy.test.ts`、`tests/integration/http-gate.test.ts`;`tests/unit/config.test.ts` 配置解析;startup-compatibility 真实 Loader 验证旧 0/1 项、重复/不同多项、显式 null、新旧 file/CLI 冲突、一次警告和 profile 不改写 |
|
|
97
|
+
| 客观退役条件 | 未来产品契约明确结束旧插件配置支持,并提供迁移说明;DSH 版本收缩不触发 |
|
|
98
|
+
| 删除 / 调整范围 | 仅旧输入检测、0/1 项转换、弃用提示和专属迁移测试;保留唯一 URL 验证、来源策略和安全回归 |
|
|
99
|
+
| 最后复核依据 | 2026-10-09,0.1.5 当前源码;计划保留 0/1 项,多项及任一显式新旧共存报错,每次激活仅一次提示 |
|
|
100
|
+
|
|
101
|
+
## 共享安全边界
|
|
102
|
+
|
|
103
|
+
包身份、未来准入后的 API 检查、具体绑定、原始 Host/Origin/Fetch Metadata、回环准入、密码/TOTP、会话、流撤销、存储故障和 CLI 确认是共享安全逻辑,不随某个 runtime 分支退役。反向代理 HTTPS→HTTP、客户端通用浏览器 fallback 也不是可自动删除的旧 DSH 专属功能。
|
|
104
|
+
|
|
105
|
+
后续实施须将“待实现”更新成实际位置与测试。组合修复已将 Connection 改为依赖 webStartup/webServer,删除 web-runtime 的过时 trustedHosts 转发;`tests/browser/startup-compatibility.spec.ts` 在 alpha.2 原补丁复现 required Connection 等待 webRuntime 的审计失败。不得通过伪造服务、关闭启动审计或放开原生 listener 完成。alpha.1/2 的 startup-compatibility 与 dsh-gate 各 4/4 通过;类型、单元 38/38、集成 29/29 通过。仍不代表新配置、TLS/IPv6 或最终六版矩阵已完成。
|
|
106
|
+
|
|
107
|
+
2026-10-09 任务 3 复核:DSH 开发依赖均升级 alpha.2,Cordis/Schemastery 范围不变。新增 public-url / runtime-capabilities 及配置解析测试,六版真实安装锚点的 WebServer 版本和能力校验均通过。任务 3 曾保留 resolver 过渡路径,任务 4 已删除;当前生产入口仅使用统一启动前解析与监听后定稿,不并行维护两套来源规则。
|
|
108
|
+
|
|
109
|
+
2026-10-10 任务 4 复核:DenyGate 下原生监听后定稿,ready 与 AuthGate 共用唯一来源策略;启动输出使用实际端口并去重。Connection 正常丢失时撤回 ready,桥接预检失败由官方 fiber 释放 listener/admin/存储锁。多来源传输回归拆成独立单入口,保留 HTTP/HTTPS、默认端口、IP、回环、Cookie、头和升级拒绝断言。真实 Loader 旧字段每次激活一次弃用提示且不改写文件;安装包仅在隔离目录测试。
|
|
110
|
+
|
|
111
|
+
任务 4 补证:三个能力组 startup/deployment 各 9/9 通过,alpha.2 dsh-gate 3/3;类型、52 项单元、34 项集成与包验证通过。四个旧 WebApp 的 `localWebUrl` 都使用固定 LOOPBACK_HOST,不能把其模型侧地址误写成插件真实 bind IP。文件、CLI 及旧迁移的插件入口仍按实际生效值;未改写旧版原生注册。显式 null 的 host/port/TLS 不再被当作缺省,证书整组 CLI 覆盖仍优先。
|
|
112
|
+
|
|
113
|
+
2026-10-10 任务 5 复核:旧 HTTP/回环桥接集中在 runtime-capabilities;现代桥接使用原生协议和归一化 authority,zone 不进入便携公开 URL。静态检查、55 项单元、45 项集成通过;alpha.2 原生传输和既有代理浏览器 9/9,rc.1/alpha.1 旧能力拒绝与具体非回环 IPv4 真实包各 4/4,无跳过。TLS 材料错误、Connection 丢失和存储通知故障关闭入口;外层和原生 Cookie 协议独立验证。上述证据来自 0.1.5 开发包;开发包证据不能替代最终 0.1.6 全六版验证。
|
|
114
|
+
|
|
115
|
+
2026-10-10 任务 6 复核:默认测试/开发运行时为 alpha.2,两个既有 CI 矩阵覆盖六版;release 沿用共同默认。原生 systemPrompt Web section 与 DSH_WEB_URL 的最终地址相同且无 token。rc.1/alpha.1/alpha.2 的真实 startup/deployment/native-transport/admin CLI 分别 29/29、29/29、33/33,无跳过;旧多项、重复项、null 及新旧冲突均经过 Loader。静态、55 项单元、45 项集成通过。alpha.2 的最终 0.1.6 六版全量交付另需最终产物证据;onboarding 精确适用范围缺口继续保留。
|
package/docs/releasing.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
Each release starts from a tested commit on `master`. A `vX.Y.Z` tag must match the stable version in `package.json` and the dated entries in both changelogs. The tag workflow repeats the full checks, builds the npm archive, verifies or publishes the npm version, and creates a GitHub Release containing the same archive and `SHA256SUMS`.
|
|
6
6
|
|
|
7
|
+
Before changing version support for a release, review the [legacy compatibility inventory](legacy-compatibility.md) (Chinese maintenance document). Check peers, compatibility declarations, runtime admission, test targets, CI and guides together. Remove runtime adaptations whose applicable versions no longer intersect support in that same change, while keeping shared security checks. Old plugin configuration has independent retirement conditions; update the inventory before packing.
|
|
8
|
+
|
|
7
9
|
## Prepare the version
|
|
8
10
|
|
|
9
11
|
Update `package.json` to `X.Y.Z`, move user-visible changes from Unreleased into `## X.Y.Z - YYYY-MM-DD` in both changelogs, and update any versioned installation examples. Open a pull request, let `CI Verify` pass, merge it, and wait for the `master` check to pass. Do not tag a commit whose checks are still running.
|
|
@@ -27,18 +29,18 @@ Use the version that is already on `master`:
|
|
|
27
29
|
```sh
|
|
28
30
|
git switch master
|
|
29
31
|
git pull --ff-only origin master
|
|
30
|
-
git tag -a v0.1.
|
|
31
|
-
git push origin v0.1.
|
|
32
|
+
git tag -a v0.1.6 -m "Release v0.1.6"
|
|
33
|
+
git push origin v0.1.6
|
|
32
34
|
```
|
|
33
35
|
|
|
34
|
-
Replace `0.1.
|
|
36
|
+
Replace `0.1.6` in these commands with the intended version. The tag must point to a commit reachable from `master`. A mismatched tag, missing changelog entry, failed test, or mismatched existing npm archive stops the release.
|
|
35
37
|
|
|
36
38
|
After the workflow completes, confirm the run, GitHub Release, and npm version:
|
|
37
39
|
|
|
38
40
|
```sh
|
|
39
41
|
gh run list --workflow release.yml --limit 5
|
|
40
|
-
gh release view v0.1.
|
|
41
|
-
npm view dsh-auth-remote@0.1.
|
|
42
|
+
gh release view v0.1.6
|
|
43
|
+
npm view dsh-auth-remote@0.1.6 version dist.integrity
|
|
42
44
|
```
|
|
43
45
|
|
|
44
46
|
The GitHub Release includes the `.tgz` and `SHA256SUMS`. Download them into the same directory and run `sha256sum -c SHA256SUMS` there to check the release asset. A failed workflow should be inspected in **Actions → Release** before retrying; npm versions are immutable, so the workflow only skips an existing version when its archive bytes match.
|
package/docs/releasing.zh-CN.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
每次发布都从已通过检查的 `master` 提交开始。`vX.Y.Z` 标签必须与 `package.json` 中的稳定版本以及两份更新日志的日期条目一致。标签工作流会再次执行完整检查、构建 npm 压缩包、核对或发布 npm 版本,并创建包含相同压缩包和 `SHA256SUMS` 的 GitHub Release。
|
|
6
6
|
|
|
7
|
+
发布准备中修改支持版本前,先复核 [Legacy 兼容维护清单](legacy-compatibility.md),共同检查 peers、兼容声明、运行时准入、测试目标、CI 和指南。同次删除与支持集合无交集的专属运行时适配,保留共享安全逻辑;旧插件配置退役有独立条件。打包前更新并人工核对清单。
|
|
8
|
+
|
|
7
9
|
## 准备版本
|
|
8
10
|
|
|
9
11
|
将 `package.json` 更新为 `X.Y.Z`,把两份更新日志中用户可见的“未发布”变更移入 `## X.Y.Z - YYYY-MM-DD`,同时更新带版本号的安装示例。创建 Pull Request,等待 `CI Verify` 通过,合入后再等待 `master` 检查通过。检查尚未结束时不要打标签。
|
|
@@ -27,18 +29,18 @@ pnpm smoke:packed
|
|
|
27
29
|
```sh
|
|
28
30
|
git switch master
|
|
29
31
|
git pull --ff-only origin master
|
|
30
|
-
git tag -a v0.1.
|
|
31
|
-
git push origin v0.1.
|
|
32
|
+
git tag -a v0.1.6 -m "Release v0.1.6"
|
|
33
|
+
git push origin v0.1.6
|
|
32
34
|
```
|
|
33
35
|
|
|
34
|
-
执行时把 `0.1.
|
|
36
|
+
执行时把 `0.1.6` 换成目标版本。标签必须指向 `master` 可达的提交。标签版本不匹配、缺少更新日志条目、测试失败,或 npm 现存版本与本次压缩包字节不同,都会阻止发布。
|
|
35
37
|
|
|
36
38
|
工作流结束后检查运行状态、GitHub Release 和 npm 版本:
|
|
37
39
|
|
|
38
40
|
```sh
|
|
39
41
|
gh run list --workflow release.yml --limit 5
|
|
40
|
-
gh release view v0.1.
|
|
41
|
-
npm view dsh-auth-remote@0.1.
|
|
42
|
+
gh release view v0.1.6
|
|
43
|
+
npm view dsh-auth-remote@0.1.6 version dist.integrity
|
|
42
44
|
```
|
|
43
45
|
|
|
44
46
|
GitHub Release 包含 `.tgz` 和 `SHA256SUMS`。把两者下载到同一个目录,在该目录运行 `sha256sum -c SHA256SUMS` 验证附件。工作流失败时先查看 **Actions → Release** 再重试;npm 版本不可覆盖,因此只有现存版本的压缩包字节与本次构建一致时,工作流才会跳过重复发布。
|
package/docs/reverse-proxy.md
CHANGED
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
[简体中文](reverse-proxy.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
DSH Auth Remote validates the browser authority before rewriting authenticated traffic for DSH.
|
|
5
|
+
DSH Auth Remote validates the browser authority before rewriting authenticated traffic for DSH. Select one HTTP(S) root and set it as `publicUrl`, for example `https://dsh.example.com/`. It configures admission and advertised entry, without changing proxy routing or TLS. The bridge needs no extra Connection row or `--trusted-host`. TLS may terminate at a proxy while DSH listens on private HTTP.
|
|
6
6
|
|
|
7
7
|
## Direct loopback
|
|
8
8
|
|
|
9
|
-
With the [profile example](../examples/web-profile-auth-remote.patch.yml), DSH binds `127.0.0.1:13090`. A browser on the same host may use `http://127.0.0.1:13090
|
|
9
|
+
With the [profile example](../examples/web-profile-auth-remote.patch.yml), DSH binds `127.0.0.1:13090`. A browser on the same host may use `http://127.0.0.1:13090/`. Literal `localhost`, canonical `127.0.0.0/8` and bracketed `::1` are implicitly allowed when the actual listener is reachable. An IPv4-mapped IPv6 loopback origin is admitted when it is the effective `publicUrl`, either configured explicitly or derived from the listener. For an alpha.2 IPv6 HTTP or HTTPS listener, follow the [native transport configuration](deployment.md#native-https-and-ipv6). The auth bundle disables the native `webserver` row; an independent profile disable is recommended.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Admission is the unique effective public origin plus literal loopback. Without a public URL, derive one root from the actual bound protocol, address and port. Root paths only are supported; no child path, query, fragment or credentials. Mutations and WebSocket upgrades need Origin matching their Host; extra CLI native trusted hosts do not widen this policy. A GET without Origin cannot set or clear auth cookies when its protocol is unknown. See the [old-field migration rules](deployment.md#migrate-old-allowedorigins) before changing a legacy array.
|
|
12
12
|
|
|
13
13
|
## Nginx with external TLS
|
|
14
14
|
|
|
@@ -16,12 +16,14 @@ Copy [the Nginx example](../examples/nginx.conf) into an `http {}` context. Repl
|
|
|
16
16
|
|
|
17
17
|
Use `$http_host` for the original Host including a nondefault port and `$http_origin` for the actual Origin. Nginx must explicitly forward `Upgrade` and a mapped `Connection` header for WebSockets. HTTP/1.1 upstream, disabled response buffering/cache, disabled request buffering, and long read/send timeouts keep event streams, uploads and long connections working. Do not replace Origin with the upstream URL or omit it on browser mutations. The proxy should not cache login, status or authenticated responses.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Set `publicUrl: https://dsh.example.com/` for the example. For a public `:8443` listener, use `https://dsh.example.com:8443/` and preserve that port in Host. Plugin Secure cookies follow the validated external HTTPS origin, not the private HTTP socket or a forwarded-protocol hint. Add a path to `preserveOriginPaths` only when it needs the original public Host; native Connection trust then follows the final origin automatically.
|
|
20
20
|
|
|
21
21
|
## Traefik with external TLS
|
|
22
22
|
|
|
23
23
|
[The Traefik file-provider example](../examples/traefik-dsh.yml) defines one Host router, a replaceable TLS resolver and upstream URL, `passHostHeader: true`, and immediate response flushing. Supply a private reachable upstream for the chosen Traefik network setup. The example intentionally has no middleware that strips Origin, rewrites Host or caches responses. Keep WebSocket and stream forwarding enabled in the surrounding proxy stack.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
Use one canonical public entry; route alternate hostnames to it before requests reach the protected upstream. Replace `publicUrl` and restart after an entry change, then verify the new root and rejection of the former non-loopback origin. Check anonymous redirect/API denial, password plus TOTP login, cookies, Settings, WebSocket, SSE, uploads, previews and revocation. Keep access private until `/auth-remote/ready` reports the expected plugin/protocol and `ready: true`.
|
|
26
|
+
|
|
27
|
+
An alpha.2 native HTTPS upstream also works behind a public HTTP or HTTPS proxy. Use an HTTPS upstream URL and configure the proxy's upstream certificate verification and hostname/SNI for that certificate. Plugin cookies follow the external entry's protocol; server-side native cookies use the listener's HTTPS audience/Secure. Preserve Host/Origin even when the two transport protocols differ. Relative file/CLI certificate paths have different bases; see the [path rules](deployment.md#configuration-priority-and-path-bases).
|
|
26
28
|
|
|
27
29
|
The authentication gate ignores `Forwarded` and `X-Forwarded-*` for trust decisions. This avoids treating a client-supplied hint as proof of TLS or hostname. The source checkout's browser suite tests these rules with its own Node HTTP/HTTPS forwarder; it does not execute Nginx or Traefik binaries.
|