API 网关插件litestartup-com/dsh-api-gateway

dsh-api-gateway

DeepSeek Harness 宿主插件：一个带鉴权、fail-closed 的 loopback 反向代理，把宿主机自身的
/api 面（apiproxy = dsh-client-connection + dsh-host-apiproxy）暴露给另一台机器上的客户端
（典型：dsh-agent-manager）。

v0.2.0 起（S3）：插件不再自己驱动 agent。会话、消息、问答、授权全部由宿主的 apiproxy 处理，
插件只做三件事：鉴权、白名单、透传。

为什么需要它

DSH 的 /api 只认 loopback（Host 头栅栏不是鉴权，跨机直连 :3080 不可行也不安全）。
本插件跑在 DSH 进程内，内部 fetch 天然走 loopback，对外靠 API Key 鉴权 + 白名单保护。

安装

dsh plugin --profile web add github:litestartup-com/dsh-api-gateway

在宿主组合加一行（见 examples/cordis.yml），重启 DSH。

配置

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| prefix | /api-gw/v1 | 路由前缀 |
| enabled | true | 主开关（可 admin 运行时切换） |
| apiKeys | [] | 静态 API 密钥 |
| provisionedKey | — | POST {prefix}/key 一次性自助发放的密钥（存 settings） |
| allowKeyProvision | true | 允许首次无钥自助发放 |
| adminKey | — | 设置后启用 admin 端点 |
| corsOrigin |  | CORS 来源（'' 或具体域/数组） |
| exposeErrors | true | 错误响应是否带内部细节 |
| proxyTarget | http://127.0.0.1:3080/api | 上游 /api 基础地址 |
| proxyWhitelist | 默认白名单 | 可选：覆盖默认白名单 |

端点

| 方法 | 路径 | 鉴权 |
| --- | --- | --- |
| GET | {prefix}/health | 无 |
| POST | {prefix}/key | 首次无钥（一次性自助发放） |
| POST | {prefix}/admin/enable | X-Admin-Key |
| POST | {prefix}/admin/rotate-key | X-Admin-Key |
| POST | {prefix}/proxy/ | X-API-Key / Bearer |
| POST | {prefix}/proxy/respond | X-API-Key / Bearer |
| POST | {prefix}/sessions/{id}/sandbox-mode | X-API-Key / Bearer |
| GET | {prefix}/events.mux（WebSocket 升级） | X-API-Key |

sessions/{id}/sandbox-mode：请求体 { "mode": "read-only" | "workspace-write" }，给活会话写一个
sandbox/mode 覆盖事件（dsh-sandbox-policy/session-mode，持久、冷醒 replay 恢复）。冷/失联会话 → 409
session_not_live；danger-full-access 不可经 wire 授予（宿主 UI 专属）。这是 wire 上唯一能按会话设置
沙箱模式的通道（session.create 无沙箱字段），供 manager 在创建会话后、首次 prompt 前调用一次。

同一 mux 升级路径也注册在 {prefix}/proxy/events.mux，使客户端「base + method」的统一约定
（manager 的 rpc base 即 /api-gw/v1/proxy）无需为 mux 特判。

mux 管道下行只读：客户端发任何帧都被 1008 关闭（与宿主 mux 行为一致）。断线重连是客户端的事。

白名单（默认）

session.list, session.create, session.history,
session.prompt, session.cancel, session.rename,
session.fork, session.updateQueue, session.attachment,
session.models, session.selectModel,
respond,  host.describe

白名单外 → 403 { error: 'method_not_allowed' }，不发往上游。特权面
（credentials.、settings.、host.openPath、host.pickDirectory、llm.discoverModels 等）
在代理上不可达。注意：真实方法名是 host.describe（host.version 不存在）。

安全模型

- 鉴权不可退化：constant-time 比较、CSPRNG 密钥、一次性自助发放（已有任何密钥即永久关闭）。
- 白名单 fail-closed；代理不解析 RPC 包络，只按路径段校验方法名，字节透传。
- 密钥绝不写日志；apiKeys/adminKey 在 settings 线上 surface 脱敏。

部署步骤

1. 构建并提交：pnpm build && pnpm test（42 测试全绿；lib/ 必须同步提交）。
2. 更新宿主安装：dsh plugin update（或 profiles/web 下 pnpm install）。
3. 重启 DSH。
4. 跑验收（见下）。

验收步骤

1. GET {prefix}/health → 200，upstream: ok。
2. POST {prefix}/proxy/credentials.set（带正确 key）→ 403 method_not_allowed。
3. POST {prefix}/proxy/session.list 用错 key → 401。
4. 带正确 key：POST {prefix}/proxy/host.describe 返回 DSH 版本；session.list 返回会话列表。
5. WebSocket 连 ws://host{prefix}/proxy/events.mux（握手带 X-API-Key），
session.prompt 后应实时收到 session/event 帧直到 turn/end。

自动化验收：本仓库 scripts/proxy-host.mjs（独立验收宿主）+
dsh-agent-manager/scripts/smoke-proxy-b.ts（manager 走 proxy 路径的端到端冒烟）。

卸载

删除组合里的插件行（可选 dsh plugin remove dsh-api-gateway），重启。

文档范围

本仓库只保留使用者需要的内容：README、openapi.yaml、示例与测试。
内部设计与重构计划不在本仓库（集中在不公开发布的内部设计库）——代码、接口契约与
示例即完整的可运行、可自托管交付物。

License

MIT