linear-cli 安全机制深剖:API Key 保护、终端转义符过滤与凭据原子写入完整指南
linear-cli 安全机制深剖:API Key 保护、终端转义符过滤与凭据原子写入完整指南
linear-cli 是一款让你在终端里直接管理 Linear issue、一键创建分支与 PR 的命令行工具。把 API Key 交给一个本地 CLI,总让人有点不放心。这篇文章带你钻进 linear-cli 的源码,看清它如何用系统钥匙串保管 API Key、如何过滤终端转义符防止注入、又是怎样原子写入凭据文件——一次搞懂这套"agent friendly"工具的 3 大安全防线。
🔐 第一道防线:API Key 如何被保护
凭据默认存进系统钥匙串,不落明文
linear-cli 把 API Key 交给操作系统原生的密钥管理,而不是硬塞进本地文本文件:
| 平台 | 后端 | 调用方式 |
|---|---|---|
| macOS | Keychain | 通过系统自带 /usr/bin/security |
| Linux | libsecret | 依赖 secret-tool |
| Windows | Credential Manager | 通过 advapi32.dll |
本地 credentials.toml 只存"清单",不存密钥:
# credentials.toml(钥匙串模式)
default = "acme"
workspaces = ["acme", "side-project"]
真正的密钥躺在钥匙串里,路径定义在 auth/keyring/。
密钥全程"打码",连 Debug 都看不到
内部用 ConfigSecret 类型包装密钥,它的 Debug 输出永远显示 <redacted>,避免密钥被打进日志或报错信息里:
impl fmt::Debug for ConfigSecret {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("<redacted>")
}
}
交互输入密钥时终端显示为掩码
linear auth login 手动输入密钥时,终端会显示为掩码,避免明文回显;脚本场景可用 --key <key> 直接传入。实现见 commands/auth/login.rs。
传参只走 stdin,绝不进命令行
命令行参数在 ps 里对同机其他用户可见,所以写入钥匙串时,密钥只通过 stdin 传给 secret-tool,而不进参数。这一点源码注释里写得很直白:
/// The secret goes to stdin, never to the arguments, where other users
/// could see it.
见 auth/keyring/secret_tool.rs。
只读"用到的那个"工作区密钥,失败不泄露
钥匙串查询是懒加载的——命令只读取所选工作区那一条,且每个工作区最多查一次(OnceCell 缓存)。失败分类 LookupFailureCategory 刻意不携带钥匙串输出,因为那段输出里可能包含密钥本体。见 auth/keyring/mod.rs。
🛡️ 第二道防线:终端转义符过滤
标题、成员名、评论正文都是"别人写的",可能夹带转义序列——移动光标、改样式,甚至改掉终端窗口标题。linear-cli 在给自己的输出加样式之前,先清洗所有远程文本,堵住"终端注入"这条路。
核心逻辑在 platform/terminal_text.rs:
multiline():保留换行和制表符,其余控制字符替换为 U+FFFD(�)single_line():换行、回车、制表符一律压成空格\r\n归一化为\n,裸\r变\n
一条"注入"样例被拦下后的效果:
原始: ok ]0;pwned [2J ...
清洗后: ok ]0;pwned [2J ...
转义符、CSI、响铃、退格统统变成 � 占位符,任何序列都进不了你的终端。
📦 第三道防线:凭据文件原子写入
写凭据最怕两件事:写到一半崩溃,留下半截文件;文件权限太宽,被旁人读走。platform/private_file.rs 的 write_atomic 用经典的"临时文件 + rename"手法解决:
- 在同目录建一个**只属主可读(0o600)**的新临时文件
- 写入内容并
sync_all()落盘 - 原子
rename覆盖目标 - 再
sync目录,确保 rename 持久
由此带来三个好处:
- 中途被打断绝不会留下截断文件
- 无论旧文件权限多松,新结果都只有属主能读
- 符号链接被替换而非跟随,防止被诱导写到别处
新目录用 0o700 创建,private_dir 还会校验目录确属当前用户、不是符号链接,见 platform/private_file.rs。
读入侧同样设防
读取凭据文件时(auth/file.rs)也有护栏:
- 大小上限 1MB(
MAX_CONFIG_BYTES),超限直接报too large - Unix 下用
O_NONBLOCK打开,防止有人放个 FIFO 把启动卡死 - 非普通文件(目录、设备等)直接拒绝,报
not a regular file
小结
| 机制 | 关键做法 | 源码位置 |
|---|---|---|
| API Key 保护 | 系统钥匙串 + stdin 传参 + Debug 打码 | auth/keyring/ |
| 终端转义符过滤 | 远程文本统一清洗为 U+FFFD | terminal_text.rs |
| 凭据原子写入 | 临时文件 + rename + 0o600 / 0o700 | private_file.rs |
linear-cli 把"密钥不落明文、注入进不来、写入不半路"这三件事做成了默认行为,无需任何额外配置。想亲手验证,可运行 linear auth list 查看已配置的工作区,或阅读 docs/authentication.md 了解多工作区与密钥选择顺序。