Add umbrella validation entry point

2026-04-09 04:38:15 +00:00
parent cdf17bf1c4
commit 3bb0a79057
7 changed files with 78 additions and 13 deletions
--- a/ACCEPTANCE.md
+++ b/ACCEPTANCE.md
@@ -227,6 +227,17 @@
 - Server / Client 类型检查必须全绿
 - 新增联调测试后，happy path 与至少一组安全失败路径必须全绿

+推荐的 umbrella 仓库最小回归入口：
+
+```bash
+./scripts/validate-v1.sh
+```
+
+该脚本会顺序执行：
+- `Yonexus.Protocol`: `npm run test`
+- `Yonexus.Server`: `npm run check && npm run test`
+- `Yonexus.Client`: `npm run check && npm run test`
+
 ---

 ## 8. 当前对应关系
--- a/TASKLIST.md
+++ b/TASKLIST.md
@@ -1112,13 +1112,15 @@
 - [x] 持续补齐中，关键路径已覆盖并继续收尾剩余少量边界场景（2026-04-09）

 **进展补充（2026-04-09）**
- 基于本轮锁定的 v1 边界，`AF-04` 暂保持未覆盖并标记为“语义待确认”，因为当前实现仍把错误 secret 统一归入 `invalid_signature`
- `RP-04`（key rotation）继续保留为 v2+ 议题，与本轮在 `PLAN.md` / `FEAT.md` 固化的 v1 边界保持一致
+- 基于本轮锁定的 v1 边界，`AF-04` 已明确按 v1 语义并入 `invalid_signature`，不再作为“未完成测试缺口”单独追踪；若后续要恢复 `invalid_secret`，需先同步调整协议与实现
+- `RP-03`（管理员主动撤销）与 `RP-04`（key rotation）继续保留为 v2+ 议题，与 `PLAN.md` / `FEAT.md` 的 v1 边界保持一致
 - 已补充 `CF-05`：`hello` 缺失 payload 时返回 `MALFORMED_MESSAGE` 且保持连接可继续诊断
 - 已补充 `SR-04`：Client 首次运行/无凭证状态会自动补 keypair，并在 `hello_ack(pair_required)` 后进入完整配对流，不需要手工预置 state
 - 已同步将 `CF-07`（保留字 rule 注册拒绝）在失败路径矩阵里标记为已覆盖，和现有 Client/Server rule registry 测试保持一致
 - 本轮新增 `CF-01` / `CF-02`：补齐 client transport 在网络分区与首次建连失败时的指数退避重连测试
 - 本轮新增 `SR-02`：补齐 server restart 后 active session 不恢复、但 durable trust record 保留且客户端需要重新 hello/auth 的恢复测试
+- 已新增 umbrella 仓库一键回归入口 `scripts/validate-v1.sh`，把 Protocol / Server / Client 的最小 v1 验证串成单次执行；若某子仓库尚未安装依赖，会直接给出明确提示而不是停在模糊报错
+- 已顺手修复本轮回归暴露的 TypeScript 收尾问题：Protocol payload 泛型约束、Server `pairedAt` 持久化字段、Client/Server config 严格模式报错、测试态 runtime 通知服务注入

 **目标**
 - 系统性覆盖 pairing/auth 失败路径
@@ -1200,12 +1202,10 @@
 - 已同步更新 `tests/failure-path/MATRIX.md`，标记 CF-01、CF-02、PF-08、PF-10、SR-02 为已覆盖

 **当前剩余未覆盖重点**
- AF-04：当前实现未单独暴露 `invalid_secret` 分支，需先决定是否保留该错误码语义
- RP-03 / RP-04：管理员主动撤销与 key rotation 语义仍未实现
+- RP-03 / RP-04：管理员主动撤销与 key rotation 语义仍未实现（按 v2+ 保留）
 - PF-04 当前已覆盖运行时失败路径与通知服务单测，但仍缺少真实 Discord 环境端到端验证

 **待完成**
- AF-04：当前实现未单独暴露 `invalid_secret` 分支，需先决定是否保留该错误码语义
 - RP-03 / RP-04：管理员主动撤销与 key rotation 语义仍未实现
 - 补少量真实环境 smoke test / live validation（非阻塞 v1 交付）

