Cover the split-screen auth shell in Storybook

.github/pull_request_template.md

@@ -0,0 +1,101 @@
+## Summary
+
+<!--
+State WHAT is changing and WHY, in two to five sentences.
+A reader should understand the change without opening the diff.
+Describe the problem first, then the outcome.
+-->
+
+## Type of change
+
+<!-- Tick the one option that best describes this PR. -->
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor (no change in behaviour)
+- [ ] Performance improvement
+- [ ] Documentation
+- [ ] Tests only
+- [ ] Build, CI or dependency update
+- [ ] Other (please specify):
+
+## Related issues
+
+<!--
+Link the issue(s) this PR relates to. Use one keyword per issue so that each is closed on merge:
+
+  Fixes #123
+  Fixes #124, fixes #125
+  Fixes owner/other-repo#456
+
+Closing keywords only take effect when the PR targets the repository's default branch.
+Use "Related to #123" if the PR should not close the issue.
+If there is no issue, write "N/A" and explain the motivation in the Summary.
+-->
+
+## Approach and context
+
+<!--
+Explain how the change works and why this approach was chosen.
+Include, where relevant:
+  - The decisions you made that are not obvious from the code.
+  - Alternatives you considered and why you rejected them.
+  - Known limitations or shortcomings, and any planned follow-up work.
+  - Background such as benchmark results or design documents.
+
+Summarise the key points of any external link. Links may be inaccessible to future readers.
+-->
+
+## How this was tested
+
+<!--
+Describe what you ran and what you observed. Be specific, and state only what you actually did.
+For example: the automated tests added or changed, manual steps and their outcome,
+environments or platforms covered, and anything you were unable to test.
+For a bug fix, note the test that fails without the fix.
+-->
+
+## Compatibility and risk
+
+- [ ] This change is backwards compatible.
+- [ ] This change is **breaking** (complete the details below).
+- [ ] This change deprecates existing behaviour (complete the details below).
+
+<!--
+If breaking or deprecating, describe: what changes, who is affected,
+and the migration path or recommended alternative.
+Also note any deployment, configuration, data migration or rollback considerations.
+-->
+
+## User-facing change
+
+<!--
+Does this PR change behaviour that users, operators or API consumers will notice?
+If not, write "None".
+If so, write one or two sentences suitable for release notes, in plain language and from the
+user's point of view. If users must take action when upgrading, state clearly that action is required.
+-->
+
+```release-note
+
+```
+
+## Notes for reviewers
+
+<!--
+Help reviewers focus. For example:
+  - Where to start, or a suggested order in which to read the files.
+  - Areas where you would particularly value scrutiny, or where you are uncertain.
+  - How any mechanical, generated or bulk changes were produced (for example a search-and-replace
+    or a code generator), so that reviewers can reproduce the steps.
+  - Screenshots or recordings for visual changes (include before and after where useful).
+-->
+
+## Checklist
+- [ ] The PR has a single, focused purpose and contains no unrelated changes.
+- [ ] The title is a clear, imperative summary of the change (for example, "Add retry to payment client").
+- [ ] I have added or updated tests that cover this change.
+- [ ] The build succeeds and the tests pass locally.
+- [ ] The code follows the existing patterns and style of this repository.
+- [ ] I have updated documentation, changelogs or API references where required.
+- [ ] I have reviewed my own diff, and this description reflects the final state of the change.

docs/web/database.md

@@ -76,14 +76,14 @@ updates (`UPDATE ... WHERE ... AND RowVersion = @RowVersion`).
 | `UserAccount`         | `Domain.Entities.UserAccount`, `Features.Users`             | `Username` and `Email` are unique                                                                                                                                                                         |
 | `UserCredential`      | `Domain.Entities.UserCredential`, `Features.Users`          | Argon2id password hash; `IsRevoked`/`RevokedAt` track credential rotation, not JWTs                                                                                                                       |
 | `UserVerification`    | `Domain.Entities.UserVerification`, `Features.Users`        | Written when a user confirms their email                                                                                                                                                                  |
-| `UserProfile`         | `Domain.Entities.UserProfile`, `Features.Users`             | 1:1 with `UserAccount`; holds the user's biography; written via `IUserProfileRepository`, read via `IUserListRepository.GetByIdAsync`'s left join                                                         |
-| `UserAvatar`          | `Domain.Entities.UserAvatar`, `Features.Users`              | Links a `UserProfile` to a `Photo` as its avatar; written via `IUserProfileRepository.SaveAvatarAsync`                                                                                                    |
+| `UserProfile`         | `Domain.Entities.UserProfile`, `Features.Users`             | 1:1 with `UserAccount`; holds the user's biography; written via `IUserProfileRepository`, read via `IUserListRepository`'s left joins in both `GetByIdAsync` and `GetAllAsync`                                                  |
+| `UserAvatar`          | `Domain.Entities.UserAvatar`, `Features.Users`              | Links a `UserProfile` to a `Photo` as its avatar; written via `IUserProfileRepository.SaveAvatarAsync`, read via `IUserListRepository`'s `ValidTo IS NULL` join for the active avatar                                                                                           |
 | `BreweryPost`         | `Domain.Entities.BreweryPost`, `Features.Breweries`         | A user-submitted brewery listing                                                                                                                                                                          |
 | `BreweryPostLocation` | `Domain.Entities.BreweryPostLocation`, `Features.Breweries` | 1:1 with `BreweryPost`; `Coordinates` is a `GEOGRAPHY` column, read via a plain Dapper query that selects `CONVERT(varbinary(max), Coordinates)`, since Dapper can't deserialize SQL Server UDTs directly |
 | `City`                | `Domain.Entities.City`, `Features.Locations`                | Referenced by `BreweryPostLocation.CityID`; `CityName` and `StateProvinceID` together are unique; written via `ILocationRepository`, read via `ILocationRepository` and `IBreweryRepository`'s location joins, currently written only by `Database.Seed` |
 | `StateProvince`       | `Domain.Entities.StateProvince`, `Features.Locations`       | Referenced by `City.StateProvinceID`; created on demand by `ILocationRepository.GetOrCreateCityIdAsync`, read via `IBreweryRepository`'s location joins                                                   |
 | `Country`             | `Domain.Entities.Country`, `Features.Locations`             | Referenced by `StateProvince.CountryID`; created on demand by `ILocationRepository.GetOrCreateCityIdAsync`, read via `IBreweryRepository`'s location joins                                                |
-| `Photo`               | `Domain.Entities.Photo`, `Features.PhotoUpload`             | Written via `IPhotoUploadRepository.CreateAsync`, sent as an `UploadPhotoCommand` from other features' handlers; not yet seeded by `Database.Seed`                                                        |
+| `Photo`               | `Domain.Entities.Photo`, `Features.PhotoUpload`             | Written via `IPhotoUploadRepository.CreateAsync`, sent as an `UploadPhotoCommand` from other features' handlers; `Hyperlink` holds the object key within the bucket, which readers sign into a time-limited URL via `IFileStorageProvider.GetPresignedUrl`; the active avatar's row is also read via `IUserListRepository`'s `Media.Photo` join; not yet seeded by `Database.Seed`                                                |
 
 ### Tables defined in the schema but not yet wired to a feature slice
 

docs/web/environment-variables.md

@@ -260,17 +260,25 @@ and retrieving photos via an S3-compatible object store.
 
 ```bash
 SEAWEEDFS_SERVICE_URL=http://seaweedfs:8333   # Required, no default
+SEAWEEDFS_PUBLIC_URL=http://localhost:8333    # Optional, defaults to SEAWEEDFS_SERVICE_URL
 SEAWEEDFS_ACCESS_KEY_ID=admin                 # Required, no default
 SEAWEEDFS_SECRET_ACCESS_KEY=secret            # Required, no default
 SEAWEEDFS_BUCKET=my-bucket                    # Required, no default
 ```
 
 - **Implementation**: `S3FileStorageProvider` throws on construction if any of
-  these four values is missing
+  the four required values is missing
 - **Local dev**: point at the `seaweedfs` Docker service (S3 API on port 8333)
 - **Production**: point at any S3-compatible endpoint (AWS S3, a hosted
   SeaweedFS cluster, and so on); `ForcePathStyle` is always enabled, which
   SeaweedFS requires and AWS S3 also accepts
+- **`SEAWEEDFS_PUBLIC_URL`**: the endpoint download URLs are signed against,
+  used by `GetPresignedUrl` and reaching the API response as
+  `PublicUserProfileDto.AvatarUrl`. A presigned URL is signed over its host, so
+  this has to be the address the browser uses (`http://localhost:8333` with the
+  dev compose file, which publishes the S3 API port), separate from the
+  in-network `SEAWEEDFS_SERVICE_URL` the API uploads through. The two can be the
+  same value wherever one address serves both
 
 ## Docker-specific variables
 
@@ -341,6 +349,7 @@ from the template in place; edit them manually if you go that route.
 | `SMTP_FROM_EMAIL`             |    ✓    |          |   ✓    |   Yes    | Email sender address         |
 | `SMTP_FROM_NAME`              |    ✓    |          |   ✓    |    No    | Defaults to `The Biergarten` |
 | `SEAWEEDFS_SERVICE_URL`       |    ✓    |          |   ✓    |   Yes    | S3-compatible endpoint URL   |
+| `SEAWEEDFS_PUBLIC_URL`        |    ✓    |          |   ✓    |    No    | Endpoint download URLs are signed against; defaults to `SEAWEEDFS_SERVICE_URL` |
 | `SEAWEEDFS_ACCESS_KEY_ID`     |    ✓    |          |   ✓    |   Yes    | S3 access key                |
 | `SEAWEEDFS_SECRET_ACCESS_KEY` |    ✓    |          |   ✓    |   Yes    | S3 secret key                |
 | `SEAWEEDFS_BUCKET`            |    ✓    |          |   ✓    |   Yes    | S3 bucket name               |
@@ -415,6 +424,7 @@ SMTP_FROM_NAME=The Biergarten App
 
 # SeaweedFS (S3-compatible storage)
 SEAWEEDFS_SERVICE_URL=http://seaweedfs:8333
+SEAWEEDFS_PUBLIC_URL=http://localhost:8333
 SEAWEEDFS_ACCESS_KEY_ID=<generated-with-openssl>
 SEAWEEDFS_SECRET_ACCESS_KEY=<generated-with-openssl>
 SEAWEEDFS_BUCKET=my-bucket

docs/web/testing.md

@@ -257,7 +257,8 @@ API.Specs/
 │   └── ApiGeneralSteps.cs              # Shared/general step definitions
 ├── Mocks/
 │   ├── MockEmailDispatcher.cs          # Substitutes Features.Emails' IEmailDispatcher
