Blog & guides
Signed feature-flag bundles: why and how
Why NanoFlags signs every published configuration with Ed25519, exactly what the signature covers, how SDKs verify it by default, how signing keys rotate without breaking clients, and what a signature does not prove.
NanoFlags engineeringPublished 4 min read
On this page
A feature flag is a remote switch inside your application. Whoever can change the configuration your SDK loads can change what your users get, without a deploy and without a code review. So the question "is this really the configuration that was published?" deserves a cryptographic answer, not a hope that every cache and proxy on the way behaves.
What is signed
When a revision is published, the publisher Worker signs it once, before distribution, with an Ed25519 key. It signs two views: the server view (every flag of the environment) and the client view that browser keys receive (only client-exposed flags and the segments they reference). The edge and the live connections then serve those signed bytes unchanged.
The signature (64 bytes, base64url) covers the UTF-8 bytes of a small canonical string:
nanoflags-bundle-v1
<environment id>
<revision>
<checksum>
<sha256 hex of the bundle JSON text, exactly as sent>Binding the environment id and the revision number into the message means a valid bundle of one environment cannot be replayed as another environment's, and a bundle cannot be relabelled with a different revision. Hashing the bundle text exactly as sent avoids every JSON re-serialisation pitfall: a client never has to reproduce our formatting, it hashes the bytes it received.
Why Ed25519
- Small keys and signatures (32-byte public keys, 64-byte signatures), so a public key fits in an SDK release and a header.
- Deterministic signatures: the same text signed with the same key always yields the same signature. Two publisher paths (the direct push and the durable outbox) can sign the same revision independently and produce identical objects.
- Available natively in WebCrypto on Node.js 20+, current browsers, Cloudflare Workers, Deno and Bun, so the JavaScript SDK verifies without bundling a crypto library.
Verification is on by default
From JavaScript SDK 0.4.0, and in the Python and Go SDKs from 0.1.0, the SDK verifies every bundle when it reads from the official edge (https://edge.nanoflags.io) and rejects unsigned bundles there. The SDKs ship with the production public keys and load GET /v1/keys once when a bundle names a key id they do not know.
- A bundle with a bad signature is rejected; the previous bundle stays in use and the SDK emits an
errorevent withsignature. - A bundle that cannot be checked is never applied silently. On a runtime without Ed25519 in WebCrypto you must opt out explicitly with
verify: false. - If you fetch bundles through your own proxy or cache, pin the keys yourself and require signatures:
const flags = createClient({
sdkKey, baseUrl,
verify: {
publicKeys: [{ kty: "OKP", crv: "Ed25519", x: "wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U", kid: "k1" }],
require: true,
},
});Any other client can verify too. This is the complete check in plain Node.js:
import { createHash, createPublicKey, verify } from "node:crypto";
const base = "https://edge.nanoflags.io";
const res = await fetch(`${base}/v1/bundle`, { headers: { Authorization: `Bearer ${process.env.NANOFLAGS_SDK_KEY}` } });
const text = await res.text(); // keep the raw text: the signature covers the bundle bytes exactly as sent
if (res.headers.get("x-nanoflags-signed") !== "true") throw new Error("unsigned bundle");
const { revision, checksum } = JSON.parse(text);
const marker = '"bundle":';
const bundleText = text.slice(text.indexOf(marker) + marker.length, text.lastIndexOf("}"));
const message = ["nanoflags-bundle-v1", res.headers.get("x-nanoflags-environment-id"), revision, checksum,
createHash("sha256").update(bundleText, "utf8").digest("hex")].join("\n");
const { keys } = await (await fetch(`${base}/v1/keys`)).json(); // or pin the key in your build
const jwk = keys.find((k) => k.kid === res.headers.get("x-nanoflags-key-id"));
const ok = verify(null, Buffer.from(message, "utf8"),
createPublicKey({ key: { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, format: "jwk" }),
Buffer.from(res.headers.get("x-nanoflags-signature"), "base64url"));Rotating the signing key
A signing key that can never change is a liability. GET /v1/keys therefore lists every public key with a kid and a status (active or retiring), and every signed bundle names the kid it was signed with:
$ curl -s https://edge.nanoflags.io/v1/keys
{"keys":[{"kty":"OKP","crv":"Ed25519","x":"wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U","kid":"k1","alg":"EdDSA","use":"sig","status":"active"}]}A rotation runs in an order that never leaves a client holding a signature it cannot check:
- Generate a new key pair and publish the new public key next to the current one, both
active. Wait at least five minutes, the cache lifetime of/v1/keys. - Switch the publisher to the new key id and private key in one deployment. The publisher refuses to sign if the private key's id does not match the configured id, so a half-finished rotation cannot produce signatures under the wrong id.
- Re-sign what is currently served, so every environment's current revision carries the new key id.
- Mark the old key
retiring, and remove it only after the longest time an SDK may keep a persisted bundle signed with it (30 days is the default we plan for).
SDKs that only know the old key keep working throughout: they meet an unknown kid, load /v1/keys once and accept the new key from there. At the time of writing k1 is the only production key and no production rotation has been performed yet; the procedure is implemented and tested, and we will note the first rotation in the changelog.
What a signature does not prove
- Keys fetched from
/v1/keysare only as trustworthy as the edge that served them. If the edge itself is in your threat model, pin the public key in your build, as shown above. - Bundles of shared test sessions are not signed.
- Signing protects what flows from NanoFlags to your SDKs. Who may change the configuration in the first place is a separate control: roles, reviewed changes and scenario checks.
The exact contract (headers, canonical string, live messages) is in the edge API reference, and key handling in Security.
- security
- ed25519
- signing
- key rotation