--- a/Yonexus.Client
+++ b/Yonexus.Client
--- a/Yonexus.Protocol
+++ b/Yonexus.Protocol
--- a/Yonexus.Server
+++ b/Yonexus.Server
--- a/scripts/validate-v1.sh
+++ b/scripts/validate-v1.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+run_step() {
+  local title="$1"
+  shift
+
+  echo
+  echo ">>> ${title}"
+  "$@"
+}
+
+ensure_node_modules() {
+  local dir="$1"
+
+  if [[ ! -d "$ROOT_DIR/$dir/node_modules" ]]; then
+    echo "Missing dependencies in $dir (node_modules not found)."
+    echo "Run: (cd '$ROOT_DIR/$dir' && npm install)"
+    return 1
+  fi
+}
+
+run_npm_script() {
+  local dir="$1"
+  local script="$2"
+
+  ensure_node_modules "$dir"
+  run_step "${dir}: npm run ${script}" bash -lc "cd '$ROOT_DIR/$dir' && npm run ${script}"
+}
+
+run_npm_script "Yonexus.Protocol" test
+run_npm_script "Yonexus.Server" check
+run_npm_script "Yonexus.Server" test
+run_npm_script "Yonexus.Client" check
+run_npm_script "Yonexus.Client" test
+
+echo
+printf 'Yonexus v1 validation passed.\n'
--- a/tests/failure-path/MATRIX.md
+++ b/tests/failure-path/MATRIX.md
@@ -7,6 +7,7 @@ This document defines the systematic test coverage for pairing and authenticatio
 - ✅ = Test implemented
 - 🔄 = Test stub exists, needs implementation
 - ⬜ = Not yet implemented
+- ⏸ = Deferred / intentionally out of v1 scope
 - 🔴 = Critical path, high priority

 ---
@@ -35,7 +36,7 @@ This document defines the systematic test coverage for pairing and authenticatio
 | AF-01 | Unknown identifier | Auth from unpaired client | `auth_failed(unknown_identifier)` | ✅ |
 | AF-02 | Not paired | Auth before pairing complete | `auth_failed(not_paired)` | ✅ |
 | AF-03 | Invalid signature | Wrong private key used | `auth_failed(invalid_signature)` | ✅ |
-| AF-04 | Wrong secret | Client has outdated secret | `auth_failed(invalid_secret)` | ⬜ |
+| AF-04 | Wrong secret | Client has outdated secret | 当前实现将其并入 `auth_failed(invalid_signature)`；`invalid_secret` 语义保留待后续确认 | ⏸ |
 | AF-05 | Stale timestamp | Proof timestamp >10s old | `auth_failed(stale_timestamp)` | ✅ |
 | AF-06 | Future timestamp | Proof timestamp in future | `auth_failed(future_timestamp)` | ✅ |
 | AF-07 | Nonce collision | Reused nonce within window | `auth_failed(nonce_collision)` → `re_pair_required` 🔴 | ✅ |
@@ -52,8 +53,8 @@ This document defines the systematic test coverage for pairing and authenticatio
 |----|----------|-------|---------------|---------------|--------|
 | RP-01 | Nonce collision | Replay attack detected | Clear secret, reset state | Enter `pair_required` | ✅ |
 | RP-02 | Rate limit exceeded | Brute force detected | Clear secret, reset state | Enter `pair_required` | ✅ |
-| RP-03 | Admin-initiated | Manual revocation | Mark revoked, notify | Enter `pair_required` | ⬜ |
-| RP-04 | Key rotation | Client sends new public key | Update key, keep secret | Continue with new key | ⬜ |
+| RP-03 | Admin-initiated | Manual revocation | Mark revoked, notify | Enter `pair_required` | ⏸ |
+| RP-04 | Key rotation | Client sends new public key | Update key, keep secret | Continue with new key | ⏸ |

 ---

@@ -132,10 +133,23 @@ npm test -- failure-paths

 ### Current Notes

- AF-04 (`invalid_secret`) 仍未单独覆盖：现有实现把“错误 secret 导致的验签失败”统一落到 `invalid_signature`，是否拆分错误码仍待确认。
- RP-04（key rotation）当前仍视为 v2+ 议题；v1 尚未承诺“无重配对换 key”语义，因此暂不强行补测试。
+- AF-04 (`invalid_secret`) 目前明确按 v1 语义并入 `invalid_signature`，不再单独视为未完成缺口；若后续要保留独立错误码，需要先同步更新协议与实现。
+- RP-03（管理员主动撤销）与 RP-04（key rotation）继续作为 v2+ 议题保留，不阻塞当前 v1 交付判断。
 - 本轮已补齐 AF-01/02/03/05/06/09/10/11、RP-01/02、CF-01/02/03/04/05/07、HF-01/02、PF-08/09/10、SR-01/02/03/04/05/06。

+### Umbrella Validation Entry Point
+
+在 umbrella 仓库根目录可运行：
+
+```bash
+./scripts/validate-v1.sh
+```
+
+它会顺序执行：
+- `Yonexus.Protocol` 测试
+- `Yonexus.Server` 类型检查 + 测试
+- `Yonexus.Client` 类型检查 + 测试
+
 ### Adding New Test Cases

 1. Add row to appropriate table above