All articles
Engineering3 min read

Signing and verifying Fleet release indexes with DSSE and Ed25519

Notes on the signed release index shared by Fleet Agent, Fleet Desktop, and the Leaflow website, covering DSSE verification, key rotation, and server caching.

  • Leaflow Engineering· Leaflow Team

Fleet ships two clients: Fleet Agent for Linux and Fleet Desktop for Windows. Both fetch v1/index.json from releases.leaflow.net (for example /fleet-agent/v1/index.json), read channels.stable.version, and pull the matching installer and SHA-256 checksum from dl.leaflow.net. The Leaflow website download pages and /api/download/... routes read the exact same index files.

Because those index files sit in object storage behind a CDN, HTTPS alone does not guard against a modified bucket, a tampered mirror path, or a stale cached snapshot. Signing the index lets both the clients and the website run one shared verification check before trusting any version or URL.

Why wrap the index in DSSE

We avoided putting a signature field directly inside the release JSON. Go (clients) and Node.js (the website) serialize key ordering, whitespace, and escaping differently, so canonical JSON adds unnecessary edge cases. Signing untyped bytes also leaves no schema binding between different signed documents.

We went with Dead Simple Signing Envelope (DSSE) v1 instead. The outer envelope has three fields, with the serialized release index Base64-encoded in payload. Verifiers check the raw signed bytes first and only call JSON.parse after verification succeeds:

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

Signatures use Ed25519. Public keys are pinned as Base64 strings in both the clients and the website, converted into an OKP JWK for Node.js node:crypto verify() on the server (and checked with Go's crypto/ed25519 in the clients). Signing and verification run over the DSSE Pre-Authentication Encoding (PAE), which length-prefixes payloadType and the decoded payload:

Pre-Authentication Encoding
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,
    ]);
}

Because payloadType sits at the front of the PAE buffer, an envelope signed for another schema fails verification immediately.

Verification checklist shared by clients and the website

Before rendering a version or issuing a download redirect, the website runs the same verification steps as the Fleet clients and rejects the response on any failure:

CheckRiskRule
Response sizeOversized upstream payload exhausting memoryReject responses larger than 256 KiB (256 << 10)
Envelope and signatureTampered or forged indexExact payloadType match and at least one valid Ed25519 signature for a pinned product key
Product fieldValid index for another product substituted hereDecoded index.product equals the requested product
Expiry windowStale snapshot replayed to freeze updatesindex.expires_at * 1000 is greater than the current timestamp
Artifact path and hashPath traversal or malformed checksumpath matches ^v[\w.+-]+/[\w.+-]+$ and sha256 is 64 lowercase hex characters

Handling key rotation

Each product pins an array of accepted Ed25519 public keys, and verification succeeds if any key in the array verifies any signature on the envelope:

Pinned release keys
const RELEASE_KEYS = {
    'fleet-agent': ['<current-ed25519-public-key>'],
    'fleet-desktop/windows': ['<current-ed25519-public-key>'],
} as const;

Rotating a release key happens over two releases: first ship a client and website build that appends the incoming public key alongside the existing one; once active installs carry both keys, switch the release pipeline to sign index.json with the new private key; after older signed envelopes pass expires_at, drop the retired key in the next release.

Both pages and redirect endpoints resolve the entry matching channels.stable.version in releases and join its relative artifact path against mirrors[0].

Server-side caching and request deduplication

releases.leaflow.net does not expose CORS headers to browsers, so the website fetches and verifies indexes on the Node.js server with a 300-second cache window.

Two layers work together. Upstream fetches use Next.js data caching (next: { revalidate: 300 }) with a 10-second timeout (AbortSignal.timeout(10_000)), matching the page revalidation interval. In addition, an in-process memo() layer deduplicates concurrent calls to latestRelease() so simultaneous download clicks share a single in-flight fetch and Ed25519 verification promise.

When a promise rejects, memo() evicts its key right away (value.catch(() => entries.delete(key))). As soon as an upstream outage clears, the next visit to the Fleet Agent download page or the Fleet Desktop download page reads the fresh index without waiting for the five-minute timer.

TagsFleetSecurityEd25519Release Engineering