# Team Brief — AuthBlocks: Normalize the Account-Creation Pages (NewUser vs. Registration vs. SuperRegister)

**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 one repo.

**Status:** scoped request, **decisions approved 2026-06-20** — ready for implementation. Author: product-designer (for a downstream consumer team).
Date: 2026-06-20.

---

## 1. The problem in one sentence

AuthBlocks ships **three** account-creation pages whose identities have drifted: the **New User** page
(`/useradmin/users/new`) is broken and has become a half-built *duplicate of the invite/registration flow*
instead of the **direct admin-provisioning** path it is named for — while a separate page,
**SuperRegister** (`/account/superregister`), is the page that actually performs direct admin provisioning.
The two "create an account now" identities live in different places, one of them is broken, and the labels
lie about what each does. This brief normalizes the three paths into distinct, correctly-named flows.

The intended end state (per the consuming team):

1. **Direct provision** — admin creates a *live* account immediately (username + email + password + roles),
   bypassing email entirely. This is what **New User** should be.
2. **Admin invite-by-email** — admin sends a registration code + link to an email; the recipient redeems it
   to create their own account. This is the **Registration** flow.
3. **Public self-service redeem** — the recipient lands on the public **Register** page and completes
   account creation with the code. (Already correct; included for completeness.)

---

## 2. Current-state analysis (read this before designing — it is the crux)

### 2.1 New User — `/useradmin/users/new` (BROKEN + mislabeled + duplicate)

- **Page:** `AuthBlocksWeb/Components/Pages/UserAdmin/Users/NewUser.razor` — just renders `<NewUserForm/>`.
- **Form markup:** `.../Users/NewUserForm.razor`. The card header reads **"Activate New User"**. The body
  text reads:
  > *"Create a new user account, bypassing email registration. The password must be provided now."*
  This message describes **direct provisioning** — and it is the **wrong message for what the page actually
  does**, because:
  - The form has **only an Email field**. There is **no username field, no password field, and no role
    selector** — despite the copy promising "the password must be provided now."
  - The submit button is labeled **"Send Registration Code"** — i.e. invite-flow language, contradicting the
    "bypassing email registration" body copy directly above it.
- **What it actually does:** **nothing — it throws.** The form's `OnValidSubmit` is wired to a stub:
  ```csharp
  // NewUserForm.razor.cs
  private void X()
  {
      throw new NotImplementedException();
  }
  ```
  The code-behind also carries a **commented-out body** that, if enabled, would call
  `Client.CreatePendingRegistration(...)` and pop a `UserSubmittedModal` — i.e. it would make NewUser
  **identical to the invite/Registration flow**. So the page is mid-migration: someone started turning the
  direct-provision page into a second copy of the invite page, didn't finish, and left a throwing stub.
- **Backing model is the invite model, not the provision model:** `NewUserForm` binds
  `PendingRegistrationInputModel Input` and injects `PendingRegistrationClient` — the *registration* model
  and client, **not** `AdminRegisterRequest` / the admin-register path. This is the concrete duplication:
  NewUser is plumbed for invites, not for direct provisioning.

**In short:** NewUser is named for direct provisioning, *says* it does direct provisioning ("bypassing email
registration… password must be provided now"), is *wired* for invites (PendingRegistration model/client +
commented-out invite call), is *labeled* for invites ("Send Registration Code"), and **actually throws
`NotImplementedException`**. Every layer disagrees with every other layer.

### 2.2 SuperRegister — `/account/superregister` (the REAL direct-provision page, working)

- **Page:** `AuthBlocksWeb/Components/Pages/Account/SuperRegister.razor`. `[HierarchicalRoleAuthorize(UserAdmin)]`,
  `@rendermode InteractiveServer`. Title "Admin Register"; header "Create a new account."
- **This is the genuine direct-provision UI.** Full form: Username, Email, Password, Confirm Password, and a
  **multi-select Roles** dropdown populated from `AuthApiClient.GetRolesAsync`.
- **Backing model + call:** binds `AdminRegisterRequest` (UserName, Email, Password, ConfirmPassword,
  RoleIds) and calls `AuthApiClient.AdminRegisterAsync(Input, token)` → `POST api/auth/admin-register`.
- **What that endpoint does** (`AuthBlocksLib/Routes/AuthRoutes.cs`, `AdminRegister`, role-gated to
  `UserAdmin`): rejects a duplicate email; resolves each `RoleId` to a role name up front (fail-fast);
  creates the user via `userService.Add(user, request.Password)` with `EmailConfirmed = true`; assigns
  roles (deleting the half-created user if a role assignment fails); returns an `AuthResponse`. **No email,
  no token, no pending row — a live account immediately.** This is exactly the behavior the consumer wants
  *New User* to have.

