deepdrft/product-notes/authblocks-password-reset-brief.md

# Team Brief — Email-Backed Password Reset for AuthBlocks

**Audience:** an orchestrator (and its implementers) working **only** in the AuthBlocks repository at
`C:\Development\AuthBlocks`. You do not need, and should not assume, any knowledge of the products that
consume AuthBlocks. Everything you need is in this brief or in that repo.

**Status:** scoped request, not yet started. Author: product-designer (for a downstream consumer team).
Date: 2026-06-19.

---

## 1. The goal in one sentence

Replace the non-functional "Reset Password" stub on the AuthBlocks user-administration **Users** page
with a real, email-backed password-reset flow — so that triggering "Reset Password" for a user sends
that user an email containing a secure, time-limited reset link, and following the link lets them set a
new password.

This is an **upstream library feature**, delivered entirely inside AuthBlocks and published as a normal
version bump. Consumers pick it up by referencing the new package version.

---

## 2. Where the stub lives today

`AuthBlocksWeb/Components/Pages/UserAdmin/Users/Users.razor` — the user grid has a per-row **Reset
Password** `MudButton` whose handler is empty:

```csharp
private async Task ResetPassword(UserInputModel? item)
{
    // todo integrate with email for secure reset
}
```

There is **no backing API endpoint** for this action. `AuthBlocksLib/Routes/AuthRoutes.cs` maps
`login`, `register`, `admin-register`, `refresh`, `logout`, `me`, `roles` — and nothing for password
reset. So this is a build-from-scratch flow on both the API side (new endpoints) and the Web side
(wire the button + add a public reset page), reusing AuthBlocks' existing email and token machinery.

---

## 3. What AuthBlocks already has that you should reuse

**The pending-registration flow is your template.** AuthBlocks already does almost exactly this shape
of work for invitations — generate a secure token, email a link, validate the token when the user
returns. Read it end-to-end before designing reset; you are building a sibling flow:

- **Email sending is real and wired.** `AuthBlocksLib/AuthBlocksExtensions.cs` (~line 109) registers
  `services.AddScoped<IGeneralEmailSender, MailtrapEmailSender>();`. The `IGeneralEmailSender`
  abstraction and `MailtrapEmailSender` implementation come from the shared NetBlocks library
  (namespace `API.Common.Email.Mailtrap`). The send signature in use is:

  ```csharp
  await emailSender.SendEmailAsync(toAddress, cc: null, subject, htmlBody);
  ```

  See it called for real at `AuthBlocksLib/Routes/PendingRegistrationRoutes.cs:124`.

- **Email connection config.** The host populates `AuthBlocksOptions.EmailConnection` (a NetBlocks
  `EmailConnection` with `Host` + `Token`) plus `ApplicationName` and `SupportEmail` when it calls
  `AddAuthBlocks(options => { ... })`. Those flow into `AuthBlocksExtensions` and are available to your
  reset endpoint exactly as they are to the registration endpoint. **You do not need to invent any new
  config or sender** — reuse `IGeneralEmailSender` and `AuthBlocksOptions`.

- **An HTML email template pattern.** `AuthBlocksLib/Common/RegistrationEmailTemplate.cs` is a static
  `Create(token, link, applicationName, supportEmail)` returning a styled HTML string. Build a sibling
  `PasswordResetEmailTemplate.Create(...)` in the same file's neighbourhood and the same house style
  (the registration template is teal-branded, table-layout, support-line-collapses-when-empty — match
  it). Do **not** reuse the registration template verbatim; the copy is invitation-specific.

- **A token service pattern.** `AuthBlocksLib/Services/RegistrationTokenService.cs` generates a random
  token, SHA-256-hashes `{email}::{token}`, persists the hash with a 7-day expiry, and validates /
  consumes it. **However — for password reset, prefer ASP.NET Identity's built-in reset token** (see
  §4) rather than re-implementing this hand-rolled scheme. The registration token service is a *style*
  reference for endpoint shape and email-link construction, not necessarily the token mechanism.

- **The deep-link construction idiom.** The registration flow builds its link with
  `QueryHelpers.AddQueryString(returnHost, { UserEmail, RegistrationToken })` and the public register
  page reads those query params and pre-fills (`Register.razor`, `[SupplyParameterFromQuery]`). Mirror
  this for the reset page: link carries `email` + `resetToken`; the reset page reads them.

- **Identity is fully present.** `UserService` wraps `UserManager<ApplicationUser>` (see
  `AuthBlocksData/Services/UserService.cs`). `UserManager` gives you the canonical reset primitives —
  use them.

---

## 4. Recommended mechanism: ASP.NET Identity's built-in reset token

