ADR 0008: Rotation-friendly envelope

Preserve V1 decryption compatibility while making V2 root-key rotation replace only per-record data-key wrapping and leave ciphertext intact.

Status: accepted for v0.4 groundwork.

Encrypted-envelope V1 authenticates the wrapped-data-key object as part of content encryption. That strongly binds the layers, but it also means replacing a data-key wrapping invalidates the content tag. Root-key rotation would have to process every record’s plaintext.

New records use encrypted-envelope V2. Its content authentication binds the format, version, suite, vault ID, complete record context, encoding, and content nonce. Its data-key wrapping separately binds the same routing context and the key version. The wrapped-data-key object is not part of content additional data. Rewrapping uses a fresh wrapping nonce and leaves the content nonce and ciphertext byte-for-byte unchanged.

V1 is not reinterpreted or removed. Parsers and decryption retain its original authenticated-data rules and deterministic compatibility vector. During root rotation, a V1 record is authenticated, decrypted locally, re-encrypted with a fresh content nonce as V2, and then processed like any V2 record. Temporary record-key and plaintext buffers are erased on the best-effort basis available in JavaScript and libsodium.

This decision does not itself define rotation transactions, checkpoints, device-envelope updates, or Recovery Kit replacement. Those operations build on this format and must not publish the new vault key version until every required encrypted artifact is durable.