### 2.3 New Registration — `/useradmin/registrations/new` (the invite flow, working)

- **Page:** `AuthBlocksWeb/Components/Pages/UserAdmin/Registrations/NewRegistration.razor` → `<NewRegistrationForm/>`.
- **Form:** `.../Registrations/NewRegistrationForm.razor`. Header **"Provision New User"** (note: this label
  is *also* slightly off — it performs an *invite*, not a provision; see decisions §5). Body: *"A registration
  code and link will be sent to the email address provided."* Fields: Email + multi-select Roles. Button:
  "Send Registration Code".
- **Backing model + call:** binds `PendingRegistrationInputModel`, injects `PendingRegistrationClient`, and
  on submit calls `Client.CreatePendingRegistration(email, roles, returnHost=.../account/register)`, then
  shows `RegistrationSubmittedModal` (which reports "An email has been sent to: …").
- **What that hits:** `POST api/pendingregistration/create` (`AuthBlocksLib/Routes/PendingRegistrationRoutes.cs`,
  `Create`, group role-gated to `UserAdmin`): rejects existing user / existing pending registration;
  generates a registration token; persists a `PendingRegistration` row with the token **hash** and an expiry;
  emails a code + a deep link (`returnHost?UserEmail=&RegistrationToken=`) via `IGeneralEmailSender`. The
  recipient later redeems at the public **Register** page (`POST api/auth/register`, which validates the
  code, creates the user, consumes the token).

### 2.4 The duplication, stated precisely

`NewUserForm` and `NewRegistrationForm` **bind the same model (`PendingRegistrationInputModel`) and the same
client (`PendingRegistrationClient`), and NewUser's commented-out handler is a near-copy of
NewRegistration's `CreatePendingRegistration` handler.** NewUser is, in its half-built state, a strictly
worse duplicate of NewRegistration (no roles field, throwing stub) — while the page that *should* own
NewUser's intended behavior (direct provision) is the separate `SuperRegister`. The system has:

- **two pages aimed at the invite flow** (Registration = working; NewUser = broken duplicate), and
- **one page doing direct provision under a different name/route** (SuperRegister),
- **zero working pages at the New User route doing what "New User" implies.**

### 2.5 The API is already correct — this is a Web-layer normalization

Both endpoints exist and work today: `admin-register` (direct provision, role-gated) and
`pendingregistration/create` (invite). **No new API endpoints are required.** This task is about pointing
the right *page* at the right *existing* endpoint, with honest labels and routes. (Contrast the
password-reset brief, which was build-from-scratch on both tiers.)

---

## 3. The normalization design

End state: **three crisp paths, each at one page, each correctly labeled, each on the right endpoint.**

| Path | Page (canonical) | Route | Endpoint | Result |
|---|---|---|---|---|
| Direct provision | **New User** | `/useradmin/users/new` | `POST api/auth/admin-register` | live account now |
| Admin invite | **New Registration** | `/useradmin/registrations/new` | `POST api/pendingregistration/create` | emailed code + link |
| Public redeem | **Register** | `/account/register` | `POST api/auth/register` | recipient self-creates |

The core move: **make `NewUser` the canonical direct-provision page by absorbing SuperRegister's behavior**,
fix its copy, and resolve the now-redundant SuperRegister. Registration stays as-is (modulo a label tidy).

### 3.1 Recommended approach — "Absorb into NewUser, retire SuperRegister"

1. **Rebuild `NewUserForm` as the direct-provision form.** Re-bind it from `PendingRegistrationInputModel` /
   `PendingRegistrationClient` to **`AdminRegisterRequest`** and the **auth client** that calls
   `AdminRegisterAsync` (the `IAuthApiClient` + `IAuthSession` token pattern SuperRegister already uses).
   Bring across SuperRegister's full field set: Username, Email, Password, Confirm Password, and the
   role multi-select sourced from `GetRolesAsync`. Delete the throwing `X()` stub and the commented-out
   invite handler. Keep the existing card/`MudContainer` chrome so it matches the other UserAdmin pages
   (NewUser/NewRegistration share a card layout that the standalone SuperRegister does not).
