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
Require documentation for every item of the API reference
- Commit
b1cf9a3bea0c81c1cb3ed2e0ddce2b9a56e175ef- Author
- Leitwolf11 ·
- Parents
e9eb2812a47b
Changes
.github/workflows/backend.yml | 7 +- apps/api/Accounts/AccountContracts.cs | 38 +++++++ apps/api/Accounts/AccountEndpoints.cs | 67 ++++++++++++ apps/api/Accounts/AccountNamePolicy.cs | 19 ++++ apps/api/Accounts/AccountRecord.cs | 18 ++++ apps/api/Accounts/AccountService.cs | 53 +++++++++ apps/api/Accounts/EmailAddressPolicy.cs | 12 +++ apps/api/Accounts/IAccountStore.cs | 33 ++++++ apps/api/Accounts/InMemoryAccountStore.cs | 18 ++++ apps/api/Accounts/PasswordPolicy.cs | 11 ++ apps/api/Accounts/SessionService.cs | 36 +++++++ apps/api/Progmaweb.Api.csproj | 3 + apps/api/Program.cs | 5 + apps/api/Security/ForwardedHeadersPolicy.cs | 9 ++ apps/api/Security/SecurityHeadersMiddleware.cs | 9 ++ docs/api/CheckDocumentation.cs | 118 +++++++++++++++++++++ docs/api/docfx.json | 22 +++- docs/api/filterConfig.yml | 14 +++ docs/api/index.md | 23 +++- .../Progmasoft.Progmaweb.Api.Accounts.md | 10 ++ .../Progmasoft.Progmaweb.Api.Security.md | 10 ++ justfile | 1 + 22 files changed, 528 insertions(+), 8 deletions(-) diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.yml index a1f6320..6504906 100644 --- a/.github/workflows/backend.yml +++ b/.github/workflows/backend.yml @@ -47,10 +47,13 @@ jobs: - run: dotnet build Progmaweb.slnx --configuration Release --no-restore - run: dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration Release --no-build --coverlet --coverlet-output-format cobertura - # Documentation gate: DocFX reads the API project and builds the - # reference; an unresolved reference or a broken link is an error. + # Documentation gate. DocFX reads the API project and builds the + # reference; an unresolved reference or a broken link is an error. The + # coverage check then fails when a namespace, type or member of the + # reference has no description, which DocFX itself does not report. - run: dotnet tool restore - run: dotnet docfx docs/api/docfx.json --warningsAsErrors + - run: dotnet run docs/api/CheckDocumentation.cs -- docs/api - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: diff --git a/apps/api/Accounts/AccountContracts.cs b/apps/api/Accounts/AccountContracts.cs index ca7ddb1..4a803a0 100644 --- a/apps/api/Accounts/AccountContracts.cs +++ b/apps/api/Accounts/AccountContracts.cs @@ -3,27 +3,65 @@ namespace Progmasoft.Progmaweb.Api.Accounts; +/// <summary>Body of <c>POST /api/v1/accounts/register</c>.</summary> +/// <remarks> +/// Every field is optional on the wire so that a missing value is reported as a validation error of that field +/// instead of a malformed request. +/// </remarks> +/// <param name="AccountName">Requested account name; see <see cref="AccountNamePolicy"/>.</param> +/// <param name="Email">Email address of the account; see <see cref="EmailAddressPolicy"/>.</param> +/// <param name="Password">Password in plain text; see <see cref="PasswordPolicy"/>. It is hashed before it is stored.</param> public sealed record RegisterAccountRequest(string? AccountName, string? Email, string? Password); +/// <summary>Body of <c>POST /api/v1/accounts/login</c>.</summary> +/// <param name="Email">Email address the account was registered with.</param> +/// <param name="Password">Password in plain text.</param> public sealed record LoginAccountRequest(string? Email, string? Password); +/// <summary>Public view of an account, returned by the register, login and <c>/me</c> endpoints.</summary> +/// <param name="AccountName">Account name in its canonical spelling.</param> +/// <param name="Email">Email address as the owner entered it.</param> +/// <param name="CreatedAt">Moment the account was created, in UTC.</param> public sealed record AccountResponse(string AccountName, string Email, DateTimeOffset CreatedAt); +/// <summary>An account together with the session that was just opened for it.</summary> +/// <param name="Account">The signed-in account.</param> +/// <param name="SessionToken"> +/// Session token for the cookie. It exists only here and in the browser; the store keeps its digest. +/// </param> +/// <param name="ExpiresAt">Moment the session stops being valid, in UTC.</param> internal sealed record AuthenticatedAccount(AccountRecord Account, string SessionToken, DateTimeOffset ExpiresAt); +/// <summary>Outcome of asking the store to create an account.</summary> internal enum CreateAccountStatus { + /// <summary>The account was stored.</summary> Created, + /// <summary>Another account already has this name, compared without case.</summary> AccountNameUnavailable, + /// <summary>Another account already has this email address, compared without case.</summary> EmailUnavailable, + /// <summary>Another account is already linked to this Google identity.</summary> GoogleSubjectUnavailable } +/// <summary>Result of <see cref="IAccountStore.CreateAsync"/>.</summary> +/// <param name="Status">Whether the account was stored, and if not, which uniqueness rule refused it.</param> +/// <param name="Account">The stored account; <see langword="null"/> unless <paramref name="Status"/> is created.</param> internal sealed record CreateAccountResult(CreateAccountStatus Status, AccountRecord? Account) { + /// <summary>Creates the result of a stored account.</summary> + /// <param name="account">The account that was stored.</param> + /// <returns>A result with the created status and the account.</returns> public static CreateAccountResult Created(AccountRecord account) => new(CreateAccountStatus.Created, account); + /// <summary>Creates the result of a refused account name.</summary> + /// <returns>A result without an account.</returns> public static CreateAccountResult AccountNameUnavailable() => new(CreateAccountStatus.AccountNameUnavailable, null); + /// <summary>Creates the result of a refused email address.</summary> + /// <returns>A result without an account.</returns> public static CreateAccountResult EmailUnavailable() => new(CreateAccountStatus.EmailUnavailable, null); + /// <summary>Creates the result of a refused Google identity.</summary> + /// <returns>A result without an account.</returns> public static CreateAccountResult GoogleSubjectUnavailable() => new(CreateAccountStatus.GoogleSubjectUnavailable, null); } diff --git a/apps/api/Accounts/AccountEndpoints.cs b/apps/api/Accounts/AccountEndpoints.cs index 06f4997..c5be51c 100644 --- a/apps/api/Accounts/AccountEndpoints.cs +++ b/apps/api/Accounts/AccountEndpoints.cs @@ -7,10 +7,29 @@ using System.Security.Claims; using Microsoft.AspNetCore.Authentication; using Microsoft.AspNetCore.Authentication.Google; +/// <summary>HTTP endpoints of the account service under <c>/api/v1/accounts</c>.</summary> +/// <remarks> +/// <list type="table"> +/// <item><term><c>POST /register</c></term><description>Creates a password account and signs it in.</description></item> +/// <item><term><c>POST /login</c></term><description>Signs in with email address and password.</description></item> +/// <item><term><c>POST /logout</c></term><description>Ends the current session.</description></item> +/// <item><term><c>GET /me</c></term><description>Returns the signed-in account.</description></item> +/// <item><term><c>GET /oauth/google/start</c></term><description>Begins sign-in with Google.</description></item> +/// <item><term><c>GET /oauth/google/complete</c></term><description>Finishes sign-in with Google.</description></item> +/// </list> +/// The endpoints that accept credentials share the <c>account-auth</c> rate limit. +/// </remarks> internal static class AccountEndpoints { + /// <summary> + /// Authentication scheme of the short-lived cookie that carries the Google identity between the provider callback + /// and <c>/oauth/google/complete</c>. + /// </summary> internal const string ExternalCookieScheme = "ProgmasoftExternal"; + /// <summary>Registers the account endpoints.</summary> + /// <param name="endpoints">The route builder of the application.</param> + /// <returns>The same route builder, for chaining.</returns> public static IEndpointRouteBuilder MapAccountEndpoints(this IEndpointRouteBuilder endpoints) { RouteGroupBuilder accounts = endpoints.MapGroup("/api/v1/accounts"); @@ -25,6 +44,15 @@ internal static class AccountEndpoints return endpoints; } + /// <summary>Begins sign-in with Google.</summary> + /// <param name="accountName"> + /// Account name to create when the Google identity is new; omitted when signing in to an existing account. + /// </param> + /// <param name="configuration">Application configuration with the Google client credentials.</param> + /// <returns> + /// A challenge that sends the browser to Google, a redirect back to registration when the name is invalid, or + /// 503 when Google sign-in is not configured. + /// </returns> private static IResult StartGoogleAsync(string? accountName, IConfiguration configuration) { if (string.IsNullOrWhiteSpace(configuration["Authentication:Google:ClientId"]) || @@ -54,6 +82,12 @@ internal static class AccountEndpoints return Results.Challenge(properties, [GoogleDefaults.AuthenticationScheme]); } + /// <summary>Finishes sign-in with Google after the provider callback.</summary> + /// <param name="accounts">Account service.</param> + /// <param name="sessions">Session service.</param> + /// <param name="context">The current request, holding the external cookie.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>A redirect to the dashboard on success, or to the page that explains the failure.</returns> private static async Task<IResult> CompleteGoogleAsync( AccountService accounts, SessionService sessions, @@ -90,6 +124,13 @@ internal static class AccountEndpoints return Results.Redirect($"/{Uri.EscapeDataString(authentication.Account.AccountName)}/dashboard"); } + /// <summary>Creates a password account and opens a session for it.</summary> + /// <param name="request">The registration body.</param> + /// <param name="accounts">Account service.</param> + /// <param name="sessions">Session service.</param> + /// <param name="context">The current request; receives the session cookie.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>201 with the account, or a validation problem that names each refused field.</returns> private static async Task<IResult> RegisterAsync( RegisterAccountRequest request, AccountService accounts, @@ -110,6 +151,15 @@ internal static class AccountEndpoints ToResponse(authentication.Account)); } + /// <summary>Signs in with email address and password.</summary> + /// <param name="request">The login body.</param> + /// <param name="accounts">Account service.</param> + /// <param name="sessions">Session service.</param> + /// <param name="context">The current request; receives the session cookie.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns> + /// 200 with the account, or 401 with one message that does not reveal whether the address or the password was wrong. + /// </returns> private static async Task<IResult> LoginAsync( LoginAccountRequest request, AccountService accounts, @@ -130,6 +180,11 @@ internal static class AccountEndpoints return Results.Ok(ToResponse(authentication.Account)); } + /// <summary>Ends the current session and deletes its cookie.</summary> + /// <param name="sessions">Session service.</param> + /// <param name="context">The current request.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>204, also when no session existed.</returns> private static async Task<IResult> LogoutAsync( SessionService sessions, HttpContext context, @@ -147,6 +202,11 @@ internal static class AccountEndpoints return Results.NoContent(); } + /// <summary>Returns the account of the current session.</summary> + /// <param name="sessions">Session service.</param> + /// <param name="context">The current request.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>200 with the account, or 401 when the request has no valid session.</returns> private static async Task<IResult> MeAsync( SessionService sessions, HttpContext context, @@ -157,6 +217,10 @@ internal static class AccountEndpoints return account is null ? Results.Unauthorized() : Results.Ok(ToResponse(account)); } + /// <summary>Writes the session cookie of a new session to the response.</summary> + /// <param name="context">The current request.</param> + /// <param name="sessions">Session service, which names the cookie.</param> + /// <param name="authentication">The session that was opened.</param> private static void WriteSessionCookie( HttpContext context, SessionService sessions, @@ -166,6 +230,9 @@ internal static class AccountEndpoints authentication.SessionToken, SessionService.CreateCookieOptions(authentication.ExpiresAt)); + /// <summary>Projects a stored account to its public view.</summary> + /// <param name="account">The stored account.</param> + /// <returns>The fields a client may see.</returns> private static AccountResponse ToResponse(AccountRecord account) => new(account.AccountName, account.Email, account.CreatedAt); } diff --git a/apps/api/Accounts/AccountNamePolicy.cs b/apps/api/Accounts/AccountNamePolicy.cs index 76e9dcf..3b2328d 100644 --- a/apps/api/Accounts/AccountNamePolicy.cs +++ b/apps/api/Accounts/AccountNamePolicy.cs @@ -6,19 +6,35 @@ using System.Text.RegularExpressions; namespace Progmasoft.Progmaweb.Api.Accounts; +/// <summary>Rules for account names.</summary> +/// <remarks> +/// A name is 8 to 128 ASCII letters or digits and begins with an upper-case letter. Names are unique without regard +/// to case, so two names that differ only in case cannot both exist, while each keeps the spelling its owner chose. +/// The same name is the ViGet publisher name. +/// </remarks> internal static partial class AccountNamePolicy { + /// <summary>Fewest characters an account name may have.</summary> public const int MinimumLength = 8; + /// <summary>Most characters an account name may have.</summary> public const int MaximumLength = 128; + /// <summary>Names nobody may register, in their lookup form.</summary> // These names identify Progmasoft itself and the initial administrative identity. They are provisioned only by // trusted operations tooling, never by the public registration endpoint. private static readonly FrozenSet<string> ReservedNames = new[] { "LEITWOLF", "PROGMASOFT" }.ToFrozenSet(StringComparer.Ordinal); + /// <summary>Matches a name of the allowed length, alphabet and first letter.</summary> + /// <returns>The compiled expression.</returns> [GeneratedRegex("^[A-Z][A-Za-z0-9]{7,127}$", RegexOptions.CultureInvariant)] private static partial Regex CanonicalPattern(); + /// <summary>Validates an account name and returns its canonical spelling.</summary> + /// <param name="value">The name as entered; surrounding white space is ignored.</param> + /// <param name="canonical">The trimmed name. It is meaningful only when the method returns <see langword="true"/>.</param> + /// <param name="error">Message for the user when the name is refused; empty otherwise.</param> + /// <returns><see langword="true"/> when the name satisfies every rule and is not reserved.</returns> public static bool TryNormalize(string? value, out string canonical, out string error) { canonical = value?.Trim() ?? string.Empty; @@ -45,5 +61,8 @@ internal static partial class AccountNamePolicy return true; } + /// <summary>Returns the key under which a name is compared for uniqueness.</summary> + /// <param name="canonical">A name that <see cref="TryNormalize"/> accepted.</param> + /// <returns>The name in upper case.</returns> public static string NormalizeForLookup(string canonical) => canonical.ToUpperInvariant(); } diff --git a/apps/api/Accounts/AccountRecord.cs b/apps/api/Accounts/AccountRecord.cs index 7625168..5e27f3e 100644 --- a/apps/api/Accounts/AccountRecord.cs +++ b/apps/api/Accounts/AccountRecord.cs @@ -3,6 +3,19 @@ namespace Progmasoft.Progmaweb.Api.Accounts; +/// <summary>An account as the store keeps it.</summary> +/// <param name="Id">Stable identifier; sessions refer to the account by it.</param> +/// <param name="AccountName">Account name in its canonical spelling, as shown and used in URLs.</param> +/// <param name="NormalizedAccountName">Upper-case form of the name; the uniqueness key.</param> +/// <param name="Email">Email address as the owner entered it.</param> +/// <param name="NormalizedEmail">Upper-case form of the address; the uniqueness key.</param> +/// <param name="GoogleSubject"> +/// Subject identifier of the linked Google identity; <see langword="null"/> for a password account. +/// </param> +/// <param name="PasswordHash"> +/// ASP.NET Core Identity password hash; <see langword="null"/> for an account that signs in through Google only. +/// </param> +/// <param name="CreatedAt">Moment the account was created, in UTC.</param> internal sealed record AccountRecord( Guid Id, string AccountName, @@ -13,6 +26,11 @@ internal sealed record AccountRecord( string? PasswordHash, DateTimeOffset CreatedAt); +/// <summary>A session as the store keeps it.</summary> +/// <param name="TokenDigest">SHA-256 digest of the session token. The token itself is never stored.</param> +/// <param name="AccountId">Identifier of the account the session belongs to.</param> +/// <param name="CreatedAt">Moment the session was opened, in UTC.</param> +/// <param name="ExpiresAt">Moment the session stops being valid, in UTC.</param> internal sealed record SessionRecord( byte[] TokenDigest, Guid AccountId, diff --git a/apps/api/Accounts/AccountService.cs b/apps/api/Accounts/AccountService.cs index 7168eb6..cd3e711 100644 --- a/apps/api/Accounts/AccountService.cs +++ b/apps/api/Accounts/AccountService.cs @@ -5,10 +5,14 @@ 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", @@ -18,11 +22,24 @@ internal sealed class AccountService( 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> and <c>password</c>. + /// </returns> public async ValueTask<(AuthenticatedAccount? Authentication, Dictionary<string, string[]> Errors)> RegisterAsync( RegisterAccountRequest request, SessionService sessions, @@ -63,6 +80,15 @@ internal sealed class AccountService( 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, @@ -92,6 +118,18 @@ internal sealed class AccountService( return await sessions.CreateAsync(account, 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="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, @@ -165,6 +203,12 @@ internal sealed class AccountService( return (await sessions.CreateAsync(account, cancellationToken), GoogleAccountFailure.None); } + /// <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, @@ -192,11 +236,20 @@ internal sealed class AccountService( } } +/// <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 } diff --git a/apps/api/Accounts/EmailAddressPolicy.cs b/apps/api/Accounts/EmailAddressPolicy.cs index 9710b0c..898d07c 100644 --- a/apps/api/Accounts/EmailAddressPolicy.cs +++ b/apps/api/Accounts/EmailAddressPolicy.cs @@ -5,10 +5,22 @@ using System.Net.Mail; namespace Progmasoft.Progmaweb.Api.Accounts; +/// <summary>Rules for email addresses.</summary> +/// <remarks> +/// An address is accepted when it parses as a single mailbox without a display name and is at most 254 characters +/// long. Ownership of the address is not verified. +/// </remarks> internal static class EmailAddressPolicy { + /// <summary>Most characters an email address may have.</summary> public const int MaximumLength = 254; + /// <summary>Validates an email address and returns its stored and lookup forms.</summary> + /// <param name="value">The address as entered; surrounding white space is ignored.</param> + /// <param name="canonical">The trimmed address, kept as the owner wrote it.</param> + /// <param name="normalized">The address in upper case; the uniqueness key. Empty when the address is refused.</param> + /// <param name="error">Message for the user when the address is refused; empty otherwise.</param> + /// <returns><see langword="true"/> when the address is a single valid mailbox.</returns> public static bool TryNormalize(string? value, out string canonical, out string normalized, out string error) { canonical = value?.Trim() ?? string.Empty; diff --git a/apps/api/Accounts/IAccountStore.cs b/apps/api/Accounts/IAccountStore.cs index 6bb2955..cef8bee 100644 --- a/apps/api/Accounts/IAccountStore.cs +++ b/apps/api/Accounts/IAccountStore.cs @@ -3,14 +3,47 @@ namespace Progmasoft.Progmaweb.Api.Accounts; +/// <summary>Persistence of accounts and sessions.</summary> +/// <remarks> +/// The store owns the uniqueness rules: account name, email address and Google identity are each unique, and a +/// creation that would break one of them is refused atomically. It offers no enumeration and no bulk deletion. +/// </remarks> internal interface IAccountStore { + /// <summary>Stores a new account unless its name, email address or Google identity is taken.</summary> + /// <param name="account">The account to store, with its normalized keys filled in.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>The stored account, or the uniqueness rule that refused it.</returns> ValueTask<CreateAccountResult> CreateAsync(AccountRecord account, CancellationToken cancellationToken); + /// <summary>Finds an account by its normalized email address.</summary> + /// <param name="normalizedEmail">Upper-case email address, as <see cref="EmailAddressPolicy"/> produces it.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>The account, or <see langword="null"/> when no account has this address.</returns> ValueTask<AccountRecord?> FindByEmailAsync(string normalizedEmail, CancellationToken cancellationToken); + /// <summary>Finds the account linked to a Google identity.</summary> + /// <param name="googleSubject">Subject identifier Google issued for the identity.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>The account, or <see langword="null"/> when the identity is not linked.</returns> ValueTask<AccountRecord?> FindByGoogleSubjectAsync(string googleSubject, CancellationToken cancellationToken); + /// <summary>Finds an account by its identifier.</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 does not exist.</returns> ValueTask<AccountRecord?> FindByIdAsync(Guid id, CancellationToken cancellationToken); + /// <summary>Stores a session, replacing one with the same token digest.</summary> + /// <param name="session">The session to store.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>A task that completes when the session is stored.</returns> ValueTask StoreSessionAsync(SessionRecord session, CancellationToken cancellationToken); + /// <summary>Finds a session by the digest of its token.</summary> + /// <param name="tokenDigest">SHA-256 digest of the session token.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>The session, or <see langword="null"/> when it does not exist or was revoked.</returns> ValueTask<SessionRecord?> FindSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken); + /// <summary>Removes a session. Revoking an unknown session is not an error.</summary> + /// <param name="tokenDigest">SHA-256 digest of the session token.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>A task that completes when the session is gone.</returns> ValueTask RevokeSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken); } diff --git a/apps/api/Accounts/InMemoryAccountStore.cs b/apps/api/Accounts/InMemoryAccountStore.cs index 9f183e7..7a6930f 100644 --- a/apps/api/Accounts/InMemoryAccountStore.cs +++ b/apps/api/Accounts/InMemoryAccountStore.cs @@ -5,15 +5,27 @@ namespace Progmasoft.Progmaweb.Api.Accounts; // This development store models the uniqueness and session semantics required by the future PostgreSQL implementation. // It deliberately exposes no enumeration or bulk-delete surface to public endpoints. +/// <summary>An <see cref="IAccountStore"/> that keeps everything in the memory of the process.</summary> +/// <remarks> +/// It implements the uniqueness and session rules a durable store must keep, under one lock. Nothing survives a +/// restart of the service: every account and every session is lost when the process stops. +/// </remarks> internal sealed class InMemoryAccountStore : IAccountStore { + /// <summary>Guards every dictionary below; each operation holds it for its whole duration.</summary> private readonly Lock gate = new(); + /// <summary>Every account, by identifier.</summary> private readonly Dictionary<Guid, AccountRecord> accountsById = []; + /// <summary>Account identifiers by normalized email address; the uniqueness index of addresses.</summary> private readonly Dictionary<string, Guid> accountIdsByEmail = new(StringComparer.Ordinal); + /// <summary>Account identifiers by Google subject; the uniqueness index of linked identities.</summary> private readonly Dictionary<string, Guid> accountIdsByGoogleSubject = new(StringComparer.Ordinal); + /// <summary>Account identifiers by normalized account name; the uniqueness index of names.</summary> private readonly Dictionary<string, Guid> accountIdsByName = new(StringComparer.Ordinal); + /// <summary>Sessions by the hexadecimal form of their token digest.</summary> private readonly Dictionary<string, SessionRecord> sessionsByDigest = new(StringComparer.Ordinal); + /// <inheritdoc/> public ValueTask<CreateAccountResult> CreateAsync(AccountRecord account, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); @@ -46,6 +58,7 @@ internal sealed class InMemoryAccountStore : IAccountStore } } + /// <inheritdoc/> public ValueTask<AccountRecord?> FindByGoogleSubjectAsync( string googleSubject, CancellationToken cancellationToken) @@ -58,6 +71,7 @@ internal sealed class InMemoryAccountStore : IAccountStore } } + /// <inheritdoc/> public ValueTask<AccountRecord?> FindByEmailAsync(string normalizedEmail, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); @@ -68,6 +82,7 @@ internal sealed class InMemoryAccountStore : IAccountStore } } + /// <inheritdoc/> public ValueTask<AccountRecord?> FindByIdAsync(Guid id, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); @@ -78,6 +93,7 @@ internal sealed class InMemoryAccountStore : IAccountStore } } + /// <inheritdoc/> public ValueTask StoreSessionAsync(SessionRecord session, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); @@ -88,6 +104,7 @@ internal sealed class InMemoryAccountStore : IAccountStore } } + /// <inheritdoc/> public ValueTask<SessionRecord?> FindSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); @@ -98,6 +115,7 @@ internal sealed class InMemoryAccountStore : IAccountStore } } + /// <inheritdoc/> public ValueTask RevokeSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); diff --git a/apps/api/Accounts/PasswordPolicy.cs b/apps/api/Accounts/PasswordPolicy.cs index baf8c75..6a5bf38 100644 --- a/apps/api/Accounts/PasswordPolicy.cs +++ b/apps/api/Accounts/PasswordPolicy.cs @@ -3,11 +3,22 @@ namespace Progmasoft.Progmaweb.Api.Accounts; +/// <summary>Rules for passwords.</summary> +/// <remarks> +/// Only length is constrained, so long passphrases are welcome. The upper bound keeps hashing cost bounded for a +/// request that an anonymous caller can send. +/// </remarks> internal static class PasswordPolicy { + /// <summary>Fewest characters a password may have.</summary> public const int MinimumLength = 12; + /// <summary>Most characters a password may have.</summary> public const int MaximumLength = 256; + /// <summary>Validates a new password.</summary> + /// <param name="password">The password in plain text.</param> + /// <param name="error">Message for the user when the password is refused; empty otherwise.</param> + /// <returns><see langword="true"/> when the password may be used.</returns> public static bool TryValidate(string? password, out string error) { if (password is null || password.Length < MinimumLength) diff --git a/apps/api/Accounts/SessionService.cs b/apps/api/Accounts/SessionService.cs index c96be11..d6d04b0 100644 --- a/apps/api/Accounts/SessionService.cs +++ b/apps/api/Accounts/SessionService.cs @@ -6,20 +6,37 @@ using Microsoft.Extensions.Options; namespace Progmasoft.Progmaweb.Api.Accounts; +/// <summary>Settings of account sessions, bound from the <c>AccountSessions</c> configuration section.</summary> internal sealed class AccountSessionOptions { + /// <summary>Name of the configuration section.</summary> public const string SectionName = "AccountSessions"; + /// <summary>Hours a session stays valid. Values outside 1 to 168 are clamped to that range.</summary> public int LifetimeHours { get; init; } = 12; + /// <summary>Name of the session cookie. The <c>__Host-</c> prefix binds it to this host over HTTPS.</summary> public string CookieName { get; init; } = "__Host-ProgmasoftSession"; } +/// <summary>Opens, checks and revokes account sessions.</summary> +/// <remarks> +/// A session is a random 256-bit token that only the browser holds. The store keeps its SHA-256 digest, so a copy +/// of the store does not reveal a usable token. +/// </remarks> +/// <param name="store">Store that keeps the session digests.</param> +/// <param name="timeProvider">Clock used for creation and expiry.</param> +/// <param name="options">Session settings.</param> internal sealed class SessionService( IAccountStore store, TimeProvider timeProvider, IOptions<AccountSessionOptions> options) { + /// <summary>The session settings in effect.</summary> private readonly AccountSessionOptions settings = options.Value; + /// <summary>Opens a session for an account.</summary> + /// <param name="account">The account that signed in.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>The account with the new session token and its expiry.</returns> public async ValueTask<AuthenticatedAccount> CreateAsync(AccountRecord account, CancellationToken cancellationToken) { byte[] tokenBytes = RandomNumberGenerator.GetBytes(32); @@ -35,6 +52,13 @@ internal sealed class SessionService( return new AuthenticatedAccount(account, token, expiresAt); } + /// <summary>Resolves a session token to its account.</summary> + /// <param name="token">The token from the session cookie.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns> + /// The account, or <see langword="null"/> when the token is malformed, unknown or expired. An expired session is + /// revoked on the way. + /// </returns> public async ValueTask<AccountRecord?> AuthenticateAsync(string? token, CancellationToken cancellationToken) { if (!TryDigest(token, out byte[] digest)) @@ -57,6 +81,10 @@ internal sealed class SessionService( return await store.FindByIdAsync(session.AccountId, cancellationToken); } + /// <summary>Ends the session of a token. A malformed or unknown token is ignored.</summary> + /// <param name="token">The token from the session cookie.</param> + /// <param name="cancellationToken">Cancels the operation.</param> + /// <returns>A task that completes when the session is gone.</returns> public async ValueTask RevokeAsync(string? token, CancellationToken cancellationToken) { if (TryDigest(token, out byte[] digest)) @@ -65,6 +93,9 @@ internal sealed class SessionService( } } + /// <summary>Creates the attributes of the session cookie.</summary> + /// <param name="expiresAt">Moment the session expires; the cookie expires with it.</param> + /// <returns>Options for a secure, HTTP-only, same-site cookie on the root path.</returns> public static CookieOptions CreateCookieOptions(DateTimeOffset expiresAt) => new() { Expires = expiresAt, @@ -75,8 +106,13 @@ internal sealed class SessionService( Secure = true }; + /// <summary>Name of the session cookie.</summary> public string CookieName => settings.CookieName; + /// <summary>Computes the digest of a token that has the shape of a session token.</summary> + /// <param name="token">The candidate token.</param> + /// <param name="digest">The SHA-256 digest; empty when the token is refused.</param> + /// <returns><see langword="true"/> when the token has a plausible length and alphabet.</returns> private static bool TryDigest(string? token, out byte[] digest) { digest = []; diff --git a/apps/api/Progmaweb.Api.csproj b/apps/api/Progmaweb.Api.csproj index c633ca7..926e696 100644 --- a/apps/api/Progmaweb.Api.csproj +++ b/apps/api/Progmaweb.Api.csproj @@ -7,6 +7,9 @@ <RootNamespace>Progmasoft.Progmaweb.Api</RootNamespace> <AssemblyName>Progmaweb.Api</AssemblyName> <Version>1.0.0</Version> + <!-- The XML documentation is compiled so that a broken reference or an undocumented public + declaration fails the build; DocFX publishes the same comments. --> + <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Authentication.Google" Version="10.0.11" /> diff --git a/apps/api/Program.cs b/apps/api/Program.cs index 0b71d06..5f6a7a5 100644 --- a/apps/api/Program.cs +++ b/apps/api/Program.cs @@ -82,4 +82,9 @@ app.MapAccountEndpoints(); app.Run(); +/// <summary>Entry point of the Progmaweb account API.</summary> +/// <remarks> +/// The top-level statements configure the services, the request pipeline and the routes. The class is declared so +/// that the integration tests can start the application in memory. +/// </remarks> public partial class Program; diff --git a/apps/api/Security/ForwardedHeadersPolicy.cs b/apps/api/Security/ForwardedHeadersPolicy.cs index 046ad56..776c1e4 100644 --- a/apps/api/Security/ForwardedHeadersPolicy.cs +++ b/apps/api/Security/ForwardedHeadersPolicy.cs @@ -6,11 +6,20 @@ using Microsoft.AspNetCore.HttpOverrides; namespace Progmasoft.Progmaweb.Api.Security; +/// <summary>Decides which forwarded headers the API trusts.</summary> +/// <remarks> +/// The API listens on loopback behind Nginx and the Next.js server. Only those local proxies may state the client +/// address, host and scheme; the authentication rate limiter depends on the client address being genuine. +/// </remarks> internal static class ForwardedHeadersPolicy { + /// <summary>Number of proxy hops whose headers are read.</summary> internal const int MaximumForwardedHops = 1; + /// <summary>Addresses of the proxies that may send forwarded headers.</summary> internal static readonly IPAddress[] TrustedProxies = [IPAddress.Loopback, IPAddress.IPv6Loopback]; + /// <summary>Applies the policy to the forwarded-headers middleware.</summary> + /// <param name="options">Options to configure.</param> public static void Configure(ForwardedHeadersOptions options) { options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedHost | diff --git a/apps/api/Security/SecurityHeadersMiddleware.cs b/apps/api/Security/SecurityHeadersMiddleware.cs index 42383ef..d17a3fe 100644 --- a/apps/api/Security/SecurityHeadersMiddleware.cs +++ b/apps/api/Security/SecurityHeadersMiddleware.cs @@ -3,8 +3,17 @@ namespace Progmasoft.Progmaweb.Api.Security; +/// <summary>Adds the security headers of a JSON API to every response.</summary> +/// <remarks> +/// The API serves no documents, so its content security policy allows nothing, it may not be framed, and its +/// responses are never cached. +/// </remarks> +/// <param name="next">The next middleware in the pipeline.</param> internal sealed class SecurityHeadersMiddleware(RequestDelegate next) { + /// <summary>Sets the headers and continues the pipeline.</summary> + /// <param name="context">The current request.</param> + /// <returns>A task that completes when the rest of the pipeline has run.</returns> public async Task InvokeAsync(HttpContext context) { IHeaderDictionary headers = context.Response.Headers; diff --git a/docs/api/CheckDocumentation.cs b/docs/api/CheckDocumentation.cs new file mode 100644 index 0000000..f359661 --- /dev/null +++ b/docs/api/CheckDocumentation.cs @@ -0,0 +1,118 @@ +// SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> +// SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 + +// Documentation coverage gate of the API reference. +// +// DocFX builds a reference from whatever comments exist and does not report a declaration that has none. This +// program reads the metadata DocFX generated and fails when a namespace, type or member is undocumented, so the +// reference cannot contain an entry without a description. +// +// Usage, after `dotnet docfx metadata docs/api/docfx.json`: +// +// dotnet run docs/api/CheckDocumentation.cs -- docs/api +// +// The exit code is 0 when everything is documented, 1 when something is not, and 2 when the metadata is missing. + +using System.Text.RegularExpressions; + +string root = args.Length > 0 ? args[0] : "docs/api"; +string referenceDirectory = Path.Combine(root, "reference"); +string namespaceDirectory = Path.Combine(root, "namespaces"); + +if (!Directory.Exists(referenceDirectory)) +{ + Console.Error.WriteLine($"No metadata in '{referenceDirectory}'. Run 'dotnet docfx metadata' first."); + return 2; +} + +// A namespace has no declaration that could carry a comment. Its description is an overwrite file named after it. +HashSet<string> describedNamespaces = Directory.Exists(namespaceDirectory) + ? Directory.EnumerateFiles(namespaceDirectory, "*.md") + .Where(HasDescription) + .Select(path => Path.GetFileNameWithoutExtension(path)!) + .ToHashSet(StringComparer.Ordinal) + : []; + +List<string> undocumented = []; +int checkedItems = 0; + +foreach (string file in Directory.EnumerateFiles(referenceDirectory, "*.yml").Order(StringComparer.Ordinal)) +{ + if (Path.GetFileName(file) == "toc.yml") + { + continue; + } + + // The items a file defines come first; the `references` section after them repeats names of other files. + string text = File.ReadAllText(file).ReplaceLineEndings("\n"); + int references = text.IndexOf("\nreferences:", StringComparison.Ordinal); + string definitions = references < 0 ? text : text[..references]; + + foreach (string item in ItemStart().Split(definitions).Skip(1)) + { + string uid = item[..item.IndexOf('\n')].Trim(); + string type = ItemType().Match(item) is { Success: true } match ? match.Groups[1].Value : "Item"; + checkedItems++; + + bool documented = type == "Namespace" + ? describedNamespaces.Contains(uid) + : ItemSummary().IsMatch(item); + if (!documented) + { + undocumented.Add($"{type} {uid}"); + } + } +} + +if (checkedItems == 0) +{ + Console.Error.WriteLine($"The metadata in '{referenceDirectory}' defines nothing; the gate would pass vacuously."); + return 2; +} + +if (undocumented.Count != 0) +{ + Console.Error.WriteLine($"{undocumented.Count} of {checkedItems} API items have no documentation:"); + foreach (string entry in undocumented) + { + Console.Error.WriteLine($" {entry}"); + } + + Console.Error.WriteLine("Add a <summary> to each declaration, or a file in docs/api/namespaces for a namespace."); + return 1; +} + +Console.WriteLine($"All {checkedItems} API items are documented."); +return 0; + +// An overwrite file describes its namespace when it has text after its front matter and comment header. +static bool HasDescription(string path) +{ + string text = File.ReadAllText(path).ReplaceLineEndings("\n"); + int frontMatterEnd = text.IndexOf("\n---", 3, StringComparison.Ordinal); + if (!text.StartsWith("---\n", StringComparison.Ordinal) || frontMatterEnd < 0) + { + return false; + } + + string body = HtmlComment().Replace(text[(frontMatterEnd + 4)..], string.Empty); + return text[..frontMatterEnd].Contains($"uid: {Path.GetFileNameWithoutExtension(path)}", StringComparison.Ordinal) + && !string.IsNullOrWhiteSpace(body); +} + +internal static partial class Program +{ + // Every defined item starts with its identifier at the left margin. + [GeneratedRegex(@"^- uid: ", RegexOptions.Multiline)] + private static partial Regex ItemStart(); + + [GeneratedRegex(@"^ type: (\w+)", RegexOptions.Multiline)] + private static partial Regex ItemType(); + + // A summary with content: text on the same line, or a block scalar followed by an indented line. + [GeneratedRegex(@"^ summary: (?:[^\s>|].*|[>|][-+]?\n \S)", RegexOptions.Multiline)] + private static partial Regex ItemSummary(); + + [GeneratedRegex(@"<!--.*?-->", RegexOptions.Singleline)] + private static partial Regex HtmlComment(); +} diff --git a/docs/api/docfx.json b/docs/api/docfx.json index e10a9b0..eb2ffe7 100644 --- a/docs/api/docfx.json +++ b/docs/api/docfx.json @@ -4,23 +4,37 @@ "src": [ { "src": "../../apps/api", - "files": ["Progmaweb.Api.csproj"] + "files": [ + "Progmaweb.Api.csproj" + ] } ], "dest": "reference", - "includePrivateMembers": true + "includePrivateMembers": true, + "filter": "filterConfig.yml" } ], "build": { "content": [ { - "files": ["index.md", "toc.yml", "reference/**/*.yml"] + "files": [ + "index.md", + "toc.yml", + "reference/**/*.yml" + ] } ], "dest": "_site", "globalMetadata": { "_appTitle": "Progmaweb API", "_enableSearch": false - } + }, + "overwrite": [ + { + "files": [ + "namespaces/*.md" + ] + } + ] } } diff --git a/docs/api/filterConfig.yml b/docs/api/filterConfig.yml new file mode 100644 index 0000000..5b7b327 --- /dev/null +++ b/docs/api/filterConfig.yml @@ -0,0 +1,14 @@ +# SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> +# SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 + +# Code that a source generator writes at build time is not part of the +# reference: nobody maintains it, and it cannot carry documentation. +apiRules: + - exclude: + uidRegex: ^System\.Text\.RegularExpressions\.Generated + # The regular-expression generator also writes the body of this partial + # method, and its generated comment replaces the one on the declaration, so + # the summary in the source never reaches the reference. + - exclude: + uidRegex: ^Progmasoft\.Progmaweb\.Api\.Accounts\.AccountNamePolicy\.CanonicalPattern$ + type: Method diff --git a/docs/api/index.md b/docs/api/index.md index 868fff1..71b532b 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -12,8 +12,27 @@ The service is an application, not a library, so most of its types are internal. The reference includes them: it documents the code for the people who maintain it. -Build it from the repository root: +Build and check it from the repository root: ```sh -docfx docs/api/docfx.json --warningsAsErrors +dotnet tool restore +dotnet docfx docs/api/docfx.json --warningsAsErrors +dotnet run docs/api/CheckDocumentation.cs -- docs/api ``` + +## What the gate requires + +Three things fail the check, locally and in CI: + +- **A broken link or an unresolved reference.** DocFX runs with every warning treated as an error. +- **An undocumented public declaration or a wrong `cref`.** The API project compiles its XML documentation, and the + build treats the compiler's documentation warnings as errors. +- **Any undocumented item of the reference.** `CheckDocumentation.cs` reads the metadata DocFX generated and fails + when a namespace, type or member has no summary. This covers internal and private members too, which the compiler + does not check. + +A namespace has no declaration that could hold a comment. Its description is a file in `namespaces/`, named after +the namespace. + +`filterConfig.yml` lists what is left out of the reference: code written by a source generator, which nobody +maintains and which cannot carry documentation. Do not add an entry there to get past the gate; write the summary. diff --git a/docs/api/namespaces/Progmasoft.Progmaweb.Api.Accounts.md b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Accounts.md new file mode 100644 index 0000000..926cd64 --- /dev/null +++ b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Accounts.md @@ -0,0 +1,10 @@ +--- +uid: Progmasoft.Progmaweb.Api.Accounts +summary: *content +--- + +<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> --> +<!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 --> + +Accounts and sessions: the HTTP endpoints, the rules for account names, email addresses and passwords, the +registration and sign-in logic, and the store that keeps accounts and session digests. diff --git a/docs/api/namespaces/Progmasoft.Progmaweb.Api.Security.md b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Security.md new file mode 100644 index 0000000..c4cf45a --- /dev/null +++ b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Security.md @@ -0,0 +1,10 @@ +--- +uid: Progmasoft.Progmaweb.Api.Security +summary: *content +--- + +<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> --> +<!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 --> + +Request-pipeline policy that is not specific to accounts: which forwarded headers the service trusts and which +security headers every response carries. diff --git a/justfile b/justfile index d3c29c6..7543809 100644 --- a/justfile +++ b/justfile @@ -23,3 +23,4 @@ verify: web-check web-build api-build api-test api-docs: dotnet tool restore dotnet docfx docs/api/docfx.json --warningsAsErrors + dotnet run docs/api/CheckDocumentation.cs -- docs/api