Skip to content
NanoFlags
Start free

Reference

Verifiable history

Signatures prove that a configuration came from NanoFlags. Verifiable history goes further: every revision ever published is recorded in a public, append-only log that your SDKs and your own CI check, so a configuration cannot be served to some clients without being visible to everyone — and, if you turn on co-signing, nothing reaches your users without your own signature.

What it gives you

  • One history for everyone. Each published revision of an environment is appended to a tree that can only grow. Every client and every auditor sees the same history; showing one client a configuration that others do not see would require a second, inconsistent tree, which clients detect.
  • Proof, not trust. With verifyLog: true the JavaScript SDK applies a new configuration only after checking that it is in the log, byte for byte, under a tree head signed by NanoFlags, and that the new tree extends the one it saw before.
  • Your key, your rules (optional). With customer co-signing, publishing to an environment also needs a signature made with your own key in your CI. SDKs configured with your public key reject anything without it — even a configuration validly signed by NanoFlags.
  • An audit trail you can run. nanoflags log verify downloads the whole history and checks it on your machine; nanoflags log monitor is a one-shot job for CI that fails if the history ever forks, shrinks or is rewritten.

How the log works

Each environment has its own log: a Merkle tree hashed as in RFC 6962 / RFC 9162. A leaf is a short text that describes one published revision; a node is the hash of its two children. Every distributed revision becomes a leaf right after distribution, and NanoFlags signs the tree's head — its size, root hash and time — with the same Ed25519 key that signs bundles (GET /v1/keys).

LineContent
1nanoflags-log-v1
2–4Environment id, revision number, checksum — the same values the bundle signature covers
5–6SHA-256 of the exact bundle bytes served to server keys, and of those served to browser keys
7Publish time (epoch milliseconds)
8–10Revision kind (publish, kill), mode (standard, cosigned, emergency), and the co-signing key id or -
  • Append-only in the database. Leaves and signed heads can be inserted, never updated or deleted: triggers refuse UPDATE, DELETE and TRUNCATE, and no client role holds any privilege on the tables. The history is kept when an environment is deleted (it contains hashes, numbers and times — never your configuration).
  • Checked before it is signed. The database computes leaf hashes, roots and proofs; the publisher verifies them against the bytes it signed before it signs a head, and the database accepts a head only for the root it computed.
  • Re-signing is visible. If a revision is ever re-signed with new bytes (for example after a change to the browser view rules), that becomes a new leaf of the same revision — the old one stays.

Verify in the SDK

ts
import { createClient } from "@nanoflags/sdk";

const flags = createClient({
  sdkKey: process.env.NANOFLAGS_SDK_KEY!,
  baseUrl: "https://edge.nanoflags.io",
  verifyLog: true,
});
flags.on("error", (e) => console.warn(e.code, e.message)); // "log" when an update cannot be verified
  • The evidence (leaf, inclusion proof, signed head) comes with each bundle in the X-NanoFlags-Log header. Pushed revisions arrive before their entry is written; the SDK fetches it from GET /v1/log/proof with a few short retries.
  • The SDK remembers the newest tree head it verified (also in its persistent store) and checks every new head against it with a consistency proof (GET /v1/log/consistency, one request per new head).
  • A configuration that fails any check is not applied: the configuration in use stays, an error with code log is emitted, and the SDK tries again with backoff. It never crashes.
  • verifyLog implies signature verification with require: true.

Audit with the CLI

Any key of the environment can read its log. A full check downloads every entry, recomputes the root and compares it with the signed head:

sh
NANOFLAGS_SDK_KEY=nf_srv_… npx @nanoflags/cli log verify --env <environment id> --state nanoflags-log.json

For a scheduled CI job, log monitor only checks that the current signed head extends the one saved in the state file (keep the file between runs, for example in your CI cache). It exits with code 1 if the log forked, shrank or was rewritten:

sh
npx @nanoflags/cli log monitor --state .cache/nanoflags-log.json

Both commands verify head signatures with the keys built into the CLI for the hosted edge; pass --public-keys keys.json to use your own pinned copy. log verify also lists co-signed revisions, emergency revisions and revision numbers that have no entry (revisions published before the log was enabled).

Customer co-signing

Available on Scale and Enterprise. While an environment has an active co-signing key, every publish to it must carry your signature over the same canonical strings NanoFlags signs (the server and the browser view of the revision).

  • 1. Create a key in a safe place: npx @nanoflags/cli keygen --out ci-cosign.jwk --kid ci-2026. Keep the private key in your CI's secret store. The command prints the public key.
  • 2. Register the public key (owner or admin): dashboard → Settings → Environments → Security → Customer co-signing. Registration and retirement are recorded in the activity log. Registering the first key turns co-signing on.
  • 3. Sign and publish from CI with an admin key of the environment:
