path: root/apps/api/Accounts/AccountService.cs

// SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
// SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1

using Microsoft.AspNetCore.Identity;

namespace Progmasoft.Progmaweb.Api.Accounts;

/// <summary>Registration and sign-in rules of the account service.</summary>
/// <param name="store">Store that keeps accounts.</param>
/// <param name="timeProvider">Clock used for creation times.</param>
internal sealed class AccountService(
    IAccountStore store,
    TimeProvider timeProvider)
{
    /// <summary>An account that never exists; the subject of the dummy verification.</summary>
    private static readonly AccountRecord DummyAccount = new(
        Guid.Empty,
        "Missing00",
        "MISSING00",
        "missing@example.invalid",
        "MISSING@EXAMPLE.INVALID",
        null,
        string.Empty,
        DateTimeOffset.UnixEpoch);
    /// <summary>
    /// A hash that no submitted password matches. Verifying against it makes a sign-in with an unknown address cost
    /// as much as one with a wrong password.
    /// </summary>
    private static readonly string DummyPasswordHash =
        new PasswordHasher<AccountRecord>().HashPassword(DummyAccount, "not-the-provided-password");

    /// <summary>Hashes and verifies passwords with the ASP.NET Core Identity algorithm.</summary>
    private readonly PasswordHasher<AccountRecord> passwordHasher = new();

    /// <summary>Creates a password account and opens a session for it.</summary>
    /// <param name="request">The registration body.</param>
    /// <param name="sessions">Session service.</param>
    /// <param name="cancellationToken">Cancels the operation.</param>
    /// <returns>
    /// The signed-in account and no errors, or no account and the messages of each refused field, keyed by
    /// <c>accountName</c>, <c>email</c>, <c>password</c> and <c>acceptPolicies</c>.
    /// </returns>
    public async ValueTask<(AuthenticatedAccount? Authentication, Dictionary<string, string[]> Errors)> RegisterAsync(
        RegisterAccountRequest request,
        SessionService sessions,
        CancellationToken cancellationToken)
    {
        Dictionary<string, string[]> errors = ValidateRegistration(request, out string accountName,
            out string email, out string normalizedEmail);
        if (errors.Count != 0)
        {
            return (null, errors);
        }

        DateTimeOffset now = timeProvider.GetUtcNow();
        AccountRecord provisional = new(
            Guid.NewGuid(),
            accountName,
            AccountNamePolicy.NormalizeForLookup(accountName),
            email,
            normalizedEmail,
            null,
            string.Empty,
            now,
            PolicyAcceptance.CurrentVersion,
            now);

        string passwordHash = passwordHasher.HashPassword(provisional, request.Password!);
        AccountRecord account = provisional with { PasswordHash = passwordHash };
        CreateAccountResult result = await store.CreateAsync(account, cancellationToken);

        if (result.Status is CreateAccountStatus.AccountNameUnavailable)
        {
            return (null, new Dictionary<string, string[]> { ["accountName"] = ["That account name is unavailable."] });
        }

        if (result.Status is CreateAccountStatus.EmailUnavailable)
        {
            return (null, new Dictionary<string, string[]> { ["email"] = ["That email address is already registered."] });
        }

        // The store returns the account as it keeps it, which is what every later read returns.
        AuthenticatedAccount authentication = await sessions.CreateAsync(result.Account ?? account, cancellationToken);
        return (authentication, errors);
    }

    /// <summary>Signs in with email address and password.</summary>
    /// <remarks>
    /// An unknown address costs one password verification against a private dummy hash, so the response time does not
    /// reveal whether an address is registered.
    /// </remarks>
    /// <param name="request">The login body.</param>
    /// <param name="sessions">Session service.</param>
    /// <param name="cancellationToken">Cancels the operation.</param>
    /// <returns>The signed-in account, or <see langword="null"/> when the credentials are refused.</returns>
    public async ValueTask<AuthenticatedAccount?> LoginAsync(
        LoginAccountRequest request,
        SessionService sessions,
        CancellationToken cancellationToken)
    {
        AccountRecord? account = await VerifyPasswordAsync(request.Email, request.Password, cancellationToken);
        return account is null ? null : await sessions.CreateAsync(account, cancellationToken);
    }

    /// <summary>Checks an email address and password without opening a session.</summary>
    /// <remarks>
    /// Progmasoft Credentials signs the account in with its own cookie and must not open a session of the account
    /// site. The verification is the one <see cref="LoginAsync"/> uses, with the same cost for an unknown address.
    /// </remarks>
    /// <param name="email">Email address as entered.</param>
    /// <param name="password">Password as entered.</param>
    /// <param name="cancellationToken">Cancels the operation.</param>
    /// <returns>The account, or <see langword="null"/> when the credentials are refused.</returns>
    public async ValueTask<AccountRecord?> VerifyPasswordAsync(
        string? email,
        string? password,
        CancellationToken cancellationToken)
    {
        if (!EmailAddressPolicy.TryNormalize(email, out _, out string normalizedEmail, out _) ||
            password is null || password.Length > PasswordPolicy.MaximumLength)
        {
            return null;
        }

        AccountRecord? account = await store.FindByEmailAsync(normalizedEmail, cancellationToken);
        if (account is null || account.PasswordHash is null)
        {
            // Reuse one private hash so an unknown email follows one expensive verification, like a bad password.
            _ = passwordHasher.VerifyHashedPassword(DummyAccount, DummyPasswordHash, password);
            return null;
        }

        PasswordVerificationResult verification =
            passwordHasher.VerifyHashedPassword(account, account.PasswordHash, password);
        return verification is PasswordVerificationResult.Failed ? null : account;
    }

    /// <summary>Finds an account by its identifier, for a Credentials session that names it.</summary>
    /// <param name="id">Identifier of the account.</param>
    /// <param name="cancellationToken">Cancels the operation.</param>
    /// <returns>The account, or <see langword="null"/> when it no longer exists.</returns>
    public ValueTask<AccountRecord?> FindAsync(Guid id, CancellationToken cancellationToken) =>
        store.FindByIdAsync(id, cancellationToken);

    /// <summary>Signs in with a Google identity, creating the account on first use.</summary>
    /// <remarks>
    /// An identity that is already linked signs in to its account. A new identity creates an account under the
    /// requested name. A new identity whose email address belongs to an existing account is refused: password
    /// registrations do not verify the address, so linking by address could hand an account to someone else.
    /// </remarks>
    /// <param name="providerSubject">Subject identifier Google issued for the identity.</param>
    /// <param name="providerEmail">Email address Google reported for the identity.</param>
    /// <param name="requestedAccountName">Account name to create for a new identity; may be <see langword="null"/>.</param>
    /// <param name="acceptedPolicies">
    /// Version of the policies the person accepted before leaving for Google; a new identity creates an account only
    /// when it is <see cref="PolicyAcceptance.CurrentVersion"/>.
    /// </param>
    /// <param name="sessions">Session service.</param>
    /// <param name="cancellationToken">Cancels the operation.</param>
    /// <returns>The signed-in account, or no account and the reason.</returns>
    public async ValueTask<(AuthenticatedAccount? Authentication, GoogleAccountFailure Failure)>
        AuthenticateGoogleAsync(
            string? providerSubject,
            string? providerEmail,
            string? requestedAccountName,
            string? acceptedPolicies,
            SessionService sessions,
            CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(providerSubject) ||
            !EmailAddressPolicy.TryNormalize(providerEmail, out string email, out string normalizedEmail, out _))
        {
            return (null, GoogleAccountFailure.ProviderRejected);
        }

        AccountRecord? knownGoogleAccount =
            await store.FindByGoogleSubjectAsync(providerSubject, cancellationToken);
        if (knownGoogleAccount is not null)
        {
            return (await sessions.CreateAsync(knownGoogleAccount, cancellationToken), GoogleAccountFailure.None);
        }

        AccountRecord? existing = await store.FindByEmailAsync(normalizedEmail, cancellationToken);
        if (existing is not null)
        {
            // Password registrations do not verify ownership of the supplied email address yet. Automatically
            // linking a verified Google identity by email would therefore let two unrelated people share an
            // account (and any already-issued sessions) when one of them registered the other's address.
            return (null, GoogleAccountFailure.ProviderRejected);
        }

        if (requestedAccountName is null)
        {
            return (null, GoogleAccountFailure.AccountNameRequired);
        }

        if (!AccountNamePolicy.TryNormalize(requestedAccountName, out string accountName, out _))
        {
            return (null, GoogleAccountFailure.InvalidAccountName);
        }

        if (acceptedPolicies != PolicyAcceptance.CurrentVersion)
        {
            return (null, GoogleAccountFailure.PoliciesRequired);
        }

        DateTimeOffset now = timeProvider.GetUtcNow();
        AccountRecord account = new(
            Guid.NewGuid(),
            accountName,
            AccountNamePolicy.NormalizeForLookup(accountName),
            email,
            normalizedEmail,
            providerSubject,
            null,
            now,
            PolicyAcceptance.CurrentVersion,
            now);
        CreateAccountResult result = await store.CreateAsync(account, cancellationToken);

        if (result.Status is CreateAccountStatus.AccountNameUnavailable)
        {
            return (null, GoogleAccountFailure.AccountNameUnavailable);
        }

        if (result.Status is CreateAccountStatus.EmailUnavailable)
        {
            // Any different identity can win the email race, including an unverified password registration.
            return (null, GoogleAccountFailure.ProviderRejected);
        }

        if (result.Status is CreateAccountStatus.GoogleSubjectUnavailable)
        {
            AccountRecord? concurrent = await store.FindByGoogleSubjectAsync(providerSubject, cancellationToken);
            return concurrent is null
                ? (null, GoogleAccountFailure.ProviderRejected)
                : (await sessions.CreateAsync(concurrent, cancellationToken), GoogleAccountFailure.None);
        }

        return (await sessions.CreateAsync(result.Account ?? account, cancellationToken), GoogleAccountFailure.None);
    }

    /// <summary>
    /// Creates the account of a reserved name, which public registration refuses. Only trusted operations tooling
    /// calls this; see <see cref="AccountCommand"/>.
    /// </summary>
    /// <param name="accountName">The reserved name, as it is to be spelled.</param>
    /// <param name="email">The email address of the account.</param>
    /// <param name="password">The password, which the operator typed.</param>
    /// <param name="cancellationToken">Cancels the operation.</param>
    /// <returns>The created account, or the message that says why it was refused.</returns>
    public async ValueTask<(AccountRecord? Account, string? Error)> ProvisionReservedAsync(
        string? accountName,
        string? email,
        string? password,
        CancellationToken cancellationToken)
    {
        if (!AccountNamePolicy.TryNormalizeReserved(accountName, out string name, out string nameError))
        {
            return (null, nameError);
        }

        if (!EmailAddressPolicy.TryNormalize(email, out string address, out string normalizedEmail, out string emailError))
        {
            return (null, emailError);
        }

        if (!PasswordPolicy.TryValidate(password, out string passwordError))
        {
            return (null, passwordError);
        }

        AccountRecord provisional = new(
            Guid.NewGuid(),
            name,
            AccountNamePolicy.NormalizeForLookup(name),
            address,
            normalizedEmail,
            null,
            string.Empty,
            timeProvider.GetUtcNow());
        AccountRecord account = provisional with { PasswordHash = passwordHasher.HashPassword(provisional, password!) };
        CreateAccountResult result = await store.CreateAsync(account, cancellationToken);
        return result.Status switch
        {
            CreateAccountStatus.AccountNameUnavailable => (null, $"The account '{name}' exists already."),
            CreateAccountStatus.EmailUnavailable => (null, "That email address is already registered."),
            _ => (result.Account ?? account, null)
        };
    }

    /// <summary>Validates every field of a registration and collects the messages of the refused ones.</summary>
    /// <param name="request">The registration body.</param>
    /// <param name="accountName">The canonical account name.</param>
    /// <param name="email">The email address as entered, trimmed.</param>
    /// <param name="normalizedEmail">The email address in its lookup form.</param>
    /// <returns>Messages keyed by field name; empty when the registration is valid.</returns>
    private static Dictionary<string, string[]> ValidateRegistration(
        RegisterAccountRequest request,
        out string accountName,
        out string email,
        out string normalizedEmail)
    {
        Dictionary<string, string[]> errors = [];

        if (!AccountNamePolicy.TryNormalize(request.AccountName, out accountName, out string accountNameError))
        {
            errors["accountName"] = [accountNameError];
        }

        if (!EmailAddressPolicy.TryNormalize(request.Email, out email, out normalizedEmail, out string emailError))
        {
            errors["email"] = [emailError];
        }

        if (!PasswordPolicy.TryValidate(request.Password, out string passwordError))
        {
            errors["password"] = [passwordError];
        }

        if (request.AcceptPolicies is not true)
        {
            errors["acceptPolicies"] = [PolicyAcceptance.RequiredMessage];
        }

        return errors;
    }
}

/// <summary>Reason a sign-in with Google did not produce a session.</summary>
internal enum GoogleAccountFailure
{
    /// <summary>The sign-in succeeded.</summary>
    None,
    /// <summary>
    /// The identity cannot be used: Google reported no usable subject or address, or the address belongs to another
    /// account.
    /// </summary>
    ProviderRejected,
    /// <summary>The identity is new and no account name was supplied.</summary>
    AccountNameRequired,
    /// <summary>The supplied account name breaks <see cref="AccountNamePolicy"/>.</summary>
    InvalidAccountName,
    /// <summary>The supplied account name is taken.</summary>
    AccountNameUnavailable,
    /// <summary>The identity is new and the person did not accept the current policies.</summary>
    PoliciesRequired
}