• 
      

    Add a class for handling secrets encoding/decoding.

    Review Request #15182 — Created July 21, 2026 and updated — Latest diff uploaded

    Information

    cryptozoology
    master

    Reviewers

    When managing stored secrets (such as auth-related state or other
    sensitive data), the current best practice is to:

    1. Generate a one-time-use key (a DEK, or Data Encryption Key)
    2. Encrypt the plaintext
    3. Key-wrap (effectively encrypt) the DEK using a parent KEK (Key
      Encryption Key), identified by a KID (key ID)
    4. 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 Secret class, 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).

    Secret is 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 a Secret using with Secret.from_encoded()
    and run all operations that need access to the plaintext within that
    context.

    Unit tests pass.

    Commits

    Files