DSH Auth Plugin — DeepSeek Harness 登录认证插件

给 DeepSeek Harness Web GUI 添加登录保护的 Cordis 插件。 零第三方依赖、单文件、极简配置，同时支持：

🔑 用户名 + 密码登录（scrypt 哈希存储）
🦖 Solana 钱包登录（ed25519 签名验证 + 公钥白名单）
🛡️ 统一会话管理（HMAC-SHA256 令牌 + HttpOnly Cookie + 登出吊销）

特性总览

特性	说明	状态
用户名密码登录	scrypt 哈希存储，支持明文（开发环境）与哈希	✅
通用 OAuth 2.0 登录	任意授权码 provider（GitHub/Google/Discord…），纯配置接入	✅
Solana 钱包登录	Phantom/Solflare，ed25519 challenge-response	✅
EVM 钱包登录	MetaMask 等，EIP-191 personal_sign + ecrecover	✅ 新增
白名单强制	钱包登录 `allowlist`/`allowlist` 必填，禁止任意钱包	✅
会话令牌	HMAC-SHA256 自包含 token（JWT 风格）	✅
防重放	一次性 nonce/state，消费即删	✅
登出吊销	服务端内存黑名单，防被窃 cookie 复用	✅
统一门卫	包装 webserver fallback，保护全部 SPA 页面与静态资源	✅
核心零依赖	`node:crypto`（scrypt/ed25519/HMAC）+ Node 全局 fetch + 手写 base58	✅
可选增强	EVM 需要纯 JS 库 `@noble/curves`+`@noble/hashes`（缺失时自动禁用）	⚙️
极简安装	复制 1 个文件 + 2 行配置，无需 pnpm/npm	✅
npm 发布就绪	`exports`/`files`/`engines`/`prepack` 校验，`npm pack` 验证通过	✅
bundle 化	`dsh.bundle` 声明，`dsh plugin add` 一行安装即生效	✅

版本：1.8.0（package.json）· 测试：60 项（34 单元 + 26 端到端）

架构与工作原理

模块解析基础

DSH 的 Loader 以 profile 目录（~/.dsh/profiles/web/）为 baseUrl，插件行的 name 直接传给 Node import()，因此：

name: "./dsh-auth-plugin.js" → 相对 profile 目录加载文件
name: "@scope/pkg" → 从 profile 的 node_modules 解析
name: "file:///abs/path" → 绝对路径加载

