DodoSSH/src/DodoSSH.Domain/Vaults.cs

namespace DodoSSH.Domain;

/// <summary>
/// A container of encrypted items sharing one vault key.
/// </summary>
/// <remarks>
/// The vault name is plaintext, unlike item names. A user has to be able to pick a vault before
/// anything is decrypted, and vault names are few and low-signal compared with a full host
/// inventory.
/// </remarks>
public sealed class Vault
{
    /// <summary>Primary key.</summary>
    public Guid Id { get; set; }

    /// <summary>Display name.</summary>
    public string Name { get; set; } = string.Empty;

    /// <summary>Whether this belongs to a user or a team.</summary>
    public VaultOwnerKind OwnerKind { get; set; }

    /// <summary>Owning user, for a personal vault.</summary>
    public Guid? OwnerUserId { get; set; }

    /// <summary>Owning user, for a personal vault.</summary>
    public UserAccount? OwnerUser { get; set; }

    /// <summary>Owning team, for a team vault.</summary>
    public Guid? TeamId { get; set; }

    /// <summary>Owning team, for a team vault.</summary>
    public Team? Team { get; set; }

    /// <summary>
    /// Current key generation. Bumped on rekey, and part of every item's AAD, so a server cannot
    /// roll a row back to a superseded generation.
    /// </summary>
    public int KeyGeneration { get; set; } = 1;

    /// <summary>Whether a membership or key change has left this vault needing a rekey.</summary>
    public bool RekeyRequired { get; set; }

    /// <summary>Why a rekey is pending.</summary>
    public RekeyReason RekeyReason { get; set; }

    /// <summary>Creation timestamp.</summary>
    public DateTimeOffset CreatedAtUtc { get; set; }

    /// <summary>Last modification timestamp.</summary>
    public DateTimeOffset UpdatedAtUtc { get; set; }

    /// <summary>Soft-delete marker.</summary>
    public DateTimeOffset? DeletedAtUtc { get; set; }

    /// <summary>
    /// The highest change-log sequence whose tombstone has been collected from this vault.
    /// </summary>
    /// <remarks>
    /// A cursor below it may have been issued before a deletion this server no longer records, so a pull
    /// from it is refused and the client starts over — see <c>TombstoneCollector</c> and ADR 0003. Zero until
    /// anything has been collected.
    /// </remarks>
    public long SyncHorizon { get; set; }

    /// <summary>Wrapped vault keys, one per recipient per generation.</summary>
    public ICollection<VaultKeyGrant> KeyGrants { get; } = [];

    /// <summary>Hosts in this vault.</summary>
    public ICollection<SshHost> Hosts { get; } = [];
}

/// <summary>
/// A vault key wrapped to one recipient, for one key generation.
/// </summary>
/// <remarks>
/// <para>
/// The server stores <see cref="WrappedKey"/> verbatim and cannot verify that it is the correct
/// vault key. A malicious granter can seal garbage; the recipient detects it on first unwrap as a
/// tag failure, and <see cref="Signature"/> names who did it. Detectable and attributable is the
/// right failure mode here — silent is not achievable, since verification would require the
/// server to hold the key.
/// </para>
/// <para>
/// <see cref="GranterKeyFingerprint"/> and <see cref="KeyLogHead"/> are recorded so a recipient
/// can check both who wrapped this and what view of the key log they held at the time.
/// </para>
/// </remarks>
public sealed class VaultKeyGrant
{
    /// <summary>Primary key.</summary>
    public Guid Id { get; set; }

    /// <summary>The vault.</summary>
    public Guid VaultId { get; set; }

    /// <summary>The vault.</summary>
    public Vault? Vault { get; set; }

    /// <summary>Key generation this grant is for.</summary>
    public int KeyGeneration { get; set; }

    /// <summary>Why this grant exists: a member, a recovery key, or escrow.</summary>
    public GrantKind Kind { get; set; }

    /// <summary>Recipient, for a member grant.</summary>
    public Guid? RecipientUserId { get; set; }

    /// <summary>Recipient, for a member grant.</summary>
    public UserAccount? RecipientUser { get; set; }

    /// <summary>
    /// Fingerprint of the exact public key this was wrapped to, so a later key rotation
    /// invalidates the grant explicitly rather than silently.
    /// </summary>
    public byte[] RecipientKeyFingerprint { get; set; } = [];

    /// <summary>The vault key, sealed to the recipient. Opaque.</summary>
    public byte[] WrappedKey { get; set; } = [];

    /// <summary>Who created this grant.</summary>
    public Guid GranterUserId { get; set; }

    /// <summary>Fingerprint of the granter's identity key.</summary>
    public byte[] GranterKeyFingerprint { get; set; } = [];

    /// <summary>Key log head the granter observed. Enables fork detection.</summary>
    public byte[]? KeyLogHead { get; set; }

    /// <summary>
    /// Ed25519 signature by the granter over the canonical grant tuple. Verified by clients, not
    /// by the server: server-side verification would be a convenience, never the boundary.
    /// </summary>
    public byte[] Signature { get; set; } = [];

    /// <summary>Grant state.</summary>
    public GrantState State { get; set; }

    /// <summary>Creation timestamp.</summary>
    public DateTimeOffset CreatedAtUtc { get; set; }

    /// <summary>Revocation timestamp.</summary>
    public DateTimeOffset? RevokedAtUtc { get; set; }
}