-│   └── MockEmailProvider.cs            # Substitutes Features.Emails' IEmailProvider
+│   ├── MockEmailProvider.cs            # Substitutes Features.Emails' IEmailProvider
+│   └── MockFileStorageProvider.cs      # Substitutes Features.ImageUploads' IFileStorageProvider
 └── TestApiFactory.cs                   # Test server setup (swaps in the mocks above)
 ```
 

web/.env.example

@@ -68,8 +68,12 @@ WEBSITE_BASE_URL=http://localhost:3000
 # ======================
 # SeaweedFS (S3) Configuration
 # ======================
-# Credentials and default bucket for the local SeaweedFS S3-compatible storage
+# Credentials and default bucket for the local SeaweedFS S3-compatible storage.
+# SEAWEEDFS_SERVICE_URL is the in-network endpoint the API uploads through;
+# SEAWEEDFS_PUBLIC_URL is the endpoint download URLs are signed against, so it has to be
+# reachable from the browser. It defaults to SEAWEEDFS_SERVICE_URL when left blank.
 SEAWEEDFS_SERVICE_URL=http://seaweedfs:8333
+SEAWEEDFS_PUBLIC_URL=http://localhost:8333
 SEAWEEDFS_ACCESS_KEY_ID=admin
 SEAWEEDFS_SECRET_ACCESS_KEY=secret
 SEAWEEDFS_BUCKET=my-bucket

web/backend/API/API.Specs/Features/PublicUserProfile.feature

@@ -13,9 +13,61 @@ Scenario: Public profile exposes only allowlisted fields
     Then the response has HTTP status 200
     And the public profile response should match the registered account
     And the response JSON should have "biography" equal ""
+    And the response JSON should have "avatarUrl" equal ""
     And the response JSON should not contain "email"
     And the response JSON should not contain "dateOfBirth"
 
+Scenario: Public profile exposes the uploaded avatar
+    Given I have registered a new account
+    And I have a valid access token for my account
+    And I have uploaded an avatar
+    When I retrieve the public profile by ID
+    Then the response has HTTP status 200
+    And the public profile response should carry my current avatar
+
+Scenario: Public profile exposes the current avatar after it is replaced
+    Given I have registered a new account
+    And I have a valid access token for my account
+    And I have uploaded an avatar
+    And I have uploaded a new avatar, replacing the previous one
+    When I retrieve the public profile by ID
+    Then the response has HTTP status 200
+    And the public profile response should carry my current avatar
+    And the public profile response should not carry my previous avatar
+
+Scenario: Fetching the avatar without authentication succeeds
+    Given I have registered a new account
+    And I have a valid access token for my account
+    And I have uploaded an avatar
+    When I retrieve the public profile by ID without authentication
+    Then the response has HTTP status 200
+    And the public profile response should carry my current avatar
+
+Scenario: A different user can read someone else's avatar
+    Given I have registered a new account
+    And I have a valid access token for my account
+    And I have uploaded an avatar
+    And I am logged in as a different user
+    When I retrieve the public profile by ID
+    Then the response has HTTP status 200
+    And the public profile response should carry my current avatar
+
+Scenario: Listing user accounts exposes each account's avatar
+    Given I have registered a new account
+    And I have a valid access token for my account
+    And I have uploaded an avatar
+    When I list user accounts
+    Then the response has HTTP status 200
+    And my listed account should carry my current avatar
+
+Scenario: Listing user accounts exposes each account's biography
+    Given I have registered a new account
+    And I have a valid access token for my account
+    And I have set my biography to "Drinks lagers."
+    When I list user accounts
+    Then the response has HTTP status 200
+    And my listed account should carry my biography
+
 Scenario: Public profile for a non-existent account returns not found
     Given I have registered a new account
     And I have a valid access token for my account
@@ -26,6 +78,7 @@ Scenario: Fetching the public profile without authentication succeeds
     Given I have registered a new account
     When I retrieve the public profile by ID without authentication
     Then the response has HTTP status 200
+    And the response JSON should have "avatarUrl" equal ""
     And the response JSON should not contain "email"
     And the response JSON should not contain "dateOfBirth"
 
@@ -50,6 +103,7 @@ Scenario: Listing user accounts as an authenticated user excludes private fields
     And I have a valid access token for my account
     When I list user accounts
     Then the response has HTTP status 200
+    And the response JSON should contain "avatarUrl"
     And the response JSON should not contain "email"
     And the response JSON should not contain "dateOfBirth"
 
@@ -60,6 +114,14 @@ Scenario: The caller can fetch their own account
     Then the response has HTTP status 200
     And the public profile response should match the registered account
 
+Scenario: The caller's own account omits the avatar graph
+    Given I have registered a new account
+    And I have a valid access token for my account
+    And I have uploaded an avatar
+    When I retrieve my own account
+    Then the response has HTTP status 200
+    And the response JSON should not contain "userAvatar"
+
 Scenario: The account endpoint serves the caller named by the access token
     Given I have registered a new account
     And I am logged in as a different user

web/backend/API/API.Specs/Mocks/MockFileStorageProvider.cs

@@ -0,0 +1,55 @@
+using Features.ImageUploads.Services;
+
+namespace API.Specs.Mocks;
+
+/// <summary>
+///     Test double for <see cref="IFileStorageProvider" /> that records uploads in memory, so specs can
+///     exercise photo-backed features without object storage.
+/// </summary>
+public class MockFileStorageProvider : IFileStorageProvider
+{
+    private readonly List<string> _keys = [];
+    private readonly Dictionary<string, byte[]> _objects = new();
+
+    public IReadOnlyCollection<string> UploadedKeys => _keys.ToList();
+
+    /// <summary>The key of the most recent upload.</summary>
+    /// <exception cref="InvalidOperationException">Thrown when nothing has been uploaded yet.</exception>
+    public string LastUploadedKey =>
+        _keys.Count > 0
+            ? _keys[^1]
+            : throw new InvalidOperationException("no file has been uploaded");
+
+    public Task UploadAsync(
+        string key,
+        Stream content,
+        string contentType,
+        CancellationToken cancellationToken = default
+    )
+    {
+        using MemoryStream buffer = new();
+        content.CopyTo(buffer);
+
+        if (!_objects.ContainsKey(key))
+            _keys.Add(key);
+
+        _objects[key] = buffer.ToArray();
+        return Task.CompletedTask;
+    }
+
+    public Task DeleteAsync(string key, CancellationToken cancellationToken = default)
+    {
+        _objects.Remove(key);
+        _keys.Remove(key);
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    ///     Stands in for a signed download URL: an absolute URL on a host the object store would serve,
+    ///     carrying the key in its path, so specs can assert the shape callers actually receive.
+    /// </summary>
+    public string GetPresignedUrl(string key, TimeSpan expiresIn)
+    {
+        return $"https://storage.test/{key}?X-Amz-Expires={(int)expiresIn.TotalSeconds}";
+    }
+}

web/backend/API/API.Specs/Steps/ApiGeneralSteps.cs

@@ -183,6 +183,25 @@ public class ApiGeneralSteps(ScenarioContext scenario)
             AssertFieldAbsent(payloadElem, field);
     }
 
+    [Then("the response JSON should contain {string}")]
+    public void ThenTheResponseJsonShouldContainString(string field)
+    {
+        scenario.TryGetValue<string>(ResponseBodyKey, out string? responseBody).Should().BeTrue();
+
+        using JsonDocument doc = JsonDocument.Parse(responseBody!);
+        JsonElement root = doc.RootElement;
+
+        if (root.ValueKind == JsonValueKind.Object &&
+            !root.TryGetProperty(field, out _) &&
+            root.TryGetProperty("payload", out JsonElement payloadElem))
+        {
+            AssertFieldPresent(payloadElem, field);
+            return;
+        }
+
+        AssertFieldPresent(root, field);
+    }
+
     /// <summary>
     ///     Recurses into arrays so a listing endpoint's response can be asserted the same way as a
     ///     single-resource response.
@@ -203,4 +222,31 @@ public class ApiGeneralSteps(ScenarioContext scenario)
                 break;
         }
     }
+
+    /// <summary>
+    ///     Recurses into arrays so every item of a listing endpoint's response must carry the field.
+    /// </summary>
+    private static void AssertFieldPresent(JsonElement element, string field)
+    {
+        switch (element.ValueKind)
+        {
+            case JsonValueKind.Object:
+                element
+                    .TryGetProperty(field, out _)
+                    .Should()
+                    .BeTrue("Expected field '{0}' to be present in the response", field);
+                break;
+            case JsonValueKind.Array:
+                element
+                    .EnumerateArray()
+                    .Should()
+                    .NotBeEmpty(
+                        "Expected at least one item to assert field '{0}' against",
+                        field
+                    );
+                foreach (JsonElement item in element.EnumerateArray())
+                    AssertFieldPresent(item, field);
+                break;
+        }
+    }
 }

web/backend/API/API.Specs/Steps/UserSteps.cs

@@ -1,5 +1,12 @@
 using System.Text.Json;
+using API.Specs.Mocks;
+using Features.ImageUploads.Services;
+using Features.Users.Commands.Profile.UploadAvatar;
+using Features.Users.Repository;
 using FluentAssertions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
 using Reqnroll;
 
 namespace API.Specs.Steps;
@@ -10,6 +17,11 @@ public class UserSteps(ScenarioContext scenario) : ApiStepsBase(scenario)
     private const string AccessTokenKey = "accessToken";
     private const string RegisteredUserIdKey = "registeredUserId";
     private const string RegisteredUsernameKey = "registeredUsername";
+    private const string CurrentAvatarKeyKey = "currentAvatarKey";
+    private const string PreviousAvatarKeyKey = "previousAvatarKey";
+    private const string BiographyKey = "biography";
+
+    private static readonly byte[] PngSignature = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];
 
     private async Task SendAsync(HttpRequestMessage requestMessage)
     {
@@ -36,22 +48,193 @@ public class UserSteps(ScenarioContext scenario) : ApiStepsBase(scenario)
             : throw new InvalidOperationException("registered user ID not found in scenario");
     }
 
+    /// <summary>
+    ///     Builds the smallest upload the photo validator accepts: a PNG signature padded out to the
+    ///     1 KiB minimum.
+    /// </summary>
+    private static IFormFile CreateAvatarFile()
+    {
+        byte[] content = new byte[2048];
+        PngSignature.CopyTo(content, 0);
+        MemoryStream stream = new(content);
+
+        return new FormFile(stream, 0, content.Length, "file", "avatar.png")
+        {
+            Headers = new HeaderDictionary { ["Content-Type"] = "image/png" },
+        };
+    }
+
+    /// <summary>
+    ///     Uploads an avatar and records the object key the storage provider actually received, rather
+    ///     than re-deriving the key template the handler uses.
+    /// </summary>
+    private async Task UploadAvatarAsync()
+    {
+        Guid userId = GetRegisteredUserId();
+
+        using IServiceScope scope = GetFactory().Services.CreateScope();
+        IMediator mediator = scope.ServiceProvider.GetRequiredService<IMediator>();
+        await mediator.Send(new UploadAvatarCommand(userId, CreateAvatarFile()));
+
+        if (Scenario.TryGetValue<string>(CurrentAvatarKeyKey, out string? existing))
+            Scenario[PreviousAvatarKeyKey] = existing;
+
+        Scenario[CurrentAvatarKeyKey] = GetStorageProvider().LastUploadedKey;
+    }
+
+    private MockFileStorageProvider GetStorageProvider()
+    {
+        return (MockFileStorageProvider)
+            GetFactory().Services.GetRequiredService<IFileStorageProvider>();
+    }
+
+    private string GetCurrentAvatarKey()
+    {
+        return Scenario.TryGetValue(CurrentAvatarKeyKey, out string? key) && key is not null
+            ? key
+            : throw new InvalidOperationException("no avatar has been uploaded in this scenario");
+    }
+
+    private string GetPreviousAvatarKey()
+    {
+        return Scenario.TryGetValue(PreviousAvatarKeyKey, out string? key) && key is not null
+            ? key
+            : throw new InvalidOperationException(
+                "only one avatar has been uploaded in this scenario"
+            );
+    }
+
+    /// <summary>
+    ///     Asserts that <paramref name="avatarUrl" /> is something a browser can fetch -- an absolute
+    ///     HTTP(S) URL -- pointing at the object stored under <paramref name="expectedKey" />. A bare
+    ///     storage key would resolve against the page's own origin, so the shape is the contract here,
+    ///     not just the value.
+    /// </summary>
+    private static Uri AssertFetchableUrl(string? avatarUrl, string expectedKey)
+    {
+        avatarUrl.Should().NotBeNullOrWhiteSpace();
+
+        Uri.TryCreate(avatarUrl, UriKind.Absolute, out Uri? uri)
+            .Should()
+            .BeTrue("avatarUrl must be an absolute URL, but was '{0}'", avatarUrl);
+        uri!.Scheme.Should().BeOneOf("http", "https");
+        uri.AbsolutePath.Should().EndWith(expectedKey, "the URL must address the uploaded object");
+
+        return uri;
+    }
+
+    private string GetAvatarUrlFromResponse()
+    {
+        Scenario.TryGetValue<string>(ResponseBodyKey, out string? responseBody).Should().BeTrue();
+
+        using JsonDocument doc = JsonDocument.Parse(responseBody!);
+        return doc.RootElement.GetProperty("avatarUrl").GetString()!;
+    }
+
+    [Given("I have uploaded an avatar")]
+    public async Task GivenIHaveUploadedAnAvatar()
+    {
+        await UploadAvatarAsync();
+    }
+
+    [Given("I have uploaded a new avatar, replacing the previous one")]
+    public async Task GivenIHaveUploadedANewAvatarReplacingThePreviousOne()
+    {
+        await UploadAvatarAsync();
+    }
+
+    /// <summary>
+    ///     Writes the biography straight through the repository: registration creates the profile row
+    ///     with an empty biography, and no endpoint edits it yet.
+    /// </summary>
+    [Given("I have set my biography to {string}")]
+    public async Task GivenIHaveSetMyBiographyTo(string biography)
+    {
+        using IServiceScope scope = GetFactory().Services.CreateScope();
+        IUserProfileRepository profiles =
+            scope.ServiceProvider.GetRequiredService<IUserProfileRepository>();
+
+        await profiles.UpdateBiographyAsync(
+            GetRegisteredUserId(),
+            biography,
+            CancellationToken.None
+        );
+
+        Scenario[BiographyKey] = biography;
+    }
+
+    [Then("the public profile response should carry my current avatar")]
+    public void ThenThePublicProfileResponseShouldCarryMyCurrentAvatar()
+    {
+        AssertFetchableUrl(GetAvatarUrlFromResponse(), GetCurrentAvatarKey());
+    }
+
+    [Then("the public profile response should not carry my previous avatar")]
+    public void ThenThePublicProfileResponseShouldNotCarryMyPreviousAvatar()
+    {
+        Uri uri = AssertFetchableUrl(GetAvatarUrlFromResponse(), GetCurrentAvatarKey());
+        uri.AbsolutePath.Should().NotContain(GetPreviousAvatarKey());
+    }
+
+    [Then("my listed account should carry my current avatar")]
+    public void ThenMyListedAccountShouldCarryMyCurrentAvatar()
+    {
+        AssertFetchableUrl(
+            GetMyListedAccount().GetProperty("avatarUrl").GetString(),
+            GetCurrentAvatarKey()
+        );
+    }
+
+    [Then("my listed account should carry my biography")]
+    public void ThenMyListedAccountShouldCarryMyBiography()
+    {
+        string expected =
+            Scenario.TryGetValue(BiographyKey, out string? biography) && biography is not null
+                ? biography
+                : throw new InvalidOperationException("no biography was set in this scenario");
+
+        GetMyListedAccount().GetProperty("biography").GetString().Should().Be(expected);
+    }
+
+    /// <summary>Finds the registered account in a listing response.</summary>
+    private JsonElement GetMyListedAccount()
+    {
+        Scenario.TryGetValue<string>(ResponseBodyKey, out string? responseBody).Should().BeTrue();
+
+        using JsonDocument doc = JsonDocument.Parse(responseBody!);
+        doc.RootElement.ValueKind.Should().Be(JsonValueKind.Array);
+
+        return doc
+            .RootElement.EnumerateArray()
+            .Should()
+            .ContainSingle(item =>
+                item.GetProperty("userAccountId").GetGuid() == GetRegisteredUserId()
+            )
+            .Subject.Clone();
+    }
+
     [When("I retrieve the public profile by ID")]
     public async Task WhenIRetrieveThePublicProfileById()
     {
-        await SendAsync(NewAuthenticatedRequest(HttpMethod.Get, $"/api/user/{GetRegisteredUserId()}/profile"));
+        await SendAsync(
+            NewAuthenticatedRequest(HttpMethod.Get, $"/api/user/{GetRegisteredUserId()}/profile")
+        );
     }
 
     [When("I retrieve the public profile by ID without authentication")]
     public async Task WhenIRetrieveThePublicProfileByIdWithoutAuthentication()
     {
-        await SendAsync(new HttpRequestMessage(HttpMethod.Get, $"/api/user/{GetRegisteredUserId()}/profile"));
+        await SendAsync(
+            new HttpRequestMessage(HttpMethod.Get, $"/api/user/{GetRegisteredUserId()}/profile")
+        );
     }
 
     [When("I retrieve the public profile by a non-existent ID")]
     public async Task WhenIRetrieveThePublicProfileByANonExistentId()
     {
-        await SendAsync(NewAuthenticatedRequest(HttpMethod.Get, $"/api/user/{Guid.NewGuid()}/profile"));
+        await SendAsync(
+            NewAuthenticatedRequest(HttpMethod.Get, $"/api/user/{Guid.NewGuid()}/profile")
+        );
     }
 
     [When("I retrieve my own account without authentication")]

web/backend/API/API.Specs/TestApiFactory.cs

@@ -1,6 +1,7 @@
 using API.Core;
 using API.Specs.Mocks;
 using Features.Emails.Services;
+using Features.ImageUploads.Services;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Mvc.Testing;
 using Microsoft.Extensions.DependencyInjection;
@@ -32,6 +33,15 @@ internal class TestApiFactory : WebApplicationFactory<Program>
                 services.Remove(emailDispatcherDescriptor);
 
             services.AddScoped<IEmailDispatcher, MockEmailDispatcher>();
+
+            ServiceDescriptor? fileStorageDescriptor = services.SingleOrDefault(d =>
+                d.ServiceType == typeof(IFileStorageProvider)
+            );
+
+            if (fileStorageDescriptor != null)
+                services.Remove(fileStorageDescriptor);
+
+            services.AddSingleton<IFileStorageProvider, MockFileStorageProvider>();
         });
     }
 }

web/backend/Configuration/ConfigurationKeys.cs

@@ -23,6 +23,14 @@ public static class ConfigurationKeys
     public const string SmtpFromName = "SMTP_FROM_NAME";
 
     public const string SeaweedFsServiceUrl = "SEAWEEDFS_SERVICE_URL";
+
+    /// <summary>
+    ///     The browser-reachable base URL of the object store, used to sign download URLs. Falls back to
+    ///     <see cref="SeaweedFsServiceUrl" /> when unset: SigV4 covers the host, so a URL signed against
+    ///     the container-internal endpoint is only usable by callers that can resolve that host.
+    /// </summary>
+    public const string SeaweedFsPublicUrl = "SEAWEEDFS_PUBLIC_URL";
+
     public const string SeaweedFsAccessKeyId = "SEAWEEDFS_ACCESS_KEY_ID";
     public const string SeaweedFsSecretAccessKey = "SEAWEEDFS_SECRET_ACCESS_KEY";
     public const string SeaweedFsBucket = "SEAWEEDFS_BUCKET";

web/backend/Domain/Domain.Entities/Entities/UserAccount.cs

@@ -1,3 +1,5 @@
+using System.Text.Json.Serialization;
+
 namespace Domain.Entities;
 
 public sealed class UserAccount
@@ -20,4 +22,10 @@ public sealed class UserAccount
     // Navigation properties
     public UserCredential? UserCredential { get; set; }
     public UserProfile? UserProfile { get; set; }
+
+    // GET /api/user/authenticated serializes this entity directly, and the avatar graph carries the
+    // storage key and uploader of the underlying Photo. Clients read the avatar from
+    // PublicUserProfileDto.AvatarUrl, which is a signed URL, so keep this one out of the response.
+    [JsonIgnore]
+    public UserAvatar? UserAvatar { get; set; }
 }

web/backend/Features/Features.PhotoUpload/Services/S3FileStorageProvider.cs

@@ -13,11 +13,14 @@ public class S3FileStorageProvider : IFileStorageProvider, IDisposable
 {
     private readonly string _bucket;
     private readonly IAmazonS3 _client;
+    private readonly IAmazonS3 _presignClient;
+    private readonly Protocol _presignProtocol;
 
     /// <summary>
     ///     Initializes a new instance of the <see cref="S3FileStorageProvider" /> class, reading storage
     ///     configuration (<c>SEAWEEDFS_SERVICE_URL</c>, <c>SEAWEEDFS_ACCESS_KEY_ID</c>,
-    ///     <c>SEAWEEDFS_SECRET_ACCESS_KEY</c>, <c>SEAWEEDFS_BUCKET</c>) from <paramref name="configuration" />.
+    ///     <c>SEAWEEDFS_SECRET_ACCESS_KEY</c>, <c>SEAWEEDFS_BUCKET</c>, and the optional
+    ///     <c>SEAWEEDFS_PUBLIC_URL</c>) from <paramref name="configuration" />.
     /// </summary>
     /// <exception cref="InvalidOperationException">
     ///     Thrown when any of the required configuration values is not set.
@@ -45,6 +48,31 @@ public class S3FileStorageProvider : IFileStorageProvider, IDisposable
         AmazonS3Config config = new() { ServiceURL = serviceUrl, ForcePathStyle = true };
 
         _client = new AmazonS3Client(accessKeyId, secretAccessKey, config);
+
+        // A presigned URL is signed over its host, so one signed against the container-internal
+        // endpoint is only usable from inside the network. Sign downloads against the public
+        // endpoint instead, so a browser can fetch the object.
+        string? configuredPublicUrl = configuration[ConfigurationKeys.SeaweedFsPublicUrl];
+        string publicUrl = string.IsNullOrWhiteSpace(configuredPublicUrl)
+            ? serviceUrl
+            : configuredPublicUrl;
+
+        _presignClient =
+            publicUrl == serviceUrl
+                ? _client
+                : new AmazonS3Client(
+                    accessKeyId,
+                    secretAccessKey,
+                    new AmazonS3Config { ServiceURL = publicUrl, ForcePathStyle = true }
+                );
+
+        // GetPreSignedUrlRequest.Protocol defaults to HTTPS and ignores the ServiceURL scheme, so
+        // take the scheme from the endpoint the URL is signed against.
+        _presignProtocol =
+            Uri.TryCreate(publicUrl, UriKind.Absolute, out Uri? publicUri)
+            && publicUri.Scheme == Uri.UriSchemeHttp
+                ? Protocol.HTTP
+                : Protocol.HTTPS;
     }
 
     /// <inheritdoc/>
@@ -82,14 +110,18 @@ public class S3FileStorageProvider : IFileStorageProvider, IDisposable
             BucketName = _bucket,
             Key = key,
             Expires = DateTime.UtcNow.Add(expiresIn),
+            Protocol = _presignProtocol,
         };
 
-        return _client.GetPreSignedURL(request);
+        return _presignClient.GetPreSignedURL(request);
     }
 
     /// <inheritdoc/>
     public void Dispose()
     {
+        if (!ReferenceEquals(_presignClient, _client))
+            _presignClient.Dispose();
+
         _client.Dispose();
         GC.SuppressFinalize(this);
     }

web/backend/Features/Features.Users.Tests/Queries/GetAllUsersHandlerTests.cs

@@ -1,4 +1,5 @@
 using Domain.Entities;
+using Features.ImageUploads.Services;
 using Features.Users.Dtos;
 using Features.Users.Queries.GetAllUsers;
 using Features.Users.Repository;
@@ -9,27 +10,36 @@ namespace Features.Users.Tests.Queries;
 
 public class GetAllUsersHandlerTests
 {
+    private readonly Mock<IUserListRepository> _repoMock = new();
+    private readonly Mock<IFileStorageProvider> _storageMock = new();
+    private readonly GetAllUsersHandler _handler;
+
+    public GetAllUsersHandlerTests()
+    {
+        _storageMock
+            .Setup(s => s.GetPresignedUrl(It.IsAny<string>(), It.IsAny<TimeSpan>()))
+            .Returns((string key, TimeSpan _) => $"https://storage.test/{key}?signed");
+
+        _handler = new GetAllUsersHandler(_repoMock.Object, _storageMock.Object);
+    }
+
     [Fact]
     public async Task Handle_PassesLimitAndOffset_ToRepository()
     {
-        Mock<IUserListRepository> repoMock = new();
-        GetAllUsersHandler handler = new(repoMock.Object);
-        repoMock.Setup(r => r.GetAllAsync(10, 5)).ReturnsAsync(Array.Empty<UserAccount>());
+        _repoMock.Setup(r => r.GetAllAsync(10, 5)).ReturnsAsync(Array.Empty<UserAccount>());
 
-        IEnumerable<PublicUserProfileDto> result = await handler.Handle(
+        IEnumerable<PublicUserProfileDto> result = await _handler.Handle(
             new GetAllUsersQuery(10, 5),
             CancellationToken.None
         );
 
         result.Should().BeEmpty();
-        repoMock.Verify(r => r.GetAllAsync(10, 5), Times.Once);
+        _repoMock.Verify(r => r.GetAllAsync(10, 5), Times.Once);
     }
 
     [Fact]
     public async Task Handle_MapsUsersToPublicProfileDtos_AndExcludesPrivateFields()
     {
-        Mock<IUserListRepository> repoMock = new();
-        GetAllUsersHandler handler = new(repoMock.Object);
         UserAccount user = new()
         {
             UserAccountId = Guid.NewGuid(),
@@ -38,13 +48,60 @@ public class GetAllUsersHandlerTests
             LastName = "One",
             CreatedAt = DateTime.UtcNow,
         };
-        repoMock.Setup(r => r.GetAllAsync(null, null)).ReturnsAsync([user]);
+        _repoMock.Setup(r => r.GetAllAsync(null, null)).ReturnsAsync([user]);
 
-        IEnumerable<PublicUserProfileDto> result = await handler.Handle(
+        IEnumerable<PublicUserProfileDto> result = await _handler.Handle(
             new GetAllUsersQuery(null, null),
             CancellationToken.None
         );
 
-        result.Should().ContainSingle().Which.Should().BeEquivalentTo(user.ToPublicProfileDto());
+        result
+            .Should()
+            .ContainSingle()
+            .Which.Should()
+            .BeEquivalentTo(user.ToPublicProfileDto(_storageMock.Object));
+    }
+
+    [Fact]
+    public async Task Handle_MapsEachUsersOwnAvatarUrl()
+    {
+        string avatarKey = $"avatars/{Guid.NewGuid()}/{Guid.NewGuid()}";
+        UserAccount withAvatar = new()
+        {
+            UserAccountId = Guid.NewGuid(),
+            Username = "has-avatar",
+            FirstName = "Has",
+            LastName = "Avatar",
+            CreatedAt = DateTime.UtcNow,
+            UserProfile = new UserProfile { Biography = "Drinks lagers." },
+            UserAvatar = new UserAvatar { Photo = new Photo { Hyperlink = avatarKey } },
+        };
+        UserAccount withoutAvatar = new()
+        {
+            UserAccountId = Guid.NewGuid(),
+            Username = "no-avatar",
+            FirstName = "No",
+            LastName = "Avatar",
+            CreatedAt = DateTime.UtcNow,
+        };
+        _repoMock.Setup(r => r.GetAllAsync(null, null)).ReturnsAsync([withAvatar, withoutAvatar]);
+
+        IEnumerable<PublicUserProfileDto> result = await _handler.Handle(
+            new GetAllUsersQuery(null, null),
+            CancellationToken.None
+        );
+
+        result
+            .Select(dto => dto.AvatarUrl)
+            .Should()
+            .Equal($"https://storage.test/{avatarKey}?signed", string.Empty);
+        _storageMock.Verify(
+            s => s.GetPresignedUrl(avatarKey, UserDtoMapper.AvatarUrlLifetime),
+            Times.Once
+        );
+        _storageMock.Verify(
+            s => s.GetPresignedUrl(It.IsAny<string>(), It.IsAny<TimeSpan>()),
+            Times.Once
+        );
     }
 }

web/backend/Features/Features.Users.Tests/Queries/GetPublicUserProfileByIdHandlerTests.cs

@@ -1,5 +1,6 @@
 using Domain.Entities;
 using Domain.Exceptions;
+using Features.ImageUploads.Services;
 using Features.Users.Dtos;
 using Features.Users.Queries.GetPublicUserProfileById;
 using Features.Users.Repository;
@@ -12,15 +13,21 @@ public class GetPublicUserProfileByIdHandlerTests
 {
     private readonly GetPublicUserProfileByIdHandler _handler;
     private readonly Mock<IUserListRepository> _repoMock = new();
+    private readonly Mock<IFileStorageProvider> _storageMock = new();
 
     public GetPublicUserProfileByIdHandlerTests()
     {
-        _handler = new GetPublicUserProfileByIdHandler(_repoMock.Object);
+        _storageMock
+            .Setup(s => s.GetPresignedUrl(It.IsAny<string>(), It.IsAny<TimeSpan>()))
+            .Returns((string key, TimeSpan _) => $"https://storage.test/{key}?signed");
+
+        _handler = new GetPublicUserProfileByIdHandler(_repoMock.Object, _storageMock.Object);
     }
 
     [Fact]
     public async Task Handle_ReturnsPublicProfile_WhenFound()
     {
+        string avatarKey = $"avatars/{Guid.NewGuid()}/{Guid.NewGuid()}";
         UserAccount user = new()
         {
             UserAccountId = Guid.NewGuid(),
@@ -31,6 +38,7 @@ public class GetPublicUserProfileByIdHandlerTests
             DateOfBirth = new DateTime(1990, 1, 1),
             CreatedAt = new DateTime(2024, 1, 1),
             UserProfile = new UserProfile { Biography = "Drinks lagers." },
+            UserAvatar = new UserAvatar { Photo = new Photo { Hyperlink = avatarKey } },
         };
         _repoMock.Setup(r => r.GetByIdAsync(user.UserAccountId)).ReturnsAsync(user);
 
@@ -48,13 +56,48 @@ public class GetPublicUserProfileByIdHandlerTests
                     user.FirstName,
                     user.LastName,
                     "Drinks lagers.",
+                    $"https://storage.test/{avatarKey}?signed",
                     user.CreatedAt
                 )
             );
     }
 
+    /// <summary>
+    ///     <c>Photo.Hyperlink</c> holds an object key, so the DTO has to carry a signed URL rather than
+    ///     the stored value: a bare key resolves against the calling page's own origin.
+    /// </summary>
     [Fact]
-    public async Task Handle_ReturnsEmptyBiography_WhenProfileMissing()
+    public async Task Handle_SignsTheAvatarKey_RatherThanReturningIt()
+    {
+        string avatarKey = $"avatars/{Guid.NewGuid()}/{Guid.NewGuid()}";
+        UserAccount user = new()
+        {
+            UserAccountId = Guid.NewGuid(),
+            Username = "test",
+            FirstName = "Jane",
+            LastName = "Doe",
+            CreatedAt = new DateTime(2024, 1, 1),
+            UserAvatar = new UserAvatar { Photo = new Photo { Hyperlink = avatarKey } },
+        };
+        _repoMock.Setup(r => r.GetByIdAsync(user.UserAccountId)).ReturnsAsync(user);
+
+        PublicUserProfileDto result = await _handler.Handle(
+            new GetPublicUserProfileByIdQuery(user.UserAccountId),
+            CancellationToken.None
+        );
+
+        result.AvatarUrl.Should().NotBe(avatarKey);
+        Uri.TryCreate(result.AvatarUrl, UriKind.Absolute, out Uri? uri).Should().BeTrue();
+        uri!.Scheme.Should().BeOneOf("http", "https");
+        uri.AbsolutePath.Should().EndWith(avatarKey);
+        _storageMock.Verify(
+            s => s.GetPresignedUrl(avatarKey, UserDtoMapper.AvatarUrlLifetime),
+            Times.Once
+        );
+    }
+
+    [Fact]
+    public async Task Handle_ReturnsEmptyBiographyAndAvatarUrl_WhenProfileMissing()
     {
         UserAccount user = new()
         {
@@ -72,6 +115,57 @@ public class GetPublicUserProfileByIdHandlerTests
         );
 
         result.Biography.Should().BeEmpty();
+        result.AvatarUrl.Should().BeEmpty();
+    }
+
+    [Fact]
+    public async Task Handle_ReturnsEmptyAvatarUrl_WhenProfileHasNoAvatar()
+    {
+        UserAccount user = new()
+        {
+            UserAccountId = Guid.NewGuid(),
+            Username = "test",
+            FirstName = "Jane",
+            LastName = "Doe",
+            CreatedAt = new DateTime(2024, 1, 1),
+            UserProfile = new UserProfile { Biography = "Drinks lagers." },
+        };
+        _repoMock.Setup(r => r.GetByIdAsync(user.UserAccountId)).ReturnsAsync(user);
+
+        PublicUserProfileDto result = await _handler.Handle(
+            new GetPublicUserProfileByIdQuery(user.UserAccountId),
+            CancellationToken.None
+        );
+
+        result.Biography.Should().Be("Drinks lagers.");
+        result.AvatarUrl.Should().BeEmpty();
+    }
+
+    [Fact]
+    public async Task Handle_ReturnsEmptyAvatarUrl_WhenAvatarHasNoPhoto()
+    {
+        UserAccount user = new()
+        {
+            UserAccountId = Guid.NewGuid(),
+            Username = "test",
+            FirstName = "Jane",
+            LastName = "Doe",
+            CreatedAt = new DateTime(2024, 1, 1),
+            UserProfile = new UserProfile { Biography = "Drinks lagers." },
+            UserAvatar = new UserAvatar(),
+        };
+        _repoMock.Setup(r => r.GetByIdAsync(user.UserAccountId)).ReturnsAsync(user);
+
+        PublicUserProfileDto result = await _handler.Handle(
+            new GetPublicUserProfileByIdQuery(user.UserAccountId),
+            CancellationToken.None
+        );
+
+        result.AvatarUrl.Should().BeEmpty();
+        _storageMock.Verify(
+            s => s.GetPresignedUrl(It.IsAny<string>(), It.IsAny<TimeSpan>()),
+            Times.Never
+        );
     }
 
     [Fact]

web/backend/Features/Features.Users/Dtos/UserDtoMapper.cs

@@ -1,19 +1,39 @@
 using Domain.Entities;
+using Features.ImageUploads.Services;
 
 namespace Features.Users.Dtos;
 
 /// <summary>Converts user domain entities into API response models.</summary>
 public static class UserDtoMapper
 {
+    /// <summary>
+    ///     How long a presigned avatar URL stays valid. Long enough to outlive the page that embeds it,
+    ///     short enough that a leaked URL stops working.
+    /// </summary>
+    public static readonly TimeSpan AvatarUrlLifetime = TimeSpan.FromHours(1);
+
     /// <summary>Converts a user account into its public-profile representation.</summary>
-    public static PublicUserProfileDto ToPublicProfileDto(this UserAccount user)
+    /// <param name="user">The account to convert.</param>
+    /// <param name="fileStorageProvider">
+    ///     Signs the download URL for the account's avatar. <c>Photo.Hyperlink</c> holds an object key
+    ///     rather than a URL, so it has to be signed before a client can fetch it.
+    /// </param>
+    public static PublicUserProfileDto ToPublicProfileDto(
+        this UserAccount user,
+        IFileStorageProvider fileStorageProvider
+    )
     {
+        string? avatarKey = user.UserAvatar?.Photo?.Hyperlink;
+
         return new PublicUserProfileDto(
             UserAccountId : user.UserAccountId,
             Username : user.Username,
             FirstName : user.FirstName,
             LastName : user.LastName,
             Biography : user.UserProfile?.Biography ?? string.Empty,
+            AvatarUrl : string.IsNullOrWhiteSpace(avatarKey)
+                ? string.Empty
+                : fileStorageProvider.GetPresignedUrl(avatarKey, AvatarUrlLifetime),
             CreatedAt : user.CreatedAt
         );
     }

web/backend/Features/Features.Users/Dtos/UserDtos.cs

@@ -7,5 +7,6 @@ public record PublicUserProfileDto(
     string FirstName,
     string LastName,
     string Biography,
+    string AvatarUrl,
     DateTime CreatedAt
 );

web/backend/Features/Features.Users/Queries/GetAllUsers/GetAllUsersHandler.cs

@@ -1,12 +1,15 @@
 using Domain.Entities;
+using Features.ImageUploads.Services;
 using Features.Users.Dtos;
 using Features.Users.Repository;
 using MediatR;
 
 namespace Features.Users.Queries.GetAllUsers;
 
-public class GetAllUsersHandler(IUserListRepository repository)
-    : IRequestHandler<GetAllUsersQuery, IEnumerable<PublicUserProfileDto>>
+public class GetAllUsersHandler(
+    IUserListRepository repository,
+    IFileStorageProvider fileStorageProvider
+) : IRequestHandler<GetAllUsersQuery, IEnumerable<PublicUserProfileDto>>
 {
     public async Task<IEnumerable<PublicUserProfileDto>> Handle(
         GetAllUsersQuery request,
@@ -14,6 +17,6 @@ public class GetAllUsersHandler(IUserListRepository repository)
     )
     {
         IEnumerable<UserAccount> users = await repository.GetAllAsync(request.Limit, request.Offset);
-        return users.Select(user => user.ToPublicProfileDto());
+        return users.Select(user => user.ToPublicProfileDto(fileStorageProvider));
     }
 }

web/backend/Features/Features.Users/Queries/GetPublicUserProfileById/GetPublicUserProfileByIdHandler.cs

@@ -1,13 +1,16 @@
 using Domain.Entities;
 using Domain.Exceptions;
+using Features.ImageUploads.Services;
 using Features.Users.Dtos;
 using Features.Users.Repository;
 using MediatR;
 
 namespace Features.Users.Queries.GetPublicUserProfileById;
 
-public class GetPublicUserProfileByIdHandler(IUserListRepository repository)
-    : IRequestHandler<GetPublicUserProfileByIdQuery, PublicUserProfileDto>
+public class GetPublicUserProfileByIdHandler(
+    IUserListRepository repository,
+    IFileStorageProvider fileStorageProvider
+) : IRequestHandler<GetPublicUserProfileByIdQuery, PublicUserProfileDto>
 {
     /// <exception cref="NotFoundException">Thrown when no user account exists with the given ID.</exception>
     public async Task<PublicUserProfileDto> Handle(
@@ -18,6 +21,6 @@ public class GetPublicUserProfileByIdHandler(IUserListRepository repository)
         UserAccount? user = await repository.GetByIdAsync(request.UserAccountId);
         if (user is null)
             throw new NotFoundException($"User with ID {request.UserAccountId} not found");
-        return user.ToPublicProfileDto();
+        return user.ToPublicProfileDto(fileStorageProvider);
     }
 }

web/backend/Features/Features.Users/Repository/UserListRepository.cs

@@ -15,7 +15,10 @@ public class UserListRepository(ISqlConnectionFactory connectionFactory)
     /// <inheritdoc />
     /// <remarks>
     ///     Left-joins <c>Social.UserProfile</c>, so <see cref="UserAccount.UserProfile" /> is
-    ///     <c>null</c> for an account whose profile has yet to be created.
+    ///     <c>null</c> for an account whose profile has yet to be created, and left-joins the
+    ///     account's active <c>Social.UserAvatar</c> (<c>ValidTo IS NULL</c>) with its
+    ///     <c>Media.Photo</c>, so <see cref="UserAccount.UserAvatar" /> is <c>null</c> for an account
+    ///     with no avatar.
     /// </remarks>
     public async Task<UserAccount?> GetByIdAsync(Guid id)
     {
@@ -23,51 +26,89 @@ public class UserListRepository(ISqlConnectionFactory connectionFactory)
         IEnumerable<UserAccount> results = await connection.QueryAsync<
             UserAccount,
             UserProfile,
+            Photo,
+            UserAvatar,
             UserAccount
         >(
             """
             SELECT 
-                ua.UserAccountID, 
-                ua.Username, 
-                ua.FirstName, ua.LastName, ua.Email, ua.CreatedAt, ua.UpdatedAt,
-                ua.DateOfBirth, ua.RowVersion,
-                up.UserProfileID, up.UserAccountID, up.Biography, up.RowVersion
+                ua.UserAccountID, ua.Username, ua.FirstName, ua.LastName,
+                ua.Email, ua.CreatedAt, ua.UpdatedAt, ua.DateOfBirth,
+                ua.RowVersion, up.UserProfileID, up.UserAccountID,
+                up.Biography, up.RowVersion, p.PhotoID, p.UploadedByID, 
+                p.Hyperlink, p.UploadedAt, p.RowVersion, av.UserAvatarID, 
+                av.UserProfileID, av.PhotoID, av.ValidFrom, av.ValidTo,
+                av.RowVersion
             FROM Auth.UserAccount ua
-            LEFT JOIN Social.UserProfile up ON ua.UserAccountID = up.UserAccountID
+            LEFT JOIN Social.UserProfile up 
+                ON ua.UserAccountID = up.UserAccountID
+            LEFT JOIN Social.UserAvatar av
+                ON up.UserProfileID = av.UserProfileID 
+                       AND av.ValidTo IS NULL
+            LEFT JOIN Media.Photo p ON av.PhotoID = p.PhotoID
             WHERE ua.UserAccountID = @UserAccountId
             """,
             MapUserRow,
             new { UserAccountId = id },
-            splitOn: "UserProfileID"
+            splitOn: AvatarSplitOn
         );
 
         return results.SingleOrDefault();
     }
 
-    private static UserAccount MapUserRow(UserAccount user, UserProfile? profile)
-    {
-        user.UserProfile = profile;
-        return user;
-    }
-
     /// <inheritdoc />
     /// <remarks>
     ///     Always applies pagination via <c>OFFSET</c>/<c>FETCH</c>, ordered by creation date descending.
     ///     A <c>null</c> <paramref name="limit" />/<paramref name="offset" /> is treated as "no limit"/"no offset".
-    ///     Does not select <c>Email</c> or <c>DateOfBirth</c>: this listing is consumed only as public
-    ///     profiles, so those fields are left at their default rather than read from the database.
+    ///     Joins the same profile and active-avatar rows as <see cref="GetByIdAsync" />, both of which are
+    ///     part of a public profile. Does not select <c>Email</c> or <c>DateOfBirth</c>: this listing is
+    ///     consumed only as public profiles, so those fields are left at their default rather than read
+    ///     from the database.
     /// </remarks>
     public async Task<IEnumerable<UserAccount>> GetAllAsync(int? limit, int? offset)
     {
         await using DbConnection connection = await CreateConnection();
-        return await connection.QueryAsync<UserAccount>(
+        return await connection.QueryAsync<
+            UserAccount,
+            UserProfile,
+            Photo,
+            UserAvatar,
+            UserAccount
+        >(
             """
-            SELECT UserAccountID, Username, FirstName, LastName, CreatedAt, UpdatedAt, RowVersion
-            FROM Auth.UserAccount
-            ORDER BY CreatedAt DESC
+            SELECT
+                ua.UserAccountID, ua.Username, ua.FirstName, ua.LastName,
+                ua.CreatedAt, ua.UpdatedAt, ua.RowVersion,
+                up.UserProfileID, up.UserAccountID, up.Biography, up.RowVersion,
+                p.PhotoID, p.UploadedByID, p.Hyperlink, p.UploadedAt, p.RowVersion,
+                av.UserAvatarID, av.UserProfileID, av.PhotoID, av.ValidFrom, av.ValidTo,
+                av.RowVersion
+            FROM Auth.UserAccount ua
+            LEFT JOIN Social.UserProfile up ON ua.UserAccountID = up.UserAccountID
+            LEFT JOIN Social.UserAvatar av
+                ON up.UserProfileID = av.UserProfileID AND av.ValidTo IS NULL
+            LEFT JOIN Media.Photo p ON av.PhotoID = p.PhotoID
+            ORDER BY ua.CreatedAt DESC
             OFFSET @Offset ROWS FETCH NEXT @Limit ROWS ONLY
             """,
-            new { Offset = offset ?? 0, Limit = limit ?? int.MaxValue }
+            MapUserRow,
+            new { Offset = offset ?? 0, Limit = limit ?? int.MaxValue },
+            splitOn: AvatarSplitOn
         );
     }
+
+    private const string AvatarSplitOn = "UserProfileID,PhotoID,UserAvatarID";
+
+    private static UserAccount MapUserRow(
+        UserAccount user,
+        UserProfile? profile,
+        Photo? photo,
+        UserAvatar? avatar
+    )
+    {
+        user.UserProfile = profile;
+        avatar?.Photo = photo;
+        user.UserAvatar = avatar;
+        return user;
+    }
 }

web/docker-compose.db.yaml

@@ -70,6 +70,7 @@ services:
       DB_USER: "${DB_USER}"
       DB_PASSWORD: "${DB_PASSWORD}"
       SEAWEEDFS_SERVICE_URL: "${SEAWEEDFS_SERVICE_URL}"
+      SEAWEEDFS_PUBLIC_URL: "${SEAWEEDFS_PUBLIC_URL}"
       SEAWEEDFS_ACCESS_KEY_ID: "${SEAWEEDFS_ACCESS_KEY_ID}"
       SEAWEEDFS_SECRET_ACCESS_KEY: "${SEAWEEDFS_SECRET_ACCESS_KEY}"
       SEAWEEDFS_BUCKET: "${SEAWEEDFS_BUCKET}"

web/docker-compose.dev.yaml

@@ -72,6 +72,7 @@ services:
       DB_USER: "${DB_USER}"
       DB_PASSWORD: "${DB_PASSWORD}"
       SEAWEEDFS_SERVICE_URL: "${SEAWEEDFS_SERVICE_URL}"
+      SEAWEEDFS_PUBLIC_URL: "${SEAWEEDFS_PUBLIC_URL}"
       SEAWEEDFS_ACCESS_KEY_ID: "${SEAWEEDFS_ACCESS_KEY_ID}"
       SEAWEEDFS_SECRET_ACCESS_KEY: "${SEAWEEDFS_SECRET_ACCESS_KEY}"
       SEAWEEDFS_BUCKET: "${SEAWEEDFS_BUCKET}"
@@ -110,6 +111,7 @@ services:
       CONFIRMATION_TOKEN_SECRET: "${CONFIRMATION_TOKEN_SECRET}"
       WEBSITE_BASE_URL: "${WEBSITE_BASE_URL}"
       SEAWEEDFS_SERVICE_URL: "${SEAWEEDFS_SERVICE_URL}"
+      SEAWEEDFS_PUBLIC_URL: "${SEAWEEDFS_PUBLIC_URL}"
       SEAWEEDFS_ACCESS_KEY_ID: "${SEAWEEDFS_ACCESS_KEY_ID}"
       SEAWEEDFS_SECRET_ACCESS_KEY: "${SEAWEEDFS_SECRET_ACCESS_KEY}"
       SEAWEEDFS_BUCKET: "${SEAWEEDFS_BUCKET}"

web/docker-compose.min.yaml

@@ -84,6 +84,7 @@ services:
       DB_USER: "${DB_USER}"
       DB_PASSWORD: "${DB_PASSWORD}"
       SEAWEEDFS_SERVICE_URL: "${SEAWEEDFS_SERVICE_URL}"
+      SEAWEEDFS_PUBLIC_URL: "${SEAWEEDFS_PUBLIC_URL}"
       SEAWEEDFS_ACCESS_KEY_ID: "${SEAWEEDFS_ACCESS_KEY_ID}"
       SEAWEEDFS_SECRET_ACCESS_KEY: "${SEAWEEDFS_SECRET_ACCESS_KEY}"
       SEAWEEDFS_BUCKET: "${SEAWEEDFS_BUCKET}"

web/docker-compose.prod.seed.yaml

@@ -19,6 +19,7 @@ services:
       DB_USER: "${DB_USER}"
       DB_PASSWORD: "${DB_PASSWORD}"
       SEAWEEDFS_SERVICE_URL: "${SEAWEEDFS_SERVICE_URL}"
+      SEAWEEDFS_PUBLIC_URL: "${SEAWEEDFS_PUBLIC_URL}"
       SEAWEEDFS_ACCESS_KEY_ID: "${SEAWEEDFS_ACCESS_KEY_ID}"
       SEAWEEDFS_SECRET_ACCESS_KEY: "${SEAWEEDFS_SECRET_ACCESS_KEY}"
       SEAWEEDFS_BUCKET: "${SEAWEEDFS_BUCKET}"

web/docker-compose.prod.yaml

@@ -51,6 +51,7 @@ services:
       CONFIRMATION_TOKEN_SECRET: "${CONFIRMATION_TOKEN_SECRET}"
       WEBSITE_BASE_URL: "${WEBSITE_BASE_URL}"
       SEAWEEDFS_SERVICE_URL: "${SEAWEEDFS_SERVICE_URL}"
+      SEAWEEDFS_PUBLIC_URL: "${SEAWEEDFS_PUBLIC_URL}"
       SEAWEEDFS_ACCESS_KEY_ID: "${SEAWEEDFS_ACCESS_KEY_ID}"
       SEAWEEDFS_SECRET_ACCESS_KEY: "${SEAWEEDFS_SECRET_ACCESS_KEY}"
       SEAWEEDFS_BUCKET: "${SEAWEEDFS_BUCKET}"

web/docker-compose.test.yaml

@@ -70,6 +70,7 @@ services:
       DB_USER: "${DB_USER}"
       DB_PASSWORD: "${DB_PASSWORD}"
       SEAWEEDFS_SERVICE_URL: "${SEAWEEDFS_SERVICE_URL}"
+      SEAWEEDFS_PUBLIC_URL: "${SEAWEEDFS_PUBLIC_URL}"
       SEAWEEDFS_ACCESS_KEY_ID: "${SEAWEEDFS_ACCESS_KEY_ID}"
       SEAWEEDFS_SECRET_ACCESS_KEY: "${SEAWEEDFS_SECRET_ACCESS_KEY}"
       SEAWEEDFS_BUCKET: "${SEAWEEDFS_BUCKET}"

web/frontend/app/features/auth/components/AuthCardHeading.tsx

@@ -0,0 +1,13 @@
+interface AuthCardHeadingProps {
+    title: string;
+    subtitle: string;
+}
+
+const AuthCardHeading = ({ title, subtitle }: AuthCardHeadingProps) => (
+    <div className="flex flex-col gap-1.5">
+        <h1 className="text-[1.875rem]">{title}</h1>
+        <p className="text-[var(--color-muted)]">{subtitle}</p>
+    </div>
+);
+
+export default AuthCardHeading;

web/frontend/app/features/auth/components/AuthErrorAlert.tsx

@@ -0,0 +1,21 @@
+interface AuthErrorAlertProps {
+    message: string;
+    /** Per-field messages to list beneath the summary. */
+    details?: readonly string[];
+}
+
+const AuthErrorAlert = ({ message, details }: AuthErrorAlertProps) => (
+    <div role="alert" className="alert alert-error alert-soft flex-col items-start">
+        <span>{message}</span>
+
+        {details?.length ? (
+            <ul className="list-inside list-disc text-sm">
+                {details.map((detail) => (
+                    <li key={detail}>{detail}</li>
+                ))}
+            </ul>
+        ) : null}
+    </div>
+);
+
+export default AuthErrorAlert;

web/frontend/app/features/auth/components/AuthSplitLayout.stories.tsx

@@ -1,56 +1,59 @@
 import { zodResolver } from '@hookform/resolvers/zod';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useForm } from 'react-hook-form';
-import { expect, within } from 'storybook/test';
+import { expect, fireEvent, userEvent, within } from 'storybook/test';
+import AuthCardHeading from './AuthCardHeading';
+import AuthErrorAlert from './AuthErrorAlert';
 import AuthSplitLayout from './AuthSplitLayout';
 import AuthSwitchPrompt from './AuthSwitchPrompt';
 import LoginForm from './LoginForm';
 import RegisterForm from './RegisterForm';
-import { loginSchema, registerSchema, type LoginSchema, type RegisterSchema } from '../schemas';
+import RegisterStepProgress from './RegisterStepProgress';
+import { useRegisterWizard } from '../hooks/useRegisterWizard';
+import { loginSchema, type LoginSchema } from '../schemas';
 
-const authSplitLayoutDescription = `The shared split-screen shell behind /login and /register: a brand panel carrying the headline and a form panel that centers the page's own heading, form, and switch prompt. Both stories compose the real forms, so they show the production layout at any viewport.`;
+const noop = () => undefined;
 