2. **Fix the copy.** Header → e.g. **"New User — Direct Provision"** (or "Activate New User", kept, now that
   the page genuinely activates one). Body → keep the accurate *"Create a live account now, bypassing email
   registration. Set the password directly."* Button → **"Create Account"** (retire the misleading
   "Send Registration Code" on this page). On success, show a confirmation and route back to
   `/useradmin/users` (force-reload so the grid refreshes — mirror NewRegistration's post-submit nav).
3. **Retire `SuperRegister`.** Once NewUser owns direct provision, SuperRegister is a duplicate. Preferred:
   **delete the page and redirect `/account/superregister` → `/useradmin/users/new`** so any existing
   bookmark or consumer nav link doesn't 404 during the consumer's catch-up window (see §7). Keep the
   redirect lightweight (a `NavigationManager.NavigateTo` in a thin page, or a server redirect). Do **not**
   leave two separate-but-identical "create now" pages alive.
4. **Tidy Registration's label** (small, optional but recommended for the normalization to be coherent):
   the invite page header currently says **"Provision New User"**, which collides with the direct-provision
   concept now owned by NewUser. Rename it to **"Invite New User"** / **"New Registration"** so "provision"
   unambiguously means *direct* and "invite/registration" means *emailed code*. No behavior change.

**Why this approach:** NewUser's route (`/useradmin/users/new`) is where an admin looking at the Users grid
expects to click "add a user," and it lives in the UserAdmin/Users area beside the grid — the natural home
for the canonical create-now action. SuperRegister sits oddly under `/account/*` (the *public* auth area,
alongside Login/Register) despite being an admin-only action; folding it into UserAdmin/Users fixes that
mis-placement as a side effect. The API already supports it, so this is low-risk re-pointing, not new
behavior.

### 3.2 Alternatives considered

- **B — Keep SuperRegister canonical; make NewUser a redirect to it.** Inverse of the recommendation:
  delete `NewUserForm`'s logic, point `/useradmin/users/new` → `/account/superregister`. Cheaper (no form
  rebuild), but it **enshrines the mis-placement** (admin-only page under `/account/*`) and leaves the
  visual inconsistency (SuperRegister doesn't use the UserAdmin card chrome). Rejected: it normalizes the
  *names* but not the *information architecture*. Choose this only if rebuilding the form is deemed
  out-of-budget for now — and even then, treat it as interim.
- **C — Keep both pages, share one form component.** Extract a single `DirectProvisionForm` component and
  render it from both `NewUser.razor` and `SuperRegister.razor`. Eliminates code duplication but **leaves
  two routes for one action** — exactly the "two create-now pages" the consumer is asking to remove. Rejected
  for the explicit goal; the duplication the consumer dislikes is at the *page/route* level, not just code.
- **D — Make NewUser a *chooser*** (two buttons: "Create now" vs. "Invite by email").** A single entry point
  that branches to the two real flows. Genuinely nice UX and worth noting as a *future* enhancement, but it
  is scope-creep on a "normalize what exists" request and introduces a fourth surface. Defer.

**Recommendation: A.** It produces the cleanest end state (correct names, correct routes, correct IA, no
redundant page) at the cost of one form rebuild that is mostly a copy of SuperRegister's already-working
form.

---

## 4. Constraints

- **No new API endpoints.** `admin-register` and `pendingregistration/create` already exist and are correct
  (§2.5). If you find yourself adding an endpoint, stop — you've taken a wrong turn.
- **Preserve role-gating.** Direct provision must stay `[HierarchicalRoleAuthorize(UserAdmin)]` (SuperRegister
  has it; ensure rebuilt NewUser keeps it — NewUser currently inherits whatever the UserAdmin pages set, so
  verify the attribute is present on the page).
- **Reuse the existing client + session pattern.** Direct provision uses `IAuthApiClient.AdminRegisterAsync`
  + `IAuthSession.GetValidTokenAsync` (as SuperRegister does). Do not introduce a new client; do not route
  direct provision through `PendingRegistrationClient`.
- **Match the UserAdmin page conventions.** NewUser/NewRegistration use a `MudContainer` + `MudCard` +
  back-button layout; keep the rebuilt NewUser in that house style rather than transplanting SuperRegister's
  bare `MudGrid` layout verbatim.
- **No 404s for retired routes.** If SuperRegister is removed, `/account/superregister` must redirect, not
  break (§3.1.3, §7).
- **Versioning:** lands as a normal AuthBlocks Web version bump, packed/pushed via `pack.ps1`. `AuthBlocksWeb`
  is currently `Cerebellum.AuthBlocks.Web` **10.3.36**; bump to **10.3.37** (or the next free patch if
  another bump has landed since this brief). **Record the published version** so the consumer can pin.

---

## 5. Decisions for the sponsor (Daniel) — resolved 2026-06-20

1. **Which page is canonical for direct provision?** **DECISION (2026-06-20): New User** (`/useradmin/users/new`)
   is the canonical direct-provision page, absorbing SuperRegister (§3.1). ✅ approved.
2. **What happens to SuperRegister?** **DECISION (2026-06-20): delete + redirect** `/account/superregister` →
   `/useradmin/users/new`. ✅ approved.
3. **Route naming.** **DECISION (2026-06-20):** keep `/useradmin/users/new` as the canonical direct-provision
   route. No `/account/*` route retained. ✅ approved.
4. **Copy/wording on NewUser.** **DECISION (2026-06-20):** go with the recommended strings in §3.1.2 — header
   "New User — Direct Provision" or "Activate New User"; button "Create Account"; accurate direct-provision body
   copy. Implementer discretion within that intent. ✅ approved.
5. **Tidy the Registration label** ("Provision New User" → "Invite New User"/"New Registration")?
   **DECISION (2026-06-20):** yes, in scope. ✅ approved.
6. **Future chooser page (Alternative D)** — **DECISION (2026-06-20):** deferred; captured as a possible later
   enhancement. ✅ approved (defer).

---

## 6. Acceptance criteria

1. Navigating to `/useradmin/users/new` shows a **direct-provision form** with Username, Email, Password,
   Confirm Password, and a Roles multi-select — **no "Send Registration Code" language**, no throwing stub.
2. Submitting that form with a valid username/email/password (and optional roles) calls
   `POST api/auth/admin-register`, creates a **live account immediately** (no email sent, no pending-
   registration row), assigns the selected roles, shows a success confirmation, and returns to
   `/useradmin/users` with the new user visible in the grid.
3. The page's copy accurately describes direct provisioning; the button reads "Create Account" (or the
   sponsor-approved string).