sh
export NANOFLAGS_KEY=$NANOFLAGS_ADMIN_KEY
npx @nanoflags/cli sign --key ci-cosign.jwk --expect reviewed-bundle.json --out cosign.json
npx @nanoflags/cli publish --expected-revision 41 --cosign cosign.json

sign downloads the draft, computes the exact bundle bytes the publisher will sign on your machine (it never signs a hash it was handed), checks that your key is the one registered under its id, and signs. Check what you sign: the draft comes from NanoFlags, and co-signing exists for the case where NanoFlags cannot be trusted. Pass --expect <bundle.json> (a file with the flags and segments your pipeline reviewed, for example from your configuration as code or a --bundle-out file of a reviewed run) or --expect-checksum <md5>: sign then refuses (exit 1, nothing written) when the draft differs, and prints a per-flag diff. The edge verifies both signatures before anything is published, the database refuses any revision of the environment without a co-signature, and the publisher verifies both signatures again before a revision is distributed or logged.

  • 4. Configure your SDKs with the public key: coSignerKeys: [{ kty: "OKP", crv: "Ed25519", x: "…", kid: "ci-2026" }]. They then reject configuration without a valid co-signature (error code cosign) and keep what they have.
  • Rotation: register the new key, switch CI and SDKs to it, then retire the old key. Retiring the last key turns co-signing off.
Publishing a co-signed environment
The dashboard does not hold your key, so it cannot publish a co-signed environment (it says so). Publish from CI as above. Work that needs an approval — such as a draft with edits proposed by an AI agent — is published through its change: once an owner or admin who did not author or edit it approves the change in the dashboard, sign the draft and add --change <change id> to publish. Co-signing and required approval cannot be combined on one environment yet.

Kill switch and emergencies

The kill switch must keep working when your CI key is out of reach. Kill-switch revisions are therefore accepted with the NanoFlags signature only, and the log records them with mode emergency — visible to every auditor. SDKs with coSignerKeys accept such a revision only when allowEmergencyWithoutCosign is on (the default) and it differs from the configuration in use only by flags turned off; with verifyLog the log must also record it as an emergency. Anything else without your signature is rejected. Set allowEmergencyWithoutCosign: false to refuse kill-switch revisions too. A client that starts with no configuration in use cannot compare, and does not accept an emergency revision; neither does a client that missed the co-signed revision just before it (the edge serves only the latest revision). Either one keeps what it has (or stays without configuration) until the next co-signed publish.

Endpoints and formats

EndpointAnswer
GET /v1/log/head{ environmentId, head: { size, root, timestamp, kid, signature } } — the latest signed tree head
GET /v1/log/proof?revision=<n>{ index, leaf, proof, head } — inclusion of the revision's newest leaf in the latest head
GET /v1/log/consistency?first=<m>&second=<n>{ first, second, proof, head } — RFC 9162 consistency proof
GET /v1/log/entries?start=&limit=Leaf texts, at most 1000 per request
  • Authentication: Authorization: Bearer <any key of the environment>. Rate limited per key (and per client network for browser keys); 429 with Retry-After beyond it.
  • Hashing: leaf hash = SHA-256(0x00 ‖ leaf text in UTF-8), node hash = SHA-256(0x01 ‖ left ‖ right); proofs are lists of lower-case hex hashes, bottom-up.
  • Signed head string: nanoflags-log-head-v1\n<environment id>\n<size>\n<root hex>\n<timestamp ms>, Ed25519, base64url signature, key id kid from /v1/keys.
  • /v1/bundle adds X-NanoFlags-Log (base64url JSON of { index, leaf, proof, head }) and, on co-signed environments, X-NanoFlags-Cosignature and X-NanoFlags-Cosigner-Key-Id for the view served. Live messages carry cosignature and cosignerKid.

What it protects against, and what not

ScenarioWithoutWith verifiable history (and co-signing)
A configuration served to some clients only (targeted tampering)Undetectable if validly signedDetected: it must be in the one log every client and auditor checks
History rewritten after the factUndetectableDetected by consistency proofs (SDK) and log monitor (CI)
NanoFlags signing key or account misusedClients accept the configurationVisible in the log; with co-signing, rejected by your SDKs
Network attacker changes a bundleRejected (signature)Rejected (signature, log)
Updates withheld (a client kept on an old configuration)Not detectedNot prevented; log monitor shows the current head so you can compare

The log proves what was published, not that it is what you intended: review your configuration as usual, and with co-signing compare the bytes in your CI before signing.

Limits and availability

  • The transparency log is on every plan; customer co-signing is included in Scale and Enterprise.
  • verifyLog, coSignerKeys and allowEmergencyWithoutCosign are in the JavaScript SDK (@nanoflags/sdk). The other SDKs verify bundle signatures but not the log or co-signatures yet; use nanoflags log monitor in CI for them.
  • Revisions published before the log was enabled for your environment are not in it.
  • Proofs are served for logs of up to 65,536 entries per environment.
  • Test-session bundles are not logged.

See also Security (keys and bundle signing) and Kill switch.