Skip to content

0046: Linear policy chain

  • Status: accepted
  • Date: 2026-11-14 (decided by Ben on 2026-10-29; no quorum in version 1 decided by Ben on 2026-10-31)
  • Change: policy-linear-chain (design in openspec/changes/policy-linear-chain/design.md; DECISIONs on ticket 01M5XKHPN4Y5P5A2MWSWVZ3CTV)
  • Supersedes: 0017 (two-phase revocation fold) and 0043 (role reductions bind policy records)
  • Amends: 0005, 0006, 0010, 0025, 0041 and 0042 (see "What this changes in other ADRs" below)
  • Amended by: 0052 (epoch wraps are keyed by the link that calls for them, which closes the shared-folder limitation on lost mints under "Consequences")
  • Stands: 0019 (sync never rebases or force-pushes; the git publish below relies on it)

Context

Policy records formed a causal DAG ordered by (HLC, id) and decided in two, then three passes (a fourth was proposed, then dropped with fix-reduction-pass2-bypass), with contest detection on top (ADRs 0017 and 0043). The author of a record chose its parents and its HLC, and so its place in fold order, after the fact. Every security finding in the reviews of member-roles-and-rename and fix-reduction-pass2-bypass used that freedom: a demoted admin's backdated grants (F1), masked revocations (B1), puppet revocations that shield a device (B2), a demoted admin undoing her own demotion with backdated puppets (M0, ticket 01M61AA7MQ, critical), the backdated self-grant and the forged-revocation lock-out of #184, the approver member-id squat (01M5XECA0J) and the mint races of pull-before-privilege-writes (01M5VCJ7KE). Three rounds of patches each closed one form and opened another.

On 2026-10-29 Ben ruled to stop patching and put policy in one order, as Keybase sigchains, 1Password and Bitwarden do, and answered the design's four open questions: offline privilege writes are refused (Q1); shared-folder vaults keep multi-admin writes, with lost races detected after the fact (Q2); version 1 mitigates equivocation with the join pin, the fingerprint in key verify, the data-anchor cross-check and the existing branch-protection warnings (Q3). His Q4 ruling (restoring a role a quorum removed needs the same quorum) was withdrawn on 2026-10-31, when he removed quorum from version 1. Format version 1 changes in place, since nothing has been released.

Decision

One chain, one order

  • A vault has one policy chain. Collections are not separate chains, because a grant on prod and the revocation of a device that reads prod must be ordered against each other.
  • Genesis is link 0: seqno 0 and no parent. Every other record carries one parent (a single id, not an array, so no decoder can accept two parents by mistake) and a seqno greater than 0, both signed and part of the record id. Records are stored at their slot path policy/<seqno>.pol, the seqno as 20 zero-padded decimal digits. The path is write-once. The HLC stays for display and decides nothing.
  • Validation is a replay in slot order. The run is the longest sequence of occupied slots from slot 0 with no empty slot in it. Each slot file of the run is checked once, against the state after the current tip: a file that does not decode, whose seqno is not its slot (path-mismatch), whose parent is not the tip (stale-parent), whose signature fails, whose author is not active at the tip, or that fails its kind's own check is void, occupies its slot and has no effect. Anything else is a link and becomes the tip. Files above the first empty slot are held (gap) and have no effect.
  • Every check reads only the slot file and the run below it. The device key record a record needs is carried in the record itself (Genesis, add-member, add-device, supersession and recovery registration; at most 4096 bytes), and keys/<keyid>.key is only a copy. So adding any file never changes a verdict in the run; it can only extend the run. The state is a function of the set of slot files alone, and replay costs one check per slot file, with no passes, sub-folds or budget.
  • A writer names the tip as parent and writes at the first empty slot. No link is ever written above an empty slot, so a late record can only extend the chain: a backdated record must name a tip that is no longer the tip, and is void. A void file costs a writer one slot and never wedges the vault.
  • Each (collection, epoch number) is minted by at most one link. Every mint carries kek_commit, a commitment to its KEK, and a client uses only a wrap whose KEK matches it, trying sync-tool conflict copies of the wrap path too.

The transport orders races, not history

The transport decides which of two records written at the same moment takes a slot. It is not trusted for authenticity (every link is signed and names its parent, so it cannot forge, alter, reorder or move one), and it is trusted only in part for freshness (it can withhold or rewrite links; the pin below catches that for every client that saw them).

