opc/soft_quay_web
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a89821a5718c43551349018a7f2709b0f2f5e34f
soft_quay_web/docs/02-requirements.md
T
ilaandClaude Fable 5 a89821a571 Initialize harness coding docs from design spec 
Split docs/softbox-catalog-design.md into the numbered harness doc set
(00-06, api.md, current-state, agent-context, tasks) following the
harness_coding_docs template and soft_quay conventions. Register the
nine open decision items from the design spec into the 06-tasks
roadmap as W- tasks and backlog entries. Keep the original design
spec as an archived design input with a header note.

Recreated after the repository's previous git history was lost to an
external reset; content matches the original initial commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-20 00:43:58 +08:00

5.9 KiB
Raw Blame History

需求

本文只描述要什么与怎么算达成,不涉及技术实现。 技术方案、组件边界见 架构设计;协议字段见 协议合约(权威源为客户端仓库 soft_quay)。

一、业务现状

项 状态
客户端 soft_quay 已完成 Phase 0~4:清单验签、下载、安装、更新、自更新均可运行,但真实 Catalog 来源未配置,显示 catalog_source_unconfigured
协议 清单 / 包 / 许可证协议 v1 已在 soft_quay/docs/api.md + schemas/ 定稿;canonicalization corpus 已冻结(soft_quay/T-614)
发布侧 本仓库为全新项目,尚无代码;客户端当前 blocker 之一就是缺可信发布源
约束 客户端不做在线校验;下架、撤销、兼容都必须离线表达在签名文件里

二、用户角色

  • 发布者(操作者):登记软件、触发发布 / 下架 / 撤销、签发许可证、查看审计。
  • 子软件 CI:提交标准 ZIP 候选包与 Release 元数据。
  • soft_quay 客户端:只消费对象存储 / CDN 上的静态签名文件,不访问本系统任何接口。

三、功能清单

第一版(按阶段交付,阶段见 任务路线图)

功能 发布者能做什么 优先级
协议对齐签名 产出与客户端字节级一致的规范 JSON + Ed25519 签名;corpus 全向量回归通过 P0
Schema 校验 发布前自动校验 manifest / app.json 合规,不合规拒绝发布 P0
双通道清单生成 一键产出 manifest-modern.json / manifest-win7.json,通道互不交叉 P0
本地静态发布模拟 本地生成签名清单 + 静态 HTTP 服务,客户端可跑通「清单→下载→安装」闭环 P0
软件登记 维护每款软件的元数据(id/name/version/channel/status/…) P1
构建包接收校验 接收 CI 的 ZIP 候选包,校验结构与声明一致性,计算 size/SHA-256 P1
发布记录 每次发布登记 url/size/sha256/signature 坐标,可浏览历史 P1
正式发布 原子上传对象存储 / CDN:先包后清单 P1
签名服务隔离 私钥进 KMS/HSM 或独立签名服务;Web 端只经受控接口请求签名 P1
下架与撤销 用 status 下架软件;维护签名的许可证撤销名单 P2
许可证签发 绑定 machine_hash + products 签发 Ed25519 许可证 P2
Web 管理后台 登记 / 发布 / 下架 / 撤销 / 签发 / 审计查看的操作界面 P2
审计 每次发布 / 下架 / 撤销 / 签发的 append-only 记录 P2

后续迭代(记录不实现)

功能 描述
密钥轮换 需先与客户端协调协议升级(key ID 字段);单公钥期间禁止另造签名域
package.signature 独立验签域 v1 客户端不独立验证;定义待签名字节 + 公钥域后再实现
图标分发映射 sha256: 内容哈希到实际下载位置 / 分辨率变体的发布端映射
多操作者与审批流 多人权限模型、发布审批;首期单操作者

四、核心用户故事

  1. 作为发布者,我在本地用测试密钥对生成一份签名清单,soft_quay 客户端验签通过并显示软件列表——这是第一里程碑,在任何 UI 之前达成。
  2. 子软件 CI 产出 json-parser_1.4.2_windows_amd64.zip 后,我把它提交给发布系统;系统校验包结构与登记信息一致、算出 size/SHA-256,生成新清单、签名并发布;客户端下次刷新即看到新版本。
  3. 我下架一款软件时,只改它的 status,不改名;客户端按 status 过滤,旧用户不受影响。
  4. 我给一台机器签发许可证时,只提交 machine_hash 与产品列表;系统不保存任何原始硬件序列号。
  5. 任何人拿到发布系统的数据库或 Web 服务器权限,都拿不到签名私钥;伪造清单在客户端必然验签失败。

五、验收标准

  • 字节级对齐:对 corpus 中每个合法向量,本系统 canonicalizer 产出的规范字节与 signed_payload_base64 逐字节一致;每个非法向量按 want_error 拒绝;期望值不得自举。
  • 客户端验签:生成的 manifest 被 soft_quay 客户端(内置对应测试公钥)验签通过;篡改任一字节后验签失败。
  • Schema 合规:不合规清单(未知字段、重复 id、非法 SemVer、architectures 与 packages 不对应、非 HTTPS URL)被拒绝且有明确错误信息。
  • 通道隔离:win7 清单中不出现 min_os 高于 win7 或仅 modern 的包;两清单 channel 字段正确。
  • 发布原子性:清单可见时,其引用的所有包与图标已可下载;模拟"清单先于包"的发布被系统拒绝。
  • 私钥隔离:代码库、配置样例、日志、数据库 dump 中均无私钥材料;签名只能通过受控接口对已知结构进行。
  • Ingestion:包结构非法、app.json 与登记不一致、声明版本 / 架构不符的候选包被拒绝并给出原因。
  • 审计:每次发布 / 下架 / 撤销 / 签发均产生含操作者、时间、内容摘要、签名指纹的记录;记录不可修改。

六、范围边界与决策

问题 决策
客户端接口 无;客户端只拉静态文件,本系统无面向客户端的运行时 API
账号体系 首期单发布者;多操作者 / 审批流为后续迭代(裁定项 W-501)
首期部署 本地 / 静态文件模拟,不先建正式对象存储
首期密钥 离线生成的测试密钥对(与客户端内置测试公钥、corpus 配对);正式私钥管理另裁(W-003)
包目标 只登记实际支持并测试过的目标,不生成占位包

七、待确认 / 风险点

设计规格 §十 的九个未定项已全部登记为裁定任务或 Backlog,映射见 任务路线图 的「未定项裁定清单」。其中立项前必须裁定的是:签名私钥管理(W-003)、协议权威源引用方式(W-001 内裁定)、正式域名与对象存储(W-004,Phase 3 前)。

Reference in New Issue View Git Blame Copy Permalink