File: AuthHandshakeMessageHandler.cs
Web Access
Project: Microsoft.NET.Build.Containers.csproj (Microsoft.NET.Build.Containers)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System.ComponentModel;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Net;
using System.Net.Http.Headers;
using System.Net.Sockets;
using System.Text;
using System.Text.Json;
using System.Text.RegularExpressions;
using Microsoft.Extensions.Logging;
using Microsoft.NET.Build.Containers.Credentials;
using Microsoft.NET.Build.Containers.Resources;
using Valleysoft.DockerCredsProvider;

namespace Microsoft.NET.Build.Containers;

/// <summary>
/// A delegating handler that performs the Docker auth handshake as described <see href="https://docs.docker.com/registry/spec/auth/token/">in their docs</see> if a request isn't authenticated
/// </summary>
internal sealed partial class AuthHandshakeMessageHandler : DelegatingHandler
{
    private const int MaxRequestRetries = 5; // Arbitrary but seems to work ok for chunked uploads to ghcr.io

    /// <summary>
    /// Unique identifier that is used to tag requests from this library to external registries.
    /// </summary>
    /// <remarks>
    /// Valid characters for this clientID are in the unicode range <see href="https://wintelguy.com/unicode_character_lookup.pl/?str=20-7E">20-7E</see>
    /// </remarks>
    private const string ClientID = "netsdkcontainers";
    private const string BasicAuthScheme = "Basic";
    private const string BearerAuthScheme = "Bearer";

    private sealed record AuthInfo(string Realm, string? Service, string? Scope);

    private readonly string _registryName;
    private readonly Uri _registryUri;
    private readonly bool _isInsecureRegistry;
    private readonly int _insecureRegistryHttpPort;
    private readonly ILogger _logger;
    private readonly RegistryMode _registryMode;
    private readonly Func<Uri, HttpMessageHandler> _createRealmHandler;
    private readonly Func<TimeSpan, CancellationToken, Task> _delay;
    private AuthenticationHeaderValue? _authentication;

    public AuthHandshakeMessageHandler(
        string registryName,
        Uri registryUri,
        bool isInsecureRegistry,
        HttpMessageHandler innerHandler,
        ILogger logger,
        RegistryMode mode,
        Func<Uri, HttpMessageHandler>? realmHandlerFactory = null,
        Func<TimeSpan, CancellationToken, Task>? delay = null) : base(innerHandler)
    {
        _registryName = registryName;
        _registryUri = registryUri;
        _isInsecureRegistry = isInsecureRegistry;
        _insecureRegistryHttpPort = RegistryNameContainsPort(registryName) ? registryUri.Port : 80;
        _logger = logger;
        _registryMode = mode;
        _createRealmHandler = realmHandlerFactory
            ?? new AuthRealmHandlerFactory(registryName, registryUri, isInsecureRegistry).Create;
        _delay = delay ?? Task.Delay;
    }

    /// <summary>
    /// the www-authenticate header must have realm, service, and scope information, so this method parses it into that shape if present
    /// </summary>
    /// <param name="msg"></param>
    /// <param name="bearerAuthInfo"></param>
    /// <returns></returns>
    private static bool TryParseAuthenticationInfo(HttpResponseMessage msg, [NotNullWhen(true)] out string? scheme, out AuthInfo? bearerAuthInfo)
    {
        bearerAuthInfo = null;
        scheme = null;

        var authenticateHeader = msg.Headers.WwwAuthenticate;
        if (!authenticateHeader.Any())
        {
            return false;
        }

        AuthenticationHeaderValue header = authenticateHeader.First();

        if (header.Scheme is not null)
        {
            scheme = header.Scheme;

            if (header.Scheme.Equals(BasicAuthScheme, StringComparison.OrdinalIgnoreCase))
            {
                bearerAuthInfo = null;
                return true;
            }
            else if (header.Scheme.Equals(BearerAuthScheme, StringComparison.OrdinalIgnoreCase))
            {
                var keyValues = ParseBearerArgs(header.Parameter);
                if (keyValues is null)
                {
                    return false;
                }
                return TryParseBearerAuthInfo(keyValues, out bearerAuthInfo);
            }
            else
            {
                return false;
            }
        }
        return false;

        static bool TryParseBearerAuthInfo(Dictionary<string, string> authValues, [NotNullWhen(true)] out AuthInfo? authInfo)
        {
            if (authValues.TryGetValue("realm", out string? realm))
            {
                string? service = null;
                authValues.TryGetValue("service", out service);
                string? scope = null;
                authValues.TryGetValue("scope", out scope);
                authInfo = new AuthInfo(realm, service, scope);
                return true;
            }
            else
            {
                authInfo = null;
                return false;
            }
        }

        static Dictionary<string, string>? ParseBearerArgs(string? bearerHeaderArgs)
        {
            if (bearerHeaderArgs is null)
            {
                return null;
            }
            Dictionary<string, string> keyValues = new();
            foreach (Match match in BearerParameterSplitter().Matches(bearerHeaderArgs))
            {
                keyValues.Add(match.Groups["key"].Value, match.Groups["value"].Value);
            }
            return keyValues;
        }
    }

