初始化项目文档与设计规范

2026-09-11 15:44:26 +00:00
commit cc30a7cb6a
6 changed files with 1181 additions and 0 deletions
@@ -0,0 +1,107 @@
+# workload-sts - AI Agent Guide
+
+## Specification-Driven Development
+
+- 所有新功能和外部可观察行为变更都采用 specification-first：先更新
+  `docs/specification.md` 或对应设计文档，再编写实现。
+- 规格必须在实现前说明范围、非目标、协议行为、验证规则、失败语义、安全边界和验收
+  标准，并达到可由人工作出待决策选择的详细程度。
+- 规格处于 `Review` 时，只能完善设计、测试计划和不冻结实现的实验；获得人工批准前，
+  不得把待决策项当成已确认合同实现。
+- 从批准的验收标准派生测试，再实现使测试通过的最小纵向切片。
+- 实现过程中发现歧义或需要改变已批准行为时，先停止实现，更新规格并重新请求 review。
+- 规格描述外部合同和设计决策；除非构成兼容性合同，不要过早固定 Go package、函数名、
+  SQL schema 或内部模块结构。
+
+## Project Boundary
+
+本项目只负责：
+
+```text
+验证上游 workload credential
+  -> 映射规范化 principal
+  -> 判断是否允许为目标 audience/scope 签发
+  -> 签发短期 JWT assertion
+```
+
+以下内容不属于本项目：
+
+- OpenBao secret、policy、client token、lease、renewal 和 revocation；
+- Kubernetes RBAC 和 ServiceAccount 生命周期；
+- Gitea Actions job、runner 和 workflow 调度；
+- PVE/microVM 生命周期、vsock metadata 和平台 attestation；
+- 人工用户目录、密码、MFA 和交互式登录。
+
+不要为了完成下游集成而把这些职责拉入 workload-sts。需要时只定义标准协议边界和测试
+替身。
+
+## Protocol and Identity Rules
+
+- 优先实现并复用 OAuth 2.0、RFC 8693、JWT、SPIFFE 和 Kubernetes 的标准语义；不得在
+  有成熟标准或库可用时发明私有协议、token 格式或表达式解析器。
+- OAuth issuer 固定为 `https://identity.ad.ddupan.top`；变更 issuer 是破坏性迁移，必须
+  先形成单独规格和迁移计划。
+- SPIFFE 是未来可接入的上游身份协议；第一阶段不把内部 principal 表示成 SPIFFE ID，
+  也不以 URI 命名代替真正的 SVID 验证。
+- 严格区分上游 credential audience 与输出 JWT audience。Kubernetes SA JWT 用于向
+  workload-sts 证明身份；workload-sts JWT 用于访问 OpenBao、Kubernetes 或其他明确的
+  Resource Server。
+- 客户端不能控制输出 `sub`、任意 claims、签名算法或最大 TTL。
+- `client_id` 必填且没有默认值。v1 中它是未经认证的调用方自报审计标签；不得用于
+  principal mapping、授权、输出 claims 或 metric label。未来启用 client authentication
+  时继续使用同一字段，不通过省略字段表达匿名或默认 client。
+- `client_id` 必须匹配 `^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$`，即长度 3–63，且中横线
+  不能位于首尾。不得在不同入口使用更宽松的验证规则。
+- trust binding 至少绑定 credential type、issuer/verifier 和 source subject；不能只按
+  `sub` 建立跨 issuer 信任。
+- SA trust binding 中的 issuance rule 限制 principal、audience 和 scope，并直接绑定唯一
+  token profile；CEL 只处理经过验证的类型化上下文条件。客户端不能请求 profile。CEL
+  错误必须失败关闭。
+- 面向 OpenBao 的 JWT 只是登录 assertion。不得在 workload-sts 中调用 Bao 登录接口或
+  管理随后签发的 Bao token。
+
+## Security-Critical Handling
+
+- subject token、输出 JWT、Authorization header、OAuth client secret、OpenBao token、
+  mTLS 私钥和签名私钥不得进入日志、metric、trace、数据库、测试快照或错误消息。
+- 禁止记录 token endpoint 请求/响应体原文。审计只记录 request ID、受控 issuer/verifier
+  ID、principal、audience、批准后的 scope/profile、policy version、结果和输出 `jti`。
+- JWT verifier 必须校验配置的 issuer、允许算法、signature、audience、`exp` 和 `nbf`；
+  禁止只 decode 不 verify。
+- discovery/JWKS URL 必须由管理员配置。不得根据未验证 token 的 header 或 claim 动态
+  获取任意 URL。
+- 未知 issuer、principal、audience、scope、profile、`kid` 或算法必须拒绝；依赖不可用
+  时失败关闭，不得签发降级 token。
+- 测试必须使用明显的假 token 和独立密钥。不得复制 homelab 的真实 ServiceAccount
+  token、SVID、OpenBao token 或 OAuth 凭据到仓库和测试 artifact。
+- 生产签名私钥不得存入数据库或普通配置。workload-sts 可以使用自己的 Kubernetes
+  identity 获取最小权限 Bao 运行凭据来调用 Transit；不得与客户端的 Bao token 混淆。
+  签名后端与轮换合同以已批准规格为准。
+
+## Documentation Responsibilities
+
+- `README.md` 是项目入口，只描述当前能力、边界和文档导航，不替代规范。
+- `docs/specification.md` 是外部行为、验收标准和已确认决策的权威来源。
+- `docs/architecture.md` 解释组件与信任边界；与规范冲突时以规范为准。
+- `docs/security.md` 记录威胁、缓解措施和发布前安全验收。
+- 已确认决策与待批准决策必须分开。不要把提案、候选默认值或 PoC 结果写成既定事实。
+- 修改协议或 claim 合同时，同时检查 README、architecture、security 和测试是否需要同步。
+
+## Human-Reviewable Changes
+
+- 每次改动聚焦一个行为或决策，不混入无关重构、依赖升级、格式化或清理。
+- 保持每个提交边界可独立 review，并在可行时保持构建和相关测试通过。
+- 达到一个完整提交边界时，先询问用户是否创建 commit；不要未经明确授权提交或推送。
+- 创建或提交 PR 前必须再次请求用户明确授权。提交或推送许可不等于 PR 许可。
+- commit message、PR、issue 和项目文档默认优先使用中文；代码标识符、命令、配置键、
+  RFC 名称和使用英文可避免歧义的技术字段可以保留英文。
+
+## Verification
+
+- 文档改动至少运行 `git diff --check`，并检查链接、示例与已确认决策一致。
+- 实现改动运行与该纵向切片直接相关的格式化、静态检查和测试；具体命令在工具链确定后
+  写入本文件及开发文档。
+- OAuth2/JWT/SPIFFE 互操作行为必须用真实标准实现或官方测试向量验证，不能只测试项目
+  自己的 signer 与 verifier 能互相接受。
+- 安全相关测试至少覆盖错误 issuer、signature、audience、算法、过期时间、未生效时间、
+  claim 注入、权限扩大和 token 泄漏。