DodoSSH/src/DodoSSH.Client.Domain/SpelunkRoute.cs

using System.Diagnostics.CodeAnalysis;

namespace DodoSSH.Client.Domain;

/// <summary>
/// How a host is reached through Spelunk: which Spelunk, which of its servers, and which key opens the way.
/// </summary>
/// <remarks>
/// <para>
/// Spelunk manages servers through an agent that runs on each of them and keeps a connection open to
/// Spelunk. A host carrying one of these is never dialled: a connection to it asks that Spelunk for a
/// ticket, opens a WebSocket, and Spelunk hands the bytes to the agent, which connects to the SSH server on
/// the machine's own loopback. That reaches a server with no public SSH port at all — which is the case
/// this exists for — and it is why nothing here names an address to dial.
/// </para>
/// <para>
/// <b>Inside the host's encrypted payload, and nowhere else.</b> Unlike the relay, nothing about this has to
/// be readable by the DodoSSH server: the tunnel is opened by this client, against Spelunk, with a key only
/// the vault holds. So the concession ADR 0004 argues for the relay's address is not made for this.
/// </para>
/// <para>
/// <b>The API key is referenced, not embedded.</b> <see cref="ApiKeyCredentialId"/> names an ordinary
/// keychain credential whose password is the key, for the reason <see cref="HostSecret.CredentialId"/>
/// gives: one Spelunk key is the key for every server in its organisation, and a copy per host is twenty
/// places to rotate it and one to forget. It also means the key is encrypted, synced, merged and shown in
/// the keychain exactly as a password is, with no item type of its own to build and keep in step.
/// </para>
/// </remarks>
public sealed record SpelunkRoute
{
    /// <summary>The longest API address stored.</summary>
    /// <remarks>
    /// Far beyond any real address, and there for the reason <see cref="HostSecret.MaxPinnedPathLength"/>
    /// is: this is rendered by every device that decrypts the host, and an unbounded string is the shape a
    /// corrupted payload takes.
    /// </remarks>
    public const int MaxApiBaseLength = 512;

    /// <summary>
    /// The Spelunk API's base address, as <see cref="TryNormalizeApiBase"/> writes it — for example
    /// <c>https://api.spelunk.example.com</c>.
    /// </summary>
    /// <remarks>
    /// A string in its normalised form rather than a <see cref="Uri"/>, because this is compared: two hosts
    /// on the same Spelunk must say so in the same bytes, or a link from Spelunk would not find the host
    /// already saved for it and the merge would see a change nobody made.
    /// </remarks>
    public required string ApiBase { get; init; }

    /// <summary>The server's id in Spelunk.</summary>
    public required Guid ServerId { get; init; }

    /// <summary>The keychain credential whose password is the Spelunk API key.</summary>
    /// <remarks>
    /// Required rather than nullable. A route with no key can never be opened, and a host saved that way
    /// would refuse every connection with a sentence about something the editor let through. The reference
    /// can still dangle — the credential may be deleted on another machine — and that is refused where it
    /// is noticed, at connect, exactly as a missing SSH credential is.
    /// </remarks>
    public required Guid ApiKeyCredentialId { get; init; }

    /// <summary>Whether this is the route to the given server on the given Spelunk.</summary>
    /// <param name="apiBase">A normalised API base, as <see cref="TryNormalizeApiBase"/> writes it.</param>
    /// <param name="serverId">The server's id in Spelunk.</param>
    public bool IsFor(string apiBase, Guid serverId) =>
        ServerId == serverId && string.Equals(ApiBase, apiBase, StringComparison.Ordinal);

    /// <summary>Checks that this route can be stored and opened.</summary>
    public bool TryValidate([NotNullWhen(false)] out string? reason)
    {
        if (!TryNormalizeApiBase(ApiBase, out var normalized, out reason))
        {
            return false;
        }

        // Stored normalised or not at all, for the comparison the remarks on ApiBase depend on.
        if (!string.Equals(normalized, ApiBase, StringComparison.Ordinal))
        {
            reason = "The Spelunk API address is not in its normal form.";
            return false;
        }

        if (ServerId == Guid.Empty)
        {
            reason = "A host reached through Spelunk needs the id of its Spelunk server.";
            return false;
        }

        if (ApiKeyCredentialId == Guid.Empty)
        {
            reason = "A host reached through Spelunk needs a credential holding its Spelunk API key.";
            return false;
        }

        reason = null;
        return true;
    }

    /// <summary>
    /// Reads a Spelunk API address as a user or a link gives it, into the one form it is stored in.
    /// </summary>
    /// <remarks>
    /// <para>
    /// <b>HTTPS, or plain HTTP to this machine only.</b> The API key travels in a header on every tunnel, so
    /// an address that sends it in clear across a network is refused rather than stored. A Spelunk running
    /// on the developer's own box is the one place plain HTTP is harmless, and it is allowed there so the
    /// feature can be tried against one.
    /// </para>
    /// <para>
    /// No user name, password, query or fragment: none of them means anything to the API, and the first two
    /// are the classic way to make an address read as one host while naming another. What is left is the
    /// scheme, the authority and any path prefix, lower-cased where URLs are case-insensitive and without a
    /// trailing slash — so the same Spelunk typed twice is stored the same way twice.
    /// </para>
    /// </remarks>
    public static bool TryNormalizeApiBase(
        string? text,
        [NotNullWhen(true)] out string? apiBase,
        [NotNullWhen(false)] out string? reason)
    {
        apiBase = null;

        var trimmed = text?.Trim() ?? string.Empty;

        if (trimmed.Length == 0)
        {
            reason = "A host reached through Spelunk needs the address of the Spelunk API.";
            return false;
        }

        if (trimmed.Length > MaxApiBaseLength
            || !Uri.TryCreate(trimmed, UriKind.Absolute, out var uri)
            || uri.Scheme is not ("https" or "http")
            || uri.HostNameType is UriHostNameType.Unknown
            || string.IsNullOrEmpty(uri.Host))
        {
            reason = "The Spelunk API address must be a web address, like https://api.spelunk.example.com.";
            return false;
        }

        if (string.Equals(uri.Scheme, Uri.UriSchemeHttp, StringComparison.Ordinal) && !uri.IsLoopback)
        {
            reason = "The Spelunk API address must use https, because the API key is sent with every connection.";
            return false;
        }

        if (uri.UserInfo.Length > 0 || uri.Query.Length > 0 || uri.Fragment.Length > 0)
        {
            reason = "The Spelunk API address cannot carry a user name, a query or a fragment.";
            return false;
        }

        apiBase = uri.GetLeftPart(UriPartial.Path).TrimEnd('/');
        reason = null;
        return true;
    }
}