尧图网站建设 
Craft Agents 凭据安全设计AES-256-GCM 加密存储全流程解析【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossCraft Agents 是一款开源的 AI Agent 开发工具它的凭据安全设计值得所有工具开发者借鉴所有 API 密钥、OAuth 令牌等敏感凭据都通过AES-256-GCM 认证加密写入本地加密文件~/.craft-agent/credentials.enc加密密钥则由操作系统级硬件指纹经PBKDF2派生而来。本文带你从零看懂这套凭据加密存储的完整流程——不需要密码学背景也能理解它的每一道安全防线 一、为什么凭据安全是 AI 工具的必修课使用 AI Agent 工具时你总要提供钥匙Anthropic 的 API Key、ChatGPT 的 OAuth 令牌、AWS 的 IAM 密钥、Telegram 机器人令牌……一旦这些凭据以明文躺在磁盘上任何能读取你文件的程序都能冒充你的账号。Craft Agents 的方案可以概括为一句话凭据加密存储 机器绑定密钥 完整性校验三者缺一不可。二、凭据都有谁12 种敏感凭据的统一管理在 types.ts 中定义了全部 12 种凭据类型覆盖四大场景场景凭据类型典型例子全局认证anthropic_api_key、claude_oauthClaude 订阅 OAuth 令牌LLM 连接llm_api_key、llm_oauth、llm_iam、llm_service_account各家模型 API Key、AWS/GCP 密钥工作区与数据源workspace_oauth、source_oauth、source_bearer、source_apikey、source_basicMCP 服务器、数据库连接消息网关messaging_bearerTelegram Bot Token每个凭据用类型::作用域的键名唯一定位例如llm_api_key::openai-default、source_oauth::ws-123::github。这里有个小细节分隔符特意选用::而不是/因为 URL 和服务器名称里经常出现斜杠用双冒号可以彻底避免冲突见 types.ts 第 171-207 行。 统一的键名体系让取哪把钥匙变成了纯粹的字符串拼接加密层无需感知业务细节。三、加密核心AES-256-GCM 到底加密了什么AES-256-GCM 是当今最主流的认证加密模式它同时提供两样东西机密性256 位密钥的 AES密文无法还原出明文完整性GCM 模式会额外生成 16 字节的Auth Tag认证标签密文被篡改哪怕 1 个比特解密时都会直接失败。这意味着 Craft Agents 的凭据文件不仅看不见而且改不动 加密文件的二进制布局在 secure-storage.ts 第 15-24 行 的文件头注释中完整定义[文件头 - 64 字节] ├── Magic: CRAFT01\08 字节魔数校验 ├── Flags: 4 字节保留 ├── Salt: 32 字节PBKDF2 随机盐 └── 保留: 20 字节 [加密载荷] ├── IV: 12 字节每次写入随机生成 ├── AuthTag: 16 字节GCM 认证标签 └── 密文: 变长加密后的 JSON 凭据库常量定义见 secure-storage.ts 第 48-58 行。四、密钥从哪来硬件指纹 PBKDF2 密钥派生这是整个设计最精妙的部分加密密钥从不保存在磁盘上也从不让你输入。它从这台机器独有的指纹推导而来。getStableMachineId() 函数第 65-99 行 在三大平台各取最稳定的标识macOSIOPlatformUUID绑定逻辑主板终身不变Windows注册表MachineGuid安装系统时生成Linux/var/lib/dbus/machine-id随后在 getEncryptionKey()第 319-333 行 中完成密钥派生机器指纹 --SHA-256-- 加盐材料 --PBKDF2-SHA256 (10万次迭代)-- 32字节 AES-256 密钥为什么这样做很稳10 万次 PBKDF2 迭代把密钥拉伸到计算上难以暴力破解的程度PBKDF2_ITERATIONS 100000硬件指纹稳如磐石——早期版本曾用主机名派生密钥但 DHCP 换名就会导致凭据全部变砖v2 方案彻底修复了这个问题旧数据自动迁移loadStoreSync()第 198-256 行 会先尝试新密钥失败再尝试 v1 旧密钥成功即用新密钥重新加密回写用户无感完成升级。⚠️ 代价是凭据文件绑定当前机器。把credentials.enc拷到别的电脑无法解密——这恰恰是一种安全特性。五、写入与读取全流程写入流程saveStoreSync()第 281-317 行目录不存在则以0700权限创建~/.craft-agent/序列化整个凭据库为 JSON含版本号、创建/更新时间戳每次写入都随机生成新的 12 字节 IV——这是 GCM 安全的硬性要求AES-256-GCM 加密取出 16 字节 Auth Tag拼装文件头 IV Auth Tag 密文以0600权限仅属主可读写落盘。读取流程则相反校验魔数 → 读取盐值 → 派生密钥 → 用 IV 和 Auth Tag 解密 → 解析 JSON。任何一步失败都说明文件已损坏或被篡改。六、容错与自愈文件损坏了怎么办工程师没有止步于加密还做足了异常处理最小长度校验文件短于头部IV标签直接判定损坏双密钥尝试新旧密钥都失败才确认损坏避免误删损坏自愈handleCorruptedFile()第 350-362 行 会删除坏文件并清空缓存程序回到未配置的干净状态提示你重新认证即可启动体检CredentialManager.checkHealth()manager.ts 第 629-699 行 在应用启动时主动触发一次完整解密区分文件损坏与机器迁移导致解密失败给出友好提示而不是让用户撞上晦涩报错过期感知isExpired()manager.ts 第 596-612 行 提前 5 分钟判定 OAuth 令牌过期且对缺少过期时间的令牌采取宁可按过期处理的保守策略。七、常见问题 FAQ问为什么不用系统钥匙串Keychain答Craft Agents 选择自研加密文件是为了跨三平台行为完全一致且免去认证弹窗保证 CLI、桌面端、无头服务器体验统一。代价是没有系统级熵源因此用硬件指纹 PBKDF2 补齐。后端接口设计在 backends/types.ts理论上可随时插入新后端按优先级自动排序当前环境变量后端已被主动禁用强制手动录入凭据。问0600 权限意味着什么答POSIX 文件权限只有你的用户账号能读写这个文件其他用户包括同机他人一律拒绝访问是加密之外的第二道防线。问密钥存在哪里答哪儿都不存在。每次启动从硬件指纹 文件内盐值现算内存中使用完即弃磁盘上不留任何密钥痕迹。问如何彻底清除凭据答删除~/.craft-agent/credentials.enc即可代码层面也可调用 manager.delete() 按类型精确移除。小结Craft Agents 的凭据安全设计是一条完整闭环12 种凭据统一建模 → AES-256-GCM 认证加密 → 硬件指纹 PBKDF2 派生密钥 → 0600 权限落盘 → 双密钥迁移 → 损坏自愈 → 启动体检对普通用户而言你只需正常填入 API Key对安全而言每一层都在默默工作。这套 credentials 模块核心约 1200 行堪称中小型项目凭据存储的参考实现值得收藏研究 【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Craft Agents 凭据安全设计：AES-256-GCM 加密存储全流程解析
Craft Agents 凭据安全设计AES-256-GCM 加密存储全流程解析【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossCraft Agents 是一款开源的 AI Agent 开发工具它的凭据安全设计值得所有工具开发者借鉴所有 API 密钥、OAuth 令牌等敏感凭据都通过AES-256-GCM 认证加密写入本地加密文件~/.craft-agent/credentials.enc加密密钥则由操作系统级硬件指纹经PBKDF2派生而来。本文带你从零看懂这套凭据加密存储的完整流程——不需要密码学背景也能理解它的每一道安全防线 一、为什么凭据安全是 AI 工具的必修课使用 AI Agent 工具时你总要提供钥匙Anthropic 的 API Key、ChatGPT 的 OAuth 令牌、AWS 的 IAM 密钥、Telegram 机器人令牌……一旦这些凭据以明文躺在磁盘上任何能读取你文件的程序都能冒充你的账号。Craft Agents 的方案可以概括为一句话凭据加密存储 机器绑定密钥 完整性校验三者缺一不可。二、凭据都有谁12 种敏感凭据的统一管理在 types.ts 中定义了全部 12 种凭据类型覆盖四大场景场景凭据类型典型例子全局认证anthropic_api_key、claude_oauthClaude 订阅 OAuth 令牌LLM 连接llm_api_key、llm_oauth、llm_iam、llm_service_account各家模型 API Key、AWS/GCP 密钥工作区与数据源workspace_oauth、source_oauth、source_bearer、source_apikey、source_basicMCP 服务器、数据库连接消息网关messaging_bearerTelegram Bot Token每个凭据用类型::作用域的键名唯一定位例如llm_api_key::openai-default、source_oauth::ws-123::github。这里有个小细节分隔符特意选用::而不是/因为 URL 和服务器名称里经常出现斜杠用双冒号可以彻底避免冲突见 types.ts 第 171-207 行。 统一的键名体系让取哪把钥匙变成了纯粹的字符串拼接加密层无需感知业务细节。三、加密核心AES-256-GCM 到底加密了什么AES-256-GCM 是当今最主流的认证加密模式它同时提供两样东西机密性256 位密钥的 AES密文无法还原出明文完整性GCM 模式会额外生成 16 字节的Auth Tag认证标签密文被篡改哪怕 1 个比特解密时都会直接失败。这意味着 Craft Agents 的凭据文件不仅看不见而且改不动 加密文件的二进制布局在 secure-storage.ts 第 15-24 行 的文件头注释中完整定义[文件头 - 64 字节] ├── Magic: CRAFT01\08 字节魔数校验 ├── Flags: 4 字节保留 ├── Salt: 32 字节PBKDF2 随机盐 └── 保留: 20 字节 [加密载荷] ├── IV: 12 字节每次写入随机生成 ├── AuthTag: 16 字节GCM 认证标签 └── 密文: 变长加密后的 JSON 凭据库常量定义见 secure-storage.ts 第 48-58 行。四、密钥从哪来硬件指纹 PBKDF2 密钥派生这是整个设计最精妙的部分加密密钥从不保存在磁盘上也从不让你输入。它从这台机器独有的指纹推导而来。getStableMachineId() 函数第 65-99 行 在三大平台各取最稳定的标识macOSIOPlatformUUID绑定逻辑主板终身不变Windows注册表MachineGuid安装系统时生成Linux/var/lib/dbus/machine-id随后在 getEncryptionKey()第 319-333 行 中完成密钥派生机器指纹 --SHA-256-- 加盐材料 --PBKDF2-SHA256 (10万次迭代)-- 32字节 AES-256 密钥为什么这样做很稳10 万次 PBKDF2 迭代把密钥拉伸到计算上难以暴力破解的程度PBKDF2_ITERATIONS 100000硬件指纹稳如磐石——早期版本曾用主机名派生密钥但 DHCP 换名就会导致凭据全部变砖v2 方案彻底修复了这个问题旧数据自动迁移loadStoreSync()第 198-256 行 会先尝试新密钥失败再尝试 v1 旧密钥成功即用新密钥重新加密回写用户无感完成升级。⚠️ 代价是凭据文件绑定当前机器。把credentials.enc拷到别的电脑无法解密——这恰恰是一种安全特性。五、写入与读取全流程写入流程saveStoreSync()第 281-317 行目录不存在则以0700权限创建~/.craft-agent/序列化整个凭据库为 JSON含版本号、创建/更新时间戳每次写入都随机生成新的 12 字节 IV——这是 GCM 安全的硬性要求AES-256-GCM 加密取出 16 字节 Auth Tag拼装文件头 IV Auth Tag 密文以0600权限仅属主可读写落盘。读取流程则相反校验魔数 → 读取盐值 → 派生密钥 → 用 IV 和 Auth Tag 解密 → 解析 JSON。任何一步失败都说明文件已损坏或被篡改。六、容错与自愈文件损坏了怎么办工程师没有止步于加密还做足了异常处理最小长度校验文件短于头部IV标签直接判定损坏双密钥尝试新旧密钥都失败才确认损坏避免误删损坏自愈handleCorruptedFile()第 350-362 行 会删除坏文件并清空缓存程序回到未配置的干净状态提示你重新认证即可启动体检CredentialManager.checkHealth()manager.ts 第 629-699 行 在应用启动时主动触发一次完整解密区分文件损坏与机器迁移导致解密失败给出友好提示而不是让用户撞上晦涩报错过期感知isExpired()manager.ts 第 596-612 行 提前 5 分钟判定 OAuth 令牌过期且对缺少过期时间的令牌采取宁可按过期处理的保守策略。七、常见问题 FAQ问为什么不用系统钥匙串Keychain答Craft Agents 选择自研加密文件是为了跨三平台行为完全一致且免去认证弹窗保证 CLI、桌面端、无头服务器体验统一。代价是没有系统级熵源因此用硬件指纹 PBKDF2 补齐。后端接口设计在 backends/types.ts理论上可随时插入新后端按优先级自动排序当前环境变量后端已被主动禁用强制手动录入凭据。问0600 权限意味着什么答POSIX 文件权限只有你的用户账号能读写这个文件其他用户包括同机他人一律拒绝访问是加密之外的第二道防线。问密钥存在哪里答哪儿都不存在。每次启动从硬件指纹 文件内盐值现算内存中使用完即弃磁盘上不留任何密钥痕迹。问如何彻底清除凭据答删除~/.craft-agent/credentials.enc即可代码层面也可调用 manager.delete() 按类型精确移除。小结Craft Agents 的凭据安全设计是一条完整闭环12 种凭据统一建模 → AES-256-GCM 认证加密 → 硬件指纹 PBKDF2 派生密钥 → 0600 权限落盘 → 双密钥迁移 → 损坏自愈 → 启动体检对普通用户而言你只需正常填入 API Key对安全而言每一层都在默默工作。这套 credentials 模块核心约 1200 行堪称中小型项目凭据存储的参考实现值得收藏研究 【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考