记录 SPIRE 替代决策并停止项目开发

AGENTS.md

@@ -1,5 +1,12 @@
 # workload-sts - AI Agent Guide
 
+## Project Lifecycle
+
+- 本项目已由 SPIRE 替代并停止开发，详见 `docs/superseded-by-spire.md`。
+- 不再增加功能、依赖、部署物或发布流程；现有代码只作为 PoC 历史保留。
+- 除维护替代决策、修复敏感信息或协助归档外，新的 workload identity 工作应进入独立
+  SPIRE 基础设施项目。
+
 ## Specification-Driven Development
 
 - 所有新功能和外部可观察行为变更都采用 specification-first：先更新

README.md

@@ -1,5 +1,9 @@
 # workload-sts
 
+> **项目已停止开发。** 本方案已由 SPIRE 的 workload attestation、SPIFFE Workload API、
+> JWT-SVID/X.509-SVID 和 OIDC Discovery Provider 替代。仓库仅保留设计与 PoC 历史，
+> 不应部署或继续扩展。详见 [`docs/superseded-by-spire.md`](docs/superseded-by-spire.md)。
+
 面向 workload identity 的 OAuth 2.0 Security Token Service。它验证 Kubernetes
 ServiceAccount JWT 等上游身份，执行签发授权，并生成短期、限定 audience 的 JWT
 assertion。
@@ -7,8 +11,8 @@ assertion。
 项目只负责“验证身份后签发 assertion”。OpenBao 等下游资源服务器自行验证 JWT、
 映射本地权限并管理自己的 token、lease 和凭据生命周期。
 
-项目目前处于 PoC 阶段，尚未提供可运行服务或稳定 API。RFC 8693 请求约束和 OpenBao
+项目在 PoC 阶段停止，未提供可运行服务或稳定 API。仓库中的 RFC 8693 与 OpenBao
-Transit RS256/JWKS 互操作已有可执行测试。
+Transit 代码只用于保存当时的技术验证，不构成受支持的软件。
 
 ## 目标
 
@@ -84,13 +88,13 @@ ID。
 
 ## 文档
 
+- SPIRE 替代决策：[`docs/superseded-by-spire.md`](docs/superseded-by-spire.md)
 - 系统边界与数据流：[`docs/architecture.md`](docs/architecture.md)
 - 规范行为与待决策项：[`docs/specification.md`](docs/specification.md)
 - 威胁模型与安全要求：[`docs/security.md`](docs/security.md)
 - 首轮库与签名 PoC 结论：[`docs/poc.md`](docs/poc.md)
 
-v0.1 规范已经批准；首轮 PoC 决定不引入 Fosite，使用 chi 路由、窄协议层、Go JOSE 和
+其余文档均为替代决策前的历史材料，不再代表实施计划。
-官方 OpenBao API。详见 PoC 文档。
 
 ## 计划中的最小纵向切片
 

docs/architecture.md

@@ -1,5 +1,8 @@
 # 系统架构
 
+> **历史文档：** 本架构已由 SPIRE 方案替代，不再作为实施目标。参见
+> [`superseded-by-spire.md`](superseded-by-spire.md)。
+
 本文是 [`specification.md`](specification.md) 的架构视图。规范定义外部行为，本文解释
 组件边界；二者冲突时以规范为准。当前 v0.1 设计已经批准。
 

docs/poc.md

@@ -1,5 +1,8 @@
 # 首轮协议与签名 PoC
 
+> **历史文档：** 此 PoC 已结束且不会演进为服务。项目由 SPIRE 替代，参见
+> [`superseded-by-spire.md`](superseded-by-spire.md)。
+
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | Complete |

docs/security.md

@@ -1,5 +1,8 @@
 # 安全模型
 
+> **历史文档：** workload-sts 未投入生产，本安全设计已停止实施。替代方案见
+> [`superseded-by-spire.md`](superseded-by-spire.md)。
+
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | Approved |

docs/specification.md

@@ -2,13 +2,16 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 状态 | Approved |
+| 状态 | Superseded by SPIRE |
 | 版本 | v0.1 |
 | 最后更新 | 2026-09-10 |
 
 本文定义 workload-sts 的第一阶段外部合同、范围、安全边界和验收标准。内部包结构和
 具体 OAuth2/JWT/HTTP 库不属于外部兼容性合同。
 
+> 本规格从未进入生产，现已停止实施。替代方案和理由见
+> [`superseded-by-spire.md`](superseded-by-spire.md)。以下内容仅作为历史设计记录。
+
 ## 1. 背景
 
 homelab 中的 Kubernetes workload、CI worker、长期主机以及未来的外部 attestation

docs/superseded-by-spire.md