Password reset is a solved problem in ASP.NET Identity, and rolling your own token store for it is an
avoidable security surface. **Strong recommendation:** use `UserManager<ApplicationUser>`'s built-in
reset tokens rather than the hand-rolled `RegistrationTokenService` SHA-256 scheme.

- `var token = await userManager.GeneratePasswordResetTokenAsync(user);` — produces a token bound to
  the user's security stamp; invalidated when the password changes or the stamp rotates.
- `var result = await userManager.ResetPasswordAsync(user, token, newPassword);` — validates and
  applies in one call; enforces the configured password policy.
- Token lifetime is governed by `DataProtectionTokenProviderOptions.TokenLifespan` (default 1 day) —
  confirm/configure to a sensible reset window (recommend 1–2 hours for reset, tighter than the 7-day
  registration window).

This means you likely **do not** need a new DB table or migration for reset (unlike registration,
which persists pending rows). Confirm whether the default token providers are registered in the
AuthBlocks Identity setup; if `AddDefaultTokenProviders()` (or equivalent) is not already called in the
Identity configuration, add it — that is the one wiring prerequisite for `GeneratePasswordResetTokenAsync`
to work.

*Alternative considered (and not recommended):* extend `RegistrationTokenService` / `PendingRegistration`
into a generic token table that also serves reset. Rejected — it couples two unrelated flows, re-implements
what Identity already does correctly, and adds a migration for no benefit. Use it only if there is a
hard reason the Identity token provider cannot be enabled in this setup.

---

## 5. The surfaces to build

Three pieces, mirroring the registration flow's API-endpoint + email-template + web-page triad.

### 5.1 API endpoints (`AuthBlocksLib/Routes/AuthRoutes.cs`)

