0045: A 512 byte cap on enc_name and a 252 byte bound on names
- Status: accepted (cap-enc-name-size archived 2026-10-30)
- Date: 2026-10-29
- Change:
cap-enc-name-size(design.md decisions 1 to 3) - Builds on: 0006, 0042
Context
Member display names and collection names are stored in policy records as
enc_name values: a 24 byte nonce, then the XChaCha20-Poly1305 ciphertext
of the name padded by suite.Pad, then the 16 byte tag (vault-format
"Encrypted name format"). suite.Pad writes a 4 byte length and the name,
then zeros up to the smallest bucket of 256, 1024, 4096 or 65536 bytes.
Five fields hold one: genesis enc_name and enc_collection_name, and the
enc_name of add-member, create-collection and rename-member.
policy.Validate refused only an empty enc_name, and the CLI did not bound
name length, so an enc_name could be up to 65576 bytes. Policy records are
never compacted or deleted, so whatever a valid record carries is kept by
every replica and the hosted service for the life of the vault. Since ADR
0042 any member, even a plain reader, may rename itself, so any member could
add about 64 KiB that nobody can remove, as often as it liked (agentboard
ticket 01M5VREMP4; Ben approved a cap on 2026-10-26).
Decision
- Every
enc_namefield is at most 512 bytes (policy.MaxEncName), counting the whole value as stored: nonce, ciphertext and tag. The check is inpolicy.Validate, soDecode,SignedBytes,Encode,ID,SignandVerifyall apply it, and with them every client,doctorand the hosted service. A longer value isErrMalformed, naming the field and its length ("rename-member enc_name is 513 bytes, more than 512"). It applies to all five fields, including the two genesis fields, and not to the supersedesupersession. - A longer value is malformed, not rejected. The record never decodes,
so it is never folded and never reaches the member listing or the policy
history;
doctorreports its file ascorrupt-file; the hosted service refuses to admit it like any undecodable policy item. Records that cite it as a parent are held as for any missing parent. The rule needs no KEK, so every reader enforces it equally. - Names are at most 252 bytes of UTF-8 (
vault.MaxNameBytes).sealNamein core/vault, the one path by whichInit,AddMember,CreateCollectionandRenameMemberseal a name, refuses a longer name withvault.ErrNameTooLongbefore padding, so core never builds a record its ownValidatewould refuse and writes nothing. The CLI checks first, invalidateDisplayName(init--member-name, member add, member rename) and in collection new, with exit code 1, nothing written and a message that states the limit as "252 bytes". The bound is in bytes, not characters, because bytes are what the padding sees: 252 ASCII characters or 63 characters of four bytes.
Arithmetic
An enc_name is 24 + padded + 16 bytes, and padded is one of four
bucket sizes:
| Name length (UTF-8 bytes) | Padded (bucket) | enc_name |
|---|---|---|
| 0 to 252 | 256 | 296 |
| 253 to 1020 | 1024 | 1064 |
| 1021 to 4092 | 4096 | 4136 |
| 4093 to 65532 | 65536 | 65576 |
A name of at most 252 bytes plus the 4 byte length fits the 256 byte bucket,
so every enc_name a conformant client seals is exactly 24 + 256 + 16 = 296
bytes, under 512 with 216 bytes of margin (for example for a future suite
with a longer nonce or tag). One more byte of name moves to the next bucket
and gives 1064 bytes, which the cap refuses; that is why the cap needs the
name bound. 512 is the smallest power of two that holds 296.
A side effect: every name a conformant client writes seals to the same size, so name length is not visible in policy records.
Consequences
- Each policy record can add at most 512 bytes per name field to every replica, instead of about 64 KiB.
- The cap is a decoding rule, so it must ship in the first release: a client
with it and a client without it would disagree about which records are
valid and their folds would diverge. A record over the cap already stored
(only possible by forging one before this change) becomes a
corrupt-filefinding and drops out of the fold. - Names over 252 bytes, accepted before, are refused. There are no users before the first release.
- A future suite whose nonce and tag together exceed suite 1's by more than 216 bytes would need a format version anyway.
- No encoding and no test vector changes: every vector name seals to 296 bytes.
- Device names are not
enc_namevalues (they are sealed in the key record'senc_meta) and are not covered here.
Alternatives considered
- A cap of 2048 with names bounded at 1020 bytes. Rejected: four times the bytes per record for names no person or collection needs.
- Cap only the three kinds named in the ticket. Rejected: the genesis fields are the same kind of value from the same decoder, and leaving them open would keep one unbounded name in every vault.
- A fold rejection with a reason instead of malformed. Rejected: size is
a well-formedness rule like an empty
enc_name, needs no chain context, and should keep the record out of history and admin review altogether. - Bound names only in the CLI. Rejected: core would then sign records its own decoder refuses, and another front end could do the same.