Skip to content

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

  1. Every enc_name field is at most 512 bytes (policy.MaxEncName), counting the whole value as stored: nonce, ciphertext and tag. The check is in policy.Validate, so Decode, SignedBytes, Encode, ID, Sign and Verify all apply it, and with them every client, doctor and the hosted service. A longer value is ErrMalformed, 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 supersede supersession.
  2. 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; doctor reports its file as corrupt-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.
  3. Names are at most 252 bytes of UTF-8 (vault.MaxNameBytes). sealName in core/vault, the one path by which Init, AddMember, CreateCollection and RenameMember seal a name, refuses a longer name with vault.ErrNameTooLong before padding, so core never builds a record its own Validate would refuse and writes nothing. The CLI checks first, in validateDisplayName (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-file finding 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_name values (they are sealed in the key record's enc_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.