dsh-auth

Readme

# dsh-auth

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI 的 Cookie 鉴权 bundle，遵循官方 [Web UI 快速入门](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) 与 [插件打包/安装约定](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)。它提供：

- 绑定回环、`0.0.0.0` 或指定 IPv4 地址；
- 从 `$DSH_HOME/token`（默认 `~/.dsh/token`）读取专用访问 token；
- token 不存在时生成 32 字节随机值并以 `0600` 保存；
- 内置 token 登录页，成功后写入 `HttpOnly; SameSite=Strict` Cookie；
- 在分发前统一保护 SPA、HTTP API 和 WebSocket upgrade；
- 登录后开放 Harness 的远程管理 API，并在交给下游前移除 auth Cookie；
- 为明文 LAN 来源补充基于 `crypto.getRandomValues()` 的 UUID v4 兼容层；
- 退出登录与全局 token 轮换。

本插件不会读取或复用 `~/.dsh/.credentials.yaml` 中的模型 API 密钥。

## 为什么替换 Web 宿主

DeepSeek Harness `0.1.0-rc.6` 的 `webServer` 只提供具名 route、upgrade route 和一个 SPA fallback，没有 HTTP middleware。旁挂一个 `/login` route 无法保护已有 `/api`、静态管理端或 WebSocket。

`dsh-auth` 因此以 bundle 的形式禁用内置 `webserver` 行，插入一个提供相同 `webServer` 服务面的认证宿主。现有 connection、modules、HMR 与 frontend-static 插件无需修改。

## 要求

- Node.js 22+
- DeepSeek Harness `0.1.0-rc.6`（开发者预览版迭代很快，升级后请重新运行测试）
- `pnpm` 位于 `PATH`（`dsh plugin` 会调用它；Corepack 用户可先运行 `corepack enable pnpm`）

## 构建与安装

推荐用 tarball 安装，避免 profile 链接到开发目录：

```sh
cd /path/to/dsh-auth
npm install
npm test
npm pack
dsh plugin --profile web add ./dsh-auth-0.1.0.tgz
```

验证组合层：

```sh
dsh web --dump-config
```

输出中应同时看到禁用的 `webserver` 和新增的 `auth-webserver`。

卸载：

```sh
dsh plugin --profile web remove dsh-auth
```

## 使用

本机访问：

```sh
dsh web
```

打开命令打印的 URL。若 `~/.dsh/token` 原先不存在，插件会自动创建。登录 token 可从该文件读取：

```sh
cat ~/.dsh/token
```

`DSH_HOME` 自定义时，token 位于对应目录的 `token` 文件。

### 绑定远程 IPv4

绑定所有 IPv4 网卡：

```sh
DSH_AUTH_HOST=0.0.0.0 dsh web
```

当前 Harness `rc.6` 的内置 Web 启动参数会主动拒绝 `--host 0.0.0.0`，所以该地址必须通过 `DSH_AUTH_HOST` 提供。指定某张网卡也可以：

```sh
DSH_AUTH_HOST=192.168.1.20 dsh web
```

随后访问 `http://192.168.1.20:3080`。`host` 必须是 IPv4 字面量，不接受主机名。

浏览器不会在非回环的明文 HTTP 来源暴露 `crypto.randomUUID()`，但 Harness
客户端会直接调用它。认证宿主会在客户端 bundle 之前注入一个基于
`crypto.getRandomValues()` 的 UUID v4 兼容实现；原生方法存在时不会覆盖。
这只修复 API 兼容性，不会把 HTTP 变成安全上下文，也不替代 HTTPS。

### HTTPS 与 Secure Cookie

直接绑定 LAN 时仍是明文 HTTP，token 会随 Cookie 在网络中传输。跨不可信网络使用时，应让 dsh 只绑定回环地址，并在前方配置 HTTPS 反向代理。HTTPS 已就绪后再启用：

```sh
DSH_AUTH_SECURE_COOKIE=true dsh web
```

不要在直接访问 `http://...` 时开启它；浏览器不会回传带 `Secure` 的 Cookie。

## 配置

bundle 暴露以下环境变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `DSH_AUTH_HOST` | `127.0.0.1` | IPv4 监听地址；优先于 `dsh web --host` |
| `DSH_AUTH_TOKEN_FILE` | `$DSH_HOME/token` | 专用 token 文件 |
| `DSH_AUTH_SECURE_COOKIE` | `false` | 只有精确值 `true` 才添加 `Secure` |

如需修改其他字段，在 `$DSH_HOME/profiles/web/cordis.patch.yml` 中完整重述配置。Harness patch 会整体替换 `config`，不会逐键深度合并：

```yaml
- id: auth-webserver
  config:
    host: 127.0.0.1
    port: 3080
    tokenFile: !!js dshHomePath('token')
    cookieName: dsh_auth
    cookieMaxAgeSeconds: 2592000
    secureCookie: false
    authPath: /auth
    apiPath: /api
    authorizeRemoteApi: true
    maxLoginBodyBytes: 4096
    protectTokenFile: true
```

`authorizeRemoteApi: true` 表示：Cookie 已通过恒定时间比较后，把 `/api` 请求交给 Harness 时按本机可信请求处理。这替代了上游在“尚无真实认证”情况下对设置与凭据方法保留的 loopback-only 占位栅栏。关闭该项会保留上游限制，远程登录者将无法使用部分管理功能。

## Token 与会话语义

- token 文件会去掉首尾空白；空 token、控制字符或超过 4096 字节会使插件启动失败。
- POSIX 上已有 token 文件会被收紧为 `0600`；符号链接和非普通文件会被拒绝。
- Cookie 直接携带 percent-encoded token，只对当前 Host 生效，并始终带 `HttpOnly`、`SameSite=Strict` 和 `Path=/`。
- 退出登录只清除当前浏览器 Cookie。要撤销所有浏览器，替换 token 文件并重启 `dsh web`。
- 登录页为 `/auth/login`，退出地址为 `/auth/logout`。登录与未授权响应均为 `Cache-Control: no-store`。

## 开发验证

```sh
npm test
npm run typecheck
npm pack --dry-run
```

测试覆盖 token 生成/复用与权限、跳转清洗、Cookie 登录/退出、SPA/API 鉴权、远程 API 信任转换、auth Cookie 下游隔离、upgrade 鉴权、配置拒绝和生命周期清理。

## 安全边界

- 这是单一共享 token，不是多用户、权限分级或审计系统。
- 插件不终止 TLS；公网使用必须配置 HTTPS 反向代理和网络访问控制。
- Harness 本身可执行命令和修改文件。即使有 token，也只应暴露给受信任用户和网络。

## License

MIT