Merge remote-tracking branch 'origin/main' into fix/api-without-googlefix/api-without-google

1 files changed, 36 insertions, 0 deletions

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 = [];