@@ -0,0 +1,98 @@
+# 由 SPIRE 替代 workload-sts
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | Accepted |
+| 日期 | 2026-09-13 |
+| 影响 | 停止 workload-sts 开发，不部署现有 PoC |
+
+## 决策
+
+停止实现和部署 workload-sts。workload identity 的签发、轮换、workload attestation 与
+OIDC/JWKS federation 改由 SPIRE 提供；OpenBao 继续负责 secret、policy、动态凭据和
+自身 token 生命周期。
+
+仓库保留为设计和 PoC 历史，不删除代码，但不再接受功能开发。若未来出现 SPIRE 和目标
+Resource Server 无法表达的、已经确认的 token transformation 或 credential
+materialization 需求，应基于实际用例重新立项，而不是恢复本规格。
+
+## 原因
+
+workload-sts 原计划自行实现：
+
+```text
+验证 Kubernetes 或其他 workload credential
+  -> workload principal 映射
+  -> audience/scope 策略
+  -> 短期 JWT 签发
+  -> OIDC metadata/JWKS
+```
+
+SPIRE 已原生提供其中决定系统安全性的部分：
+
+- SPIRE Agent 和 Server 执行 node attestation 与 workload attestation；
+- Kubernetes workload 可按 namespace、ServiceAccount 等 selector 注册 SPIFFE ID；
+- Linux、VM 和容器 workload 可使用 Unix、systemd、Docker 及相应 node attestor；
+- workload 通过 SPIFFE Workload API 获取自动轮换的 X.509-SVID 或指定 audience 的
+  JWT-SVID；
+- SPIRE OIDC Discovery Provider 发布 discovery document 和 JWKS，使支持 OIDC/JWT 的
+  Resource Server 可以直接信任 JWT-SVID；
+- SPIFFE federation 与 OIDC federation 覆盖后续跨环境信任。
+
+继续开发 workload-sts 会重复实现 attestation 后的身份签发、密钥轮换和 federation，
+同时引入新的数据库、策略、签名服务和高价值网络端点，安全收益为负。
+
+## 替代架构
+
+面向 OpenBao 的基本流程为：
+
+```text
+workload
+  -> local SPIRE Agent Workload API
+  -> JWT-SVID (sub = SPIFFE ID, aud = OpenBao audience)
+  -> OpenBao JWT auth
+  -> OpenBao client token
+```
+
+OpenBao 直接按受信 issuer、`sub`、audience 和 bound claims 映射 role/policy。本系统不再
+需要 OAuth Token Exchange、内部 principal UUID、Transit JWT signing key 或自己的
+JWKS endpoint。
+
+Kubernetes、长期 Linux 主机、PVE VM 和 microVM 的具体 node/workload attestation 由
+新的 SPIRE 基础设施项目设计。PVE/microVM 生命周期和 vsock metadata 仍属于平台项目，
+不进入身份控制面。
+
+## 不再保留的需求
+
+OAuth `scope` 和集中式 CEL 策略原本作为未来扩展点，但当前没有必须由中间 STS 统一
+表达的实际授权需求。OpenBao policy、Kubernetes RBAC 和各 Resource Server 继续负责
+最终授权。
+
+如果以后出现下列具体需求，再单独评估小型 broker：
+
+- Resource Server 无法直接验证 JWT-SVID；
+- 必须进行跨 trust domain 的 claim/token transformation；
+- 必须返回非 JWT 凭据，且 OpenBao 或目标平台不能原生签发；
+- 已有明确消费者需要 OAuth RFC 8693，而不能直接使用 Workload API。
+
+仅有“未来可能需要 scope”不足以恢复 workload-sts。
+
+## 后续工作
+
+新的 SPIRE 项目需要决定：
+
+1. SPIFFE trust domain 与 SPIFFE ID 命名规范；
+2. SPIRE Server/Agent 的部署和高可用边界；
+3. Kubernetes、长期主机及 VM 的 node/workload attestor；
+4. registration entry 的声明式管理方式；
+5. OIDC Discovery Provider 的稳定 HTTPS issuer；
+6. OpenBao JWT auth role、audience 和 SPIFFE ID 映射；
+7. SVID TTL、key rotation、federation 与灾难恢复。
+
+## 参考资料
+
+- [SPIRE Use Cases](https://spiffe.io/docs/latest/spire-about/use-cases/)
+- [SPIRE Concepts](https://spiffe.io/docs/latest/spire-about/spire-concepts/)
+- [Configuring SPIRE](https://spiffe.io/docs/latest/deploying/configuring/)
+- [SPIRE OIDC federation and scaling](https://spiffe.io/docs/latest/planning/scaling_spire/)
+- [Using SPIRE JWT-SVIDs to authenticate to Vault](https://spiffe.io/docs/latest/keyless/vault/readme/)