Add a class for handling secrets encoding/decoding.
Review Request #15182 — Created July 21, 2026 and updated — Latest diff uploaded
When managing stored secrets (such as auth-related state or other
sensitive data), the current best practice is to:
- Generate a one-time-use key (a DEK, or Data Encryption Key)
- Encrypt the plaintext
- Key-wrap (effectively encrypt) the DEK using a parent KEK (Key
Encryption Key), identified by a KID (key ID)- Store the resulting encrypted DEK, the KEK's KID, the encryption and
keywrap algorithms, and a version as an envelope header, with the
ciphertext appended.This change implements this through a
Secretclass, which manages a
plaintext and allows for encoding and decoding. It will generate a DEK
(unless one is available -- provided when decoding or for unit tests).Decoding takes a KEK resolver that returns the key matching the ID.
This keeps it separate from any key management mechanism (though once
that's built, this will cleanly integrate).
Secretis invalidatable, which means that it will automatically clear
its internal state when it falls out of scope or when used as a context
manager and the context closes. This helps avoid situations where the
resulting plaintext or DEK may be lingering somewhere accidentally.
Callers should decode aSecretusingwith Secret.from_encoded()
and run all operations that need access to the plaintext within that
context.
Unit tests pass.