Reference
Verifiable history
On this page
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: truethe 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 verifydownloads the whole history and checks it on your machine;nanoflags log monitoris 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).
| Line | Content |
|---|---|
| 1 | nanoflags-log-v1 |
| 2–4 | Environment id, revision number, checksum — the same values the bundle signature covers |
| 5–6 | SHA-256 of the exact bundle bytes served to server keys, and of those served to browser keys |
| 7 | Publish time (epoch milliseconds) |
| 8–10 | Revision 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,DELETEandTRUNCATE, 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
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-Logheader. Pushed revisions arrive before their entry is written; the SDK fetches it fromGET /v1/log/proofwith 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
errorwith codelogis emitted, and the SDK tries again with backoff. It never crashes. verifyLogimplies signature verification withrequire: 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:
NANOFLAGS_SDK_KEY=nf_srv_… npx @nanoflags/cli log verify --env <environment id> --state nanoflags-log.jsonFor 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:
npx @nanoflags/cli log monitor --state .cache/nanoflags-log.jsonBoth 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:
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.jsonsign 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 codecosign) 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.
--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
| Endpoint | Answer |
|---|---|
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);429withRetry-Afterbeyond 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 idkidfrom/v1/keys. /v1/bundleaddsX-NanoFlags-Log(base64url JSON of{ index, leaf, proof, head }) and, on co-signed environments,X-NanoFlags-CosignatureandX-NanoFlags-Cosigner-Key-Idfor the view served. Live messages carrycosignatureandcosignerKid.
What it protects against, and what not
| Scenario | Without | With verifiable history (and co-signing) |
|---|---|---|
| A configuration served to some clients only (targeted tampering) | Undetectable if validly signed | Detected: it must be in the one log every client and auditor checks |
| History rewritten after the fact | Undetectable | Detected by consistency proofs (SDK) and log monitor (CI) |
| NanoFlags signing key or account misused | Clients accept the configuration | Visible in the log; with co-signing, rejected by your SDKs |
| Network attacker changes a bundle | Rejected (signature) | Rejected (signature, log) |
| Updates withheld (a client kept on an old configuration) | Not detected | Not 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,coSignerKeysandallowEmergencyWithoutCosignare in the JavaScript SDK (@nanoflags/sdk). The other SDKs verify bundle signatures but not the log or co-signatures yet; usenanoflags log monitorin 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.