Transport How one of two concurrent privilege writes wins
Git, same branch A commit built with commit-tree on the fetched-and-merged HEAD, pushed without force before the local branch moves. A rejected push leaves the commit unreferenced; nothing is reset. A push rejected only because others pushed data is rebuilt with the same signed records and is not a lost race.
Git, branch mode (ADR 0041) Already one commit on the fetched tip, pushed without force.
Hosted Admission requires parent == tip and seqno == tip + 1, then a put-if-absent of the slot path, which is the per-namespace compare-and-swap; refusal reason stale-policy-head. Every policy record of a batch is checked against the advancing tip before any is stored, so a batch is refused all or nothing; the conditional write of the slot is the commit point, and a retry completes later records, key copies and wraps.
Filesystem, one machine No-replace create of the slot path plus the profile lock.
Filesystem, shared folder None across machines. The sync tool keeps one file at the slot and renames the other as a conflict copy; the loser's client reports policy-write-lost, and sync offers to re-apply what can be re-applied (not a mint, and not a revocation that mints).

Every command that writes a policy record pulls (whatever auto_pull says), checks and confirms against the pulled state, writes on the tip, publishes, and on a lost race pulls and re-checks: the same outcome is re-signed without asking, an outcome already in effect exits 0, a changed outcome asks again (exit 2 policy-changed without a terminal), and three races lost to new links, or two minutes, exit 4 policy-busy. Privilege writes are refused offline (exit 4, nothing written); there is no --offline and no queue. Data writes stay offline-capable. A removal, demotion or revocation is final once the command reports it published.

Data events

policy_anchor becomes one optional link id, the writer's tip. A grant counts for an event only when it is in the chain prefix up to the anchor, and every rights-reducing link later than the anchor applies through the existing event_heads cut, which never was the problem: the reducer fixes the heads, and event ids are hashes. An event anchored on a void record is judged at the nearest link below it, conservatively; when the void record is another member's, doctor reports policy-fork-evidence. Data events are otherwise ordered as ADR 0005 says.

Anti-rollback, forks and the join pin

  • The cache pins the last accepted link (seqno, id) and a running hash of every link id from Genesis to it. On every open and pull a missing pinned link is policy-rollback and a different record at a pinned slot, or a pinned link turned void, is policy-fork (both exit 2). The client keeps its chain, refuses sync and privilege writes, keeps serving reads, and never picks between two chains by length, id, author or seniority, since each such rule hands the choice back to whoever writes records.
  • policy-write-lost (a warning) applies only when every affected link is this device's own in a filesystem vault. Third parties fail closed, so a member with folder write access cannot overwrite a revocation with a counter-record of the same parent and have everyone adopt it.
  • sync --accept-rollback <fingerprint> re-pins only to the tip the user checked with the authors, and is refused when the backend's tip differs. A chain fingerprint is a link's seqno and eight words from its id. member add prints the new member's link fingerprint, vault add --expect-head <fingerprint> refuses a chain that does not hold it, and key verify prints the tip's fingerprint. A wrong fingerprint changes nothing: it is compared with the tip that would be accepted, after any fetch and before any accept, audit line, cache save or push, on every backend.
  • A lost revocation did not happen. Whichever command finds it names it, says the target is still active and names the revocation command to run again; sync and doctor report it on every run until the end of the target key's supersession chain is revoked or gone (a rotated key is not settlement, and the report names the successor key). A record of this device voided by the loss is reported with it.

The git history check

An ordinary fast-forward commit can delete or replace slot files, which the pin catches only for clients that saw them. So every time the git backend takes in a fetched branch (sync, the pull of a privilege write, vault add and a first clone, and branch-mode receive) it checks the vault's slots against the whole history of that branch, in this final form (group 2 review rounds 1 to 4):

  • It fetches full history first, deepening a shallow repository; when it cannot, it refuses with history-unchecked and fails closed. The walk covers every commit reachable from the fetched tip, every side of every merge, and ignores replace refs and grafts.
  • A slot is any policy/<seqno>.pol path in any directory whose vault.json names this vault's id. Its first version is the bytes of the earliest commit that added it. The fetched tip must hold every slot with its first version: a missing slot is policy-rollback, other bytes are policy-fork. A delete and re-add on one line of history is a change, not a second first version.
  • Two first versions of one slot on concurrent sides of history are a fork whenever the competing version decodes as a policy record of this vault whose seqno is that slot, whoever signed it. Disputed slots are judged against the fetched tip's chain, never against the pre-fetch local copy: the report names the signer's member when the fetched tip's chain registers it and the signature verifies, and unverified otherwise. Any decodable competing record is therefore a fork; only bytes that do not decode as such a record are reported as corrupt and ignored, so junk cannot raise the alarm. A missing judge fails closed.
  • A fetched change of where the vault lives (its path in vault.toml, or its sync branch) is refused as a fork, except a move to branch mode whose history holds every slot with its first version, which is reported as vault-migrated.
  • The result is cached per vault (the last verified commit and each slot's first version), so each fetch walks only new commits that touch the policy directory. --accept-rollback <fingerprint> and vault add --expect-head record the accepted version of each disputed slot, which is how a vault whose history holds a disputed slot stays usable. A git revert that restores the files passes. A failure names the slot, the commit and its git author, and adopts nothing.
  • A rewrite of history itself (a force-push) is not caught for a client that never saw the old history. Branch protection that blocks force pushes closes that; the pin catches it for every client that did.

The CI verification action (storage-backends "CI verification action and branch protection guidance") does not exist yet and is future work (orchestrator DECISION on ticket 01M66KDMP6, point 5). When it is built it must run the same check, must require full history (a checkout with fetch depth 0), must fail on a shallow checkout it cannot deepen rather than pass on what it can see, must fail a push whose tip fails the check, and needs a test that shows it failing on such a shallow checkout (spec review R3-N2).

No quorum in version 1

Root admins are peers (Ben, 2026-10-31). Any root admin removes another root admin's admin role, grants admin to any member, and revokes another root admin's device directly, with no proposal, approval or threshold. Demotion proposals, approvals and SetQuorum (kinds 11 to 13, now reserved and never enabled), thresholds, demoted state, restore-needs-quorum, device-revocation proposals and member approve are removed. Rationale: version 1 is for individuals, families and small teams, who expect the 1Password and Bitwarden model in which any administrator can manage the others, and most findings of this change were about quorum interactions. Quorum may return as its own change on the chain; design.md section 13 lists what it would need.

What limits peers:

  • Last admin protection. Without a recovery key the last root admin cannot be removed (last-admin). With one registered, only the recovery key can remove the only root admin, by any route (recovery-required).
  • The recovery key. Only the recovery key itself can revoke, supersede or remove a role of the recovery key or member, or add a device to the recovery member; no admin, and no number of admins, can. One root admin may register a recovery key in a vault that has none (first registration, or after the recovery key revoked itself, since only the share holders could have revoked it). The self-revocation and the successor's registration may be published as one unit.

Record kinds and how they are enabled

A new record kind is added to the format only together with the rule that enables it in a vault, so whether a record counts is decided by the chain and not by which clients a team happens to run. The kinds of format version 1 (1 to 10 and 14 to 16) are enabled from Genesis. A kind beyond version 1 counts only from the link of an EnableKinds record (kind 16) signed by the recovery key itself; an EnableKinds by anyone else is void unauthorized, so a vault without a recovery key cannot enable kinds. A kind that was never enabled is void unknown-kind for every client, whatever version it runs, so no admin can freeze privilege writes with a kind nobody implements. An enabled kind a client does not implement is held when it is on the tip and validly signed; that client stops its pin there and refuses privilege writes (upgrade-required) until upgraded, and an upgrade replays it without reporting a fork. A recovery-signed link above such a held file voids it for every version (the one exception to verdict finality), which keeps the recovery key able to undo a freeze. An enabled kind cannot be disabled; a disable-kind record is ticketed for later (R2-D).

Key records and wraps on the hosted service

The hosted service stores a key record only when its bytes equal the key record a staged or stored link carries for that KeyID, because the KeyID fixes only the public keys and the vault, not the member, authoriser or signature; a variant could otherwise squat the path. It stores a wrap only when a stored link authored by the putting, active device calls for it, so a losing minter's wraps never land. The one exception is a key supersession: the new key's copies of the epochs the old key held may be put by the old key (the link's author) or by the new key while it is active.

What this changes in other ADRs

  • 0005: policy records are no longer ordered by the causal DAG or the HLC; their order is the chain. Data events keep the DAG and the (hlc, id) tie-break.
  • 0006: "a signed policy chain" is now literally a chain. The causal-past rule for policy records is replaced by chain order (it still holds for data events, read as "later in the chain than the anchor"); the M of N demotion quorum is removed; local-first anti-rollback pins the chain tip and prefix hash.
  • 0010: privilege writes need the backend's compare-and-swap (put-if-absent of the slot path, a non-forced push, or the hosted conditional write); a shared folder has none and detects lost races afterwards. Data writes stay offline-first.
  • 0025: hosted policy admission is admission on the tip with a conditional slot write and stale-policy-head (recorded in 0025's "Policy chain admission" bullet); policy slots cannot be deleted.
  • 0041: the branch-mode push is the compare-and-swap for privilege writes, and receive runs the git history check.
  • 0042: a member's current name is the enc_name of the last rename link in chain order. Its unknown-kind rule (warn, hold descendants as orphans) is replaced by the enabling rule above: since RenameMember is a version 1 kind there is no "upgrade before the first rename" step for vaults made in format version 1 as changed here.
  • 0017 and 0043 are superseded: there are no passes, arbiters, binders, yields, withdrawals, contests or held demotions.

Consequences

  • Every attack in design.md section 7 that relied on choosing a place in fold order is gone: the backdated record is void (stale-parent), or it is judged at the tip after the deciding link and void for authority. What is left is a real-time race decided by the transport before the deciding link lands, which any system where peers can manage each other has.
  • Revocations, removals and demotions are final once the command reports success. Another root admin can grant a removed role back, and two root admins in conflict can undo each other; the chain records every step with its author, and the recovery key and member revocation are the remedies.
  • Privilege commands take a round trip to the backend and fail cleanly offline.
  • Equivocation remains: a malicious remote, anyone who can force-push, or a member with write access to a shared folder can show a newcomer, or a member who has not synced for a while, a chain that forks before anything that member has seen. Everyone who synced past the fork refuses it; the join pin, key verify fingerprints and the data-anchor cross-check narrow it. Transparency logs and witness co-signing are deferred.
  • Anyone who can write to the transport can delay privilege writes with junk slot files (each costs a writer one slot; a stream can run a command into policy-busy). Removing a member's or device's push access at the forge, or write access to a shared folder, is part of revoking it. The hosted service refuses junk at admission.
  • A member with push access can raise a per-client, recoverable fork alarm by merging a side branch that once held a signed competing version of a slot; it names the member, and each client clears it once with --accept-rollback <fingerprint>.
  • Limitation, closed for wrap files by the change wrap-paths-by-mint-link (ticket 01M6BMABX8FT150Q7CSA2DN4PV; ADR 0052). Wrap paths were keyed by collection and epoch number only and wraps are write-once, so in a shared folder a mint that lost its slot left wraps at the paths the next legitimate mint needed, and every later mint, and every revocation that mints (a device revoked as compromised, any member revocation, since a RevokeMember carries a mint), failed with "existing file differs"; a planted wrap did the same, and a lost or planted wrap for one recipient could block a later grant or add-member. That change keys each wrap path by the link that calls for it, whose id nobody knows before it is signed, and all of it has merged: the vault layer and hosted admission, and the CLI regression tests, the shared-folder conflict-copy handling and doctor's stray-wrap finding, which reports a lost record's leftover wraps and names that record and its author. The CLI still never re-applies a lost mint or a revocation that mints; it names vaultfold epoch new <collection> or the revocation command to run again, and that command now succeeds. ADR 0052 lists what a member with folder write access can still do. policy-linear-chain is archived before that change, whose deltas are written on top of its own.
  • Test vectors, the golden chain, fixtures and fuzz corpora were regenerated; development vaults made before this change are re-created. The hosted service is deployed before clients; an older service would admit a stale-parent record, which new clients treat as void and report.

Alternatives considered

  • Keep patching the multi-pass fold (a fourth pass, fix-reduction-pass2-bypass). Rejected by Ben: each round closed one form of backdating and opened another, because the author still chose its place in the order.
  • A causal-authority fold with seniority. Superseded the same day: seniority hands the decision to whoever holds the older key.
  • parents as a one-element array. Rejected as an easier decoder bug than a single value.
  • Automatic fork choice (longest chain, lowest id, seniority). Rejected: each gives the choice back to whoever can write records.
  • Queued offline privilege writes. Rejected for version 1: a queued signed record names a stale tip and has to be re-signed anyway, data written meanwhile would anchor on an unpublished link, and a revocation that exists only on one laptop protects nobody. Queued unsigned intents remain possible later without a format change.
  • Keep the demotion quorum. Withdrawn by Ben on 2026-10-31 (see above). Its design history is design.md sections 5.4, 11, 12 and 13.
  • EnableKinds by any root admin, or by an admin with a recovery approval. Rejected: the first lets one rogue admin freeze a vault without a recovery key for good; the second needs the approval mechanism quorum removal took away. Recovery key only is the one option in which no single admin can freeze a vault.
  • Held files stop the walk and block writes (the design note). Rejected: one file naming a random parent would wedge the vault for good. Held and void files are skipped and the writer fills the gap.