Add to the `api/auth` group. Two endpoints, both **unauthenticated** (a user resetting a forgotten
password is by definition not logged in — the admin "Reset Password" button triggers the *first* of
these on the user's behalf, but the endpoint itself authenticates via the token, not a bearer):

1. **`POST api/auth/forgot-password`** — body `{ email, returnHost }`. Looks up the user; if found,
   generates a reset token and emails the reset link (`{returnHost}?email=&resetToken=`). **Always
   return success** regardless of whether the email exists — do **not** leak account existence (a known
   reset-flow security requirement; the registration flow's "user already exists" message is acceptable
   for an *admin-gated* invite but a *public* forgot-password must not reveal it). On email-send failure,
   log and return a generic failure.

2. **`POST api/auth/reset-password`** — body `{ email, resetToken, newPassword }`. Resolves the user,
   calls `ResetPasswordAsync(user, token, newPassword)`, returns the Identity result mapped to the
   AuthBlocks `Result`/`ApiResult` convention (see how `Register` maps results in `AuthRoutes.cs`).

Follow the existing `AuthRoutes` conventions exactly: `ApiResult<T>` / `ApiResultDto<T>` wrapping,
`ILogger<AuthLogger>` for logging, `Results.Ok` / `Results.BadRequest` / `Results.Json(..., 500)` shapes.

### 5.2 Email template (`AuthBlocksLib/Common/PasswordResetEmailTemplate.cs`)

New static `Create(resetLink, applicationName, supportEmail)` in the visual style of
`RegistrationEmailTemplate`. Reset copy: a clear "you (or an admin) requested a password reset," the CTA
button to the reset link, an expiry notice matching the token lifespan, and "ignore this email if you
didn't request it." No registration code box — reset uses an opaque token in the link, not a
user-typed code (recommended; do not show the Identity token as a copy-paste code — it is long and
URL-encoded).

### 5.3 Web surfaces (`AuthBlocksWeb`)

- **Wire the admin button.** In `Users.razor`, replace the empty `ResetPassword` handler with a call to
  an `IAuthApiClient` (or the appropriate existing client) method that hits `POST api/auth/forgot-password`
  for `item.Email`, and show a confirmation (a `StatusMessage` / dialog: "Reset email sent to {email}").
  This is the admin-initiated trigger.
- **Add a public reset page.** New `AuthBlocksWeb/Components/Pages/Account/ResetPassword.razor`,
  `@page "/account/reset-password"`, `@rendermode InteractiveServer`, **no role gate** (a forgotten-password
  user is unauthenticated). Read `email` + `resetToken` from query params (mirror `Register.razor`'s
  `[SupplyParameterFromQuery]` pre-fill), present new-password + confirm fields, submit to
  `POST api/auth/reset-password`, and on success route to `/account/login` with a success message. Match
  `Register.razor`'s form structure and validation idiom.
- **Optional: a public "forgot password?" entry.** Consider a `/account/forgot-password` page (link from
  `Login.razor`) where a user enters their email to self-initiate reset — same `forgot-password` endpoint.
  Decide whether this is in scope or whether reset is admin-initiated only (see open questions).

### 5.4 Client method

Add the `forgot-password` / `reset-password` calls to whichever API client the Web project uses for auth
(the registration/login flows go through `JwtAuthenticationStateProvider` / `IAuthApiClient` — follow the
same pattern; do not introduce a new HTTP client).

---

## 6. Constraints

- **No account-existence leak** on the public `forgot-password` path (§5.1).
- **Reuse, don't reinvent:** `IGeneralEmailSender` for sending, `AuthBlocksOptions` for config, Identity's
  token provider for tokens, the existing `Result`/`ApiResult` conventions for endpoint returns, and the
  `RegistrationEmailTemplate` house style for the email.
- **Match the existing route + result conventions** in `AuthRoutes.cs` precisely — this is a library;
  consumers rely on the shape staying idiomatic.
- **Versioning:** this lands as a normal AuthBlocks version bump (packed/pushed by `pack.ps1` like the
  other packages). Note the new version so consumers can pin to it.
- **Token lifespan** for reset should be short (recommend 1–2 hours), distinct from the 7-day
  registration token.
- **Password policy** is enforced by `ResetPasswordAsync` automatically — do not duplicate validation,
  but surface the Identity error messages back through the result.

---

## 7. Acceptance criteria

1. Clicking "Reset Password" for a user on the Users admin page sends that user a styled email with a
   working reset link, and shows the admin a confirmation. No unhandled exception, no silent no-op.
2. Following the reset link lands on `/account/reset-password` with the email pre-filled; setting a new
   password that meets policy succeeds and the user can immediately log in with the new password.
3. An expired or tampered token is rejected with a clear, non-leaky error.
4. The public `forgot-password` endpoint returns the same response whether or not the email maps to a
   real account (no existence leak).
5. Email send is exercised through the real `IGeneralEmailSender` (Mailtrap in the configured
   environment) — verify an email actually arrives.
6. No new required config beyond what `AddAuthBlocks` already accepts (reset reuses the existing email
   connection + application-name + support-email options). If a token-provider registration was missing,
   it is added and documented.
7. Published as a version bump; the new version is recorded.

---

## 8. Open questions for the implementing team / its sponsor

1. **Admin-initiated only, or also public self-serve?** Is the only entry point the admin "Reset
   Password" button (§5.3 first bullet), or do you also want a public "forgot password?" link from the
   login page (§5.3 last bullet)? The endpoints support both; the question is which Web surfaces to build.
   *Recommendation: build both endpoints, ship the admin button now, and add the public forgot-password
   page in the same pass since it is nearly free once the endpoint exists.*
2. **Token mechanism — confirm Identity's built-in is acceptable** (§4 recommendation) vs. a hard
   requirement to use the hand-rolled hashed-token scheme. *Recommendation: Identity built-in.*
3. **Reset token lifespan** — confirm the window (recommend 1–2 hours).
4. **Return host / link base** — the registration flow has the *caller* pass `returnHost`. Confirm the
   reset flow does the same (the consumer supplies the base URL of its public reset page), vs. AuthBlocks
   configuring a reset base URL in options. *Recommendation: pass `returnHost` per-call, mirroring
   registration, so AuthBlocks stays host-agnostic.*
5. **Does the public reset page (`/account/reset-password`) need to render in a consumer's own layout?**
   The page ships in the AuthBlocks RCL with no `@layout`, so it inherits whatever the consuming host sets
   as default — same as `Register.razor`. Confirm this is acceptable (it should be; it is how registration
   already behaves).

---

## 9. Suggested reading order in the repo

1. `AuthBlocksLib/Routes/PendingRegistrationRoutes.cs` — the email-sending endpoint to mirror.
2. `AuthBlocksLib/Routes/AuthRoutes.cs` — where your endpoints go; the result/logging conventions.
3. `AuthBlocksLib/Common/RegistrationEmailTemplate.cs` — the email house style.
4. `AuthBlocksWeb/Components/Pages/Account/Register.razor` — the public-page + query-param-prefill pattern
   for your reset page.
5. `AuthBlocksWeb/Components/Pages/UserAdmin/Users/Users.razor` — the stub to replace.
6. `AuthBlocksLib/AuthBlocksExtensions.cs` + `AuthBlocksOptions.cs` — the email sender + options wiring you
   reuse (and where to add a token-provider registration if one is missing).
7. `AuthBlocksData/Services/UserService.cs` — the `UserManager<ApplicationUser>` access point for the
   Identity reset primitives.