background-agents密钥加密机制深度解析AES-256-GCM与启动时注入【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agentsbackground-agents 是一个开源的后台智能体background agents编程系统它让 AI 在沙箱中后台运行编码任务。而它的密钥加密机制正是这套系统的安全底座所有 API Key、OAuth Token、数据库凭证都会先经过 AES-256-GCM 加密再落库密钥本身则通过 Terraform 在控制平面启动时注入。本文将带你完整看懂这套机制的设计与实现。先了解后台智能体系统的密钥从哪里来在 background-agents 中一个会话Session会在沙箱里跑起来执行任务而它需要用到各种凭证Claude/OpenAI 的 API Key、GitHub 访问令牌、数据库连接串等。这些凭证有三个存储级别级别适用场景典型例子 全局Global所有会话共享ANTHROPIC_API_KEY 仓库Repository单项目专属DATABASE_URL、AWS_ACCESS_KEY_ID 环境Environment多仓库组合场景环境定制凭证这些密钥一旦入库就是静态数据at rest攻击面最大——所以 background-agents 选择用AES-256-GCM 对称加密统一保护。相关设计说明见 docs/SECRETS.md。加密核心AES-256-GCM 是如何落地的整个加密逻辑集中在这约一百行的模块里非常值得一读crypto.ts。它的实现有三个关键细节1️⃣ 算法与参数选型ALGORITHM AES-GCM // 带认证的加密模式防篡改 KEY_LENGTH 256 // 256 位主密钥 IV_LENGTH 12 // 96 位初始化向量GCM 推荐值AES-GCM 相比普通 AES-CBC 的优势在于加密 完整性校验二合一密文被篡改哪怕一个字节解密也会直接失败而不是悄悄算出一串乱码。2️⃣ 每次加密都用全新的随机 IV加密时先通过crypto.getRandomValues生成 12 字节随机 IV再把IV 拼在密文前面一起 Base64 编码存储。这样每条密钥记录都拥有独立的 IV避免了同明文同密文的泄露风险。3️⃣ 密钥不存数据库只存IV 密文主密钥如TOKEN_ENCRYPTION_KEY是 32 字节256 位的 Base64 随机数用openssl rand -base64 32生成仅存在于 Worker 的密钥Secret配置中数据库里永远看不到它。 对于高价值凭证系统还叠加了一层AAD附加认证数据绑定provider-account-crypto.ts 在加密时会把账户 ID、提供商、模式版本号一起绑定进 GCM 的附加数据密文采用v1.IV.密文三段式格式——即使两条密文被互换到别的账户解密也会因 AAD 不匹配而失败。启动时注入三把主密钥如何进门background-agents 的控制平面Control Plane需要三把 AES-256 主密钥它们只在启动时注入一次环境变量保护对象TOKEN_ENCRYPTION_KEYGitHub OAuth 令牌、WebSocket 令牌等REPO_SECRETS_ENCRYPTION_KEY全局/仓库/环境三级 SecretsPROVIDER_ACCOUNTS_ENCRYPTION_KEYOpenAI/xAI 订阅凭证与刷新令牌注入路径是Terraform 部署时写入 Cloudflare Worker Secrets见 workers-control-plane.tf 中的密钥绑定AWS 自建部署则写入容器环境变量见 docs/AWS_BRING_UP.md 第 131 行附近的生成指引。更妙的是启动即校验的防呆设计。env-validation.ts 不只是检查密钥存在不存在而是验证完整契约严格的 Base64 正则校验拒绝空白与非法字符解码后必须恰好 32 字节——因为短密钥会被 Web Crypto静默降级为 AES-128/192这正是要防的坑密钥缺失时直接抛错拒绝启动绝不降级为明文存储注释里明确写着部署原则密钥没配好就大声失败而不是带病运行。运行时链路从落库到沙箱注入的完整闭环把上面的机制串起来一条密钥的生命周期是这样的写入用户在 Settings 页面保存密钥 → scoped-secrets.ts 中的encryptSecretEntries逐条调用encryptToken加密 → 密文写入数据库D1读取API永不返回明文值浏览器只能看到键名UI 中显示为••••••••掩码解密注入创建沙箱时控制平面按全局 会话目标合并解密作为环境变量注入沙箱——密钥只在内存中短暂出现特殊通道OpenAI/xAI 订阅模式的刷新令牌留在控制平面通过POST /sessions/:id/provider-auth/:provider/access-token按需换取短期访问令牌刷新令牌永不进入沙箱。给使用者的 4 条实践建议✅密钥轮换更换主密钥意味着所有密文无法解密SecretDecryptionError会明确指出失败的键名务必保留旧密文或做好迁移✅别把密钥写进镜像预构建镜像会冻结setup.sh持久化到磁盘的文件轮换后旧值仍可能残留在旧镜像里——尽量让脚本在运行时从环境变量读取✅环境密钥变更会自动使镜像失效并触发重建这是防旧凭证继续服务的兜底✅订阅凭证放对位置OpenAI/xAI 订阅凭据应配置在 Provider Accounts 而非通用 Secrets 中。小结background-agents 的密钥加密机制看似朴素处处是工程取舍用AES-256-GCM一次解决加密与防篡改用随机 IV AAD 绑定堵住常见实现漏洞用启动时注入 严格校验杜绝明文降级再用只回键名、沙箱即注的边界设计把密钥暴露面压到最小。对于任何需要托管用户凭证的系统这套加密于落库、解密于注入、密钥永不落库的模式都值得一抄。延伸阅读完整密钥管理指南docs/SECRETS.md加密实现源码packages/control-plane/src/auth/crypto.ts密钥启动校验packages/control-plane/src/env-validation.ts系统运作原理docs/HOW_IT_WORKS.md【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 background-agents密钥加密机制深度解析：AES-256-GCM与启动时注入
background-agents密钥加密机制深度解析AES-256-GCM与启动时注入【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agentsbackground-agents 是一个开源的后台智能体background agents编程系统它让 AI 在沙箱中后台运行编码任务。而它的密钥加密机制正是这套系统的安全底座所有 API Key、OAuth Token、数据库凭证都会先经过 AES-256-GCM 加密再落库密钥本身则通过 Terraform 在控制平面启动时注入。本文将带你完整看懂这套机制的设计与实现。先了解后台智能体系统的密钥从哪里来在 background-agents 中一个会话Session会在沙箱里跑起来执行任务而它需要用到各种凭证Claude/OpenAI 的 API Key、GitHub 访问令牌、数据库连接串等。这些凭证有三个存储级别级别适用场景典型例子 全局Global所有会话共享ANTHROPIC_API_KEY 仓库Repository单项目专属DATABASE_URL、AWS_ACCESS_KEY_ID 环境Environment多仓库组合场景环境定制凭证这些密钥一旦入库就是静态数据at rest攻击面最大——所以 background-agents 选择用AES-256-GCM 对称加密统一保护。相关设计说明见 docs/SECRETS.md。加密核心AES-256-GCM 是如何落地的整个加密逻辑集中在这约一百行的模块里非常值得一读crypto.ts。它的实现有三个关键细节1️⃣ 算法与参数选型ALGORITHM AES-GCM // 带认证的加密模式防篡改 KEY_LENGTH 256 // 256 位主密钥 IV_LENGTH 12 // 96 位初始化向量GCM 推荐值AES-GCM 相比普通 AES-CBC 的优势在于加密 完整性校验二合一密文被篡改哪怕一个字节解密也会直接失败而不是悄悄算出一串乱码。2️⃣ 每次加密都用全新的随机 IV加密时先通过crypto.getRandomValues生成 12 字节随机 IV再把IV 拼在密文前面一起 Base64 编码存储。这样每条密钥记录都拥有独立的 IV避免了同明文同密文的泄露风险。3️⃣ 密钥不存数据库只存IV 密文主密钥如TOKEN_ENCRYPTION_KEY是 32 字节256 位的 Base64 随机数用openssl rand -base64 32生成仅存在于 Worker 的密钥Secret配置中数据库里永远看不到它。 对于高价值凭证系统还叠加了一层AAD附加认证数据绑定provider-account-crypto.ts 在加密时会把账户 ID、提供商、模式版本号一起绑定进 GCM 的附加数据密文采用v1.IV.密文三段式格式——即使两条密文被互换到别的账户解密也会因 AAD 不匹配而失败。启动时注入三把主密钥如何进门background-agents 的控制平面Control Plane需要三把 AES-256 主密钥它们只在启动时注入一次环境变量保护对象TOKEN_ENCRYPTION_KEYGitHub OAuth 令牌、WebSocket 令牌等REPO_SECRETS_ENCRYPTION_KEY全局/仓库/环境三级 SecretsPROVIDER_ACCOUNTS_ENCRYPTION_KEYOpenAI/xAI 订阅凭证与刷新令牌注入路径是Terraform 部署时写入 Cloudflare Worker Secrets见 workers-control-plane.tf 中的密钥绑定AWS 自建部署则写入容器环境变量见 docs/AWS_BRING_UP.md 第 131 行附近的生成指引。更妙的是启动即校验的防呆设计。env-validation.ts 不只是检查密钥存在不存在而是验证完整契约严格的 Base64 正则校验拒绝空白与非法字符解码后必须恰好 32 字节——因为短密钥会被 Web Crypto静默降级为 AES-128/192这正是要防的坑密钥缺失时直接抛错拒绝启动绝不降级为明文存储注释里明确写着部署原则密钥没配好就大声失败而不是带病运行。运行时链路从落库到沙箱注入的完整闭环把上面的机制串起来一条密钥的生命周期是这样的写入用户在 Settings 页面保存密钥 → scoped-secrets.ts 中的encryptSecretEntries逐条调用encryptToken加密 → 密文写入数据库D1读取API永不返回明文值浏览器只能看到键名UI 中显示为••••••••掩码解密注入创建沙箱时控制平面按全局 会话目标合并解密作为环境变量注入沙箱——密钥只在内存中短暂出现特殊通道OpenAI/xAI 订阅模式的刷新令牌留在控制平面通过POST /sessions/:id/provider-auth/:provider/access-token按需换取短期访问令牌刷新令牌永不进入沙箱。给使用者的 4 条实践建议✅密钥轮换更换主密钥意味着所有密文无法解密SecretDecryptionError会明确指出失败的键名务必保留旧密文或做好迁移✅别把密钥写进镜像预构建镜像会冻结setup.sh持久化到磁盘的文件轮换后旧值仍可能残留在旧镜像里——尽量让脚本在运行时从环境变量读取✅环境密钥变更会自动使镜像失效并触发重建这是防旧凭证继续服务的兜底✅订阅凭证放对位置OpenAI/xAI 订阅凭据应配置在 Provider Accounts 而非通用 Secrets 中。小结background-agents 的密钥加密机制看似朴素处处是工程取舍用AES-256-GCM一次解决加密与防篡改用随机 IV AAD 绑定堵住常见实现漏洞用启动时注入 严格校验杜绝明文降级再用只回键名、沙箱即注的边界设计把密钥暴露面压到最小。对于任何需要托管用户凭证的系统这套加密于落库、解密于注入、密钥永不落库的模式都值得一抄。延伸阅读完整密钥管理指南docs/SECRETS.md加密实现源码packages/control-plane/src/auth/crypto.ts密钥启动校验packages/control-plane/src/env-validation.ts系统运作原理docs/HOW_IT_WORKS.md【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考