4. `NewUserForm` no longer binds `PendingRegistrationInputModel` / `PendingRegistrationClient`, no longer
   contains the `X()` stub or the commented-out invite handler.
5. SuperRegister is resolved per the sponsor's decision: if retired, `/account/superregister` **redirects**
   to `/useradmin/users/new` (no 404, no second working create-now page); if kept as alias, it is explicitly
   an alias, not an independent duplicate.
6. The invite flow at `/useradmin/registrations/new` still works unchanged (emails a code + link); if its
   label was tidied, the change is cosmetic only.
7. Direct provision remains `UserAdmin`-role-gated; an unauthorized user cannot reach it.
8. Published as a version bump from 10.3.36 (expected **10.3.37**); the new version number is recorded.

---

## 7. Downstream consequence (for the consumer to handle later — NOT this team's work)

The consuming product (DeepDrftManager) currently surfaces **SuperRegister (`/account/superregister`)** in
its CMS navigation as the **"Provision User"** entry, alongside a **Registrations** link. If this
normalization changes which page is canonical or its route — specifically if `/account/superregister` is
retired in favor of `/useradmin/users/new` — the consumer's nav link will need a small follow-up update
**after this AuthBlocks change ships and the consumer bumps its package reference**. The recommended
delete-**and-redirect** (§3.1.3, decision §5.2) is precisely to keep that consumer working in the interval
between this ship and the consumer's catch-up. **This is noted only so the implementing team understands why
the redirect matters; updating the consumer's nav is out of scope for AuthBlocks.**

---

## 8. Suggested reading order in the repo

1. `AuthBlocksWeb/Components/Pages/UserAdmin/Users/NewUserForm.razor` + `.razor.cs` — the broken page; the
   wrong message, the missing fields, the `X()` stub, the commented-out invite handler. **Start here.**
2. `AuthBlocksWeb/Components/Pages/Account/SuperRegister.razor` — the working direct-provision form to
   absorb (fields, role multi-select, `AdminRegisterAsync` call, `IAuthSession` token pattern).
3. `AuthBlocksWeb/Components/Pages/UserAdmin/Registrations/NewRegistrationForm.razor` + `.razor.cs` — the
   invite flow NewUser was wrongly duplicating; the post-submit modal + force-reload nav pattern to mirror.
4. `AuthBlocksLib/Routes/AuthRoutes.cs` — the `AdminRegister` endpoint (direct provision; what NewUser must
   call) and `Register` (public redeem); the `ApiResult`/result conventions.
5. `AuthBlocksLib/Routes/PendingRegistrationRoutes.cs` — the `Create` endpoint (invite); confirms the two
   endpoints are already distinct and correct (no API work needed).
6. `AuthBlocksModels/ApiModels/AuthModels.cs` — `AdminRegisterRequest` (UserName, Email, Password,
   ConfirmPassword, RoleIds) is the model NewUser should bind.
7. `AuthBlocksWeb/ApiClients/IAuthApiClient.cs` / `AuthApiClient.cs` — `AdminRegisterAsync` + `GetRolesAsync`.
8. `AuthBlocksWeb/AuthBlocksWeb.csproj` — `<Version>10.3.36</Version>` to bump.
9. `pack.ps1` — pack/push after the bump; record the published version.