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

2026-09-11 15:44:26 +00:00
commit cc30a7cb6a
6 changed files with 1181 additions and 0 deletions
@@ -0,0 +1,183 @@
+# 系统架构
+
+本文是 [`specification.md`](specification.md) 的架构视图。规范定义外部行为，本文解释
+组件边界；二者冲突时以规范为准。当前 v0.1 设计已经批准。
+
+## 组件与数据流
+
+```text
+                  Kubernetes SA JWT
+                              |
+                              v
+                    Credential Verifiers
+                              |
+                              v
+                    Principal Normalization
+                              |
+                              v
+              Issuance Policy + CEL Conditions
+                              |
+                              v
+                   OAuth 2.0 Token Endpoint
+                              |
+                              v
+                   Audience-bound JWT Issuer
+                              |
+             +----------------+----------------+
+             |                                 |
+             v                                 v
+     OpenBao JWT auth                Kubernetes/API service
+             |                                 |
+             v                                 v
+      OpenBao client token             Native authorization
+```
+
+服务验证上游 credential，但不把它直接转发给下游。签发决策成功后生成新的 JWT，
+其 issuer、audience、TTL 和 claims 由本服务控制。
+
+下游资源服务器负责最终授权。OpenBao 根据 JWT auth role 和 policy 签发自己的 client
+token；Kubernetes 根据外部 JWT authenticator 和 RBAC 授权。本服务不复制这些权限模型。
+
+## 组件边界
+
+### OAuth 2.0 协议层
+
+协议层负责 Authorization Server metadata、token endpoint、标准 OAuth2 错误和响应。
+第一阶段只实现 RFC 8693 Token Exchange 所需子集，不实现交互式用户登录。
+
+协议层只实现已批准的 RFC 8693 子集。HTTP 路由和 middleware 使用与 `net/http` 兼容的
+`chi/v5`，OAuth 表单仍由 Go 标准库显式解析，不使用框架自动 binding；JOSE 与 OpenBao
+调用使用成熟库。首轮 PoC 发现现有 OAuth2 框架仍需自定义 token
+exchange、client store 适配和 Transit signer，不能减少本项目的核心安全逻辑，因此 v0.1
+不引入完整 Authorization Server 框架。业务代码仍将 credential verification、授权和
+token materialization 保持为独立边界。详见 [`poc.md`](poc.md)。
+
+HTTP router 外层使用 `otelhttp` 生成 server span 和标准 HTTP metrics。span 与 metric 只使用
+固定路由模板及受控低基数字段，不捕获请求/响应 body、Authorization header、
+`subject_token`、输出 token、`client_id`、principal 或 `jti`。trace 与 metric provider
+通过启动依赖注入；未配置 exporter 时保持 no-op，不把 telemetry 输出到标准输出。
+
+### Credential Verifier
+
+每种 verifier 把特定上游凭据转换为不可伪造的内部事实：
+
+```text
+issuer
+source subject
+source credential type
+source audiences
+issued-at / expiry
+verified attributes
+verification method
+```
+
+verifier 不能直接决定目标 audience 或输出 claims。未经验证的请求字段不能进入
+`verified attributes`。
+
+第一阶段支持：
+
+- Kubernetes projected ServiceAccount JWT。
+
+OIDC、SPIFFE、云 workload identity 和外部 metadata 系统以后以 verifier 扩展，不改变
+token endpoint 合同。不同 credential issuer 可以使用不同验证逻辑，但 upstream issuer
+不是 OAuth client。
+
+所有 token request 都必须携带 `client_id`。v1 的 client authentication method 为
+`none`，因此该值只以 `client_id_claimed` 进入审计，不参与身份映射或授权。以后可以为
+同一字段增加 public client registration、mTLS 或 `private_key_jwt` 认证，无需改变请求
+是否包含 `client_id` 的合同。
+
+`client_id` 使用 3–63 字符的 DNS-label-like 语法，只允许小写字母、数字和中横线，且
+中横线不能位于首尾。
+
+### Principal Normalization
+
+trust binding 把上游 verifier 与 source subject 映射为稳定、不可变的内部 principal：
+
+```text
+sub = 01993f4d-5e1a-7000-8000-000000000001
+principal_name = ci/homelab-infra-plan
+```
+
+可读名称允许受控改名，JWT `sub` 使用的 ID 不随名称变化。映射规则由管理员配置；
+客户端不能在 token 请求中选择或覆盖 `sub`。一个上游身份可以没有任何映射，此时认证
+成功但 token exchange 被拒绝。
+
+### Issuance Policy
+
+授权层只回答：
+
+> 某个已验证 principal 是否可以为指定 audience 和 scope 获取 JWT？
+
+trust binding 中的 issuance rule 先限制 principal、audience 和 scope，并直接绑定唯一
+token profile；CEL 只表达需要结合已验证上下文的条件。客户端不能请求 profile。CEL
+不能调用网络、读取机密或修改状态。
+
+授权层不决定 OpenBao secret path、Bao token TTL 或 Kubernetes RBAC。
+
+### JWT Issuer
+
+JWT issuer 根据批准的 token profile 生成 claims 并请求签名后端签名。客户端只能请求
+允许缩小权限的参数，不能直接提交输出 `sub`、任意 claim、签名算法或 TTL。
+
+生产签名密钥保存在 OpenBao Transit 中；数据库和服务实例不保存私钥。
+workload-sts 使用自己的 Kubernetes ServiceAccount JWT 登录 OpenBao，取得只允许访问
+指定 Transit key 的短期运行凭据。它不替客户端登录 OpenBao，也不接触客户端随后取得
+的 Bao token。第一阶段使用 RS256；签名后端保留接口边界，以便单元测试使用内存
+signer。密钥轮换的具体运维合同在部署设计中补充。
+
+### Database
+
+HTTP 实例无本地持久状态。数据库保存配置及需要一致性的控制面状态，例如：
+
+- upstream issuer 与 verifier 配置；
+- trust binding；
+- principal、audience、scope 与 token profile；
+- CEL policy 及版本；
+- 调用方自报 `client_id` 的有界审计值；
+- 审计索引和配置变更记录。
+
+数据库不得保存 bearer token、原始 subject token、OpenBao client token 或签名私钥。
+自包含 JWT 的普通验证不依赖数据库在线 introspection。
+
+## Kubernetes 信任方向
+
+系统明确区分两条方向相反的链：
+
+```text
+Kubernetes SA JWT -> workload-sts
+```
+
+projected ServiceAccount JWT 的 audience 是 workload-sts，用于证明 Pod 的上游身份。
+
+```text
+workload-sts JWT -> kube-apiserver
+```
+
+目标 audience 是特定 Kubernetes cluster。kube-apiserver 通过外部 JWT authenticator
+验证 issuer 和 claims，再交由 RBAC 授权。workload-sts 不签发 Kubernetes
+ServiceAccount token。
+
+## 外部 workload attestation
+
+PVE、microVM、vsock metadata、Gitea runner 调度和云 metadata 不属于本仓库。对应系统
+以后可以输出本服务可验证的标准身份载体，例如 JWT-SVID 或已登记 issuer 的 JWT。
+
+本服务不依赖或理解 VMID、vsock CID、Gitea job 环境变量、runner registration token
+或虚拟机生命周期。外部系统负责防重放、实例代际和 attestation，本服务负责验证其最终
+credential 并执行签发策略。
+
+## 部署边界
+
+系统是无状态 HTTP 服务加数据库，可以部署在 Kubernetes、VM 或其他运行环境。部署位置
+不是信任语义的一部分；OAuth issuer 必须保持为稳定的
+`https://identity.ad.ddupan.top`。
+
+workload-sts 依赖 OpenBao Transit 完成生产签名，但只使用自己的最小权限运行身份；
+OpenBao 的人工管理与 break-glass 路径不得反向依赖 workload-sts。
+
+## 文档入口
+
+- 规范行为与验收标准：[`specification.md`](specification.md)
+- 威胁模型与安全要求：[`security.md`](security.md)
+- 首轮库与签名 PoC：[`poc.md`](poc.md)
@@ -0,0 +1,114 @@
+# 首轮协议与签名 PoC
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | Complete |
+| 日期 | 2026-09-10 |
+
+本 PoC 为 v0.1 实现选择验证 HTTP/OAuth2 库边界，以及 OpenBao Transit RS256 能否生成
+由标准 JOSE 实现验证的 JWT/JWKS。
+
+## OAuth2 框架
+
+检查了 Fosite v0.49.0 的公开文档和 token endpoint 实现。Fosite 支持自定义
+`TokenEndpointHandler`，extension grant 可以通过 `CanSkipClientAuth` 跳过 client
+authentication，但它没有现成的 RFC 8693 Token Exchange handler。
+
+`NewAccessRequest` 仍会先执行 Fosite 的 client authentication/store lookup。v1 的
+`client_id` 是不注册、不认证的必填审计标签，因此要接入 Fosite 需要：
+
+- 自定义 RFC 8693 request/response handler；
+- 绕开或适配 Fosite client store；
+- 自定义 Transit-backed JWT strategy；
+- 禁用本项目不提供的 authorize、refresh、OIDC、introspection 和 revocation 功能。
+
+这套适配没有替项目减少核心安全逻辑，却引入了与 v1 不一致的 client/storage 模型。
+因此 v0.1 不采用 Fosite，也不把它加入运行依赖。
+
+v0.1 使用：
+
+- Go `net/http` 与 `net/url` 处理窄 token endpoint；
+- `chi/v5` 只承担路由和标准 `net/http` middleware 组合，不接管 OAuth 表单 binding；
+- 项目代码执行 RFC 8693 子集的字段约束和 OAuth 错误映射；
+- `go-jose/v4` 作为独立 JWS/JWK 互操作验证实现；
+- 官方 `openbao/api/v2` 调用 Transit。
+
+若未来加入完整 client registration、多个 grant 或 authorization endpoint，应重新评估
+Fosite 或独立 Authorization Server 产品。
+
+HTTP 层比较了 chi 与 Echo。Echo 的集中错误处理和自动 binding 对通用 Web API 很方便，
+但本项目只有少量固定端点，OAuth 表单又需要显式约束字段来源。选择 chi 可以直接暴露
+`http.Handler`、复用标准 middleware，并避免引入第二套 handler context 和未使用的
+binding/rendering 抽象。
+
+HTTP server instrumentation 使用官方 `otelhttp`，并启用 OpenTelemetry Go trace/metric
+SDK 的依赖注入边界。SDK 不记录 HTTP body；项目也不启用 header capture。OTLP exporter
+类型留给进程启动配置选择，避免把 collector 的 gRPC/HTTP 拓扑固化进协议层。
+当前采用 OpenTelemetry Go SDK v1.46.0；`otelhttp` 随 contrib instrumentation 独立采用
+v0.71.0，仍属于其 experimental instrumentation version set，因此升级时需要单独检查
+HTTP semantic convention 与 metric 名称变化。
+
+## Transit RS256
+
+PoC 使用本地临时 OpenBao v2.6.1 dev server，创建不可导出的 `rsa-2048` Transit key，
+验证以下链路：
+
+```text
+读取 Transit key metadata
+  -> 固定 latest_version
+  -> kid = workload-sts-v<version>
+  -> 构造 RS256 protected header 与 claims
+  -> 使用同一 key_version 请求 Transit 签名
+  -> 从 Transit public_key 生成 JWKS
+  -> go-jose 解析 compact JWT
+  -> 使用 JWKS 中相同 kid 的 RSA 公钥验签
+```
+
+测试结果为通过。Transit 调用使用：
+
+```text
+path:                transit/sign/workload-sts/sha2-256
+key type:            rsa-2048
+signature_algorithm: pkcs1v15
+key_version:         显式指定
+input:               base64(JWS signing input)
+```
+
+### PoC 发现
+
+`kid` 必须在构造 JWS protected header 前确定，因此 signer 先读取 active Transit key
+version，再用该 version 签名。不能使用“签名后从 `vault:vN:` 响应推导 `kid`”的流程，
+因为修改 header 会改变 signing input。
+
+签名响应为 `vault:vN:<base64-signature>`。实现验证响应 version 与请求 version 一致，
+并将原始 RSA signature 转为 JWS 使用的 Base64URL 编码。
+
+JWKS 为 Transit metadata 中所有保留版本发布独立 key，`kid` 包含 key version，使轮换前
+签发且尚未过期的 JWT 仍可验证。
+
+## 可执行验证
+
+纯单元和互操作测试：
+
+```sh
+make test
+```
+
+真实 Transit 集成测试需要一个仅用于测试、已经启用 `transit/` 并创建
+`transit/keys/workload-sts` RSA key 的 OpenBao：
+
+```sh
+export WORKLOAD_STS_TEST_BAO_ADDR=http://127.0.0.1:8200
+export WORKLOAD_STS_TEST_BAO_TOKEN=test-only-token
+make test-transit
+```
+
+集成测试只读取 key metadata 和请求签名，不创建、轮换或删除 Transit key。
+
+## 尚未覆盖
+
+- OpenBao JWT auth 对输出 JWT 的实际登录验证；
+- kube-apiserver 外部 JWT authenticator 的实际验证；
+- Transit key rotation 后新旧 `kid` 的端到端验证；
+- workload-sts 自身通过 Kubernetes auth 获取最小权限 Transit token；
+- HTTP token endpoint、TokenReview、binding/CEL 和 PostgreSQL policy version。
@@ -0,0 +1,166 @@
+# 安全模型
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | Approved |
+| 最后更新 | 2026-09-10 |
+
+## 保护目标
+
+- 只有通过可信 verifier 验证并匹配 trust binding 的 workload 才能取得 JWT。
+- 签发的 JWT 只能用于明确的 audience，且权限不能超过 SA binding 的 issuance rule。
+- 客户端不能控制输出 subject、任意 claims、签名算法或最大 TTL。
+- subject token、输出 bearer token 和签名私钥不得进入数据库、日志、metric 或 trace。
+- 一个 issuer、principal 或策略配置错误不能静默扩大为所有 audience 的访问权。
+- OpenBao 与 Kubernetes 保留各自的最终授权权威。
+
+## 信任边界
+
+平台管理员可以配置 verifier、trust binding、audience、token profile 和 policy，因此是
+本系统的高信任主体。上游 issuer 管理员能够为其信任域签发身份；其权限必须通过
+trust binding 限制，不能因 issuer 被信任就获得所有 audience。
+
+OpenBao Transit 保管 JWT 签名私钥。workload-sts 使用自己的 Kubernetes ServiceAccount
+JWT 登录 OpenBao，并取得只能请求指定 Transit key 签名和读取其公钥所需信息的短期
+运行凭据。该凭据与客户端通过 JWT auth 获得的 Bao token 是不同安全域。资源服务器
+通过 HTTPS 获取 metadata/JWKS 或使用固定信任配置验证 JWT。
+
+数据库管理员可以改变签发配置，等价于 IAM 管理员；数据库备份和迁移必须按高敏感配置
+处理，即使其中没有 bearer token 或私钥。
+
+## 主要威胁
+
+### Subject token 重放
+
+攻击者取得尚未过期的 Kubernetes JWT 或 JWT-SVID 后可能重复交换。缓解措施包括：
+
+- 上游 token 必须使用短 TTL；
+- 严格校验其 audience 为 workload-sts；
+- 输出 JWT 使用短 TTL 和独立 audience；
+- 高风险 profile 可以要求在线状态验证或一次性机制；
+- 日志以安全指纹关联重复请求，不保存完整 token。
+
+是否对所有 subject token 实现全局 `jti` 单次消费仍待决定；默认不能假定标准
+ServiceAccount JWT 只能交换一次。
+
+### Audience confusion
+
+验证必须检查上游 token 的 audience，而不只检查签名和 issuer。输出 token 的 `aud`
+必须来自已登记 audience，禁止接受自由字符串后原样签入 JWT。
+
+不同 Kubernetes cluster、OpenBao 实例和普通 API 应使用不同 audience。资源服务器必须
+拒绝没有自己 audience 的 token。
+
+### Issuer confusion
+
+不能只按 JWT `sub` 映射 principal。trust binding 至少绑定：
+
+```text
+credential type + issuer + source subject
+```
+
+同名 ServiceAccount 在不同 cluster 中是不同来源。issuer discovery、JWKS URL 和允许的
+签名算法必须由管理员配置，不能由未验证 token 中的 URL 动态决定。
+
+### Claim injection 与权限扩大
+
+请求中的 `scope`、`audience` 和 `client_id` 都是不可信输入。`scope` 和 `audience` 只
+表示请求上限；v1 的必填 `client_id` 只用于审计且没有默认值。输出 claims 由 verifier
+事实、trust binding、issuance rule 和服务端 token profile 共同生成。
+
+CEL 只能读取经过类型化的上下文。未经验证的 Gitea repository、workflow、branch、
+job ID、HTTP header 或自报 SPIFFE ID 不能用于扩大权限。
+
+### Algorithm 与密钥混淆
+
+- 每个 issuer 固定允许的算法集合；
+- 拒绝 `none` 和未配置算法；
+- 不根据 JWT header 中的任意 URL 获取密钥；
+- `kid` 必须解析到对应 issuer 的已知密钥；
+- 签名与验证密钥用途分离；
+- 轮换时同时发布当前及仍覆盖有效 token 的旧公钥。
+
+### SSRF 与 discovery
+
+上游 issuer、discovery URL 和 JWKS URL 是管理员配置，不从 token exchange 请求动态
+创建。HTTP client 必须设置超时、响应大小上限和可接受的 TLS 信任；默认拒绝重定向到
+未批准 origin。
+
+### 策略拒绝服务
+
+CEL 环境只暴露固定变量和函数，限制表达式大小、编译时间与运行成本。策略在发布前编译
+验证；无效策略不能替换最后一个有效版本。求值错误按拒绝签发处理。
+
+## Kubernetes ServiceAccount JWT
+
+- 只接受 projected、带过期时间和明确 audience 的 token；
+- 使用 TokenReview 校验身份和 audience，并检查返回的兼容 audience；
+- cluster identity 属于 verifier 配置，不能只由 token 的通用 issuer 名推导；
+- TokenReview 不可用或失败时不得自动降级为离线 JWKS；
+- token 中的 namespace、ServiceAccount、Pod 和 Node 信息只有经过 TokenReview 返回的
+ 已认证 user/extra 信息确认后才能进入 policy context。
+
+## 未来的 SPIFFE verifier
+
+SPIFFE 不属于第一阶段。未来接入时必须验证真正的 SVID 和 trust bundle，不能仅把内部
+principal 写成 `spiffe://` URI：
+
+- JWT-SVID 必须校验 trust bundle、audience 和时效；
+- X.509-SVID 只能通过完成验证的 mTLS 连接接受；
+- 不能接受普通 header 中自报的 SPIFFE ID；
+- SPIFFE ID 到内部 principal 的 trust binding 必须显式配置。
+
+## Token 签发
+
+- 输出 JWT 必须包含 `iss`、`sub`、`aud`、`iat`、`nbf`、`exp` 和唯一 `jti`；
+- 默认不签发 refresh token；
+- token profile 由匹配身份的 trust binding/issuance rule 唯一确定，并定义 TTL 和允许
+  claims；
+- 客户端可以请求更少 scope，不能请求 TTL 或扩大 scope；
+- JWT 中不放置 secret、上游原始 token 或无界个人信息；
+- 面向 OpenBao 的 JWT 只是登录 assertion，不是 Bao client token。
+
+## 日志与审计
+
+允许记录：
+
+- request ID；
+- 上游 issuer ID 和 credential type；
+- 规范化 principal；
+- 目标 audience、批准后的 scope/profile；
+- 自报 `client_id_claimed`（每个 v1 请求必有，明确标记为未经认证）；
+- policy/version；
+- 结果、错误类别、输出 JWT `jti` 和时间。
+
+禁止记录：
+
+- Authorization header；
+- subject token 或输出 JWT；
+- mTLS 私钥或完整证书链；
+- OpenBao token；
+- OAuth client secret；
+- token endpoint 请求/响应体原文。
+
+OpenTelemetry HTTP instrumentation 不得配置 request/response body 或 Authorization、
+Cookie 等凭据 header 捕获。span name 和 `http.route` 只能使用固定路由模板；原始 URL
+query、`client_id_claimed`、principal、subject、scope 和 `jti` 不得成为 HTTP metric
+label。业务 scope/profile 指标只能使用管理员配置的受控枚举。
+
+## 发布前安全验收
+
+- 错误 issuer、签名、audience、算法、过期时间和未生效时间均被拒绝。
+- 同名但来自另一 Kubernetes cluster 的 ServiceAccount 不能匹配 trust binding。
+- 客户端不能通过请求 audience、scope、TTL 或 claims 扩大授权，且不能请求 token
+  profile。
+- 缺少或格式错误的 `client_id` 被拒绝；改变合法 `client_id` 不改变 principal、授权、
+  profile 或输出 claims。
+- `client_id` 必须匹配 `^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$`，在进入审计前完成校验，
+  防止控制字符、日志注入和无界字段大小。
+- 一个面向 OpenBao 的 JWT 不能用于 Kubernetes 或其他 API。
+- 删除或禁用 trust binding 后不再签发新 token。
+- 删除或禁用 trust binding 不会立即撤销已经签发的自包含 JWT；最大 TTL 是该变更的
+  最长生效延迟。
+- CEL 编译或运行失败时拒绝签发，且不破坏最后一个有效策略版本。
+- 日志、错误、metrics、trace、数据库和测试 artifact 不含 canary token。
+- JWKS 轮换期间，轮换前已签发且未过期的 token 仍可验证。
+- OpenBao、数据库或签名后端不可用时失败关闭，不签发降级 token。
@@ -0,0 +1,506 @@
+# Workload STS 系统规格说明书
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | Approved |
+| 版本 | v0.1 |
+| 最后更新 | 2026-09-10 |
+
+本文定义 workload-sts 的第一阶段外部合同、范围、安全边界和验收标准。内部包结构和
+具体 OAuth2/JWT/HTTP 库不属于外部兼容性合同。
+
+## 1. 背景
+
+homelab 中的 Kubernetes workload、CI worker、长期主机以及未来的外部 attestation
+系统使用不同的初始身份证明。OpenBao 能验证其中一部分身份并签发自己的 token，但
+不应承担所有跨环境主体映射和 OAuth2 federation 语义。
+
+workload-sts 在上游身份与下游资源服务器之间提供薄的 token exchange 层：验证来源、
+规范化主体、执行签发策略并生成短期 JWT。OpenBao 继续作为机密、PKI、动态凭据和自身
+token 生命周期的权威系统。
+
+## 2. 目标
+
+1. 提供符合标准 OAuth 2.0 语义的 Authorization Server metadata 与 token endpoint。
+2. 实现 RFC 8693 Token Exchange 的最小可互操作子集。
+3. 第一阶段支持 Kubernetes ServiceAccount JWT，并为其他 credential issuer 保留
+   verifier 扩展边界。
+4. 将上游身份映射为稳定、不可由客户端选择的 workload principal。
+5. 只为显式获准的 audience 和 scope 签发 JWT，由服务端选择唯一 token profile。
+6. 使 OpenBao、Kubernetes 和普通 Resource Server 能用原生 JWT 能力完成后续认证。
+7. 保持 HTTP 服务无本地状态，并记录不含 token 内容的结构化审计事件。
+
+## 3. 非目标
+
+1. 不实现用户密码、MFA、Authorization Code flow 或用户 consent。
+2. 不成为 OpenBao API proxy，不读取或返回 secret。
+3. 不签发或管理 OpenBao client token、lease、renewal 和 revocation。
+4. 不定义 OpenBao policy、Kubernetes RBAC 或应用业务权限。
+5. 不管理 workload、runner、Pod、VM 或 microVM 生命周期。
+6. 不实现 PVE/microVM vsock metadata 和 attestation。
+7. 不根据未经验证的 Gitea job 环境变量建立身份。
+8. 不实现自定义策略解析器。
+9. 第一阶段不支持任意第三方动态 client/issuer 注册。
+10. 第一阶段不直接返回 OpenBao token、SSH certificate、数据库密码或云凭据；增加非
+    JWT credential materializer 必须进入新的规格版本和安全评审。
+
+## 4. 参与者
+
+| 参与者 | 职责 |
+| --- | --- |
+| Subject | 持有上游 credential 并请求 token exchange 的 workload |
+| Credential issuer | 签发或证明 subject credential，并由对应 verifier 验证 |
+| OAuth client | 调用 token endpoint 的软件；v1 的必填 `client_id` 是自报审计标签，不参与认证 |
+| workload-sts | 验证、映射、授权并签发 JWT |
+| Policy administrator | 配置 verifier、binding、audience、issuance rule 和 profile |
+| Signing backend | 保管私钥并执行 JWT 签名；生产环境使用 OpenBao Transit |
+| Resource Server | 验证输出 JWT 并执行本地授权，例如 OpenBao 或 Kubernetes |
+
+## 5. 稳定标识
+
+### 5.1 OAuth issuer
+
+规范 issuer 为：
+
+```text
+https://identity.ad.ddupan.top
+```
+
+所有 metadata、JWKS 和 JWT `iss` 必须使用完全一致的 issuer。服务部署地址、Pod IP、
+内部 Service DNS 和数据库位置不能进入 `iss`。
+
+### 5.2 Principal
+
+每个 principal 具有不可变 ID 和可读名称：
+
+```text
+id:   <immutable identifier>
+name: ci/homelab-infra-plan
+```
+
+输出 JWT 使用不可变 ID 作为 `sub`，可选的受控 claim 表示可读名称：
+
+```json
+{
+  "sub": "<immutable principal ID>",
+  "principal_name": "ci/homelab-infra-plan"
+}
+```
+
+SPIFFE ID 只有在未来通过真正的 SVID verifier 验证后才作为 source subject 使用。内部
+principal 不使用 `spiffe://` URI 模拟 SPIFFE 身份。
+
+### 5.3 Audience
+
+audience 是已登记资源服务器的稳定标识，不是任意用户输入。初始 OpenBao audience 为：
+
+```text
+https://bao.ad.ddupan.top:8200
+```
+
+每个 Kubernetes cluster 必须使用独立 audience。
+
+## 6. OAuth 2.0 接口
+
+### 6.1 Metadata
+
+服务必须发布 RFC 8414 Authorization Server Metadata，至少公布：
+
+- `issuer`；
+- `token_endpoint`；
+- `jwks_uri`；
+- `grant_types_supported`；
+- `token_endpoint_auth_methods_supported`；
+- `scopes_supported`；
+
+第一阶段的 `token_endpoint_auth_methods_supported` 只包含 `none`。
+
+第一阶段不是 OIDC Provider，只发布：
+
+```text
+/.well-known/oauth-authorization-server
+/oauth2/token
+/oauth2/jwks
+/healthz
+/readyz
+```
+
+不发布 authorize、OIDC discovery、introspection 或 revocation endpoint。
+
+### 6.2 Token Exchange 请求
+
+服务必须接受表单编码的 RFC 8693 请求：
+
+```http
+POST /oauth2/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:token-exchange
+&subject_token=...
+&subject_token_type=urn:ietf:params:oauth:token-type:jwt
+&requested_token_type=urn:ietf:params:oauth:token-type:access_token
+&audience=https://bao.ad.ddupan.top:8200
+&scope=bao.login
+&client_id=homelab-infra-ci
+```
+
+第一阶段：
+
+- `grant_type` 只接受 token exchange；
+- `subject_token` 在第一阶段必填；
+- `subject_token_type` 必须来自已支持集合；
+- `requested_token_type` 只支持 access token；
+- `audience` 必须且只能解析为一个已登记 audience；
+- `resource`、`actor_token`、delegation 和 impersonation 暂不支持；
+- `scope` 只能请求 grant 已允许集合的子集；
+- `scope` 是保留的标准扩展点，第一阶段必须显式提交；
+- `client_id` 必填且没有默认值，是调用方自报的有界审计标签，不注册、不认证且不参与
+  授权；
+- 客户端不能提交 token profile、TTL、输出 claims、签名算法或 signing key；
+- 不返回 refresh token。
+
+第一阶段 token endpoint 不要求额外的 confidential client credential；调用者身份来自
+经过验证的 `subject_token`。必填 `client_id` 只能以 `client_id_claimed` 语义进入审计，不能
+作为已验证身份、授权输入或低基数 metric label。允许调用方自选 `client_id` 是本项目
+刻意采用的审计语义，不代表完整 OAuth client registration；依赖已注册 client identity
+的通用 OAuth 行为不在 v1 合同内。以后增加 mTLS 或 `private_key_jwt` client
+authentication 必须保持 client identity 与 subject identity 分离。
+
+缺少、为空或格式不合法的 `client_id` 返回 `invalid_request`，不推导匿名或默认 client。
+未来启用 client registration/authentication 时继续使用同一必填字段，并将审计语义从
+`client_id_claimed` 提升为经过验证的 client identity。
+
+`client_id` 长度必须为 3–63，只允许 ASCII 小写字母、数字和中横线，且首尾必须是字母
+或数字。规范正则表达式为：
+
+```regex
+^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$
+```
+
+### 6.3 成功响应
+
+成功响应使用标准 OAuth2 token response：
+
+```json
+{
+  "access_token": "<signed JWT>",
+  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
+  "token_type": "Bearer",
+  "expires_in": 300,
+  "scope": "bao.login"
+}
+```
+
+响应必须带 `Cache-Control: no-store` 和 `Pragma: no-cache`。
+
+### 6.4 错误响应
+
+错误必须使用 OAuth2/RFC 8693 标准错误，例如：
+
+- `invalid_request`；
+- `invalid_grant`；
+- `invalid_scope`；
+- `unsupported_grant_type`；
+- `invalid_target`。
+
+响应不得暴露 token 内容、签名验证细节、内部 policy 表达式或数据库信息。认证失败与
+授权失败的外部响应应避免成为主体和 grant 枚举接口。
+
+## 7. 上游凭据验证
+
+### 7.1 通用要求
+
+所有 JWT verifier 必须校验：
+
+- 配置的 issuer；
+- 允许的签名算法；
+- signature；
+- `exp`、`nbf` 和允许的时钟偏差；
+- 面向 workload-sts 的 audience；
+- subject 存在且满足该 issuer 的格式合同。
+
+discovery 与 JWKS 地址来自管理员配置，不能由请求动态提供。未知 issuer、`kid` 或算法
+必须拒绝，且不能回退到不校验签名的模式。
+
+### 7.2 Kubernetes ServiceAccount JWT
+
+第一阶段必须支持 projected ServiceAccount JWT。每个 Kubernetes cluster 作为独立
+verifier 配置，至少包含：
+
+- cluster ID；
+- issuer URL；
+- workload-sts audience；
+- TokenReview API 配置；
+- 允许映射的 namespace 与 ServiceAccount。
+
+第一阶段使用 TokenReview，并在 `spec.audiences` 显式提交 workload-sts audience；只有
+`status.authenticated=true` 且 `status.audiences` 包含兼容 audience 时才验证成功。
+TokenReview 失败或不可用时失败关闭，不自动降级为离线 JWKS。
+
+### 7.3 未来 verifier
+
+不同 credential issuer 使用不同 verifier 逻辑，并统一输出类型化的已验证身份。第一阶段
+不实现 SPIFFE、通用 OIDC、云身份或 metadata issuer；增加它们不应改变 token endpoint
+合同。
+
+未来接入 SPIFFE 时必须使用真正的 SVID 语义：
+
+- 验证 JWT-SVID trust bundle、audience 和时效；
+- 通过已验证 mTLS 连接接受 X.509-SVID；
+- 将 SPIFFE ID 作为 source subject，再显式映射到内部 principal；
+- 不接受 HTTP header 或请求字段自报的 SPIFFE ID。
+
+X.509-SVID 若作为 mTLS client authentication，预计使用 `client_credentials` 而不是
+缺少 `subject_token` 的非标准 token exchange；该流程需单独规格批准。
+
+## 8. Trust binding 与 principal
+
+trust binding 使用以下输入匹配上游身份：
+
+```text
+credential type
+upstream issuer/verifier ID
+source subject
+verified attributes
+```
+
+每个 binding 输出唯一规范化 principal，并携带该身份允许的 issuance rules。客户端不能
+请求 principal，也不能让同一个未约束通配规则跨 issuer 匹配。credential
+issuer/verifier 不是 OAuth client；自报 `client_id` 不参与 binding。
+
+初始 Kubernetes 映射示例：
+
+```yaml
+verifier: k8s-homelab
+sourceSubject: system:serviceaccount:ci:homelab-infra-plan
+principalID: 01993f4d-5e1a-7000-8000-000000000001
+principalName: ci/homelab-infra-plan
+issuanceRules:
+  - audience: https://bao.ad.ddupan.top:8200
+    allowedScopes: [bao.login]
+    tokenProfile: openbao-login-jwt
+```
+
+配置模型最终采用文件、数据库 API 或管理 API 尚待决定。
+
+## 9. 签发授权
+
+### 9.1 结构化 issuance rule
+
+binding 中的 issuance rule 至少关联：
+
+```text
+audience
+allowed scopes
+token profile
+optional CEL condition
+```
+
+有效授权为已匹配 binding、issuance rule 和客户端请求的交集。客户端可以请求更少，
+不能请求更多。服务端直接使用唯一匹配 rule 绑定的 token profile；零个匹配表示不允许
+签发，多个匹配表示配置冲突并失败关闭。
+
+### 9.2 CEL
+
+项目使用现成 CEL 实现，不自行编写表达式解析器。CEL 只处理基于已验证事实的条件，
+不能替代 principal、audience 和 scope 的结构化模型。
+
+初始 CEL 环境计划提供：
+
+```text
+credential.type
+credential.issuer
+credential.subject
+credential.attributes
+principal.id
+request.audience
+request.scopes
+```
+
+token profile 是 binding/issuance rule 的配置，不作为 CEL 输入。具体类型、允许函数、
+cost limit 和错误语义必须在实现前形成 API reference。CEL 编译或求值失败一律拒绝签发。
+
+## 10. Token profile 与 JWT claims
+
+token profile 由管理员定义，并由匹配当前 Kubernetes 身份的 binding/issuance rule 在
+服务端确定。它至少限制：
+
+- audience；
+- 最大 TTL；
+- 签名 key/algorithm；
+- 允许 scopes；
+- 固定 claims；
+- 从 verified identity 派生的 claims 模板。
+
+所有输出 JWT 必须包含：
+
+```json
+{
+  "iss": "https://identity.ad.ddupan.top",
+  "sub": "01993f4d-5e1a-7000-8000-000000000001",
+  "principal_name": "ci/homelab-infra-plan",
+  "aud": ["https://bao.ad.ddupan.top:8200"],
+  "iat": 1789062000,
+  "nbf": 1789062000,
+  "exp": 1789062300,
+  "jti": "<unique identifier>",
+  "scope": "bao.login"
+}
+```
+
+客户端不能直接提供输出 claim map。面向 OpenBao 的 token 默认不携带 Bao policy 名；
+OpenBao 应根据 `iss`、`sub`、`aud` 和必要的受控 profile claim 映射本地 JWT role。
+
+第一阶段 JWT TTL 固定为五分钟，允许 30 秒时钟偏差。输出 token 不可续期且不附带
+refresh token；客户端不能请求 TTL。这不约束资源服务器随后签发的本地 token。
+
+## 11. 签名与 JWKS
+
+生产环境通过 OpenBao Transit 完成签名，使 workload-sts 实例和数据库都不保存私钥。
+workload-sts 使用自己的 Kubernetes ServiceAccount JWT 登录 OpenBao，取得只能访问指定
+Transit signing key 和所需公钥信息的短期运行凭据。该凭据不是客户端通过 STS JWT
+登录 OpenBao 后取得的 token。实现必须：
+
+- 为 JWT 设置稳定 `kid`；
+- 发布当前公钥及仍覆盖有效 token 的旧公钥；
+- 只允许 token profile 选择的算法；
+- 在签名后端不可用时失败关闭；
+- 使轮换周期和旧公钥保留时间覆盖最大 JWT TTL 与允许时钟偏差。
+
+第一阶段使用 RS256，Transit 使用 RSA key、SHA-256 和 PKCS#1 v1.5 签名。实现前的互操作
+PoC 必须证明 Transit 生成的 JWS 能由项目 JWKS、OpenBao JWT auth 和 Kubernetes 外部
+JWT authenticator 验证；PoC 失败则返回规格阶段重新选择算法。
+
+## 12. 状态与数据库
+
+实现使用 Go 1.26、PostgreSQL、`pgx/v5` 和版本化 migration。HTTP 实例必须无本地持久
+状态，可在共享数据库之上水平扩展。数据库可以保存配置、策略版本和审计索引，但禁止
+保存：
+
+- subject token；
+- 输出 JWT；
+- Authorization header；
+- OpenBao token；
+- OAuth client secret 明文；
+- JWT signing private key。
+
+第一阶段不提供管理 API。声明式配置先离线校验，再通过独立 publish 命令在一个事务中
+写入新的 policy version；HTTP 实例只读取已激活版本。配置写入必须具有版本和审计信息。
+
+## 13. 审计与可观测性
+
+每次 token exchange 至少产生：
+
+```text
+timestamp
+request ID
+credential verifier ID/type
+upstream issuer
+client_id_claimed（v1 必有，且明确标记为未经认证）
+principal
+audience
+approved scopes/profile
+policy version
+allow/deny/error result
+output jti（仅成功时）
+```
+
+审计不得记录任何完整 bearer token，也不得把 `client_id_claimed` 表述为已认证 client。
+metrics 只能使用 verifier、audience、profile 和结果等受控低基数字段；不能把自报
+`client_id`、subject、`jti` 或请求字符串作为 metric label。
+
+## 14. 失败语义
+
+- verifier、数据库、策略或签名后端不可用时失败关闭；
+- 未知 issuer、principal、audience、scope 或 profile 均拒绝签发；
+- CEL 编译/求值失败拒绝签发；
+- 客户端断开和服务超时必须取消下游 discovery、JWKS、数据库及签名请求；
+- 重试可能产生多个仍然有效的输出 JWT，因此资源服务器不能假定一次请求只有一个
+  `jti`；
+- 内部错误对客户端返回稳定 OAuth2 错误，对日志记录无 token 的诊断原因。
+
+## 15. 第一阶段验收标准
+
+1. metadata 正确公布 issuer、token endpoint、JWKS 和支持的 grant/type。
+2. 合法 Kubernetes projected SA JWT 可映射到唯一 workload principal。
+3. 错误 issuer、signature、audience、算法、`exp` 或 `nbf` 的 JWT 被拒绝。
+4. 未配置 trust binding、audience、scope 或 profile 的请求被拒绝。
+5. 客户端请求超过 issuance rule 的 scope 时不能扩大权限，也不能提交 TTL。
+6. CEL 条件只读取类型化的已验证事实；编译或求值错误拒绝签发。
+7. 成功响应符合 RFC 8693，并带 `no-store`/`no-cache`。
+8. 输出 JWT 具有正确 `iss`、`sub`、`aud`、时效、`jti` 和批准后的 scope。
+9. OpenBao JWT auth 可以验证输出 JWT，并按自己的 role/policy 返回受限 client token。
+10. workload-sts 不接收、记录、续期或撤销该 Bao token。
+11. 面向 OpenBao 的 JWT 被配置为 Kubernetes audience 的验证器拒绝，反向亦然。
+12. workload-sts 使用自己的 Kubernetes identity 取得最小权限 Bao token，并且只能调用
+    预期 Transit key；客户端的 Bao token 不经过 workload-sts。
+13. 签名密钥轮换期间，旧的未过期 JWT 仍可通过 JWKS 验证。
+14. 日志、错误、metrics、trace、数据库和测试 artifact 不含 canary token。
+15. 两个服务实例共享数据库时，对相同配置产生一致授权结果和有效 JWT。
+16. 客户端不能选择 token profile；同一身份、audience 和 scope 匹配多个 issuance rule
+    时拒绝签发。
+17. 删除或禁用 trust binding 后不再签发新 token，已有 JWT 最迟在最大 TTL 后失效。
+18. 每个请求必须显式提交合法 `client_id`，且没有默认值；v1 只将其作为
+    `client_id_claimed` 进入审计，改变它不改变
+    principal、issuance rule、profile、scope 或输出 claims。
+
+## 16. 已确认决策
+
+- 项目名称为 `workload-sts`。
+- 使用标准 OAuth2 Token Exchange 语义，不设计私有 exchange 协议。
+- 项目职责截止于验证身份、授权签发并生成 JWT assertion。
+- OpenBao token 及其 TTL、renewal、revocation、lease 和应用清理由下游负责。
+- OpenBao 保持机密、PKI、动态凭据和最终 policy 的权威后端。
+- Kubernetes 可以作为上游 issuer，也可以原生验证 workload-sts 的外部 JWT；两个方向
+  使用不同 issuer、audience 和用途。
+- `scope` 作为标准扩展点保留并由客户端显式提交；客户端不能选择 token profile。
+- `client_id` 必填且没有默认值；v1 是调用方自报的审计标签，不注册、不认证且不参与
+  任何安全决策，未来 client authentication 继续复用同一字段。
+- `client_id` 使用 3–63 字符的 DNS-label-like 小写字母、数字和中横线语法，中横线不能
+  位于首尾。
+- 权限条件使用现成策略实现；第一阶段选择 CEL，不自行实现表达式解析器。
+- 内部 principal 使用不可变 ID；SPIFFE 只有在验证真正 SVID 时才作为上游身份，不使用
+  `spiffe://` URI 模拟 SPIFFE 语义。
+- PVE/microVM vsock metadata 与 attestation 由其他项目负责。
+- Gitea Actions 运行于 Kubernetes 时使用 Kubernetes workload identity，运行于 VM 时
+  使用对应平台提供的标准 workload identity。
+- 服务是无状态 HTTP 加数据库，部署位置不是协议或信任边界。
+- OAuth issuer 使用 `https://identity.ad.ddupan.top`。
+- 第一阶段只实现 Kubernetes projected ServiceAccount JWT verifier；其他 issuer 使用独立
+  verifier 扩展。
+- workload-sts 使用自己的 Kubernetes ServiceAccount identity 获取最小权限 Bao 运行
+  token，以调用 OpenBao Transit 签名。
+- 第一阶段只输出 JWT；直接返回其他凭据属于未来 credential materializer 的新规格。
+- 第一阶段使用 Go 1.26、Kubernetes TokenReview、PostgreSQL、`pgx/v5`、UUIDv7
+  principal、五分钟 JWT TTL 和 30 秒时钟偏差。
+- token profile 直接由匹配 Kubernetes 身份的 trust binding/issuance rule 确定。
+- 第一阶段使用 OpenBao Transit RS256，并在实现前完成 JWKS、OpenBao 和 Kubernetes
+  外部 JWT authenticator 的互操作 PoC。
+- 第一阶段只发布 RFC 8414 metadata、token、JWKS、healthz 和 readyz，不发布 OIDC、
+  authorize、introspection 或 revocation endpoint。
+- 第一阶段不提供管理 API，声明式配置经独立命令校验后原子发布为数据库 policy version。
+- 首轮 PoC 决定不采用 Fosite：v0.1 使用 Go 标准 HTTP/form 处理窄 RFC 8693 endpoint，
+  使用 `go-jose/v4` 做 JOSE/JWK 互操作，并通过官方 `openbao/api/v2` 调用 Transit。
+- HTTP 路由层使用 `chi/v5`，保持 handler 和 middleware 与标准 `net/http` 兼容；OAuth
+  表单字段仍由协议层显式解析，不使用自动 request binding。
+- 可观测性使用 OpenTelemetry Go trace 与 metric SDK，HTTP server 使用 `otelhttp`；SDK
+  exporter/reader 由进程启动配置注入，不在协议层固定 OTLP gRPC、OTLP HTTP 或具体后端。
+  第一阶段日志使用结构化日志并关联 trace/span ID，不要求启用 OpenTelemetry Logs SDK。
+
+## 17. 待批准决策
+
+- 基于已验证 principal 的限流策略；
+- CEL 类型系统、cost limit 和策略发布流程；
+- SPIFFE、通用 OIDC、云 workload identity 和外部 metadata issuer 的后续 verifier 合同；
+- 非 JWT `requested_token_type` 与 credential materializer 的安全和响应合同。
+
+## 18. 规范性参考
+
+- [RFC 6749 — The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)
+- [RFC 7519 — JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519)
+- [RFC 8414 — OAuth 2.0 Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414)
+- [RFC 8693 — OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693)
+- [RFC 9068 — JWT Profile for OAuth 2.0 Access Tokens](https://www.rfc-editor.org/rfc/rfc9068)
+- [Kubernetes Service Accounts](https://kubernetes.io/docs/concepts/security/service-accounts/)
+- [Kubernetes Authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/)
+- [SPIFFE Concepts](https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/)