progmaweb
The site and account service of Progmasoft: a Next.js frontend and an ASP.NET Core API.
Clonegit clone https://git.progmasoft.com/progmaweb
mainroot / apps / api / Accounts / AccountService.cs
// SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
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
}