feat(studio-3d): 阶段 5 —— 发布保护（签名/可选加密/平台锁定）与性能长时报告

- What: 新增 `scene3d/protect.py`（封套 v2：Ed25519 签名 + 可选 AES-256-GCM，nonce/salt 每包唯一、元数据作 AAD、明文摘要进签名、KeyProvider 只问 get_content_key）与 `record/visualization3d.py` （session.json 的 visualization3d 块：写入版本化、读取时缺块=不支持）；`package.py` 支持 v2 （payload=plain 仅签名 / aes-gcm 签名+加密）并继续读 v1，新增解压比上限与"写入后自读回"校验； `contracts.py` 新增 PlatformLock/PlatformInfo/check_platform_lock、Sealing、platform_mismatch 诊断码； `Scene3DView` 在装配前查 OS/架构、拿到 capabilities 后查图形半区，违反即撤下场景并在面板显示原因；工具 `compile_scene.py` 新增 --sign-key/--write-verify-key/--encrypt-key-id/--key-file/--lock-from-probe， `validate_scene.py` 新增 --key-file/--key-id/--verify-key/--require-signature（发布门禁），新增 `bench_scene.py`（p50/p95 分阶段 + --cpu-only + --vertices N + --package）与 `soak_scene.py`（RSS 四分位速率 + 队列上界 + 抽稀采样）；两份报告落到 docs/architecture/。 - Why: 规格 §5.2 的保护目标是"提高复制成本"而不是"防提取"，所以要的是签名（来源）+ 可选认证加密（机密性） + 密钥隔离，而不是自制加密或把 ZIP 当加密；§12 的"包保护/性能/长时"三行需要可复现的数字与判定标准，而不是一次性的观感。平台锁定还必须只降级三维：锁定不通过时二维照常。 - Verification: shared 全量通过（新增 test_scene3d_protect.py 35 项：封套往返/篡改/密钥/锁定/记录块/ compile→validate 端到端发布流程；test_scene3d_package.py 20 项含 v1↔v2 兼容）；apps/studio 全量通过（test_scene3d_view.py 30 项含锁定拒绝与 session.json 块）；ui_check 566 项 0 失败；locale_check 0 缺失；真实资产端到端：1032 顶点编译出 signed+sealed+locked 包（56 927 B 密文），validate --require-signature 退出 0，改一个字节退出 2；性能报告（perf-report-windows-dev.json）：1032 顶点 compose p50 0.50 ms（30 fps 上限内）， 20022 顶点/39480 三角形 compose p50 6.15 ms（约 33 ms 帧的 18%），采集线程 submit p95 < 0.4 ms（合成器被人为放慢到 50 ms）；长时报告（soak-report-windows-dev.json）：无窗口 10 min/60 fps 尾段 0.354 MB/min，GUI 4 min/30 fps 尾段 0.809 MB/min，队列上界（mailbox=1、单飞行合成）两者均成立。过程中修掉：GUI 进程里的合成器计时被 GIL/vsync 污染（98.8 ms vs 真值 6.1 ms）、跨线程读 last_stats 撕裂、key id 无 provider 时会静默写明文包、soak 工具自身记时间列表会无界增长、RSS 读取失败伪装成零增长、平台锁定不是终态诊断。 - Not in this change: ARM 板卡的能力报告与 2 小时门禁运行（按用户要求暂缓；命令与判定标准已写入阶段 5 文档）； GPU 显存随时间的测量（无可移植 API，报告说明渲染器缓冲估计恒定且更新路径不新建 GPU 对象）； `cryptography` 在此环境无法联网安装，本机验收用的是本机已有的 cp310 构建（pyproject 里已声明为可选 extra `protected-assets`）。
2026-09-14 16:44:33 +08:00
parent ac4dcd643f
commit 5cd92254e1
24 changed files with 5448 additions and 188 deletions
@@ -143,9 +143,26 @@ def _legacy_report(args) -> tuple[int, dict]:
    return (0 if report["status"] == "ok" else 2), report


