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 inopenspec/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
prodand the revocation of a device that readsprodmust be ordered against each other. - Genesis is link 0:
seqno0 and no parent. Every other record carries oneparent(a single id, not an array, so no decoder can accept two parents by mistake) and aseqnogreater than 0, both signed and part of the record id. Records are stored at their slot pathpolicy/<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>.keyis 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 ispolicy-rollbackand a different record at a pinned slot, or a pinned link turned void, ispolicy-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 addprints the new member's link fingerprint,vault add --expect-head <fingerprint>refuses a chain that does not hold it, andkey verifyprints 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;
syncanddoctorreport 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-uncheckedand 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>.polpath in any directory whosevault.jsonnames 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 ispolicy-rollback, other bytes arepolicy-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
unverifiedotherwise. 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 asvault-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>andvault add --expect-headrecord the accepted version of each disputed slot, which is how a vault whose history holds a disputed slot stays usable. Agit revertthat 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_nameof the last rename link in chain order. Its unknown-kind rule (warn, hold descendants as orphans) is replaced by the enabling rule above: sinceRenameMemberis 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 verifyfingerprints 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 aRevokeMembercarries 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 anddoctor'sstray-wrapfinding, 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 namesvaultfold 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-chainis 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.
parentsas 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.
EnableKindsby 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.