dsh-access-gate（中文）

DSH（DeepSeek Harness）远程访问认证门禁插件：解决"经 nginx 公网域名转发访问时，/api/* 全部 403"的问题 —— 认证通过后所有被浏览器信任护栏拦截的接口（含 settings.*、credentials.* 等 loopback 钉死的特权接口）全部可用；本机 127.0.0.1 访问不受影响；卸载插件一切还原，零残留、不污染用户配置。

同时是 dsh-lan-access 的完整替代品（0.0.0.0 绑定 + crypto.randomUUID polyfill + 远程认证 + 本机原生目录选择，一个包全包）。

功能

安装

# 方式一：npm 发布后（推荐）
dsh plugin --profile web add dsh-access-gate

# 方式二：GitHub 直装（lib/ 已提交，装上即用）
dsh plugin --profile web add github:bamboostrip/dsh-access-gate

# 方式三：本地开发（link: 符号链接，改代码只需 build + 重启）
npm run build
dsh plugin --profile web add link:E:/ALLCODE/project/dsh-auth-gate

重启 DSH 生效。默认无密码：远程直接可访问。设置访问密码（二选一）：

# ① 推荐：DSH 设置界面 → 插件配置 → 访问认证 卡片
#    写入 ~/.dsh/.credentials.yaml；保存后实时生效，无需重启
# ② 环境变量（优先于文件层，适合脚本/CI）：
$env:DSH_GATE_PASSWORD='你的密码'   # PowerShell；重启 DSH 生效

npm 刚发布的新版本在官方 registry 立即可见，但国内镜像（如 npmmirror）同步可能有几分钟到数小时延迟 —— 如果 dsh plugin add 报找不到包，改用 GitHub 方式安装即可（见上）。

密码来源优先级：config.password > 环境变量 DSH_GATE_PASSWORD > ~/.dsh/.credentials.yaml > .env。

使用

• 默认无密码：远程（公网域名 / 局域网 IP）直接访问。
• 设置密码后：本机 http://127.0.0.1:3080 免密；远程首次访问 302 到登录页，登录后 7 天内免登录（有效期可配）。
• nginx 与 DSH 同机时（remote 恒为 127.0.0.1 但 Host 是域名）同样需要密码 —— 公网流量无法绕过认证。
• 登录态在内存：DSH 进程重启后需重新登录。

公网 nginx 参考配置