$DSH_HOME/profiles/node_modules 是 dsh 全依赖闭包的扁平回退目录 （含全部 195+ 个 @deepseek-ai/* 包），所以插件里 import "@deepseek-ai/schemastery" 等依赖无需安装即可解析—— 这是"复制即用"机制的根基。

请求流（门卫架构）

浏览器请求
   │
   ▼
webserver.match(pathname)
   │
   ├─ 精确路由表命中（exact）        → 直接处理
   │    /login                          → 登录页
   │    /api/auth/login                 → 密码登录 API
   │    /api/auth/logout                → 登出 API
   │    /api/auth/solana/challenge      → Solana 钱包 challenge
   │    /api/auth/solana/verify         → Solana 钱包 verify
   │    /api/auth/evm/challenge         → EVM 钱包 challenge
   │    /api/auth/evm/verify            → EVM 钱包 verify
   │
   ├─ 最长前缀路由命中（prefix）
   │    /api/auth/oauth/<id>/start      → OAuth 授权跳转（本插件）
   │    /api/auth/oauth/<id>/callback   → OAuth 回调（本插件）
   │    /api/*（client-connection 拥有）→ 保持 DSH 自带 loopback/
   │                                      trustedHosts 篱笆（刻意不拦截）
   │
   └─ 未命中 → fallback 座位（本插件包装）
        ├─ 公开路径？                → 放行
        ├─ 有有效会话 Cookie？       → 放行（用户信息挂 req.authUser）
        ├─ 浏览器请求（Accept: html）→ 302 → /login
        └─ API 调用                  → 401 JSON { code: "auth_required" }
              │
              ▼
        frontend-static（原始 dist 服务，SPA 页面与静态资源）

关键设计：插件注册为唯一 fallback 座位持有者（替换 frontend-static 的占座，认证通过后转交原始 handler）。这比注册 prefix "/" 路由可靠—— webserver 的 prefix 匹配 pathname.startsWith("/" + "/") 对非根路径恒为 false，prefix "/" 实际拦不住任何路径（早期版本的 bug，已修复）。

会话令牌

结构：<base64url(payload)>.<HMAC-SHA256(base64url(payload))>
Payload：{ u: 用户名, r: 角色, exp: 过期时间戳 }
传输：HttpOnly + SameSite=Strict + Max-Age 的 Cookie
吊销：登出时 token 进内存黑名单（重启清空）

Solana 登录流程

登录页点击「使用 Solana 钱包登录」
   │
   ├─ 1. POST /api/auth/solana/challenge { publicKey }
   │      校验 base58(32B) → 白名单检查(403) → 签发一次性 nonce
   │      返回 { nonce, message: "DSH Login <nonce>", expiresAt }
   │
   ├─ 2. 钱包 signMessage(message)（用户在钱包中确认）
   │
   └─ 3. POST /api/auth/solana/verify { publicKey, signature, nonce }
          白名单检查(403) → 消费 nonce(401 防重放) → ed25519 验签(401)
          → 通过则签发会话 Cookie

消息编码兼容两种：Phantom signMessage 直接 UTF-8 字节，以及 SIWS v0 官方格式（\xff + 小写 "solana offchain message" + preamble，见 Agave 规范）。

OAuth 授权码流程

登录页点击「使用 GitHub 登录」
   │
   ├─ 1. GET /api/auth/oauth/<id>/start
   │      签发一次性 state（绑定 provider，防 CSRF）
   │      302 → provider 授权页 ?client_id&redirect_uri&state[&scope]
   │
   ├─ 2. 用户在 provider 页面授权
   │
   ├─ 3. provider 302 → /api/auth/oauth/<id>/callback?code=&state=
   │      消费 state（一次性+过期+绑定）→ 失败 302 /login?error=oauth_bad_state
   │      服务端 code 换 token（client_secret 不下发浏览器）
   │      带 Bearer 取 userinfo → 映射 id/name/email
   │      签发会话 Cookie → 302 /

零依赖：token 交换与 userinfo 用 Node 全局 fetch（Node 18+）。

EVM 钱包流程（MetaMask 等）

登录页点击「⬡ 使用 EVM 钱包登录」
   │
   ├─ 1. POST /api/auth/evm/challenge { address }
   │      校验 0x 地址 → 白名单检查(403) → 签发一次性 nonce
   │      返回 { nonce, message: "DSH Login <nonce>", expiresAt }
   │
   ├─ 2. 钱包 personal_sign(message, address)（用户在钱包中确认）
   │      返回 65 字节 r||s||v 十六进制签名
   │
   └─ 3. POST /api/auth/evm/verify { address, signature, nonce }
          白名单检查(403) → 消费 nonce(401 防重放)
          → EIP-191 消息哈希 → ecrecover 恢复地址（secp256k1）
          → 恢复地址 === 声明地址 → 签发会话 Cookie

依赖可选的 @noble/curves + @noble/hashes（纯 JS、无 native）；缺失时 EVM 登录自动禁用并打印警告，其他登录方式不受影响。安装（仅启用 EVM 时需要）：

dsh plugin --profile web add @noble/curves @noble/hashes

安装

方式 A：直接复制（推荐，已验证）

# 1. 复制单文件到 web profile 目录
cp lib/index.js ~/.dsh/profiles/web/dsh-auth-plugin.js

# 2. ~/.dsh/profiles/web/cordis.patch.yml 追加
- insert:
    - id: auth
      name: "./dsh-auth-plugin.js"
      config:
        users:
          admin: admin123

重启 dsh web 生效。不需要改 package.json、跑 pnpm 或安装依赖。

方式 B：npm 包安装（发布到 registry 后）

# 从 npm registry 安装到 web profile
dsh plugin --profile web add dsh-auth-plugin

然后同样在 cordis.patch.yml insert 一行（name 用包名，依赖由 dsh plugin/pnpm 解析）：

- insert:
    - id: auth
      name: "dsh-auth-plugin"
      config:
        users:
          admin: admin123

dsh plugin 是 pnpm 转发器；本插件为普通插件（无 dsh.bundle），安装后需 insert 一行声明（bundle 形态见方式 C）。

发布到 npm（维护者）

插件已做好发布就绪（package.json 含 exports/files/engines/ prepack 校验）：

npm pack                       # 本地验证产物（prepack 会先跑语法检查）
npm login
npm publish --access public

# 本地测试 tarball 安装
npm pack
dsh plugin --profile web add file:/path/to/your-org-dsh-auth-plugin-1.6.0.tgz

方式 C：bundle 化（推荐给发布后的 npm 包）✅ 已实现

本插件已声明 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }， 安装即自动成为配置层，连 cordis.patch.yml 的 insert 都省了：

dsh plugin --profile web add dsh-auth-plugin
# → pnpm 安装 → 自动加入 bundles 层 → auth 插件行自动生效
#    （默认 admin/admin123，启动警告，请立即覆盖配置）

安装后在 profile 的 cordis.patch.yml 按 id 覆盖 config 即可：

- id: auth
  config:
    users:
      admin: { password: "scrypt$...", role: admin }
    oauth:
      providers:
        github: { builtin: github, clientId: "...", clientSecret: "..." }

已在隔离 DSH_HOME 完整验证：dsh plugin add <tarball> → bundles 列表自动追加 → --dump-config 出现 # == dsh-auth-plugin 段。

安装后文件布局

~/.dsh/profiles/web/
├── cordis.patch.yml         # 认证配置（insert auth 行）
├── dsh-auth-plugin.js       # 插件本体（单文件）
├── package.json             # profile manifest（可选加 "type": "module"）
└── pnpm-workspace.yaml

快速开始

# cordis.patch.yml —— 最简配置：用户名密码登录
- insert:
    - id: auth
      name: "./dsh-auth-plugin.js"
      config:
        users:
          admin: admin123

# 用户名密码 + Solana 钱包登录（allowlist 必填）
- insert:
    - id: auth
      name: "./dsh-auth-plugin.js"
      config:
        users:
          admin:
            password: "scrypt$<salt>$<hash>"
            role: "admin"
        solana:
          enabled: true
          allowlist:
            - "Dy6mBH4YeqJCRZohd39iSFaf4jyLaxPeBakbZwt1jToL"

重启 dsh web 后访问 http://127.0.0.1:3080 即重定向到登录页。

配置参考

顶层配置

字段	类型	默认值	说明
`enabled`	boolean	`true`	总开关
`secret`	string	每次启动随机	会话签名密钥；可用环境变量 `DSH_AUTH_SECRET` 固定
`ttlHours`	number	`24`	会话有效期（小时）
`title`	string	`DSH 登录`	登录页标题
`cookie`	string	`dsh_session`	会话 Cookie 名
`users`	dict	空→`admin/admin123`	用户表（见下）
`solana`	`false` \| object	`false`	Solana 钱包登录配置（见下）
`evm`	`false` \| object	`false`	EVM 钱包登录配置（见下）
`oauth`	object	`{providers:{}}`	通用 OAuth 配置（见下）
`publicPaths`	string[]	见下	免认证路径（精确或前缀匹配）

默认 publicPaths：/login、/api/auth/login、/api/auth/logout、 /favicon.ico

⚠️ secret 为空时每次启动随机——重启后所有会话失效需重新登录。这是保守设计（无需持久化）；生产环境建议固定：secret: !!js process.env.DSH_AUTH_SECRET。

`users` 三种写法

# 1. 极简：用户名: 明文密码（开发环境）
users:
  admin: admin123

# 2. 带角色
users:
  admin: { password: admin123, role: admin }

# 3. 推荐：scrypt 哈希
users:
  admin: { password: "scrypt$<salt>$<hash>", role: admin }

明文密码启动时会打印警告（仅限开发环境）。

`solana` 配置

字段	类型	默认值	说明
`enabled`	boolean	`true`（对象形式）	开关；`solana: false` 或省略 = 禁用
`challengeTtlMs`	number	`300000`	nonce 有效期（5 分钟）
`allowlist`	string[]	必填	公钥白名单（base58），至少 1 个
`role`	string	`user`	钱包登录默认角色

⚠️ allowlist 必填：启用时缺字段或空数组都会在加载时报配置错误（schema 层拦截）——不允许"任何钱包可登录"。

`evm` 配置（MetaMask 等 EVM 钱包）

evm:
  enabled: true
  allowlist:                # 必填：只允许这些 0x 地址（小写或混合大小写均可）
    - "0x4e984616e2dd9dffe7f2413efc7da35ef64c4117"
  role: user

字段	类型	默认值	说明
`enabled`	boolean	`true`（对象形式）	开关；`evm: false` 或省略 = 禁用
`challengeTtlMs`	number	`300000`	nonce 有效期（5 分钟）
`allowlist`	string[]	必填	允许的 0x 地址，至少 1 个
`role`	string	`user`	登录成功角色

⚠️ 同 Solana：allowlist 必填；且需要可选依赖 @noble/curves + @noble/hashes（dsh plugin --profile web add @noble/curves @noble/hashes），缺失时该功能自动禁用（其余登录不受影响）。

`oauth` 通用 OAuth 2.0 配置

每个 provider 一条，纯配置接入任意标准授权码 OAuth 服务。 支持内置模板：填 builtin + 凭据即可，端点/字段映射/scope 自动填充。

最简方式：内置模板（推荐）

oauth:
  providers:
    github:                       # provider id
      builtin: "github"           # ← 内置模板：端点/字段/scope 自动填充
      clientId: "Ov23li..."
      clientSecret: "ghp_..."     # 仅服务端使用，绝不下发浏览器

内置模板一览（BUILTIN_OAUTH，显式字段可覆盖模板）：

builtin	授权端点	token 端点	userinfo 端点	默认 scope	idField
`github`	github.com/login/oauth/authorize	…/access_token	api.github.com/user	`read:user`	`id`
`google`	accounts.google.com/o/oauth2/v2/auth	oauth2.googleapis.com/token	…/oauth2/v3/userinfo	`openid email profile`	`sub`
`discord`	discord.com/oauth2/authorize	discord.com/api/oauth2/token	discord.com/api/users/@me	`identify email`	`id`
`gitlab`	gitlab.com/oauth/authorize	gitlab.com/oauth/token	gitlab.com/api/v4/user	`read_user`	`id`
`microsoft`	login.microsoftonline.com/common/oauth2/v2.0/authorize	…/token	graph.microsoft.com/v1.0/me	`User.Read`	`id`
`bitbucket`	bitbucket.org/site/oauth2/authorize	…/access_token	api.bitbucket.org/2.0/user	`account`	`uuid`

完整方式：显式配置（任意标准 OAuth 服务）

oauth:
  providers:
    custom:
      label: "我的服务"
      clientId: "..."
      clientSecret: "..."
      authorizeUrl: "https://.../authorize"
      tokenUrl: "https://.../token"
      userInfoUrl: "https://.../userinfo"
      scope: "read"                # 可选
      idField: "id"                # 可选，默认 id
      nameField: "name"            # 可选
      emailField: "email"          # 可选
      role: "user"                 # 可选
      # redirectUri: "https://..." # 可选：显式回调地址

字段	类型	默认值	说明
`builtin`	string	`""`	内置模板名（见上表）；填了则端点/字段/scope 用模板
`label`	string	provider id / 模板	登录页按钮文案
`clientId` / `clientSecret`	string	必填	OAuth 应用凭据
`authorizeUrl` / `tokenUrl` / `userInfoUrl`	string	模板值	三个端点
`responseType`	string	`code`	授权响应类型（授权码模式）
`scope`	string	模板值/空	请求的 scope（空格分隔）
`redirectUri`	string	自动	显式回调地址；留空 = `http://<Host>/api/auth/oauth/<id>/callback`
`idField` / `nameField` / `emailField`	string	`id` / 模板	userinfo 字段映射
`emailDomains`	string[]	`[]`	邮箱域名白名单；非空时邮箱域名必须命中，否则拒绝（`oauth_email_not_allowed`）
`role`	string	`user`	登录成功角色
`userInfoHeaders`	dict	`{}`	取 userinfo 附加请求头
`tokenParams`	dict	`{}`	token 请求附加参数
`stateTtlMs`	number	`600000`	state 有效期（10 分钟）

回调地址（OAuth 应用后台填写）：http(s)://<你的地址>/api/auth/oauth/<id>/callback 例如：http://127.0.0.1:3080/api/auth/oauth/github/callback 未知 builtin 名或合并后缺必需字段会在启动时报配置错误。

API 参考

`GET /login`

返回内置登录页（含密码表单 + 可选 Solana 钱包区块）。状态码：200。

`POST /api/auth/login`

用户名密码登录。支持 JSON 与 application/x-www-form-urlencoded。

curl -X POST http://127.0.0.1:3080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"secret"}'

结果	状态码	说明
成功（JSON 调用）	`200`	`{ ok, username, role }` + `Set-Cookie`
成功（浏览器表单）	`302`	重定向 `/` + `Set-Cookie`
凭据错误（JSON）	`401`	`{ error: "invalid credentials" }`
凭据错误（表单）	`401`	登录页 + 错误提示
缺参	`400`	`{ error: "username and password required" }`
方法错误	`405`	非 GET/POST

`POST /api/auth/logout`

登出。服务端将当前 token 加入吊销黑名单并清除 Cookie。成功：200 { ok: true }（JSON）或 302 → /login（浏览器）。

`POST /api/auth/solana/challenge`

签发一次性 nonce（绑定公钥）。

curl -X POST http://127.0.0.1:3080/api/auth/solana/challenge \
  -H 'Content-Type: application/json' \
  -d '{"publicKey":"<32字节base58>"}'

结果	状态码	说明
成功	`200`	`{ nonce, message, expiresAt }`
公钥非法	`400`	`{ error: "invalid public key" }`
不在白名单	`403`	`{ error: "public key not allowed" }`

`POST /api/auth/solana/verify`

提交钱包签名换取会话。

curl -X POST http://127.0.0.1:3080/api/auth/solana/verify \
  -H 'Content-Type: application/json' \
  -d '{"publicKey":"<base58>","signature":"<base58 64B>","nonce":"<challenge 返回>"}'

结果	状态码	说明
成功	`200`	`{ ok, username: "solana:<pubkey>", role, publicKey }` + `Set-Cookie`
不在白名单	`403`	拒绝
nonce 无效/过期/重放	`401`	`{ error: "invalid or expired challenge" }`
签名验证失败	`401`	`{ error: "signature verification failed" }`
缺参	`400`	`{ error: "publicKey, signature and nonce required" }`

`POST /api/auth/evm/challenge`

EVM 钱包登录第一步：签发一次性 nonce（绑定 0x 地址）。

curl -X POST http://127.0.0.1:3080/api/auth/evm/challenge \
  -H 'Content-Type: application/json' \
  -d '{"address":"0x4e984616e2dd9dffe7f2413efc7da35ef64c4117"}'

结果	状态码	说明
成功	`200`	`{ nonce, message: "DSH Login <nonce>", expiresAt }`
地址非法	`400`	`{ error: "invalid address" }`
不在白名单	`403`	`{ error: "address not allowed" }`

`POST /api/auth/evm/verify`

提交 personal_sign 签名换取会话（需要可选依赖 @noble）。

curl -X POST http://127.0.0.1:3080/api/auth/evm/verify \
  -H 'Content-Type: application/json' \
  -d '{"address":"0x...","signature":"0x<65字节r||s||v>","nonce":"<challenge 返回>"}'

结果	状态码	说明
成功	`200`	`{ ok, username: "evm:<address>", role, address }` + `Set-Cookie`
不在白名单	`403`	拒绝
nonce 无效/过期/重放	`401`	`{ error: "invalid or expired challenge" }`
ecrecover 不匹配	`401`	`{ error: "signature verification failed" }`
缺参/地址非法	`400`	`{ error: "address, signature and nonce required" }`

`GET /api/auth/oauth/<id>/start`

发起 OAuth 登录。签发一次性 state 后 302 到 provider 授权页（authorizeUrl?client_id&redirect_uri&state[&scope]）。未知 provider → 404。

`GET /api/auth/oauth/<id>/callback`

OAuth 回调（用户从 provider 授权页跳回）。浏览器直接访问即可，无需手动调用。

# 模拟（真实流程由浏览器跳转完成）
curl -i "http://127.0.0.1:3080/api/auth/oauth/github/callback?code=xxx&state=<start 返回的 state>"

结果	状态码	行为
成功	`302`	重定向 `/` + `Set-Cookie`（会话已建立）
state 无效/过期/重放	`302`	重定向 `/login?error=oauth_bad_state`（防 CSRF）
token 交换失败	`302`	`/login?error=oauth_token_failed`
userinfo 获取失败	`302`	`/login?error=oauth_userinfo_failed`
userinfo 缺 id 字段	`302`	`/login?error=oauth_no_id`
未知 provider	`302`	`/login?error=oauth_unknown_provider`

会话身份：oauth:<providerId>:<id>（如 oauth:github:user-42）。

前端集成

密码表单

内置登录页为自包含 HTML（无外部资源），POST 到 /api/auth/login，成功即设置 Cookie 并跳转 /。

Solana 钱包登录

登录页内联脚本（零外部依赖）：

检测钱包：window.solana.isPhantom → window.phantom.solana
点击按钮 → provider.connect() 取公钥
请求 challenge → provider.signMessage(TextEncoder.encode(message), "utf8")
签名 base58 编码后 POST verify → 成功 location.href = "/"

支持 Phantom、Solflare 等注入 window.solana 的钱包；未安装钱包时按钮下方提示"未检测到钱包"。

OAuth 第三方登录

登录页按配置为每个 provider 渲染一个按钮（<a href="/api/auth/oauth/<id>/start">），点击即进入标准 OAuth 授权码流程，无需前端脚本。

EVM 钱包登录

登录页「⬡ 使用 EVM 钱包登录」按钮，内联脚本检测 window.ethereum： eth_requestAccounts 取地址 → challenge → personal_sign → 提交 verify。

安全设计

项	实现
密码存储	`node:crypto` scrypt（随机盐），支持明文仅限开发
令牌完整性	HMAC-SHA256 签名，`timingSafeEqual` 比较
Cookie	`HttpOnly; SameSite=Strict; Path=/; Max-Age`
登出吊销	服务端内存黑名单（`revoked` Set）
nonce 防重放	一次性消费，`consume` 即删；绑定公钥/地址；TTL 5 分钟 + 惰性 sweep
OAuth state 防 CSRF	一次性 + 绑定 provider + 10 分钟 TTL；伪造/重用 state → `oauth_bad_state`
client_secret 保密	仅服务端持有，token 交换在服务端完成，绝不下发浏览器
userinfo 服务端获取	Bearer token 不出服务端
EVM 验签	EIP-191 `personal_sign` 消息哈希 + secp256k1 ecrecover 恢复地址，与声明地址比对
登录审计	每次登录成功 `info` / 失败 `warn` 打点（`[dsh-auth] login ok/failed: <method> <身份> [原因]`）
白名单强制	钱包登录 `allowlist`/`allowlist` 必填，challenge 与 verify 双重 403
消息重建	服务端 `DSH Login <nonce>` 重建，不信任客户端回传 message
定时器依赖	`inject: ["webServer", "timer"]` 显式声明（Cordis 强制）
`/api` 边界	保持 DSH 自带 loopback/trustedHosts 篱笆，插件不越权

用户与密钥管理

生成 scrypt 哈希

# 方式一：内置脚本
node scripts/manage-users.js hash 你的密码

# 方式二：一行命令
node --input-type=module -e "
import { scrypt, randomBytes } from 'node:crypto';
const salt = randomBytes(16).toString('hex');
scrypt(process.argv[1], salt, 32, (e,k)=>{ if(e) throw e; console.log('scrypt\$'+salt+'\$'+k.toString('hex')); });
" 你的密码

添加/修改/删除用户

直接编辑 cordis.patch.yml 的 users 表后重启即可。支持多用户、多角色（admin / user，角色目前仅作标识，可由其他插件消费 req.authUser）。

Solana 公钥获取

钱包连接后从 publicKey.toString() 得到 base58 地址，填入 allowlist。验证合法性：node -e "import('./dsh-auth-plugin.js').then(m => console.log(m.base58Decode('...').length === 32))"

测试

# 单元测试（核心零依赖，直接可跑；EVM 组需要 @noble，缺失时自动跳过）
node --test test/auth.test.js
# → 34 项：scrypt、HMAC 令牌、base58、ed25519 验签（含 SIWS v0）、
#   nonce/state 管理、EVM ecrecover、OAuth 模板合并

# 端到端测试（需要 DSH 的 node_modules 环境解析 schematery）
node --test test/e2e.test.js
# → 26 项：密码登录、Cookie、登出吊销、Solana/EVM 钱包、白名单 403、
#   fake OAuth provider 授权码流程（含内置模板）、邮箱域名白名单、防重放

已知问题与故障排除

已修复：`cannot get property "timer" without inject`（v1.1.0 → v1.2.0）

启用 Solana 后启动失败：

Error: dsh: plugin tree failed to load:
failed to apply loader entry auth (./dsh-auth-plugin.js):
cannot get property "timer" without inject

根因：ctx.setInterval() 由 Cordis 的 timer 服务提供，新版 Cordis 要求显式声明所有经 ctx 使用的服务；原 inject = ["webServer"] 遗漏了 timer。

修复：const inject = ["webServer", "timer"]。

完整排查记录见 docs/repair-timer-inject.md。

常见问题

现象	处理
启动报 `failed to import loader entry auth`	确认 `./dsh-auth-plugin.js` 相对 profile 目录路径正确、文件存在
报找不到 `@deepseek-ai/schemastery`	确认 `~/.dsh/profiles/node_modules` 存在（dsh 首次启动自动生成）
登录后又被弹回登录页	`secret` 未固定 → 重启后旧会话失效，属正常；或系统时间异常
`cannot get property "timer"`	确认 `inject` 含 `"timer"`（v1.2.0 起已内置）
Solana 按钮不显示	确认 `solana.enabled: true` 且 allowlist 非空
钱包登录报 403	钱包公钥不在 `allowlist`
钱包签名后 401	nonce 过期（5 分钟）或已被使用，重新点击登录
OAuth 按钮不显示	确认 `oauth.providers` 至少配置了一个 provider
OAuth 回调 `oauth_bad_state`	刷新/重放旧回调，或 state 过期（10 分钟）；重新从登录页发起
OAuth 回调 `oauth_token_failed`	检查 clientId/clientSecret 与回调地址是否与 provider 后台一致
OAuth 回调 `oauth_no_id`	userinfo 响应里没有 `idField` 指定字段，按 provider 响应调整映射
EVM 按钮不显示	确认 `evm.enabled: true` 且 allowlist 非空，且已安装 @noble（缺失时启动日志有警告）
EVM 登录报 403	钱包地址不在 `allowlist`
EVM 签名后 401	nonce 过期（5 分钟）或已被使用，重新点击登录；或签名格式非 0x + 65 字节
启动时的 `MODULE_TYPELESS` 警告	无碍；在 profile 的 `package.json` 加 `"type": "module"` 消除

升级与回滚

升级

cp <新版本>/lib/index.js ~/.dsh/profiles/web/dsh-auth-plugin.js
# 重启 dsh web

回滚

cp ~/.dsh/profiles/web/cordis.patch.yml.bak ~/.dsh/profiles/web/cordis.patch.yml
rm -f ~/.dsh/profiles/web/dsh-auth-plugin.js

（安装时自动备份了 cordis.patch.yml.bak；再次改动前有 .bak2。）

生产部署建议

固定 secret：secret: !!js process.env.DSH_AUTH_SECRET（环境变量注入）
HTTPS 反向代理：Nginx/Caddy 终结 TLS，转发 127.0.0.1:3080 （注意 WebSocket upgrade 头：Upgrade / Connection: upgrade）
强密码：全部用户使用 scrypt 哈希，避免明文
钱包白名单：Solana 登录务必维护 allowlist，公钥即身份
OS 边界：防火墙限制端口暴露；/api 仍由 DSH 自带篱笆保护
日志审计：如需登录审计日志，可 fork 插件在 loginHandler / verifyHandler 成功后打点

许可证

MIT

dsh-auth-plugin

DSH Auth Plugin — DeepSeek Harness 登录认证插件

目录

特性总览

架构与工作原理

模块解析基础

请求流（门卫架构）

会话令牌

Solana 登录流程

OAuth 授权码流程

EVM 钱包流程（MetaMask 等）

安装

方式 A：直接复制（推荐，已验证）

方式 B：npm 包安装（发布到 registry 后）

发布到 npm（维护者）

方式 C：bundle 化（推荐给发布后的 npm 包）✅ 已实现

安装后文件布局

快速开始

配置参考

顶层配置

users 三种写法

solana 配置

evm 配置（MetaMask 等 EVM 钱包）

oauth 通用 OAuth 2.0 配置

最简方式：内置模板（推荐）

完整方式：显式配置（任意标准 OAuth 服务）

API 参考

GET /login

POST /api/auth/login

POST /api/auth/logout

POST /api/auth/solana/challenge

POST /api/auth/solana/verify

POST /api/auth/evm/challenge

POST /api/auth/evm/verify

GET /api/auth/oauth/<id>/start

GET /api/auth/oauth/<id>/callback

前端集成

密码表单

Solana 钱包登录

OAuth 第三方登录

EVM 钱包登录

安全设计

用户与密钥管理

生成 scrypt 哈希

添加/修改/删除用户

Solana 公钥获取

测试

已知问题与故障排除

已修复：cannot get property "timer" without inject（v1.1.0 → v1.2.0）

常见问题

升级与回滚

升级

回滚

生产部署建议

许可证

社区评论

dsh-auth-plugin

DSH Auth Plugin — DeepSeek Harness 登录认证插件

目录

特性总览

架构与工作原理

模块解析基础

请求流（门卫架构）

会话令牌

Solana 登录流程

OAuth 授权码流程

EVM 钱包流程（MetaMask 等）

安装

方式 A：直接复制（推荐，已验证）

方式 B：npm 包安装（发布到 registry 后）

发布到 npm（维护者）

方式 C：bundle 化（推荐给发布后的 npm 包）✅ 已实现

安装后文件布局

快速开始

配置参考

顶层配置

users 三种写法

solana 配置

evm 配置（MetaMask 等 EVM 钱包）

oauth 通用 OAuth 2.0 配置

`users` 三种写法

`solana` 配置

`evm` 配置（MetaMask 等 EVM 钱包）

`oauth` 通用 OAuth 2.0 配置

`GET /login`

`POST /api/auth/login`

`POST /api/auth/logout`

`POST /api/auth/solana/challenge`

`POST /api/auth/solana/verify`

`POST /api/auth/evm/challenge`

`POST /api/auth/evm/verify`

`GET /api/auth/oauth/<id>/start`

`GET /api/auth/oauth/<id>/callback`

已修复：`cannot get property "timer" without inject`（v1.1.0 → v1.2.0）

`users` 三种写法

`solana` 配置

`evm` 配置（MetaMask 等 EVM 钱包）

`oauth` 通用 OAuth 2.0 配置

`GET /login`

`POST /api/auth/login`

`POST /api/auth/logout`

`POST /api/auth/solana/challenge`

`POST /api/auth/solana/verify`

`POST /api/auth/evm/challenge`

`POST /api/auth/evm/verify`

`GET /api/auth/oauth/<id>/start`

`GET /api/auth/oauth/<id>/callback`

已修复：`cannot get property "timer" without inject`（v1.1.0 → v1.2.0）