0052: Epoch wraps keyed by the calling link
- Status: accepted
- Date: 2026-11-15 (orchestrator DECISION of 2026-11-14 on ticket 01M6BMABX8FT150Q7CSA2DN4PV; coordinator rulings of 2026-11-14 on the proposal's five open questions)
- Change:
wrap-paths-by-mint-link(design inopenspec/changes/wrap-paths-by-mint-link/design.md) - Amends: 0003 (where an epoch
wrap is stored), 0004
(the
epochs/line of the layout), 0025 (the hosted service checks a wrap's link segment) and 0046 (its shared-folder limitation on lost mints is closed); see "What this changes in other ADRs" below
Context
Under the linear policy chain (ADR 0046) each (collection, epoch number)
is minted by at most one link, and the next legal mint of a collection is
always its current epoch plus one. Epoch wraps are write-once (ADR 0004)
and lived at epochs/<collection-id>/<epoch>/<keyid>.wrap, a path that
depends only on the epoch number and the recipient, so anyone could name
the paths of the next mint before it existed.
In a shared-folder vault, which has no compare-and-swap across machines, those facts collide. Alice mints epoch N+1 in her copy and writes her record and then her wraps. Another admin's record takes the slot; the sync tool keeps that record, turns Alice's into a conflict copy and copies her wraps to every copy, since nobody else had files at those paths. The chain's epoch is still N, so every later mint is epoch N+1 again, its wraps go to the paths Alice's lost wraps occupy, and the put-if-absent write fails with "existing file differs". A retry fails the same way.
A reviewer's probe in policy-linear-chain (ticket
01M6BMABX8FT150Q7CSA2DN4PV) confirmed it: vaultfold epoch new by the
losing admin and by another root admin, and device revoke --grade compromised, all failed, while --grade lost (no mint) succeeded. The
same shape held for every other wrap: a grant to a key already in the
vault wraps existing epochs at paths that were public before the grant
existed, so a file left there blocked that grant.
So any member with write access to the folder, honest or not, could
block every mint and every revocation that mints, for one collection, by
leaving one wrap file. Revocation after a compromise is the operation
that must always go through. ADR 0046's kek_commit and conflict-copy
reading cover the read side only: the write happens before any record
exists to compare against.
Decision
The path
epochs/<collection-id>/<epoch>/<link>/<keyid>.wrap
<link> is the first 8 bytes, as 16 lowercase hex characters, of the id
of the wrap's calling link: the first link in chain order after which
the recipient holds that epoch of that collection. Holding an epoch is
monotone along the chain (a revocation removes no epoch), so every wrap a
client writes has exactly one calling link. It is:
- for the wrapped set of a mint, the mint itself: Genesis for the
creator's root epoch 1, a
NewEpoch(including a created collection's first), or theRevokeDeviceorRevokeMemberthat carries the mint; - for a key that gains epochs it did not hold, the
Grant(including a history extension), theAddMemberorAddDevicethat registers the key with access, theSupersede(the new key's copies of what the old key held) or theRegisterRecovery.
A record's id is the hash of its signed bytes, which commit to the
parent, the HLC, the signature and, for a mint, a fresh random KEK
through kek_commit. No prefix of it can be predicted before the record
is signed. So no wrap path exists before the record that calls for it:
a lost record's wraps can never sit at a path a later record needs, a
re-signed record after a lost race writes under a fresh directory, and
nobody can leave a file in the way in advance. This holds for mints,
revocations and grants alike.
The path is 133 characters, so the naming bound of the vault format rises from 120 to 140 characters and the Windows path scenario's prefix becomes 120 characters (120 + 1 + 133 = 254, under 260). The alphabet is unchanged: decimal digits and lowercase hex.
The prefix length
The segment only separates the directories of different records that call for a wrap of the same (collection, epoch, recipient): the one calling link and any lost records. It does not identify the link; the policy state does.
- Eight bytes (16 hex) costs 2^64 work to produce a record whose id
shares the prefix of a given link. Such a collision puts the other
record's wraps under the link's directory, where put-if-absent makes
them conflict copies or stray files and the
kek_commitcheck refuses them for reading. A collision costs a doctor report, never a wrong KEK. - The full id (64 hex) would make the path 181 characters, which breaks the Windows scenario at any realistic vault prefix.
- Four bytes (8 hex) would fit in 125 characters but makes that cosmetic collision cheap to produce on purpose.
Resolution through the policy state
The fold records, per (key, collection, epoch), the link that first gave
the key that epoch, and exposes it as policy.State.HeldSince;
State.MintOf names the link that minted an epoch. The state's wire
encoding and every record's bytes are unchanged.
- Readers and writers derive every wrap path from
HeldSince. No code path listsepochs/to choose a recipient's wrap. - A transaction writes its wraps under the ids of the records it has
just signed.
Initsigns Genesis before it writes the root wrap. A grant plan made before the grant is signed reports collection, epoch and recipient and no path. - A wrap one device writes for a link another device authored (the
missing-kekfollow-up of ADR 0046) goes under that link's directory. - The
kek_commitcomparison and the conflict-copy fallback of ADR 0046 stay as they are. Once a link's first file has synced, its directory name is public and a folder writer can race the honest wraps for the link's other recipients; the sync tool keeps one file and the commitment decides which is used (wrap-mismatchreports the other).
Stray wraps
A wrap for a recipient that holds the epoch, under any directory other
than its calling link's, is a stray. It is never used to encrypt, and is
never read as the recipient's wrap. vaultfold doctor reports each as
stray-wrap, a warning that does not change the exit status, with one
of three details:
- the directory is that of a record that lost its slot, when a void record whose id begins with the segment is present (a slot file or a conflict copy) and verifies under its author's registered key. Doctor then names that record and its author, in the words "; the directory is that of a lost record written by ";
- the directory is that of a link that does not call for this wrap;
- no record of this vault names this directory.
Attribution comes from the signed void record only. The wrapper a wrap file names is never read for it, because whoever plants a file chooses that field. Doctor therefore names the author of the lost record, and never says who wrote the wrap file: a file under a lost record's directory need not have been written by that record's author.
orphan-wrap keeps its meaning (the recipient does not hold the epoch,
whatever the directory) and takes precedence, so a lost mint's wraps are
orphan-wrap while no link has minted that epoch number and
stray-wrap once one has, for each recipient that mint's wrapped set
holds; a recipient the winning mint does not wrap to stays
orphan-wrap. missing-wrap names the derived path. A file
at an old-layout path is corrupt-file ("not a wrap file name") and is
read by nothing. vault migrate skips and counts stray wraps like any
other wrap no kept record needs.
One read of a stray directory remains, under ADR 0046's existing rule:
the author of a lost mint can decrypt, read-only and on its own client,
the data events it wrote under that mint, so that sync can offer to
write them again. The client reads the wrap under the directory of its
own void mint record, and only when that record is present and verifies
under this device's key and the KEK matches the record's kek_commit.
The candidate directories come from the void records the client already
collects, not from a listing of epochs/. Once held, that KEK stays in
memory until the vault is reopened, even if the void record disappears
in the meantime (group 0 review, N3): it was accepted only against a
verified void record of this device and decrypts only that device's own
events, read-only. This is deliberate and pinned in part by
TestLostMintKEKNotAskedAgainOnRefresh, which shows the device is
asked for that KEK once over an open and two refreshes and the event is
listed once; removal of the void record in the meantime is not
exercised by a test. TestSyncReapplyReadsLostMintDirectory covers the
re-apply flow.
Hosted admission
The service already finds the stored link that calls for a wrap and
stores the wrap only when that link's author, active, puts it (ADR 0025,
"Policy chain admission"; ADR 0046). It now also requires the path's
<link> segment to equal the first 16 hex characters of that link's id.
Anything else is refused unauthorised-author, the existing reason for
"no stored link by this device calls for this wrap", and stored nowhere;
a path of any other shape, the old layout included, is refused
not-supported. A hosted namespace therefore never holds a stray wrap.
The service reads the chain as stored and the path only, never the
wrap's content.
The service is deployed before any client built with this change, and no service built from between the change's groups 0 and 1 is deployed (docs/operations.md, "Deploying wrap paths keyed by their calling link").
Transports
| Transport | A losing write's wraps |
|---|---|
| Git, same branch and branch mode | Never published: the losing commit is unreferenced. |
| Hosted | Never stored: the batch lost its conditional write, and its link segment names no stored link. |
| Filesystem, one machine | Written, then removed when the slot is lost: the wraps go on disk before the slot file, and a writer whose create then finds the slot taken removes the wraps it wrote, which lie under its own link directory (OpenSpec change fsstore-wraps-before-record). |
| Filesystem, shared folder | Left in every copy as stray files under the losing record's own directory. The next record writes under its own. |
Format version
Format version 1 changes in place, as it did for ADR 0046, because
nothing has been released. There is no reader for the old layout and no
converter; development vaults are re-created. The vault-small test
vector and the fixtures that embed wrap paths were regenerated; no
policy record or event changed.
What this changes in other ADRs
- 0003: each epoch KEK is still wrapped to each authorised device key,
and adding a device is still purely additive. The wrap is stored at
epochs/<collection-id>/<epoch>/<link>/<keyid>.wrap, and one epoch's wraps are spread over one directory per calling link. - 0004: the
epochs/line of the layout gains the<link>segment. Wraps were never content-addressed; they are addressed by collection, epoch, calling link and recipient, and stay write-once. - 0025: wrap admission also checks the link segment (recorded in 0025's "Wrap link segment" bullet).
- 0046: the limitation in its Consequences ("Limitation, closed for wrap files
by the change
wrap-paths-by-mint-link") records this decision. Itskek_commitrule and conflict-copy reading stand. Row 25 of the attack table in policy-linear-chain's design.md described the read side of a wrap path clash; this record is the write side.
Consequences
- No privilege write can be blocked by a wrap file that existed before
its record was signed, on any backend, however often a race repeats.
After a lost mint or a lost grant in a shared folder,
epoch new,device revoke --grade compromised,member revokeandmember grant, by the losing admin or anyone else, succeed. The CLI's advice after a lost mint ("runvaultfold epoch new <collection>") is now true. CLI regression tests replay the probe and its grant variant. - This is a claim about wrap files only. A member with folder write
access is in effect a transport operator and can still deny
availability by other means. For example, a non-directory planted at
epochs/<collection>/<next epoch>makes every mint of that collection fail with a "not a directory" error until the file is removed; doctor reports it ascorrupt-file, and the hosted service refuses such names. This is the same class as deleting files, and the layout is not changed to route around it. - Stray wraps accumulate on the filesystem backend: one directory per lost record that called for wraps, never deleted outside compaction, reported at every doctor run. That costs disk and report lines, not availability of the vault.
- The filesystem backend writes a mint's wraps before its record, so
a record is never readable while a wrap it calls for is missing, and
a wrap write that fails aborts the mint with no record published
(OpenSpec change fsstore-wraps-before-record, which closed ticket
01M7FYRJT2KQC73Z8Z003NB5PM). A process that ends between the two
steps leaves wraps under a directory no record names; doctor reports
them as
orphan-wrap, then asstray-wraponce the epoch number is minted, and the next mint writes under its own directory. vault migrateskips stray wraps and counts them. Only vaults kept in a git repository can be migrated, and a lost mint leaves no wraps there (a losing commit is unreferenced), so the strays it skips are planted files and carry no data to recover. A shared-folder vault cannot be migrated.- An epoch's wraps are no longer in one directory, and a grant plan cannot name final paths before the grant is signed.
- Equivocation, forks and lost-write detection (ADR 0046) are unchanged.
Future work
Letting sync's re-apply offer to remove a client's own stray wraps
once the data written under its lost mint has been re-applied
(coordinator ruling 5). It needs a delete primitive for wraps, which
this change does not add.
Alternatives considered
- Let a mint replace a wrap whose bytes match no link's
kek_commit(rejected on the ticket). It trusts file contents: a planter can plant bytes that do match a void record's commitment. And a replace is a write at an existing path, which no file class allows. - A policy rule that skips burned epoch numbers (rejected on the ticket). An attacker burns numbers at will, and the fold would depend on file state outside the slot files, breaking ADR 0046's property that the state is a function of the slot files alone.
- Key every wrap of an epoch by its mint only (the first draft; coordinator ruling 1). It left grants to existing keys at predictable paths. Keying by the calling link uses what the fold and the hosted service already compute and leaves no wrap path predictable.
- A hyphenated segment,
<epoch>-<id-prefix>(the ticket's example). Path segments admit only[a-z0-9]runs separated by single dots, and a dot in a directory name reads as an extension. A nested directory carries the same information. - Drop the epoch number from the path. Rejected: doctor, the exposure audit and people read it, and the link segment alone would need the policy state to say which epoch a directory is.
- The full id, or four bytes of it (ruling 2). See "The prefix length".
- Bind the link id into the wrap record. Rejected: it would stop a
stray wrap being copied into a link's directory, but the
kek_commitcheck already refuses it, and a wire change would cost the wrap test vectors for no new guarantee. - A new hosted refusal reason. Rejected:
unauthorised-authoralready means that no stored link by the putter calls for the wrap. - A format version bump with a reader for the old layout (ruling 3). Rejected before the first release.
- Deleting a client's own stray wraps now (ruling 5). Excluded: the author's recovery of data written under a lost mint needs them until that data is re-applied. See "Future work".