fix: 远端备份超时可读化、错误可见性与管理员不变量（15 项修复）

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,17 +14,16 @@
 
 - [ ] I read `CONTRIBUTING.md`.
 - [ ] Schema changes, if any, updated both runtime schema and `migrations/0001_init.sql`.
+- [ ] Schema changes, if any, bumped `STORAGE_SCHEMA_VERSION` in `src/services/storage.ts`.
 - [ ] Persistent data changes, if any, updated backup export/import or documented why backup is not needed.
 - [ ] User-facing text changes, if any, updated all locale files.
 - [ ] Bitwarden client compatibility was considered for sync/API shape changes.
 - [ ] No secrets, tokens, private deployment values, or real vault data are included.
 
 ## Checks
 
-- [ ] `npx tsc -p tsconfig.json --noEmit`
-- [ ] `npx tsc -p webapp/tsconfig.json --noEmit`
-- [ ] `npm run i18n:validate`
-- [ ] `npm run build`
+- [ ] `npm run verify` — type checks for all four tsconfigs, `npm test`, `npm run i18n:validate`, `npm run build`
+- [ ] New or changed tests: `npm test` was run at least twice (some cleanup paths are gated on `Math.random()`, so one green run can be luck)
 
 ## Notes
 

.github/dependabot.yml

@@ -8,6 +8,10 @@ updates:
       day: "monday"
       time: "05:00"
       timezone: "Asia/Shanghai"
+    # 新版本发布后先等 7 天再提 PR（cooldown）：避免上游一天连发几个补丁就刷出一串 PR，
+    # 也避免刚发布、尚未被广泛验证的版本立刻进仓。
+    cooldown:
+      default-days: 7
     open-pull-requests-limit: 5
     groups:
       npm-minor-and-patch:
@@ -26,6 +30,10 @@ updates:
       day: "monday"
       time: "05:10"
       timezone: "Asia/Shanghai"
+    # 同上。本生态的 open-pull-requests-limit 是 0，即不会开出版本更新 PR，
+    # 所以这条 cooldown 目前不影响实际行为，加它只为两个生态配置保持一致。
+    cooldown:
+      default-days: 7
     open-pull-requests-limit: 0
     groups:
       github-actions:

.github/workflows/codeql.yml

@@ -5,16 +5,19 @@ on:
     branches:
       - "**"
 
-permissions:
-  contents: read
-  actions: read
-  security-events: write
-  packages: read
+# 权限一律在 job 级声明：工作流级声明会让所有 job（含未来的新 job）共享同一套权限，
+# 而 security-events: write 只有上传分析结果的那一步需要。
+permissions: {}
 
 jobs:
   analyze:
     name: CodeQL Analyze (${{ matrix.language }})
     runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      packages: read
+      security-events: write
 
     strategy:
       fail-fast: false

.github/workflows/security-extra.yml

@@ -48,35 +48,11 @@ jobs:
       upload-sarif: true
       fail-on-vuln: true
 
-  pnpm-audit:
-    name: pnpm audit
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: read
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
-        with:
-          persist-credentials: false
-
-      - name: Setup Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
-        with:
-          node-version: 22
-
-      - name: Run pnpm audit
-        shell: bash
-        run: |
-          if [ ! -f pnpm-lock.yaml ]; then
-            echo "pnpm-lock.yaml not found, skip pnpm audit."
-            exit 0
-          fi
-
-          corepack enable
-          corepack prepare pnpm@10 --activate
-          pnpm audit --audit-level=high
+  # 说明：这里原本还有一个 `pnpm audit` job，但本仓库使用 npm（仅有
+  # package-lock.json，无 pnpm-lock.yaml），该 job 的守卫 `if [ ! -f pnpm-lock.yaml ]`
+  # 必然直接 exit 0 —— 永远不执行任何审计。实测上方 osv job 的
+  # `scan source --recursive` 会扫到 package-lock.json（321 个包），
+  # 覆盖范围等价，故移除该冗余 job。
 
   semgrep:
     name: Semgrep CE Scan