    /// <summary>
    /// Response to a request to get a token using some auth.
    /// </summary>
    /// <remarks>
    /// <see href="https://docs.docker.com/registry/spec/auth/token/#token-response-fields"/>
    /// </remarks>
    private sealed record TokenResponse(string? token, string? access_token, int? expires_in, DateTimeOffset? issued_at)
    {
        public string ResolvedToken => token ?? access_token ?? throw new ArgumentException(Resource.GetString(nameof(Strings.InvalidTokenResponse)));
        public DateTimeOffset ResolvedExpiration
        {
            get
            {
                var issueTime = this.issued_at ?? DateTimeOffset.UtcNow; // per spec, if no issued_at use the current time
                var validityDuration = this.expires_in ?? 60; // per spec, if no expires_in use 60 seconds
                var expirationTime = issueTime.AddSeconds(validityDuration);
                return expirationTime;
            }
        }
    }

    /// <summary>
    /// Uses the authentication information from a 401 response to perform the authentication dance for a given registry.
    /// Credentials for the request are retrieved from the credential provider, then used to acquire a token.
    /// That token is cached for some duration determined by the authentication mechanism on a per-host basis.
    /// </summary>
    private async Task<(AuthenticationHeaderValue, DateTimeOffset)?> GetAuthenticationAsync(string registry, string scheme, AuthInfo? bearerAuthInfo, CancellationToken cancellationToken)
    {
        // For bearer auth, validate the realm before any credential lookup so that a malicious or
        // compromised registry response cannot trigger credential retrieval toward a hostile token
        // endpoint, and so that validation errors aren't masked by credential errors. The addresses
        // the realm resolves to are checked by the realm handler when it connects.
        Uri? validatedBearerRealm = null;
        HttpMessageHandler? realmHandler = null;
        if (scheme.Equals(BearerAuthScheme, StringComparison.OrdinalIgnoreCase))
        {
            Debug.Assert(bearerAuthInfo is not null);
            validatedBearerRealm = ValidateRealmUri(bearerAuthInfo.Realm, registry, _isInsecureRegistry);
            realmHandler = _createRealmHandler(validatedBearerRealm);
        }

        // The realm is untrusted, so token requests use a separate SSRF-protected transport rather
        // than the registry transport.
        using HttpMessageInvoker? realmClient = realmHandler is null ? null : new(realmHandler, disposeHandler: true);

        DockerCredentials? privateRepoCreds;
        // Allow overrides for auth via environment variables
        if (GetDockerCredentialsFromEnvironment(_registryMode) is (string credU, string credP))
        {
            privateRepoCreds = new DockerCredentials(credU, credP);
        }
        else
        {
            privateRepoCreds = await GetLoginCredentials(registry).ConfigureAwait(false);
        }

        if (scheme.Equals(BasicAuthScheme, StringComparison.OrdinalIgnoreCase))
        {
            var authValue = new AuthenticationHeaderValue(BasicAuthScheme, Convert.ToBase64String(Encoding.ASCII.GetBytes($"{privateRepoCreds.Username}:{privateRepoCreds.Password}")));
            return new(authValue, DateTimeOffset.MaxValue);
        }
        else if (scheme.Equals(BearerAuthScheme, StringComparison.OrdinalIgnoreCase))
        {
            Debug.Assert(bearerAuthInfo is not null);
            Debug.Assert(validatedBearerRealm is not null);
            Debug.Assert(realmClient is not null);

            // Obtain a Bearer token, when the credentials are:
            // - an identity token: use it for OAuth
            // - a username/password: use them for Basic auth, and fall back to OAuth

            if (string.IsNullOrWhiteSpace(privateRepoCreds.IdentityToken))
            {
                var authenticationValueAndDuration = await TryTokenGetAsync(realmClient, privateRepoCreds, bearerAuthInfo, validatedBearerRealm, cancellationToken).ConfigureAwait(false);
                if (authenticationValueAndDuration is not null)
                {
                    return authenticationValueAndDuration;
                }
            }

            return await TryOAuthPostAsync(realmClient, privateRepoCreds, bearerAuthInfo, validatedBearerRealm, cancellationToken).ConfigureAwait(false);
        }
        else
        {
            return null;
        }
    }

