@qipenglin/dsh-web-access

Readme

# @qipenglin/dsh-web-access

中文 | [English](README.en.md)

为 DeepSeek Harness Web profile 提供可选的本机 token 与 Cookie 访问认证。当前版本只兼容官方 DSH `0.1.1-rc.2`。

## 安装

```sh
dsh plugin --profile web add github:qipenglin/dsh-web-access
dsh web
```

该命令直接从 GitHub 仓库的默认分支安装插件。仓库已包含经过验证的 `lib` 产物，安装过程无需执行构建脚本。安装完成后必须重启 Web Profile，旧进程不会自动启用认证。

重启后，`dsh web` 只输出一条包含 fragment token 的链接：

```text
dsh web: http://localhost:3080/#token=<random-token>
```

请使用完整链接首次打开页面。浏览器会在第一次异步操作前清除地址栏 fragment，以 Bearer token 换取 host-only、HttpOnly、SameSite=Strict 的会话 Cookie，然后启动 DSH Connection。以后可在同一浏览器会话中打开不带 token 的裸地址。

## 安全行为

- WebServer 必须绑定 `127.0.0.1`；安装插件后使用 `--host 0.0.0.0` 会拒绝启动。
- 静态 HTML、shell 资源、boot manifest、`/plugins` Client bundle 和 `/plugins/events` HMR graph 元数据保持公开，使浏览器启动可与认证并行执行。
- 匿名 `/api`、自定义 Connection RPC channel 和两条 Connection WebSocket 下行链路均返回 `401`。
- Host、Origin 或 Fetch Metadata 不匹配返回 `403`。
- query token、WebSocket subprotocol token、重复目标 Cookie 和重复 Authorization 会被拒绝。
- 每次进程启动都会生成新的 token、Cookie 名和会话 secret；旧 Cookie 在重启后失效。
- token 不写入 Cookie、Web Storage、history state、`DSH_WEB_URL` 或模型上下文。

插件只保护本机 Web profile。它不是远程身份系统，也不支持局域网或公网部署。

## 卸载

```sh
dsh plugin --profile web remove @qipenglin/dsh-web-access
dsh web
```

卸载并重启后，Web profile 恢复官方 `0.1.1-rc.2` 的无认证行为。安装后若版本检查、绑定或装配失败，profile 会直接启动失败，不会在同一次启动中自动降级为无认证服务。

## 桌面端集成

Host 侧公开 `ctx.webAccess`：

```ts
interface WebAccess {
  readonly origin: string
  readonly interactiveUrl: string
  readonly accessToken: string
  authorize(request: WebAccessRequest): WebAccessDecision
}
```

未来桌面 runtime 可以选择读取该服务，并在原生 WebView 外完成 Cookie bootstrap。未安装插件时服务不存在，是否退化为裸 loopback 服务由桌面 runtime 决定。

## 开发与发布检查

需要 Node `^22.19.0 || >=24.0.0` 和 pnpm `11.7.0`：

```sh
pnpm install --frozen-lockfile
pnpm test
pnpm run test:coverage
pnpm run test:installed
pnpm run typecheck
pnpm run lint
pnpm run pack:check
```

`pnpm run pack:check` 会清空并重建 `dist/`，其中只保留已校验的 `dist/qipenglin-dsh-web-access-0.1.3.tgz`。

`test:installed` 会把生成的 tarball 安装到隔离的官方 rc.2 Web profile，验证 HTTP、WebSocket、重启失效和卸载恢复行为。

## 许可证

[MIT](LICENSE)