.github/workflows/sync-global-domains.yml

@@ -11,19 +11,24 @@ on:
         default: "main"
         type: string
 
-permissions:
-  contents: write
-  pull-requests: write
+# 权限一律在 job 级声明：工作流级声明会让所有 job 共享同一套过宽权限。
+permissions: {}
 
 jobs:
   sync-global-domains:
     runs-on: ubuntu-latest
+    # 需要建分支/提交（contents）并创建 PR（pull-requests）——
+    # 这也是本文件的 checkout **不能**加 persist-credentials: false 的原因（与 verify.yml 相反）。
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         with:
-          node-version: 22
+          # 与 verify.yml、Cloudflare Workers Builds 共用同一版本来源（.nvmrc）。
+          node-version-file: '.nvmrc'
 
       - name: Sync generated Bitwarden domains
         env:

.github/workflows/verify.yml

@@ -0,0 +1,45 @@
+name: Verify
+
+# 说明：本仓库已有一套测试与校验脚本（类型检查 / i18n 对齐 / 通知与 WebAuthn
+# 安全测试 / 构建），但在本次补充前，CI 中没有任何一个 workflow 执行它们 ——
+# 测试写了却无人自动运行，回归不会被拦截。此外 `pnpm audit` 步骤因项目使用 npm
+# （仅有 package-lock.json）而被守卫跳过。此 workflow 补上“验证”这一环。
+#
+# 另：scripts/security-audit-*.mjs 三个安全回归脚本此前在 CI、npm scripts 与
+# 文档中均无引用（死资产），现已通过 `test:security-audit` 纳入 `npm test`。
+#
+# 本地复现：npm run verify
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# 仅需读取仓库内容
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Type check, i18n, tests, build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+        with:
+          # 本 job 不需要 git push，因此不把 GITHUB_TOKEN 写进 .git/config。
+          # 否则 npm ci 期间任何依赖包的 postinstall 脚本都能读到该令牌。
+          # 与 codeql.yml / security-extra.yml 保持一致。
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
+        with:
+          # 版本来源单一化：.nvmrc 同时被本 workflow 与 Cloudflare Workers Builds
+          # 的构建镜像读取（官方文档：NODE_VERSION / .nvmrc / .node-version）。
+          # 24.18.0 是 Cloudflare 构建镜像预装的版本，因此三方零分叉、零下载。
+          node-version-file: '.nvmrc'
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Verify (typecheck + i18n + tests + build)
+        run: npm run verify

.gitleaks.toml

@@ -0,0 +1,32 @@
+# gitleaks 配置：只用于排除「刻意写死的假凭据」误报 —— 测试夹具里的自述式 JWT 密钥，
+# 以及 Web 端 UI 演示数据里的假 SSH 私钥。
+#
+# 为什么需要配置级白名单，而不是改代码或加行内注释：
+#   - `scripts/lib/test-harness.ts` 定义的测试用 JWT 密钥，取值是自述式字符串
+#     `test-jwt-secret-at-least-32-characters-long`：变量名含 "secret"、熵值 3.602
+#     高于阈值，于是熵值类规则 `generic-api-key` 必然命中；另有 3 个测试文件把同一
+#     字面量写死在本地，合计 4 处（均出自提交 8efe2a6）。
+#   - `webapp/src/lib/demo.ts` 的演示密码库里有一条名为 "Production SSH key" 的假条目：
+#     `notes` 字段自己就写着 `Fake SSH key material for UI preview.`，所谓私钥的主体
+#     是字面量 `DEMO-PRIVATE-KEY`。`private-key` 规则只认 `-----BEGIN/END ... PRIVATE
+#     KEY-----` 装甲头、不校验中间是否为合法 base64，因此必然命中（2026-06-23 首次报出）。
+#   - gitleaks 的扫描单位是「**本次 push 范围内新增的行**」（日志可见它执行的是
+#     `git log -p -U0 --no-merges --first-parent <range>`）。因此即使后续提交删掉
+#     或改写这些行，只要 8efe2a6 仍在该范围内（例如合并进 main 的那次 push），
+#     行内 `gitleaks:allow` 注释也无能为力 —— 只有配置级白名单能稳定生效。
+#
+# 白名单按**那一个字面值**匹配，不是按目录、也不是按文件：
+# 测试目录或演示数据里若真的混进其它凭据（哪怕同一个文件），其它取值与其它规则仍会照常报出。
+#
+# 注意：本文件是在 gitleaks 8.24.3（CI 中 gitleaks-action 自动安装的版本）下验证的。
+# 升级 gitleaks 大版本时需复核 `[allowlist]` 的写法（新版本已改用 `[[allowlists]]`）。
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "刻意写死的假凭据：测试用自述式 JWT 密钥 + UI 演示数据里的假 SSH 私钥"
+regexes = [
+  '''test-jwt-secret-at-least-32-characters-long''',
+  '''DEMO-PRIVATE-KEY''',
+]