    /// <summary>
    /// Validates the syntax and scheme of the bearer realm URL returned in a WWW-Authenticate
    /// challenge. The addresses the realm resolves to are checked by <see cref="AuthRealmHandlerFactory"/>.
    /// </summary>
    internal static Uri ValidateRealmUri(string realm, string registryName, bool isInsecureRegistry)
    {
        if (!Uri.TryCreate(realm, UriKind.Absolute, out Uri? realmUri))
        {
            throw new InvalidAuthResponseException(
                registryName,
                Resource.FormatString(nameof(Strings.InvalidAuthResponse_RelativeOrUnparseableRealm), realm));
        }

        // Scheme allowlist. Always permit https; permit http only when the registry is insecure.
        // (Uri.Scheme is normalized to lowercase by Uri itself, so a plain comparison is fine.)
        bool schemeAllowed = realmUri.Scheme switch
        {
            "https" => true,
            "http" => isInsecureRegistry,
            _ => false,
        };
        if (!schemeAllowed)
        {
            throw new InvalidAuthResponseException(
                registryName,
                Resource.FormatString(nameof(Strings.InvalidAuthResponse_DisallowedScheme), realm, realmUri.Scheme));
        }

        return realmUri;
    }

    private static bool RegistryNameContainsPort(string registryName)
    {
        // Use a scheme that does not have a default port.
        return new Uri($"container://{registryName}").Port != -1;
    }

    /// <summary>
    /// Returns whether <paramref name="uri"/> targets the configured registry.
    /// For a registry configured as insecure, the HTTP fallback produced by
    /// <see cref="FallbackToHttpMessageHandler"/> is also accepted so that fallback can authenticate.
    /// This exception is limited to the same host and fallback port; it does not permit general
    /// HTTP or cross-host redirects.
    /// </summary>
    private bool IsRegistryOrigin(Uri uri)
    {
        if (!uri.IsAbsoluteUri
            || !uri.IdnHost.Equals(_registryUri.IdnHost, StringComparison.OrdinalIgnoreCase))
        {
            return false;
        }

        if (uri.Scheme == _registryUri.Scheme && uri.Port == _registryUri.Port)
        {
            return true;
        }

        return _isInsecureRegistry
            && _registryUri.Scheme == Uri.UriSchemeHttps
            && uri.Scheme == Uri.UriSchemeHttp
            && uri.Port == _insecureRegistryHttpPort;
    }

