Skip to content

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 in openspec/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 the RevokeDevice or RevokeMember that carries the mint;
  • for a key that gains epochs it did not hold, the Grant (including a history extension), the AddMember or AddDevice that registers the key with access, the Supersede (the new key's copies of what the old key held) or the RegisterRecovery.

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_commit check 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 lists epochs/ to choose a recipient's wrap.
  • A transaction writes its wraps under the ids of the records it has just signed. Init signs 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-kek follow-up of ADR 0046) goes under that link's directory.
  • The kek_commit comparison 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-mismatch reports 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. Its kek_commit rule 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 revoke and member grant, by the losing admin or anyone else, succeed. The CLI's advice after a lost mint ("run vaultfold 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 as corrupt-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 as stray-wrap once the epoch number is minted, and the next mint writes under its own directory.
  • vault migrate skips 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_commit check already refuses it, and a wire change would cost the wrap test vectors for no new guarantee.
  • A new hosted refusal reason. Rejected: unauthorised-author already 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".