-const LoginPanel = () => {
+const authSplitLayoutDescription = `The shared split-screen shell behind /login and /register: a full-bleed bar photo carrying the hero headline, and a solid card holding the page's own heading, form, and switch prompt. The grid splits 6fr/5fr from 820px up and stacks hero over card below it. Both stories compose the real forms, so they show the production layout at any viewport.`;
+
+const LoginPanel = ({ error }: { error?: string }) => {
     const form = useForm<LoginSchema>({ resolver: zodResolver(loginSchema) });
 
     return (
-        <div className="flex w-full max-w-[25rem] flex-col gap-4">
-            <div className="flex flex-col gap-1.5">
-                <h1 className="text-[2.125rem]">Sign in</h1>
-                <p className="text-[var(--color-muted)]">Sign in to your Biergarten account</p>
-            </div>
+        <>
+            <AuthCardHeading title="Sign in" subtitle="Sign in to your Biergarten account" />
+
+            {error ? <AuthErrorAlert message={error} /> : null}
 
             <LoginForm
-                onSubmit={form.handleSubmit(() => {})}
+                onSubmit={form.handleSubmit(noop)}
                 formState={form.formState}
                 register={form.register}
                 submitting={false}
             />
 
             <AuthSwitchPrompt lead="New to Biergarten?" to="/register" label="Create an account" />
-        </div>
+        </>
     );
 };
 
 const RegisterPanel = () => {
-    const form = useForm<RegisterSchema>({ resolver: zodResolver(registerSchema) });
+    const wizard = useRegisterWizard(noop);
 
     return (
-        <div className="flex w-full max-w-[32.5rem] flex-col gap-4">
-            <div className="flex flex-col gap-1.5">
-                <h1 className="text-[2.125rem]">Create your account</h1>
-                <p className="text-[var(--color-muted)]">Create your Biergarten account</p>
-            </div>
-
-            <RegisterForm
-                onSubmit={form.handleSubmit(() => {})}
-                formState={form.formState}
-                register={form.register}
-                submitting={false}
+        <>
+            <RegisterStepProgress
+                step={wizard.step}
+                totalSteps={wizard.totalSteps}
+                name={wizard.name}
             />
 
+            <AuthCardHeading title={wizard.title} subtitle={wizard.subtitle} />
+
+            <RegisterForm wizard={wizard} submitting={false} />
+
             <AuthSwitchPrompt lead="Already have an account?" to="/login" label="Sign in" />
-        </div>
+        </>
     );
 };
 
@@ -71,10 +74,19 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+const loginArgs = {
+    headline: 'Good to see you again.',
+    blurb: 'Sign in to pick up where you left off with our partner breweries.',
+};
+
+const registerArgs = {
+    headline: 'Pull up a chair.',
+    blurb: 'Create an account to explore partner breweries and their beers.',
+};
+
 export const Login: Story = {
     args: {
-        headline: 'Good to see you again.',
-        blurb: 'Sign in to pick up where you left off with our partner breweries.',
+        ...loginArgs,
         children: <LoginPanel />,
     },
     play: async ({ canvasElement }) => {
@@ -84,15 +96,47 @@ export const Login: Story = {
     },
 };
 
+export const LoginWithServerError: Story = {
+    args: {
+        ...loginArgs,
+        children: <LoginPanel error="Invalid username or password." />,
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('alert')).toHaveTextContent('Invalid username or password.');
+    },
+};
+
 export const Register: Story = {
     args: {
-        headline: 'Pull up a chair.',
-        blurb: 'Create an account to explore partner breweries and their beers.',
+        ...registerArgs,
         children: <RegisterPanel />,
     },
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await expect(canvas.getByLabelText(/date of birth/i)).toBeInTheDocument();
+        await expect(canvas.getByText(/step 1 of 3 · account/i)).toBeInTheDocument();
+        await expect(canvas.getByRole('button', { name: /continue/i })).toBeInTheDocument();
+    },
+};
+
+export const RegisterFinalStep: Story = {
+    args: Register.args,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.type(canvas.getByLabelText(/^username$/i), 'jane_doe');
+        await userEvent.type(canvas.getByLabelText(/^email$/i), 'jane@example.com');
+        await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
+
+        await userEvent.type(await canvas.findByLabelText(/first name/i), 'Jane');
+        await userEvent.type(canvas.getByLabelText(/last name/i), 'Doe');
+        await fireEvent.change(canvas.getByLabelText(/date of birth/i), {
+            target: { value: '2000-01-15' },
+        });
+        await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
+
+        await expect(
+            await canvas.findByRole('heading', { name: 'Secure your account' }),
+        ).toBeInTheDocument();
         await expect(canvas.getByRole('button', { name: /create account/i })).toBeInTheDocument();
     },
 };

web/frontend/app/features/auth/components/AuthSplitLayout.tsx

@@ -1,3 +1,5 @@
+import barBackground from '../../../assets/bar-background.jpg';
+
 interface AuthSplitLayoutProps {
     headline: string;
     blurb: string;
@@ -5,15 +7,32 @@ interface AuthSplitLayoutProps {
 }
 
 const AuthSplitLayout = ({ headline, blurb, children }: AuthSplitLayoutProps) => (
-    <div className="grid flex-1 grid-cols-1 bg-base-200 lg:grid-cols-[minmax(0,5fr)_minmax(0,6fr)]">
-        <aside className="flex flex-col justify-end gap-5 bg-secondary px-5 py-7 text-secondary-content lg:px-14 lg:py-12">
-            <h2 className="text-3xl leading-[1.15] text-balance lg:text-[2.75rem]">{headline}</h2>
-            <p className="max-w-[23.75rem] text-base leading-relaxed lg:text-lg">{blurb}</p>
-        </aside>
+    <div className="relative flex flex-1 bg-base-200">
+        <div
+            className="absolute inset-0 bg-base-300 bg-cover bg-center"
+            style={{ backgroundImage: `url(${barBackground})` }}
+        />
 
-        <main className="flex items-start justify-center px-5 pt-7 pb-10 lg:items-center lg:px-6 lg:py-10">
-            {children}
-        </main>
+        {/* Darkens the photo from the bottom up so the white hero text stays legible */}
+        <div className="pointer-events-none absolute inset-0 bg-[linear-gradient(0deg,#000000b3_30%,#ffffff44_100%)]" />
+
+        <div className="relative mx-auto grid w-full max-w-7xl grid-cols-1 content-between gap-6 min-[820px]:grid-cols-[minmax(0,6fr)_minmax(0,5fr)]">
+            <section className="flex flex-col justify-end gap-4 px-5 pt-8 pb-2 text-white min-[820px]:px-10 min-[820px]:py-14">
+                <h2 className="text-[2rem] leading-[1.1] text-balance [text-shadow:0_2px_24px_#0006] min-[820px]:text-[3.25rem]">
+                    {headline}
+                </h2>
+
+                <p className="max-w-[27.5rem] text-base leading-[1.5] min-[820px]:text-[1.1875rem]">
+                    {blurb}
+                </p>
+            </section>
+
+            <main className="flex items-center justify-center px-4 pt-4 pb-7 min-[820px]:py-10 min-[820px]:pr-10 min-[820px]:pl-0">
+                <div className="flex w-full max-w-[27.5rem] flex-col gap-4 rounded-box bg-base-100 px-5 py-6 shadow-[0_20px_50px_#0005] min-[820px]:p-8">
+                    {children}
+                </div>
+            </main>
+        </div>
     </div>
 );
 

web/frontend/app/features/auth/components/RegisterForm.stories.tsx

@@ -1,25 +1,30 @@
-import { zodResolver } from '@hookform/resolvers/zod';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
-import { useForm } from 'react-hook-form';
 import { expect, fireEvent, userEvent, within } from 'storybook/test';
+import AuthCardHeading from './AuthCardHeading';
 import RegisterForm from './RegisterForm';
-import { registerSchema, type RegisterSchema } from '../schemas';
+import RegisterStepProgress from './RegisterStepProgress';
+import { useRegisterWizard } from '../hooks/useRegisterWizard';
+import { type RegisterSchema } from '../schemas';
 
-const registerFormDescription = `Renders the real \`RegisterForm\` component wired to the real \`registerSchema\` (zod) through the same react-hook-form setup used on the register page, including its cross-field rule that the confirmation must match the password, so these stories validate actual client-side validation behavior rather than a re-implemented form.`;
+const registerFormDescription = `Renders the real \`RegisterForm\` driven by the real \`useRegisterWizard\` hook, so these stories exercise the production three-step flow: each step validates its own fields through \`registerSchema\` (zod) before the next one opens, entered values survive going back, and only the final step submits.`;
 
 const RegisterFormHarness = () => {
     const [submitted, setSubmitted] = useState<RegisterSchema | null>(null);
-    const form = useForm<RegisterSchema>({ resolver: zodResolver(registerSchema) });
+    const wizard = useRegisterWizard(setSubmitted);
 
     return (
-        <div className="w-full max-w-lg space-y-3 rounded-box bg-base-100 p-6 shadow-lg">
-            <RegisterForm
-                onSubmit={form.handleSubmit((values) => setSubmitted(values))}
-                formState={form.formState}
-                register={form.register}
-                submitting={false}
+        <div className="flex w-full max-w-md flex-col gap-4 rounded-box bg-base-100 p-6 shadow-lg">
+            <RegisterStepProgress
+                step={wizard.step}
+                totalSteps={wizard.totalSteps}
+                name={wizard.name}
             />
+
+            <AuthCardHeading title={wizard.title} subtitle={wizard.subtitle} />
+
+            <RegisterForm wizard={wizard} submitting={false} />
+
             {submitted ? <p data-testid="submit-result">Registered {submitted.username}</p> : null}
         </div>
     );
@@ -42,75 +47,120 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Empty: Story = {};
+type Canvas = ReturnType<typeof within>;
 
-const fillValidRegistration = async (canvas: ReturnType<typeof within>) => {
+const adultDateOfBirth = '2000-01-15';
+
+const underageDateOfBirth = () => {
+    const tenYearsAgo = new Date();
+    tenYearsAgo.setFullYear(tenYearsAgo.getFullYear() - 10);
+    return tenYearsAgo.toISOString().slice(0, 10);
+};
+
+const completeAccountStep = async (canvas: Canvas) => {
     await userEvent.type(canvas.getByLabelText(/^username$/i), 'jane_doe');
+    await userEvent.type(canvas.getByLabelText(/^email$/i), 'jane@example.com');
+    await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
+    await canvas.findByLabelText(/first name/i);
+};
+
+const completeDetailsStep = async (canvas: Canvas, dateOfBirth = adultDateOfBirth) => {
     await userEvent.type(canvas.getByLabelText(/first name/i), 'Jane');
     await userEvent.type(canvas.getByLabelText(/last name/i), 'Doe');
-    await userEvent.type(canvas.getByLabelText(/^email$/i), 'jane@example.com');
     await fireEvent.change(canvas.getByLabelText(/date of birth/i), {
-        target: { value: '2000-01-15' },
+        target: { value: dateOfBirth },
     });
-    await userEvent.type(canvas.getByLabelText('Password'), 'StrongPass1!');
-    await userEvent.type(canvas.getByLabelText(/confirm password/i), 'StrongPass1!');
+    await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
 };
 
-export const RejectsEmptySubmission: Story = {
+export const Empty: Story = {};
+
+export const BlocksAdvanceOnInvalidAccount: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
+        await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
         await expect(
-            canvas.getByText(/username must be at least 3 characters/i),
+            await canvas.findByText(/username must be at least 3 characters/i),
         ).toBeInTheDocument();
-        await expect(canvas.getByText(/first name is required/i)).toBeInTheDocument();
-        await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
-    },
-};
-
-export const RejectsInvalidEmail: Story = {
-    play: async ({ canvasElement }) => {
-        const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
-        await userEvent.clear(canvas.getByLabelText(/^email$/i));
-        await userEvent.type(canvas.getByLabelText(/^email$/i), 'jane@example');
-        await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
         await expect(canvas.getByText(/invalid email address/i)).toBeInTheDocument();
-        await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
+        await expect(canvas.getByText(/step 1 of 3/i)).toBeInTheDocument();
     },
 };
 
-export const RejectsWeakPassword: Story = {
+export const ClearsFieldErrorOnEdit: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
-        await userEvent.clear(canvas.getByLabelText('Password'));
-        await userEvent.type(canvas.getByLabelText('Password'), 'weakpassword');
-        await userEvent.clear(canvas.getByLabelText(/confirm password/i));
-        await userEvent.type(canvas.getByLabelText(/confirm password/i), 'weakpassword');
-        await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
-        await expect(canvas.getByText(/uppercase letter/i)).toBeInTheDocument();
-        await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
+        await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
+        await canvas.findByText(/username must be at least 3 characters/i);
+
+        await userEvent.type(canvas.getByLabelText(/^username$/i), 'jane_doe');
+        await expect(
+            canvas.queryByText(/username must be at least 3 characters/i),
+        ).not.toBeInTheDocument();
+    },
+};
+
+export const AdvancesToPersonalDetails: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await expect(canvas.getByRole('heading', { name: 'About you' })).toBeInTheDocument();
+        await expect(canvas.getByText(/step 2 of 3 · personal details/i)).toBeInTheDocument();
+    },
+};
+
+export const KeepsValuesWhenGoingBack: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await userEvent.click(canvas.getByRole('button', { name: /back/i }));
+        await expect(await canvas.findByLabelText(/^username$/i)).toHaveValue('jane_doe');
+        await expect(canvas.getByLabelText(/^email$/i)).toHaveValue('jane@example.com');
+    },
+};
+
+export const RejectsUnderageDateOfBirth: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas, underageDateOfBirth());
+        await expect(await canvas.findByText(/at least 19 years old/i)).toBeInTheDocument();
+        await expect(canvas.getByText(/step 2 of 3/i)).toBeInTheDocument();
     },
 };
 
 export const RejectsMismatchedConfirmPassword: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
-        await userEvent.clear(canvas.getByLabelText(/confirm password/i));
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas);
+        await userEvent.type(await canvas.findByLabelText('Password'), 'StrongPass1!');
         await userEvent.type(canvas.getByLabelText(/confirm password/i), 'Different1!');
         await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
-        await expect(canvas.getByText(/passwords must match/i)).toBeInTheDocument();
+        await expect(await canvas.findByText(/passwords must match/i)).toBeInTheDocument();
         await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
     },
 };
 
+export const RevealsBothPasswords: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas);
+        await userEvent.click(await canvas.findByRole('button', { name: /show password/i }));
+        await expect(canvas.getByLabelText('Password')).toHaveAttribute('type', 'text');
+        await expect(canvas.getByLabelText(/confirm password/i)).toHaveAttribute('type', 'text');
+    },
+};
+
 export const AcceptsValidRegistration: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas);
+        await userEvent.type(await canvas.findByLabelText('Password'), 'StrongPass1!');
+        await userEvent.type(canvas.getByLabelText(/confirm password/i), 'StrongPass1!');
         await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
-        await expect(canvas.getByTestId('submit-result')).toHaveTextContent('jane_doe');
+        await expect(await canvas.findByTestId('submit-result')).toHaveTextContent('jane_doe');
     },
 };

web/frontend/app/features/auth/components/RegisterForm.tsx

@@ -1,100 +1,127 @@
-import { BaseSyntheticEvent, useState } from 'react';
-import { FormState, UseFormRegister } from 'react-hook-form';
+import { Button } from '@headlessui/react';
+import { useState } from 'react';
 import FormField from '../../../components/ui/forms/FormField';
 import SubmitButton from '../../../components/ui/forms/SubmitButton';
-import type { RegisterSchema } from '../schemas';
+import type { RegisterWizard } from '../hooks/useRegisterWizard';
+import { minimumAgeYears } from '../schemas';
 import ShowPasswordToggle from './ShowPasswordToggle';
 
 interface RegisterFormProps {
-    onSubmit: (e?: BaseSyntheticEvent) => Promise<Awaited<void> | undefined>;
-    formState: FormState<RegisterSchema>;
-    register: UseFormRegister<RegisterSchema>;
+    wizard: RegisterWizard;
     submitting: boolean;
 }
 
-const RegisterForm = (props: RegisterFormProps) => {
+const RegisterForm = ({ wizard, submitting }: RegisterFormProps) => {
     const [showPassword, setShowPassword] = useState(false);
+    const { step, isLastStep, canGoBack, register, formState } = wizard;
+    const { errors } = formState;
 
     return (
-        <form onSubmit={props.onSubmit} className="flex flex-col gap-4">
-            <div className="grid grid-cols-1 gap-3.5 min-[420px]:grid-cols-2">
-                <FormField
-                    id="firstName"
-                    type="text"
-                    autoComplete="given-name"
-                    label="First name"
-                    error={props.formState.errors.firstName?.message}
-                    {...props.register('firstName')}
-                />
+        <form onSubmit={wizard.onSubmit} className="flex flex-col gap-4" noValidate>
+            {step === 1 && (
+                <div className="flex flex-col gap-4">
+                    <FormField
+                        id="username"
+                        type="text"
+                        autoComplete="username"
+                        label="Username"
+                        hint="3-64 characters, alphanumeric and . _ -"
+                        error={errors.username?.message}
+                        {...register('username')}
+                    />
 
-                <FormField
-                    id="lastName"
-                    type="text"
-                    autoComplete="family-name"
-                    label="Last name"
-                    error={props.formState.errors.lastName?.message}
-                    {...props.register('lastName')}
-                />
+                    <FormField
+                        id="email"
+                        type="email"
+                        autoComplete="email"
+                        label="Email"
+                        error={errors.email?.message}
+                        {...register('email')}
+                    />
+                </div>
+            )}
+
+            {step === 2 && (
+                <div className="flex flex-col gap-4">
+                    <div className="grid grid-cols-1 gap-3.5 min-[420px]:grid-cols-2">
+                        <FormField
+                            id="firstName"
+                            type="text"
+                            autoComplete="given-name"
+                            label="First name"
+                            error={errors.firstName?.message}
+                            {...register('firstName')}
+                        />
+
+                        <FormField
+                            id="lastName"
+                            type="text"
+                            autoComplete="family-name"
+                            label="Last name"
+                            error={errors.lastName?.message}
+                            {...register('lastName')}
+                        />
+                    </div>
+
+                    <FormField
+                        id="dateOfBirth"
+                        type="date"
+                        label="Date of birth"
+                        hint={`Must be ${minimumAgeYears} years or older.`}
+                        error={errors.dateOfBirth?.message}
+                        {...register('dateOfBirth')}
+                    />
+                </div>
+            )}
+
+            {step === 3 && (
+                <div className="flex flex-col gap-4">
+                    <FormField
+                        id="password"
+                        type={showPassword ? 'text' : 'password'}
+                        autoComplete="new-password"
+                        label="Password"
+                        hint="8+ chars: uppercase, lowercase, digit, special character"
+                        error={errors.password?.message}
+                        {...register('password')}
+                    />
+
+                    <FormField
+                        id="confirmPassword"
+                        type={showPassword ? 'text' : 'password'}
+                        autoComplete="new-password"
+                        label="Confirm password"
+                        error={errors.confirmPassword?.message}
+                        {...register('confirmPassword')}
+                    />
+
+                    <ShowPasswordToggle
+                        shown={showPassword}
+                        onToggle={() => setShowPassword((shown) => !shown)}
+                    />
+                </div>
+            )}
+
+            <div className="flex gap-3">
+                {canGoBack && (
+                    <Button
+                        type="button"
+                        onClick={wizard.back}
+                        className="btn btn-outline min-h-12"
+                    >
+                        Back
+                    </Button>
+                )}
+
+                <div className="flex-1">
+                    <SubmitButton
+                        isSubmitting={submitting}
+                        idleText={isLastStep ? 'Create account' : 'Continue'}
+                        submittingText="Creating account…"
+                        className="btn btn-primary min-h-12 w-full"
+                    />
+                </div>
             </div>
-
-            <FormField
-                id="username"
-                type="text"
-                autoComplete="username"
-                label="Username"
-                hint="3-64 characters, alphanumeric and . _ -"
-                error={props.formState.errors.username?.message}
-                {...props.register('username')}
-            />
-
-            <FormField
-                id="email"
-                type="email"
-                autoComplete="email"
-                label="Email"
-                error={props.formState.errors.email?.message}
-                {...props.register('email')}
-            />
-
-            <FormField
-                id="dateOfBirth"
-                type="date"
-                label="Date of birth"
-                hint="Must be 19 years or older."
-                error={props.formState.errors.dateOfBirth?.message}
-                {...props.register('dateOfBirth')}
-            />
-
-            <FormField
-                id="password"
-                type={showPassword ? 'text' : 'password'}
-                autoComplete="new-password"
-                label="Password"
-                hint="8+ chars: uppercase, lowercase, digit, special character"
-                error={props.formState.errors.password?.message}
-                {...props.register('password')}
-            />
-
-            <FormField
-                id="confirmPassword"
-                type={showPassword ? 'text' : 'password'}
-                autoComplete="new-password"
-                label="Confirm password"
-                error={props.formState.errors.confirmPassword?.message}
-                {...props.register('confirmPassword')}
-            />
-
-            <ShowPasswordToggle
-                shown={showPassword}
-                onToggle={() => setShowPassword((shown) => !shown)}
-            />
-
-            <SubmitButton
-                isSubmitting={props.submitting}
-                idleText="Create account"
-                submittingText="Creating account…"
-                className="btn btn-primary min-h-12 w-full"
-            />
         </form>
     );
 };

web/frontend/app/features/auth/components/RegisterStepProgress.tsx

@@ -0,0 +1,24 @@
+interface RegisterStepProgressProps {
+    step: number;
+    totalSteps: number;
+    name: string;
+}
+
+const RegisterStepProgress = ({ step, totalSteps, name }: RegisterStepProgressProps) => (
+    <div className="flex flex-col gap-2">
+        <div className="flex gap-1.5" aria-hidden="true">
+            {Array.from({ length: totalSteps }, (_, index) => (
+                <div
+                    key={index}
+                    className={`h-1 flex-1 rounded ${index < step ? 'bg-primary' : 'bg-base-300'}`}
+                />
+            ))}
+        </div>
+
+        <p className="text-[0.8125rem] font-semibold text-[var(--color-muted)]">
+            Step {step} of {totalSteps} · {name}
+        </p>
+    </div>
+);
+
+export default RegisterStepProgress;

web/frontend/app/features/auth/hooks/useRegisterWizard.ts

@@ -0,0 +1,87 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useEffect, useRef, useState } from 'react';
+import { useForm, type FieldErrors, type Resolver } from 'react-hook-form';
+import { earliestStepForFields, lastRegisterStepIndex, registerSteps } from '../registerSteps';
+import { registerSchema, type RegisterSchema } from '../schemas';
+
+const resolveRegisterSchema = zodResolver(registerSchema);
+
+/**
+ * Drives the multi-step register form: one react-hook-form instance spans every
+ * step so values survive going back and forward, and each step validates its own
+ * fields before the next one opens.
+ */
+export const useRegisterWizard = (onValid: (values: RegisterSchema) => void) => {
+    const [stepIndex, setStepIndex] = useState(0);
+
+    const currentStep = registerSteps[stepIndex];
+    const isLastStep = stepIndex === lastRegisterStepIndex;
+
+    // Every step submits through `handleSubmit`, so each one has to report only its
+    // own fields: resolve the whole schema, then keep the errors this step owns. The
+    // last step keeps all of them, which is also what runs the password-match
+    // refinement across steps.
+    const resolver: Resolver<RegisterSchema> = async (values, context, options) => {
+        const result = await resolveRegisterSchema(values, context, options);
+        if (isLastStep) return result;
+
+        const errors = Object.fromEntries(
+            Object.entries(result.errors).filter(([name]) =>
+                currentStep.fields.includes(name as keyof RegisterSchema),
+            ),
+        ) as FieldErrors<RegisterSchema>;
+
+        return Object.keys(errors).length ? { values: {}, errors } : { values, errors: {} };
+    };
+
+    const { register, handleSubmit, formState, setFocus } = useForm<RegisterSchema>({
+        resolver,
+        mode: 'onTouched',
+    });
+
+    const onSubmit = handleSubmit(
+        (values) => {
+            if (isLastStep) {
+                onValid(values);
+                return;
+            }
+
+            setStepIndex((index) => index + 1);
+        },
+        // The last step validates fields from earlier steps too, so open whichever
+        // step owns the problem rather than reporting it out of sight.
+        (errors: FieldErrors<RegisterSchema>) => {
+            const step = earliestStepForFields(Object.keys(errors) as (keyof RegisterSchema)[]);
+            if (step !== null) setStepIndex(step);
+        },
+    );
+
+    // Move focus into each new step, which otherwise swaps out from under the
+    // keyboard while focus sits on the button that opened it.
+    const isInitialStep = useRef(true);
+    useEffect(() => {
+        if (isInitialStep.current) {
+            isInitialStep.current = false;
+            return;
+        }
+
+        const [firstField] = registerSteps[stepIndex].fields;
+        if (firstField) setFocus(firstField);
+    }, [stepIndex, setFocus]);
+
+    return {
+        step: stepIndex + 1,
+        totalSteps: registerSteps.length,
+        name: currentStep.name,
+        title: currentStep.title,
+        subtitle: currentStep.subtitle,
+        isLastStep,
+        canGoBack: stepIndex > 0,
+        back: () => setStepIndex((index) => Math.max(index - 1, 0)),
+        onSubmit,
+        register,
+        formState,
+    };
+};
+
+export type RegisterWizard = ReturnType<typeof useRegisterWizard>;

web/frontend/app/features/auth/registerSteps.ts

@@ -0,0 +1,49 @@
+import type { z } from 'zod';
+import { registerFields, type RegisterSchema } from './schemas';
+
+interface RegisterStep {
+    name: string;
+    title: string;
+    subtitle: string;
+    /** The slice of the register schema this step collects. */
+    schema: z.ZodObject;
+    fields: readonly (keyof RegisterSchema)[];
+}
+
+const defineStep = (step: Omit<RegisterStep, 'fields'>): RegisterStep => ({
+    ...step,
+    fields: Object.keys(step.schema.shape) as (keyof RegisterSchema)[],
+});
+
+export const registerSteps: readonly RegisterStep[] = [
+    defineStep({
+        name: 'Account',
+        title: 'Create your account',
+        subtitle: 'Choose how you will sign in.',
+        schema: registerFields.pick({ username: true, email: true }),
+    }),
+    defineStep({
+        name: 'Personal details',
+        title: 'About you',
+        subtitle: 'Tell us a little about yourself.',
+        schema: registerFields.pick({ firstName: true, lastName: true, dateOfBirth: true }),
+    }),
+    defineStep({
+        name: 'Password',
+        title: 'Secure your account',
+        subtitle: 'Pick a strong password.',
+        schema: registerFields.pick({ password: true, confirmPassword: true }),
+    }),
+];
+
+export const lastRegisterStepIndex = registerSteps.length - 1;
+
+/** The step a field belongs to, so an error can open the step that owns it. */
+export const stepIndexForField = (field: keyof RegisterSchema) =>
+    registerSteps.findIndex((step) => step.fields.includes(field));
+
+/** The earliest step owning any of `fields`, or `null` when none of them do. */
+export const earliestStepForFields = (fields: readonly (keyof RegisterSchema)[]) => {
+    const indexes = fields.map(stepIndexForField).filter((index) => index >= 0);
+    return indexes.length ? Math.min(...indexes) : null;
+};

web/frontend/app/features/auth/routes/login.tsx

@@ -2,6 +2,8 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { useForm } from 'react-hook-form';
 import { redirect, useNavigation, useSubmit } from 'react-router';
 import { createAuthSession, getOptionalAuth, login } from '../auth.server';
+import AuthCardHeading from '../components/AuthCardHeading';
+import AuthErrorAlert from '../components/AuthErrorAlert';
 import AuthSplitLayout from '../components/AuthSplitLayout';
 import AuthSwitchPrompt from '../components/AuthSwitchPrompt';
 import LoginForm from '../components/LoginForm';
@@ -58,31 +60,18 @@ const Login = ({ actionData }: Route.ComponentProps) => {
             headline="Good to see you again."
             blurb="Sign in to pick up where you left off with our partner breweries."
         >
-            <div className="flex w-full max-w-[25rem] flex-col gap-4">
-                <div className="flex flex-col gap-1.5">
-                    <h1 className="text-[2.125rem]">Sign in</h1>
-                    <p className="text-[var(--color-muted)]">Sign in to your Biergarten account</p>
-                </div>
+            <AuthCardHeading title="Sign in" subtitle="Sign in to your Biergarten account" />
 
-                {actionData?.error && (
-                    <div role="alert" className="alert alert-error alert-soft">
-                        <span>{actionData.error}</span>
-                    </div>
-                )}
+            {actionData?.error && <AuthErrorAlert message={actionData.error} />}
 
-                <LoginForm
-                    onSubmit={onSubmit}
-                    formState={formState}
-                    register={register}
-                    submitting={isSubmitting}
-                />
+            <LoginForm
+                onSubmit={onSubmit}
+                formState={formState}
+                register={register}
+                submitting={isSubmitting}
+            />
 
-                <AuthSwitchPrompt
-                    lead="New to Biergarten?"
-                    to="/register"
-                    label="Create an account"
-                />
-            </div>
+            <AuthSwitchPrompt lead="New to Biergarten?" to="/register" label="Create an account" />
         </AuthSplitLayout>
     );
 };

web/frontend/app/features/auth/routes/register.tsx

@@ -1,12 +1,15 @@
-import { zodResolver } from '@hookform/resolvers/zod';
-import { useForm } from 'react-hook-form';
 import { redirect, useNavigation, useSubmit } from 'react-router';
+import { z } from 'zod';
 import { createAuthSession, getOptionalAuth, register } from '../auth.server';
+import AuthCardHeading from '../components/AuthCardHeading';
+import AuthErrorAlert from '../components/AuthErrorAlert';
 import AuthSplitLayout from '../components/AuthSplitLayout';
 import AuthSwitchPrompt from '../components/AuthSwitchPrompt';
 import RegisterForm from '../components/RegisterForm';
+import RegisterStepProgress from '../components/RegisterStepProgress';
 import { useActionErrorToast } from '../hooks/useActionErrorToast';
-import { registerSchema, type RegisterSchema } from '../schemas';
+import { useRegisterWizard } from '../hooks/useRegisterWizard';
+import { registerSchema } from '../schemas';
 import type { Route } from './+types/register';
 
 export const meta = ({}: Route.MetaArgs) => {
@@ -21,33 +24,14 @@ export const loader = async ({ request }: Route.LoaderArgs) => {
 
 export const action = async ({ request }: Route.ActionArgs) => {
     const formData = await request.formData();
-    const result = registerSchema.safeParse({
-        username: formData.get('username'),
-        firstName: formData.get('firstName'),
-        lastName: formData.get('lastName'),
-        email: formData.get('email'),
-        dateOfBirth: formData.get('dateOfBirth'),
-        password: formData.get('password'),
-        confirmPassword: formData.get('confirmPassword'),
-    });
+    const result = registerSchema.safeParse(Object.fromEntries(formData));
 
     if (!result.success) {
-        const fieldErrors = result.error.flatten().fieldErrors as Record<
-            keyof RegisterSchema,
-            string[] | undefined
-        >;
-        return { error: null, fieldErrors };
+        return { error: null, fieldErrors: z.flattenError(result.error).fieldErrors };
     }
 
     try {
-        const body = {
-            username: result.data.username,
-            firstName: result.data.firstName,
-            lastName: result.data.lastName,
-            email: result.data.email,
-            dateOfBirth: result.data.dateOfBirth,
-            password: result.data.password,
-        };
+        const { confirmPassword: _confirmPassword, ...body } = result.data;
         const payload = await register(body);
         return createAuthSession(payload, '/dashboard');
     } catch (err) {
@@ -63,16 +47,16 @@ const Register = ({ actionData }: Route.ComponentProps) => {
     const submit = useSubmit();
     const isSubmitting = navigation.state === 'submitting';
 
-    const {
-        register: field,
-        handleSubmit,
-        formState,
-    } = useForm<RegisterSchema>({ resolver: zodResolver(registerSchema) });
-
-    const onSubmit = handleSubmit((data) => {
+    const wizard = useRegisterWizard((data) => {
         submit(data, { method: 'post' });
     });
 
+    // A request that reached the action without passing client validation, so the
+    // rejected fields may well sit on a step other than the one on screen.
+    const rejectedFields = Object.values(actionData?.fieldErrors ?? {}).flatMap(
+        (messages) => messages ?? [],
+    );
+
     useActionErrorToast(actionData?.error);
 
     return (
@@ -80,27 +64,26 @@ const Register = ({ actionData }: Route.ComponentProps) => {
             headline="Pull up a chair."
             blurb="Create an account to explore partner breweries and their beers."
         >
-            <div className="flex w-full max-w-[32.5rem] flex-col gap-4">
-                <div className="flex flex-col gap-1.5">
-                    <h1 className="text-[2.125rem]">Create your account</h1>
-                    <p className="text-[var(--color-muted)]">Create your Biergarten account</p>
-                </div>
+            <RegisterStepProgress
+                step={wizard.step}
+                totalSteps={wizard.totalSteps}
+                name={wizard.name}
+            />
 
-                {actionData?.error && (
-                    <div role="alert" className="alert alert-error alert-soft">
-                        <span>{actionData.error}</span>
-                    </div>
-                )}
+            <AuthCardHeading title={wizard.title} subtitle={wizard.subtitle} />
 
-                <RegisterForm
-                    onSubmit={onSubmit}
-                    formState={formState}
-                    register={field}
-                    submitting={isSubmitting}
+            {actionData?.error && <AuthErrorAlert message={actionData.error} />}
+
+            {rejectedFields.length > 0 && (
+                <AuthErrorAlert
+                    message="Check these details before creating your account."
+                    details={rejectedFields}
                 />
+            )}
 
-                <AuthSwitchPrompt lead="Already have an account?" to="/login" label="Sign in" />
-            </div>
+            <RegisterForm wizard={wizard} submitting={isSubmitting} />
+
+            <AuthSwitchPrompt lead="Already have an account?" to="/login" label="Sign in" />
         </AuthSplitLayout>
     );
 };

web/frontend/app/features/auth/schemas.ts

@@ -7,27 +7,53 @@ export const loginSchema = z.object({
 
 export type LoginSchema = z.infer<typeof loginSchema>;
 
-export const registerSchema = z
-    .object({
-        username: z
-            .string()
-            .min(3, 'Username must be at least 3 characters')
-            .max(20, 'Username must be at most 20 characters'),
-        firstName: z.string().min(1, 'First name is required'),
-        lastName: z.string().min(1, 'Last name is required'),
-        email: z.string().email('Invalid email address'),
-        dateOfBirth: z.string().min(1, 'Date of birth is required'),
-        password: z
-            .string()
-            .min(8, 'Password must be at least 8 characters')
-            .regex(/[A-Z]/, 'Password must contain an uppercase letter')
-            .regex(/[a-z]/, 'Password must contain a lowercase letter')
-            .regex(/[0-9]/, 'Password must contain a number'),
-        confirmPassword: z.string().min(1, 'Please confirm your password'),
-    })
-    .refine((data) => data.password === data.confirmPassword, {
+export const minimumAgeYears = 19;
+
+const isOldEnough = (value: string) => {
+    const dateOfBirth = new Date(value);
+    if (Number.isNaN(dateOfBirth.getTime())) return false;
+
+    const comingOfAge = new Date(
+        dateOfBirth.getFullYear() + minimumAgeYears,
+        dateOfBirth.getMonth(),
+        dateOfBirth.getDate(),
+    );
+
+    return comingOfAge <= new Date();
+};
+
+export const registerFields = z.object({
+    username: z
+        .string()
+        .min(3, 'Username must be at least 3 characters')
+        .max(64, 'Username must be at most 64 characters')
+        .regex(
+            /^[A-Za-z0-9._-]+$/,
+            'Username can only contain letters, numbers, dots, underscores and hyphens',
+        ),
+    firstName: z.string().min(1, 'First name is required'),
+    lastName: z.string().min(1, 'Last name is required'),
+    email: z.email('Invalid email address'),
+    dateOfBirth: z
+        .string()
+        .min(1, 'Date of birth is required')
+        .refine(isOldEnough, `You must be at least ${minimumAgeYears} years old to register`),
+    password: z
+        .string()
+        .min(8, 'Password must be at least 8 characters')
+        .regex(/[A-Z]/, 'Password must contain an uppercase letter')
+        .regex(/[a-z]/, 'Password must contain a lowercase letter')
+        .regex(/[0-9]/, 'Password must contain a number')
+        .regex(/[^A-Za-z0-9]/, 'Password must contain a special character'),
+    confirmPassword: z.string().min(1, 'Please confirm your password'),
+});
+
+export const registerSchema = registerFields.refine(
+    (data) => data.password === data.confirmPassword,
+    {
         message: 'Passwords must match',
         path: ['confirmPassword'],
-    });
+    },
+);
 
 export type RegisterSchema = z.infer<typeof registerSchema>;

web/frontend/app/features/home/components/HeroSection.tsx

@@ -1,5 +1,5 @@
 import { Link } from 'react-router';
-import barBackground from '../assets/bar-background.jpg';
+import barBackground from '../../../assets/bar-background.jpg';
 
 const HeroSection = () => (
     <section className="mx-auto max-w-7xl px-5 pt-18 pb-16">

web/frontend/app/features/users/USER_PROFILE_HANDOFF.md

@@ -6,21 +6,21 @@ Covers `/users/:id` (`routes/user-profile.tsx`). Mirrors the format of
 ## Status legend
 
 - ✅ **Available**: real data, wired up.
-- ⚠️ **Partial**: schema/repository exists but no public read endpoint.
+- ⚠️ **Partial**: reads real data, but a related gap remains (see the Gap column).
 - ❌ **Missing**: no backend support; page shows filler or local-only state.
 
 ## Header & sidebar
 
-| Field                                    | Status | Source                                                    | Gap                                                                                                                                                      |
-| ---------------------------------------- | ------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Username, name, joined date              | ✅     | `GET /api/user/{id}/profile` (`PublicUserProfileDto`)     |                                                                                                                                                          |
-| `isOwnProfile`                           | ✅     | Compares the session's `userAccountId` to the route param |                                                                                                                                                          |
-| Bio                                      | ✅     | `GET /api/user/{id}/profile` (`PublicUserProfileDto`)     | Reads `Social.UserProfile.Biography` via the left join in `UserListRepository.GetByIdAsync`; an account with no profile row yet returns an empty string. |
-| Location                                 | ❌     | `FILLER_PROFILE_META.location`                            | No location field on `UserAccount` or `UserProfile`.                                                                                                     |
-| Avatar photo                             | ⚠️     | Initials placeholder (`avatar-placeholder`)               | `Social.UserAvatar` + `UploadAvatarHandler` exist but there's no GET endpoint to read a user's stored avatar back.                                       |
-| Cover photo                              | ❌     | Flat `bg-base-300` block                                  | No cover-photo concept anywhere in the schema.                                                                                                           |
-| Following / Followers counts             | ❌     | `FILLER_PROFILE_META.following` / `.followers`            | `Social.UserFollow` table exists but is unused by any query/controller — needs count queries (`WHERE UserAccountID = ?` / `WHERE FollowingID = ?`).      |
-| Breweries visited / Ratings given counts | ❌     | `FILLER_PROFILE_META.breweriesVisited` / `.ratingsGiven`  | Blocked on the same like/rating gaps called out in `BREWERY_HANDOFF.md`.                                                                                 |
+| Field                                    | Status | Source                                                    | Gap                                                                                                                                                                                                  |
+| ---------------------------------------- | ------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Username, name, joined date              | ✅     | `GET /api/user/{id}/profile` (`PublicUserProfileDto`)     |                                                                                                                                                                                                      |
+| `isOwnProfile`                           | ✅     | Compares the session's `userAccountId` to the route param |                                                                                                                                                                                                      |
+| Bio                                      | ✅     | `GET /api/user/{id}/profile` (`PublicUserProfileDto`)     | Reads `Social.UserProfile.Biography` via the left join in `UserListRepository.GetByIdAsync`; an account with no profile row yet returns an empty string.                                             |
+| Location                                 | ❌     | `FILLER_PROFILE_META.location`                            | No location field on `UserAccount` or `UserProfile`.                                                                                                                                                 |
+| Avatar photo                             | ⚠️     | `GET /api/user/{id}/profile` (`PublicUserProfileDto`)     | Reads the current `Social.UserAvatar` photo via the left joins in `UserListRepository.GetByIdAsync` and signs it into `avatarUrl`; an account with no avatar returns an empty string and `ProfileAvatar` shows initials. `UploadAvatarCommand` has no HTTP route yet, so only accounts created by `Database.Seed` have one — see (4) below.                                                                       |
+| Cover photo                              | ❌     | Flat `bg-base-300` block                                  | No cover-photo concept anywhere in the schema.                                                                                                                                                       |
+| Following / Followers counts             | ❌     | `FILLER_PROFILE_META.following` / `.followers`            | `Social.UserFollow` table exists but is unused by any query/controller — needs count queries (`WHERE UserAccountID = ?` / `WHERE FollowingID = ?`).                                                  |
+| Breweries visited / Ratings given counts | ❌     | `FILLER_PROFILE_META.breweriesVisited` / `.ratingsGiven`  | Blocked on the same like/rating gaps called out in `BREWERY_HANDOFF.md`.                                                                                                                             |
 
 ## Follow action
 
@@ -36,7 +36,7 @@ Covers `/users/:id` (`routes/user-profile.tsx`). Mirrors the format of
 | Commenter name links (brewery detail comments) | ⚠️     | `CommentItem` links only when `comment.userAccountId` is set | `FILLER_COMMENTS` has no backing accounts, so those rows render as plain text; a comment added during the session by a signed-in user does carry a real GUID and links correctly. |
 | Following-list person links (profile page)     | ⚠️     | `FollowingTab` links only when `f.userAccountId` is set      | Same gap as above — `FILLER_FOLLOWING`'s two person rows have no backing accounts, so they render as plain text until real follow data exists.                                    |
 
-Both components already support linking (see `CommentItem.stories.tsx`'s `WithLinkedAccount` story); what's missing is real account IDs on the filler rows, which can't be faked without recreating the 404 this was fixed for. This resolves itself once (4) below closes and comments/follows are loader-backed.
+Both components already support linking (see `CommentItem.stories.tsx`'s `WithLinkedAccount` story); what's missing is real account IDs on the filler rows, which can't be faked without recreating the 404 this was fixed for. This resolves itself once (3) below closes and comments/follows are loader-backed.
 
 ## Activity / Following / Liked tabs
 
@@ -49,8 +49,8 @@ Both components already support linking (see `CommentItem.stories.tsx`'s `WithLi
 
 ## Summary of backend work
 
-1. A public query + controller route to read a user's stored `Social.UserAvatar`.
-2. A location field on `UserAccount` or `UserProfile`, and a cover-photo storage concept (mirrors the avatar gap).
-3. `Social.UserFollow` command/query/controller: follow, unfollow, "is following" check, and follower/following counts.
-4. An activity/timeline query unioning ratings, likes, and comments for a user, ordered by time — depends on the like/rating/comment tables called out in `BREWERY_HANDOFF.md` existing first.
-5. Once (3) and the like/rating gaps close, swap `FILLER_PROFILE_META` / `FILLER_ACTIVITY` / `FILLER_FOLLOWING` / `FILLER_LIKED` (`utils/filler-user-profile.ts`) and the local `useState` in `routes/user-profile.tsx` for loader data and `authorizedRequest`-based mutations (see `auth.server.ts`). Swapping in real (possibly empty) arrays is also what makes the Activity/Following `EmptyState`s reachable from the actual route — today they're only exercised by the `Empty` Storybook stories, since the filler arrays are never empty.
+1. A location field on `UserAccount` or `UserProfile`, and a cover-photo storage concept.
+2. `Social.UserFollow` command/query/controller: follow, unfollow, "is following" check, and follower/following counts.
+3. An activity/timeline query unioning ratings, likes, and comments for a user, ordered by time — depends on the like/rating/comment tables called out in `BREWERY_HANDOFF.md` existing first.
+4. An avatar-upload endpoint: `UploadAvatarCommand`/`UploadAvatarHandler` exist and `Database.Seed` sends them, but no controller action does, so a signed-in user has no way to set their own avatar. Needs a `multipart/form-data` route on the authenticated caller's own account (`IFormFile`, same validation the seeder's uploads pass through).
+5. Once (2) and the like/rating gaps close, swap `FILLER_PROFILE_META` / `FILLER_ACTIVITY` / `FILLER_FOLLOWING` / `FILLER_LIKED` (`utils/filler-user-profile.ts`) and the local `useState` in `routes/user-profile.tsx` for loader data and `authorizedRequest`-based mutations (see `auth.server.ts`). Swapping in real (possibly empty) arrays is also what makes the Activity/Following `EmptyState`s reachable from the actual route — today they're only exercised by the `Empty` Storybook stories, since the filler arrays are never empty.

web/frontend/app/features/users/components/profile/ProfileAvatar.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import ProfileAvatar from './ProfileAvatar';
+
+const profileAvatarDescription = `Avatar shown at the top of the public profile sidebar. It renders the photo from the public profile payload's \`avatarUrl\`, and shows the first two letters of the display name when that field is empty or the image fails to load.`;
+
+const meta = {
+    title: 'Users/ProfileAvatar',
+    component: ProfileAvatar,
+    tags: ['autodocs'],
+    args: {
+        displayName: 'Maren Iverson',
+        avatarUrl: 'https://picsum.photos/id/1027/240/240',
+    },
+    parameters: {
+        layout: 'centered',
+        docs: {
+            description: {
+                component: profileAvatarDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof ProfileAvatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WithPhoto: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        const image = canvas.getByRole('img', { name: "Maren Iverson's avatar" });
+        await expect(image).toHaveAttribute('src', 'https://picsum.photos/id/1027/240/240');
+    },
+};
+
+export const WithoutPhoto: Story = {
+    args: { avatarUrl: '' },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('MA')).toBeInTheDocument();
+        await expect(canvas.queryByRole('img')).not.toBeInTheDocument();
+    },
+};
+
+export const BrokenPhotoUrl: Story = {
+    args: { avatarUrl: 'https://example.invalid/missing-avatar.jpg' },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(await canvas.findByText('MA')).toBeInTheDocument();
+    },
+};

web/frontend/app/features/users/components/profile/ProfileAvatar.tsx

@@ -0,0 +1,42 @@
+import { useState } from 'react';
+
+interface ProfileAvatarProps {
+    avatarUrl: string;
+    displayName: string;
+}
+
+/**
+ * Renders the user's current avatar photo, falling back to their initials when the public
+ * profile payload carries an empty `avatarUrl` or the hosted image fails to load.
+ */
+const ProfileAvatar = ({ avatarUrl, displayName }: ProfileAvatarProps) => {
+    const [didImageFail, setDidImageFail] = useState(false);
+    const showPhoto = avatarUrl.length > 0 && !didImageFail;
+
+    return (
+        <div
+            className={`avatar w-[120px] h-[120px] rounded-full border-4 border-base-200 shadow-md ${
+                showPhoto ? '' : 'avatar-placeholder'
+            }`}
+        >
+            {showPhoto ? (
+                <div className="w-full h-full rounded-full overflow-hidden">
+                    <img
+                        src={avatarUrl}
+                        alt={`${displayName}'s avatar`}
+                        className="w-full h-full object-cover"
+                        onError={() => setDidImageFail(true)}
+                    />
+                </div>
+            ) : (
+                <div className="bg-secondary text-secondary-content w-full h-full rounded-full flex items-center justify-center">
+                    <span className="text-2xl font-bold">
+                        {displayName.slice(0, 2).toUpperCase()}
+                    </span>
+                </div>
+            )}
+        </div>
+    );
+};
+
+export default ProfileAvatar;

web/frontend/app/features/users/routes/user-profile.tsx

@@ -3,6 +3,7 @@ import { data } from 'react-router';
 import RouteErrorState from '../../../components/ui/error/RouteErrorState';
 import { getOptionalAuth } from '../../auth/auth.server';
 import { getPublicUserProfile, type PublicUserProfile } from '../users.server';
+import ProfileAvatar from '../components/profile/ProfileAvatar';
 import ProfileSidebarCard from '../components/profile/ProfileSidebarCard';
 import ProfileTabs, { type ProfileTab } from '../components/profile/ProfileTabs';
 import ActivityTab from '../components/profile/tabs/ActivityTab';
@@ -80,15 +81,7 @@ const ProfileContent = ({ profile, isOwnProfile }: ProfileContentProps) => {
 
                 <div className="grid grid-cols-1 lg:grid-cols-[300px_1fr] gap-8 items-start -mt-12">
                     <div className="lg:sticky lg:top-8 flex flex-col gap-5 px-2">
-                        <div className="w-[120px] h-[120px] rounded-full border-4 border-base-200 shadow-md overflow-hidden">
-                            <div className="avatar avatar-placeholder w-full h-full">
-                                <div className="bg-secondary text-secondary-content w-full h-full flex items-center justify-center">
-                                    <span className="text-2xl font-bold">
-                                        {displayName.slice(0, 2).toUpperCase()}
-                                    </span>
-                                </div>
-                            </div>
-                        </div>
+                        <ProfileAvatar avatarUrl={profile.avatarUrl} displayName={displayName} />
 
                         <ProfileSidebarCard
                             displayName={displayName}

web/frontend/app/features/users/users.server.ts

@@ -8,6 +8,7 @@ export interface PublicUserProfile {
     firstName: string;
     lastName: string;
     biography: string;
+    avatarUrl: string;
     createdAt: string;
 }
 
@@ -49,6 +50,7 @@ export const getPublicUserProfile = async (
         firstName: string;
         lastName: string;
         biography: string;
+        avatarUrl: string;
         createdAt: string;
     } = await res.json();
 
@@ -58,6 +60,7 @@ export const getPublicUserProfile = async (
         firstName: account.firstName,
         lastName: account.lastName,
         biography: account.biography,
+        avatarUrl: account.avatarUrl,
         createdAt: account.createdAt,
     };
 };

web/frontend/app/features/users/utils/filler-user-profile.ts

@@ -1,5 +1,5 @@
 // see USER_PROFILE_HANDOFF.md — filler data pending backend support for
-// bio, location, avatar/cover photos, follower/following stats, and activity feeds.
+// location, cover photos, follower/following stats, and activity feeds.
 
 export interface FillerProfileMeta {
     bio: string;