    /// <summary>
    /// Rejects Basic or Bearer authentication challenges from an origin other than the configured registry.
    /// Disposes <paramref name="response"/> before throwing <see cref="InvalidAuthResponseException"/>
    /// on rejection; callers retain ownership of the response when this method returns normally.
    /// </summary>
    private void ValidateAuthenticationOrigin(HttpResponseMessage response, Uri requestUri)
    {
        if (response.StatusCode != HttpStatusCode.Unauthorized)
        {
            return;
        }

        Uri challengeUri = response.RequestMessage?.RequestUri ?? requestUri;
        if (IsRegistryOrigin(challengeUri))
        {
            return;
        }

        // Reject another origin based on the scheme alone; its parameters may be malformed.
        if (response.Headers.WwwAuthenticate.Any(challenge =>
            string.Equals(challenge.Scheme, BasicAuthScheme, StringComparison.OrdinalIgnoreCase)
            || string.Equals(challenge.Scheme, BearerAuthScheme, StringComparison.OrdinalIgnoreCase)))
        {
            response.Dispose();
            throw new InvalidAuthResponseException(
                _registryName,
                Resource.FormatString(
                    nameof(Strings.InvalidAuthResponse_UnexpectedAuthOrigin),
                    challengeUri.GetLeftPart(UriPartial.Authority),
                    _registryUri.GetLeftPart(UriPartial.Authority)));
        }
    }


    internal static (string credU, string credP)? TryGetCredentialsFromEnvVars(string unameVar, string passwordVar)
    {
        var credU = Environment.GetEnvironmentVariable(unameVar);
        var credP = Environment.GetEnvironmentVariable(passwordVar);
        if (!string.IsNullOrEmpty(credU) && !string.IsNullOrEmpty(credP))
        {
            return (credU, credP);
        }
        else
        {
            return null;
        }
    }

    /// <summary>
    /// Gets docker credentials from the environment variables based on registry mode.
    /// </summary>
    internal static (string credU, string credP)? GetDockerCredentialsFromEnvironment(RegistryMode mode)
    {
        if (mode == RegistryMode.Push)
        {
            if (TryGetCredentialsFromEnvVars(ContainerHelpers.PushHostObjectUser, ContainerHelpers.PushHostObjectPass) is (string, string) pushCreds)
            {
                return pushCreds;
            }

            if (TryGetCredentialsFromEnvVars(ContainerHelpers.HostObjectUser, ContainerHelpers.HostObjectPass) is (string, string) genericCreds)
            {
                return genericCreds;
            }

            return TryGetCredentialsFromEnvVars(ContainerHelpers.HostObjectUserLegacy, ContainerHelpers.HostObjectPassLegacy);
        }
        else if (mode == RegistryMode.Pull)
        {
            return TryGetCredentialsFromEnvVars(ContainerHelpers.PullHostObjectUser, ContainerHelpers.PullHostObjectPass);
        }
        else if (mode == RegistryMode.PullFromOutput)
        {
            if (TryGetCredentialsFromEnvVars(ContainerHelpers.PullHostObjectUser, ContainerHelpers.PullHostObjectPass) is (string, string) pullCreds)
            {
                return pullCreds;
            }

            if (TryGetCredentialsFromEnvVars(ContainerHelpers.HostObjectUser, ContainerHelpers.HostObjectPass) is (string, string) genericCreds)
            {
                return genericCreds;
            }

            return TryGetCredentialsFromEnvVars(ContainerHelpers.HostObjectUserLegacy, ContainerHelpers.HostObjectPassLegacy);
        }
        else
        {
            throw new InvalidEnumArgumentException(nameof(mode), (int)mode, typeof(RegistryMode));
        }
    }