.nvmrc

@@ -0,0 +1 @@
+24.21.0

CONTRIBUTING.md

@@ -109,8 +109,63 @@ For new locales, update:
 - `webapp/src/lib/i18n/locales/*`
 - `scripts/i18n-utils.cjs`
 
+### Tests
+
+`npm test` runs the whole suite. It needs no external services and no network: the
+D1 and R2 bindings are backed by in-process implementations, so the tests execute
+**real SQL** against the real schema (including the real shadow tables and the
+final swap used by restore).
+
+```sh
+npm test
+```
+
+Files worth knowing about when adding a test:
+
+- `scripts/lib/test-harness.ts` — shared fixture. Start from
+  `createSchemaDatabase()` / `insertUser()` instead of building a database by hand;
+  it also resets the process-scoped statics that would otherwise stop a second
+  database from getting a schema.
+- `scripts/lib/d1-sqlite.ts` — a `D1Database` on Node's built-in `node:sqlite`.
+- `scripts/lib/r2-memory.ts` — in-memory attachment bucket.
+- `scripts/lib/sql-recorder.ts` — records the statements that were run. Two
+  counters, do not mix them up: `queries` counts prepared statements (use it for
+  query-plan assertions) while `roundTrips` counts database round trips (use it
+  for N+1 assertions). `batch([...])` is N prepares but **one** round trip.
+- `scripts/lib/register-cloudflare-stub.mjs` — handler tests must be started as
+  `tsx --import ./scripts/lib/register-cloudflare-stub.mjs`, because
+  `cloudflare:workers` cannot be resolved under Node. This is already wired into
+  every `test:*-handler` script; copy one of them when adding another.
+
+Two rules that exist because each has already produced a false result:
+
+- **Run the suite at least twice** before calling a change green. Some cleanup
+  paths are gated on `Math.random()` and only run on a fraction of requests, so a
+  single passing run can be luck. When testing such a path, pin `Math.random` for
+  the duration of the test rather than hoping the path fires.
+- **Never assert that two timestamps differ.** Calling `new Date().toISOString()`
+  twice within the same millisecond returns the same value. Pin a baseline
+  timestamp and assert that the new value is greater.
+
 ## Recommended Checks
 
+Before opening a pull request, run the same command CI runs:
+
+```sh
+npm run verify
+```
+
+which is:
+
+```sh
+npm run typecheck   # tsconfig.json, webapp/, tsconfig.scripts.json, tsconfig.webapp-tests.json
+npm run i18n:validate
+npm test
+npm run build
+```
+
+Narrower runs while iterating.
+
 For most backend or shared changes:
 
 ```sh
@@ -126,6 +181,13 @@ npx tsc -p webapp/tsconfig.json --noEmit
 npm run build
 ```
 