+def _load_keys(args):
+    """The key provider and verification key the arguments describe, if any."""
+    from orisys_app_shared.scene3d import protect
+
+    provider = None
+    if args.key_file is not None:
+        provider = protect.load_key_file(Path(args.key_file), key_id=args.key_id)
+    verify = None
+    if args.verify_key is not None:
+        path = Path(args.verify_key)
+        if not path.is_file():
+            raise SystemExit(f"the verification key is missing: {path}")
+        verify = path.read_bytes()
+    return provider, verify
+
+
 def _package_report(args) -> tuple[int, dict]:
    from orisys_app_shared.scene3d.contracts import ExpectedGeometry, ThreeDError
    from orisys_app_shared.scene3d.package import (
+        describe_envelope,
        describe_package,
        read_package,
        scene_from_contents,
@@ -157,14 +174,64 @@ def _package_report(args) -> tuple[int, dict]:
        report["checks"].append({"check": name, "ok": bool(ok), "detail": detail})

    try:
-        contents = read_package(Path(args.asset))
-        record("envelope, manifest and every entry hash", True)
-    except ThreeDError as exc:
-        record("envelope, manifest and every entry hash", False,
-               f"{exc.diagnostic.code}: {exc.diagnostic.message}")
+        provider, verify = _load_keys(args)
+    except SystemExit as exc:
+        record("key material", False, str(exc))
        report["status"] = "rejected"
        return 2, report
-    report["manifest"] = describe_package(Path(args.asset))
+
+    # What the container says about itself, *without* a key: a support engineer can
+    # report "sealed for key id X, signed by Y" without being able to read it.
+    try:
+        report["envelope"] = describe_envelope(Path(args.asset))
+        record(
+            "envelope reads",
+            True,
+            f"v{report['envelope'].get('envelope_version')} "
+            f"{report['envelope'].get('payload')}"
+            f"{' signed' if report['envelope'].get('signed') else ' unsigned'}",
+        )
+    except ThreeDError as exc:
+        record("envelope reads", False, f"{exc.diagnostic.code}: {exc.diagnostic.message}")
+        report["status"] = "rejected"
+        return 2, report
+    if report["envelope"].get("signed"):
+        record("package is signed", True, str(report["envelope"].get("signing_key") or ""))
+    else:
+        # A warning by default, a hard failure when the caller says this is a release:
+        # an engineering package is legitimately plain, and a release package that is
+        # plain has no origin, which is the design document's step 2.
+        record(
+            "package is signed",
+            not args.require_signature,
+            "unsigned: integrity only, no origin (use --require-signature for a release "
+            "build) "
+            if not args.require_signature
+            else "unsigned: a release package must be signed",
+        )
+
+    try:
+        contents = read_package(Path(args.asset), keys=provider, verify_key_pem=verify)
+        record("signature, envelope, manifest and every entry hash", True)
+    except ThreeDError as exc:
+        record(
+            "signature, envelope, manifest and every entry hash",
+            False,
+            f"{exc.diagnostic.code}: {exc.diagnostic.message}",
+        )
+        report["status"] = "rejected"
+        return 2, report
+    report["manifest"] = describe_package(
+        Path(args.asset), keys=provider, verify_key_pem=verify
+    )
+    lock = report["manifest"].get("platform_lock")
+    if lock:
+        record(
+            "platform lock of this package",
+            True,
+            f"{lock.get('os_family') or 'any OS'} / {lock.get('machine') or 'any arch'}"
+            f"{' / ' + str(lock.get('gl_profile')) if lock.get('gl_profile') else ''}",
+        )
    try:
        expected = (
            ExpectedGeometry(
@@ -199,6 +266,24 @@ def main(argv: list[str] | None = None) -> int:
    )
    parser.add_argument("--sensor-model", default="finger")
    parser.add_argument("--hardware-revision", default="*")
+    parser.add_argument(
+        "--key-file",
+        type=Path,
+        default=None,
+        help="content key for a sealed package (hex, base64 or raw)",
+    )
+    parser.add_argument("--key-id", default="", help="key id that --key-file holds")
+    parser.add_argument(
+        "--verify-key",
+        type=Path,
+        default=None,
+        help="Ed25519 public key (PEM) a signed package must verify against",
+    )
+    parser.add_argument(
+        "--require-signature",
+        action="store_true",
+        help="treat an unsigned package as a failure: the release gate",
+    )
    parser.add_argument("--json", action="store_true", help="machine-readable output")
    args = parser.parse_args(argv)

@@ -221,7 +306,7 @@ def main(argv: list[str] | None = None) -> int:
        for item in report.get("checks", []):
            mark = "ok  " if item["ok"] else "FAIL"
            print(f"  {mark} {item['check']}  {item['detail']}")
-        for key in ("field_domain", "mesh", "uv_correspondence", "scale", "binding"):
+        for key in ("envelope", "field_domain", "mesh", "uv_correspondence", "scale", "binding"):
            if key in report:
                print(f"  {key}: {json.dumps(report[key], ensure_ascii=False, default=str)}")
        if "note" in report: