namespace DodoSSH.Contracts;

/// <summary>
/// Registers a device key against an already-enrolled account, so that machine can unlock without the
/// passphrase.
/// </summary>
/// <remarks>
/// <para>
/// Separate from enrollment, and it has to be: enrollment happens once, and the machines that want this
/// were mostly enrolled long before anyone wired a keystore up. Without this endpoint the feature would
/// only ever reach accounts created after it shipped.
/// </para>
/// <para>
/// <b>Possession of the bundle is proved by construction.</b> Only a caller who has opened the secret
/// bundle can produce <paramref name="WrappedPrivateKey"/> — it is that bundle sealed to
/// <paramref name="PublicKey"/> — so the server needs no separate challenge. A caller who sent a wrap of
/// anything else would register a device that cannot unlock, which harms nobody but themselves.
/// </para>
/// <para>
/// The platform is deliberately not carried. It would be display-only, and a wire enum mirroring the
/// server's <c>DevicePlatform</c> is exactly the shape of duplication that has produced three
/// self-consistent bugs in this repository already. A device list that wants it can add it with a
/// mapping table and a test that pins the two together.
/// </para>
/// </remarks>
/// <param name="Name">Human-readable name for this machine, shown in the account's device list.</param>
/// <param name="PublicKey">X25519 public key of this device, 32 bytes.</param>
/// <param name="WrappedPrivateKey">
/// The caller's secret bundle sealed to <paramref name="PublicKey"/>. Opaque to the server.
/// </param>
public sealed record RegisterDeviceRequest(
    string Name,
    byte[] PublicKey,
    byte[] WrappedPrivateKey);

/// <summary>The registered device.</summary>
/// <remarks>
/// Re-registering the same public key returns the existing device rather than creating a second one, so
/// a retry after a dropped response is safe and <paramref name="EnrolledAt"/> may predate the call.
/// </remarks>
/// <param name="DeviceId">The device's identifier, for later revocation.</param>
/// <param name="EnrolledAt">When this device was first registered.</param>
public sealed record RegisterDeviceResponse(
    Guid DeviceId,
    DateTimeOffset EnrolledAt);