server {
    listen 443 ssl;
    server_name codsh.famlife.top;
    # ssl_certificate ...; ssl_certificate_key ...;

    location / {
        proxy_pass http://10.144.144.7:3080;   # 家里 DSH
        proxy_http_version 1.1;                # ★ 必须（默认 1.0 会断 WS）
        proxy_set_header Host $host;           # 域名原样转发
        proxy_set_header Upgrade $http_upgrade;        # ★ WS 必需
        proxy_set_header Connection "upgrade";         # ★ WS 必需
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

公网 403 排查清单见 NOTES.md。

可选配置（profiles/web/cordis.patch.yml 覆盖 auth-gate 行）

- id: auth-gate
  config:
    # password: 'xxx'                        # 可选：行配置密码（最高优先）
    trustedRemotePrefixes: ['10.144.144.0/24']   # 内网网段免密（IPv4 CIDR）
    tokenTtlMs: 604800000                  # 登录有效期，默认 7 天

卸载（零残留）

dsh plugin --profile web remove dsh-access-gate

卸载后：包与 bundle patch 一起移除（webserver 绑定还原 DSH 默认、polyfill 停止注入），server.emit 拦截器、原生选择器路由、客户端智能 flow 与设置卡片全部随 ctx.effect 清理回调还原，登录态随进程退出消失。完整审计见 NOTES.md。

安全提示

• 默认无密码时，远程访问等价于本机操作权限（DSH 本身是远程执行工具）—— 公网暴露前请务必配置强密码，并建议 nginx 层加 IP 白名单 / Basic Auth 双保险。
• 请配合 nginx HTTPS 使用，防止密码与 Cookie 明文传输。
• 登录接口无失败次数限制（已知边界，见 NOTES §5）。

开发

npm install            # 首次：typescript / @types/node
npm run typecheck      # 类型检查
npm run build          # 编译 src/ → lib/
npm run check:package  # 包组合验证（防安装后启动失败）
npm run test:e2e       # 真机级 E2E（50 项断言，使用本机真实 DSH 模块）

• 结构：src/（TypeScript 源码）+ lib/（tsc 产物，随包提交保证装上即用）+ src/client.js（浏览器半边：智能目录选择 flow + 访问认证设置卡片）
• 对 DSH 外部 API 的依赖形状集中在 src/types.ts（每处附源码出处）—— DSH 升级后改这一处，编译器标出所有受影响调用点
• 完整技术方案与验证记录见 NOTES.md

License

MIT

dsh-access-gate (English)

An access authentication gate for DeepSeek Harness Web. It fixes the "everything on /api/* returns 403 behind a public nginx domain" problem: after password authentication, every endpoint blocked by the browser-trust fence — including the loopback-pinned privileged methods (settings.*, credentials.*, host.openPath, host.pickDirectory, llm.discoverModels, agentPreset.*) — becomes fully usable. Local 127.0.0.1 access is untouched, and uninstalling restores everything with zero residue.

It is also a full replacement for dsh-lan-access: 0.0.0.0 binding, crypto.randomUUID polyfill, remote authentication, and a native folder picker for local workspace selection — one package covers it all.

Features

Install

# Option 1: from npm (recommended after publishing)
dsh plugin --profile web add dsh-access-gate

# Option 2: straight from GitHub (lib/ is committed, works out of the box)
dsh plugin --profile web add github:bamboostrip/dsh-access-gate

# Option 3: local development (link: symlink; rebuild + restart DSH after changes)
npm run build
dsh plugin --profile web add link:E:/ALLCODE/project/dsh-auth-gate

Restart DSH to activate. No password by default — remote clients connect directly. To set an access password:

# ① Recommended: DSH Settings → Plugin configuration → "Access authentication" card
#    Stored in ~/.dsh/.credentials.yaml; takes effect immediately, no restart
# ② Environment variable (takes precedence over the file layer; handy for scripts/CI):
export DSH_GATE_PASSWORD='your-password'

Password resolution order: config.password > env DSH_GATE_PASSWORD > ~/.dsh/.credentials.yaml > .env.

Usage

• Passwordless by default: remote access (public domain / LAN IP) works directly.
• With a password: local http://127.0.0.1:3080 stays password-free; remote first visit is 302-redirected to the login page; logged-in sessions skip login for 7 days (configurable).
• When nginx runs on the same host as DSH (remote is always 127.0.0.1 but Host is a domain), a password is still required — public traffic cannot bypass authentication.
• Login state lives in memory: a DSH restart requires re-login.

Public nginx reference

server {
    listen 443 ssl;
    server_name codsh.famlife.top;
    # ssl_certificate ...; ssl_certificate_key ...;

    location / {
        proxy_pass http://10.144.144.7:3080;   # your DSH host
        proxy_http_version 1.1;                # ★ required (1.0 breaks WebSocket)
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;        # ★ WebSocket
        proxy_set_header Connection "upgrade";         # ★ WebSocket
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

A public-403 troubleshooting checklist is in NOTES.md.

Optional configuration (override the auth-gate row in profiles/web/cordis.patch.yml)

- id: auth-gate
  config:
    # password: 'xxx'                        # optional: row-level password (highest priority)
    trustedRemotePrefixes: ['10.144.144.0/24']   # password-free LAN CIDRs (IPv4)
    tokenTtlMs: 604800000                  # login TTL, default 7 days

Uninstall (zero residue)

dsh plugin --profile web remove dsh-access-gate

The package and its bundle patch disappear together (webserver binding returns to DSH defaults, polyfill stops), and the server.emit interceptor, native picker route, client smart flow, and settings card are all reverted by ctx.effect cleanup. Full audit: NOTES.md.

Security notes

• Without a password, remote access equals local machine privileges (DSH is a remote-execution tool) — configure a strong password before exposing it publicly, and consider an IP allowlist / Basic Auth at the nginx layer.
• Use nginx HTTPS to keep the password and cookie off the wire.
• The login endpoint has no rate limiting yet (known limitation, see NOTES §5).

Development

npm install            # first time: typescript / @types/node
npm run typecheck      # type checking
npm run build          # compile src/ → lib/
npm run check:package  # package composition check (prevents boot failures)
npm run test:e2e       # machine-level E2E (50 assertions against the real DSH modules)

• Layout: src/ (TypeScript source) + lib/ (tsc output, committed so installs work out of the box) + src/client.js (browser half: smart directory flow + access-authentication settings card)
• The external DSH API contract lives in src/types.ts (each declaration annotated with its source location) — when DSH upgrades, change that one file and the compiler flags every affected call site
• Full technical notes and verification records: NOTES.md

License

MIT