    /// <summary>
    /// Implements the Docker OAuth2 Authentication flow as documented at <see href="https://docs.docker.com/registry/spec/auth/oauth/"/>.
    /// </summary
    private async Task<(AuthenticationHeaderValue, DateTimeOffset)?> TryOAuthPostAsync(HttpMessageInvoker realmClient, DockerCredentials privateRepoCreds, AuthInfo bearerAuthInfo, Uri realmUri, CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();

        _logger.LogTrace("Attempting to authenticate on {uri} using POST.", realmUri);
        Dictionary<string, string?> parameters = new()
        {
            ["client_id"] = ClientID,
        };
        if (!string.IsNullOrWhiteSpace(privateRepoCreds.IdentityToken))
        {
            parameters["grant_type"] = "refresh_token";
            parameters["refresh_token"] = privateRepoCreds.IdentityToken;
        }
        else
        {
            parameters["grant_type"] = "password";
            parameters["username"] = privateRepoCreds.Username;
            parameters["password"] = privateRepoCreds.Password;
        }
        if (bearerAuthInfo.Service is not null)
        {
            parameters["service"] = bearerAuthInfo.Service;
        }
        if (bearerAuthInfo.Scope is not null)
        {
            parameters["scope"] = bearerAuthInfo.Scope;
        }
        HttpRequestMessage postMessage = new(HttpMethod.Post, realmUri)
        {
            Content = new FormUrlEncodedContent(parameters)
        };

        using HttpResponseMessage postResponse = await realmClient.SendAsync(postMessage, cancellationToken).ConfigureAwait(false);
        if (!postResponse.IsSuccessStatusCode)
        {
            await postResponse.LogHttpResponseAsync(_logger, cancellationToken).ConfigureAwait(false);
            return null; // try next method
        }
        _logger.LogTrace("Received '{statuscode}'.", postResponse.StatusCode);
        TokenResponse? tokenResponse = JsonSerializer.Deserialize<TokenResponse>(postResponse.Content.ReadAsStream(cancellationToken));
        if (tokenResponse is { } tokenEnvelope)
        {
            var authValue = new AuthenticationHeaderValue(BearerAuthScheme, tokenResponse.ResolvedToken);
            return (authValue, tokenResponse.ResolvedExpiration);
        }
        else
        {
            _logger.LogTrace(Resource.GetString(nameof(Strings.CouldntDeserializeJsonToken)));
            return null; // try next method
        }
    }

    /// <summary>
    /// Implements the Docker Token Authentication flow as documented at <see href="https://docs.docker.com/registry/spec/auth/token/"/>
    /// </summary>
    private async Task<(AuthenticationHeaderValue, DateTimeOffset)?> TryTokenGetAsync(HttpMessageInvoker realmClient, DockerCredentials privateRepoCreds, AuthInfo bearerAuthInfo, Uri realmUri, CancellationToken cancellationToken)
    {
        // this doesn't seem to be called out in the spec, but actual username/password auth information should be converted into Basic auth here,
        // even though the overall Scheme we're authenticating for is Bearer
        var header = new AuthenticationHeaderValue(BasicAuthScheme, Convert.ToBase64String(Encoding.ASCII.GetBytes($"{privateRepoCreds.Username}:{privateRepoCreds.Password}")));
        var builder = new UriBuilder(realmUri);

        _logger.LogTrace("Attempting to authenticate on {uri} using GET.", realmUri);
        var queryDict = System.Web.HttpUtility.ParseQueryString("");
        if (bearerAuthInfo.Service is string svc)
        {
            queryDict["service"] = svc;
        }
        if (bearerAuthInfo.Scope is string s)
        {
            queryDict["scope"] = s;
        }
        builder.Query = queryDict.ToString();
        var message = new HttpRequestMessage(HttpMethod.Get, builder.ToString());
        message.Headers.Authorization = header;

        using var tokenResponse = await realmClient.SendAsync(message, cancellationToken).ConfigureAwait(false);
        if (!tokenResponse.IsSuccessStatusCode)
        {
            await tokenResponse.LogHttpResponseAsync(_logger, cancellationToken).ConfigureAwait(false);
            return null; // try next method
        }

        TokenResponse? token = JsonSerializer.Deserialize<TokenResponse>(tokenResponse.Content.ReadAsStream(cancellationToken));
        if (token is null)
        {
            throw new ArgumentException(Resource.GetString(nameof(Strings.CouldntDeserializeJsonToken)));
        }
        return (new AuthenticationHeaderValue(BearerAuthScheme, token.ResolvedToken), token.ResolvedExpiration);
    }

