By name: sts description: 基于内嵌规则 的 STS 出站访问规范。用于校对后端 STS 客户端、前端禁用与 token TTL 范围。
STS Outbound Access
步骤
- 打开
本文件内嵌规则。 - 在后端检查 STS 客户端封装与配置。
- 在前端确认无 STS 交换调用。
核对点
- STS 客户端仅存在于后端
backend/internal/infra/sts/**。 - 前端
web-admin/**禁止调用_internal/sts/exchange。 - Token TTL ≤ 300s 且带 scope。
指南
STS — Plugin Outbound Access Guide
插件调用宿主 PowerX 的唯一合法方式：短期凭证（STS）交换与使用。
目标：最小权限、最短有效期、显式失败与审计（PG-STS-001）。
1. 交换端点与语义
- 交换地址：
/_p/_internal/sts/exchange（由宿主暴露） - 输入：插件当前会话/上下文（由宿主反代注入并在后端持有）
- 输出：
access_token（短期） +expires_in+ 可选scopes
插件侧以 Server-to-Server 方式请求；不得从浏览器或前端直接交换 STS。
2. Token 要求
- 有效期：≤ 5 分钟（默认 300s）
- 权限：必须带 Scope（最小权限）
- 承载：后续请求使用
Authorization: Bearer STS.***
3. 客户端实现建议
- 封装：
backend/internal/infra/sts/client.go（或client_gen.go） - 策略：
- 失败回退：过期 → 重新交换；网络错误 → 指数退避重试（最多 N 次）
- 缓存：内存缓存 token，基于过期时间提前刷新（如剩余 <60s 时刷新）
- 并发：使用单航班（singleflight）避免风暴
- 审计：成功/失败均记录结构化日志（不打印敏感值）
4. 典型调用流程
Service → STS Client (ensure token) → Host API (with Bearer STS.***)
- 错误处理：
- 401/403：Scope 或 token 失效 → 记录并切换降级逻辑
- 5xx：宿主暂时不可用 → 重试（带抖动），超出阈值快速失败
- 观测：记录
tenant_uuid/request_id/plugin_id，便于宿主端关联追踪
5. 安全注意事项
- 不在前端/浏览器交换或存储 STS
- 不写入日志/metrics 的敏感正文
- 不持久化 STS（仅内存缓存）
- 不把 STS 透传给第三方（只用于访问宿主 PowerX）
6. 与配置/环境联动
- 环境变量：
POWERX_STS_ENDPOINT（可选，默认宿主固定路径） - 允许通过
POWERX_STS_SCOPES明确本插件需要的最小权限清单，以便运营审计
7. 合规清单（Checklist）
- 仅通过
/_p/_internal/sts/exchange交换 STS - Token TTL ≤ 300s，带 Scope
- 有缓存/刷新/单航班/退避重试策略
- 结构化日志（不含敏感正文）
- 仅用于宿主 API；不在前端/浏览器层使用
- 失败显式、可审计、可观测
（相关 Gate：PG-STS-001）
规则（内嵌）
sts.yaml
# STS — Outbound Access
# Gate: PG-STS-001
kind: ruleset
id: sts
version: 1.0.0
summary: "插件对宿主的出站访问必须通过短期凭证（STS）交换与使用"
checks:
- id: sts-client-exists
desc: 存在 STS 客户端封装且只在后端使用
assert:
type: path
target:
- backend/internal/infra/sts/**
- id: sts-no-frontend
desc: 不得在前端/浏览器层发起 STS 交换
assert:
type: fileban
target: web-admin/**
pattern:
- "_internal/sts/exchange"
- id: sts-token-ttl
desc: Token TTL ≤ 300s，带 scope
assert:
type: config
target: backend/config/**
query: ensure_sts_ttl_le_300_and_scoped()