# 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 泄漏。