全部文章
工程实践约 4 分钟阅读

用 DSSE 与 Ed25519 校验 Fleet 发布索引

记录 Fleet Agent、Fleet Desktop 和官网下载页共用的签名发布索引格式,以及服务端验签与缓存的实现细节。

  • Leaflow 工程团队· Leaflow

Fleet 的客户端分两套发布:Fleet Agent 面向 Linux 机器,Fleet Desktop 面向 Windows。两边检查更新时都去 releases.leaflow.net 拿对应的 v1/index.json(比如 /fleet-agent/v1/index.json),解析出 channels.stable.version,再到 dl.leaflow.net 拉实际的安装包和 SHA-256。Leaflow 官网的下载页和 /api/download/... 跳转路由复用了这份索引。

索引文件本身放在对象存储里,经 CDN 分发。只靠 HTTPS 没法覆盖存储桶误操作、镜像被改写或者 CDN 长时间返回过期缓存这些情况,所以我们在索引外层加了签名,并让客户端和官网执行同一套校验逻辑。

为什么把索引放进 DSSE 信封

做这层签名的时候没往索引 JSON 里直接塞 signature 字段。Go(客户端)和 Node.js(官网)对 JSON 键排序、空白符和转义字符的默认行为不一样,硬做 canonical JSON 规范化会多出不少边界问题;而且裸字节签名不带类型信息,别处签出来的东西容易跨场景混用。

我们最后采用了 DSSE(Dead Simple Signing Envelope)v1 格式。外层只有三个字段,发布流水线把索引 JSON 序列化后转成 Base64 放进 payload,校验端先拿原始字节验签,验签成功后再 JSON.parse:

fleet-agent/v1/index.json
{
    "payloadType": "application/vnd.leaflow.release-index.v1+json",
    "payload": "eyJwcm9kdWN0IjoiZmxlZXQtYWdlbnQiLC4uLn0=",
    "signatures": [
        {
            "sig": "<base64-ed25519-signature>"
        }
    ]
}

签名算法固定用 Ed25519,公钥在客户端和官网代码里以 Base64 字符串硬编码,运行时转成 OKP JWK 交给 Node.js node:crypto 的 verify()(客户端侧对应 Go 标准库 crypto/ed25519)。签名的输入按 DSSE 规范拼成 PAE(Pre-Authentication Encoding),把 payloadType 和解码后的 payload 分别加上字节长度前缀:

预认证编码(PAE)
function buildPae(payloadType: string, payloadBase64: string): Buffer {
    const type = Buffer.from(payloadType);
    const payload = Buffer.from(payloadBase64, 'base64');
    return Buffer.concat([
        Buffer.from(`DSSEv1 ${type.length} `),
        type,
        Buffer.from(` ${payload.length} `),
        payload,
    ]);
}

payloadType 写进了 PAE 的最前面,签给别处用的信封拿来冒充发布索引,验签这一步就会直接失败。

客户端与官网的校验清单

官网在渲染下载页和响应 /api/download/... 跳转前,会执行和客户端一致的校验流程,任意一步不满足就抛错退出:

检查项对应风险校验规则
响应体积异常上游响应打满内存响应文本超过 256 KiB(256 << 10)直接丢弃
信封与签名索引被篡改或伪造payloadType 完全匹配,且至少一条 Ed25519 签名对得上该产品的固定公钥
产品字段拿其他产品的有效签名索引跨产品替换解码后的 index.product 与请求的产品名一致
有效期攻击者或过期缓存重放旧版本索引index.expires_at * 1000 大于当前时间戳
产物路径与校验值镜像路径跳出目录或畸形哈希path 匹配 ^v[\w.+-]+/[\w.+-]+$,sha256 为 64 位小写十六进制

公钥轮换的处理方式

每个产品的公钥配置写成字符串数组,验签时只要数组中任意一把公钥能对上信封里的任意一条签名即可:

按产品固定发布公钥
const RELEASE_KEYS = {
    'fleet-agent': ['<current-ed25519-public-key>'],
    'fleet-desktop/windows': ['<current-ed25519-public-key>'],
} as const;

需要更换发布私钥时,先给客户端和官网发一版把新公钥追加进数组,同时留着旧公钥;等活跃版本都带上新公钥后,发布流水线切到新私钥签发 index.json;旧签名索引过了 expires_at 以后,下一版再把旧公钥删掉。

channels.stable.version 指向哪个版本,页面和下载接口就取 releases 里对应的那一项,并将产物相对路径拼到 mirrors[0] 上。

官网服务端的缓存与并发合并

releases.leaflow.net 没有对浏览器开放跨域,索引完全在官网的 Node 服务端读取,缓存间隔设为 300 秒(五分钟)。

这里叠了两层缓存。第一层是 Next.js 的 fetch 数据缓存(next: { revalidate: 300 })配合 10 秒超时(AbortSignal.timeout(10_000)),和下载页的页面重新验证间隔保持一致。第二层是进程内的 memo():下载接口每次被点击都会调用 latestRelease(),并发进来的一批请求会拿到同一个正在执行的 Promise,不会重复去拉索引和反复做 Ed25519 验签。

memo() 在 Promise 拒绝时会立刻删掉对应的键(value.catch(() => entries.delete(key)))。上游抖动或者签发异常恢复之后,下一个访问 Fleet Agent 下载页 或 Fleet Desktop 下载页 的请求就能重新拉到有效索引。

标签Fleet安全Ed25519发布工程