namespace DodoSSH.Contracts;

/// <summary>
/// An opaque ciphertext blob together with the plaintext metadata needed to recompute its AAD.
/// </summary>
/// <remarks>
/// <para>
/// The server stores and returns these verbatim. It cannot decrypt one, cannot validate the
/// contents, and cannot merge two. See docs/crypto.md.
/// </para>
/// <para>
/// <see cref="Envelope"/> is a complete DSH1 envelope and already carries its own algorithm
/// identifier and nonce, so neither is repeated here. <see cref="KeyGeneration"/> and
/// <see cref="AadVersion"/> are stored as columns because the AAD is recomputed from the row
/// rather than transmitted, and because they are what makes a lazy re-encrypt-on-write
/// migration possible later.
/// </para>
/// <para>
/// <b>Added 2026-07-29:</b> <see cref="WrappedDataKey"/> and <see cref="DataKeyId"/>. The
/// specification has required a per-item data key since §3, the database has carried
/// <c>data_key_wrap</c> and <c>content_key_id</c> since the first migration, and
/// <c>DshAad.ItemPayload</c> binds the data key id — but this record had nowhere to put either,
/// so a spec-compliant item could not actually be transmitted. Found by writing the client that
/// has to produce one. Safe to add now and not later: no payload has ever been stored, and only
/// clients can re-encrypt.
/// </para>
/// </remarks>
/// <param name="Envelope">The complete DSH1 envelope, base64 on the wire.</param>
/// <param name="WrappedDataKey">
/// The item's data key, wrapped under the vault key. Also a DSH1 envelope, and also opaque. It
/// travels with the payload because a data key belongs to one item <em>version</em>: rotating a
/// vault key re-wraps 32 bytes per item and never rewrites a content blob.
/// </param>
/// <param name="DataKeyId">
/// Identifies the data key, stored as <c>content_key_id</c>. Part of the payload's AAD, so a
/// server cannot pair one item's envelope with another's key wrap. Reserved as the seam for
/// per-item grants in M5.
/// </param>
/// <param name="KeyGeneration">Vault key generation this payload was encrypted under.</param>
/// <param name="AadVersion">Version of the AAD derivation rule used.</param>
public sealed record EncryptedPayload(
    byte[] Envelope,
    byte[] WrappedDataKey,
    Guid DataKeyId,
    uint KeyGeneration,
    byte AadVersion);