+For changes under `scripts/` (tests and tooling):
+
+```sh
+npx tsc -p tsconfig.scripts.json --noEmit
+npm test
+```
+
 For documentation-only changes:
 
 ```sh

README.md

@@ -112,6 +112,11 @@ npm run deploy
 
 # Optional: KV mode
 npm run deploy:kv
+#  The first deploy pins the KV namespace id into wrangler.kv.toml (commit that change).
+#  If the account already has a namespace with a *similar* title, the script stops and asks
+#  you to choose explicitly instead of guessing (a wrong guess sends attachments elsewhere):
+#    node scripts/ensure-kv.cjs --id <32-hex>   # reuse one of the candidates
+#    node scripts/ensure-kv.cjs --force-new     # create a new namespace anyway
 
 # Local development
 npm run dev

README_ZH.md

@@ -111,6 +111,11 @@ npm run deploy
 
 # 可选：KV 模式
 npm run deploy:kv
+#  首次部署会把账号里的 KV 命名空间 id 写回 wrangler.kv.toml（记得把这次改动一并提交）。
+#  若账号里已有「标题相近但名字不完全一致」的命名空间，脚本会停下来让你显式选择，
+#  而不是替你猜（猜错会把附件写进另一个库）：
+#    node scripts/ensure-kv.cjs --id <32 位 hex>   # 复用其中一个
+#    node scripts/ensure-kv.cjs --force-new        # 确实要新建
 
 # 本地开发
 npm run dev

SECURITY.md

@@ -13,6 +13,9 @@ Use GitHub Private Vulnerability Reporting instead:
 3. Click **Report a vulnerability**.
 4. Submit the report privately.
 
+Direct link (replace the owner if this file is reused by another fork):
+<https://github.com/cakkl/nodewarden/security/advisories/new>
+
 NodeWarden is independent from Bitwarden. Please do not report NodeWarden-specific issues to the official Bitwarden team.
 
 ## What to Include
@@ -60,6 +63,42 @@ We aim to acknowledge valid private reports within 72 hours, investigate the iss
 
 Please do not publicly disclose vulnerability details before a fix or mitigation is available.
 
+## Administrator Bootstrap and Role Assignment
+
+NodeWarden has no separate setup step or setup token. Administrator privilege is
+assigned as follows.
+
+**First account.** The first account that registers on an instance is granted the
+`admin` role, and the instance is then marked as registered. This is recorded in
+the security audit log as `user.register.first_admin`.
+
+**Later accounts.** After the first account exists, registration requires an
+invite code (`Invite code is required`, HTTP 403) and the new account gets the
+default `user` role. These are recorded as `user.register.invite`. Registration
+can therefore not be used to obtain administrator privilege on an existing
+instance.
+
+**Recovery when no administrator exists.** If an instance ends up with no account
+holding the `admin` role — for example the last administrator account was deleted
+— the database bootstrap promotes the **earliest-created** account back to `admin`
+on its next schema initialization. This is a system action with no actor, and is
+recorded in the security audit log as `user.bootstrap.admin_promoted`.
+
+Two properties of that recovery path are worth knowing:
+
+* **Administrator accounts are not protected against deletion.** NodeWarden does
+  not block deleting the last administrator. The bootstrap exists so an instance
+  cannot become permanently unmanageable, but it is not a substitute for
+  administrative care on a multi-user instance.
+* **The account that regains the role is selected by account creation time, not
+  by trust.** On a multi-user instance, make sure you intend to delete an
+  administrator account before doing so.
+
+The bootstrap only runs when the runtime schema is initialized or re-initialized
+(for example after a schema version change), not on every request. Operators who
+need tighter control over administrator assignment should edit the `users.role`
+column directly and treat the bootstrap as a recovery mechanism only.
+
 ## Supported Versions
 
 Security fixes are generally provided for the latest release and the latest code on the default branch.