    private static async Task<DockerCredentials> GetLoginCredentials(string registry)
    {
        // For authentication with Docker Hub, 'docker login' uses 'https://index.docker.io/v1/' as the registry key.
        // And 'podman login docker.io' uses 'docker.io'.
        // Try the key used by 'docker' first, and then fall back to the regular case for 'podman'.
        if (registry == ContainerHelpers.DockerRegistryAlias)
        {
            try
            {
                return await CredsProvider.GetCredentialsAsync("https://index.docker.io/v1/").ConfigureAwait(false);
            }
            catch
            { }
        }

        try
        {
            return await CredsProvider.GetCredentialsAsync(registry).ConfigureAwait(false);
        }
        catch (Exception e)
        {
            throw new CredentialRetrievalException(registry, e);
        }
    }

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (request.RequestUri is null)
        {
            throw new ArgumentException(Resource.GetString(nameof(Strings.NoRequestUriSpecified)), nameof(request));
        }

        bool isRegistryOrigin = IsRegistryOrigin(request.RequestUri);
        AuthenticationHeaderValue? attemptedAuthentication = isRegistryOrigin ? Volatile.Read(ref _authentication) : null;
        if (attemptedAuthentication is not null)
        {
            request.Headers.Authorization = attemptedAuthentication;
        }

        int retryCount = 0;
        List<Exception>? requestExceptions = null;
        AuthenticationHeaderValue? authenticationToCache = null;

        while (retryCount < MaxRequestRetries)
        {
            try
            {
                // Redirects mutate the request URI and clear Authorization, including for same-origin redirects.
                // Restore only the existing credential, and only while retrying the registry itself.
                if (retryCount > 0 && IsRegistryOrigin(request.RequestUri)
                    && (authenticationToCache ?? attemptedAuthentication) is { } retryAuthentication)
                {
                    request.Headers.Authorization = retryAuthentication;
                }

                var response = await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
                ValidateAuthenticationOrigin(response, request.RequestUri);
                if (authenticationToCache is not null && response.StatusCode != HttpStatusCode.Unauthorized)
                {
                    Interlocked.Exchange(ref _authentication, authenticationToCache);
                }

                if (response.StatusCode != HttpStatusCode.Unauthorized
                    || !isRegistryOrigin
                    || authenticationToCache is not null)
                {
                    return response;
                }

                string? scheme;
                AuthInfo? authInfo;
                bool challengeParsed;
                try
                {
                    challengeParsed = TryParseAuthenticationInfo(response, out scheme, out authInfo);
                }
                catch
                {
                    response.Dispose();
                    throw;
                }

                if (!challengeParsed)
                {
                    return response;
                }

                using (response)
                {
                    // Load the reply so the HTTP connection becomes available to send the authentication request.
                    // Ideally we'd call LoadIntoBufferAsync, but it has no overload that accepts a CancellationToken so we call ReadAsByteArrayAsync instead.
                    _ = await response.Content.ReadAsByteArrayAsync(cancellationToken).ConfigureAwait(false);
                }

                if (attemptedAuthentication is not null)
                {
                    Interlocked.CompareExchange(ref _authentication, null, attemptedAuthentication);
                }

                if (await GetAuthenticationAsync(_registryName, scheme!, authInfo, cancellationToken).ConfigureAwait(false) is not (AuthenticationHeaderValue authHeader, _))
                {
                    throw new UnableToAccessRepositoryException(_registryName);
                }

                authenticationToCache = authHeader;
                request.Headers.Authorization = authHeader;
                continue;
            }
            catch (HttpRequestException e) when (e.InnerException is IOException ioe && ioe.InnerException is SocketException se)
            {
                requestExceptions ??= new();
                requestExceptions.Add(e);

                retryCount += 1;
                _logger.LogInformation("Encountered a HttpRequestException {error} with message \"{message}\". Pausing before retry.", e.HttpRequestError, se.Message);
                _logger.LogTrace("Exception details: {ex}", se);
                await _delay(TimeSpan.FromSeconds(1.0 * Math.Pow(2, retryCount)), cancellationToken).ConfigureAwait(false);

                // retry
                continue;
            }
        }

        throw new ApplicationException(Resource.GetString(nameof(Strings.TooManyRetries)), new AggregateException(requestExceptions!));
    }

    [GeneratedRegex("(?<key>\\w+)=\"(?<value>[^\"]*)\"(?:,|$)")]
    private static partial Regex BearerParameterSplitter();
}