NextMyDay/docs/specs/spec-010-admin-account-ui.md

SPEC-010 — the admin & account UI (M0.2)

Field	Value
Status	Implemented (2026-10-15) — see §8; build/vet/test -race green · static binary · AC-1…AC-7
Created	2026-10-15
Author	OpenArchitect
Target milestone	M0.2 (make the admin actually usable)
Governing decisions	D-009 · D-019 · D-029 · D-034 · D-041 · PROJECT_PLAN.md §7
Related	SPEC-004 (identity/users) · SPEC-006 (§8 nudge) · SPEC-008 (modules) · SPEC-009 (the shell)

---

1. Goal

Make the signed-in experience usable: a nav, an Account page (add a passkey), and a Users page (create users + send the enrolment invite). Today the core services exist but there is no UI — the admin lands on the dashboard with no menu and no way to add a user or a passkey.

2. Non-goals

Departments/positions (M1). Module enable/disable UI beyond a link to the existing console. Passkey removal (later).

---

3. The nav (shell)

The shell renders a nav = registry entries (D-038) plus core entries, role-gated:

Entry	Route	Who
Home	/{GUID}/home	everyone
Account	/{GUID}/account	everyone
Users	/{GUID}/users	admin
Modules	/{GUID}/core/modules	admin (the existing console)

4. Account page — /{GUID}/account

• Show the user's factors: passkeys (count) · TOTP (enrolled yes/no).
• Add a passkey — the WebAuthn ceremony, reusing the D-041 nudge page/flow (no duplication).
• Don't ask again — users.passkey_opt_out (stop the banner).

5. Users page — /{GUID}/users (admin)

• List every user: display name · email · role · manager · identity status (pending_enrollment / active / none).
• Create user: display name · email · role (only roles below the creator, D-019) · manager (defaults to the creator).
• On create: users.Create → identities.Mint → email the enrolment invite — the /{GUID} link (SPEC-006). The identity is pending_enrollment; the invite carries the bounded window (A1).
• Show the invite link in the UI too, so the admin can copy it if mail isn't configured.

6. The post-setup passkey prompt (fixes the admin never being nudged)

The D-041 nudge fires on a TOTP login — but the wizard's finish mints a session directly, so the admin is never nudged. Add: while the signed-in user has no passkey, has not opted out, and the origin is not loopback, the shell shows a prominent banner — "You have no passkey. Add one." — linking to the Account page. It disappears once a passkey exists or the user opts out.

7. Acceptance criteria

#	Criterion
AC-1	The shell shows the nav; Users/Modules appear only for an admin
AC-2	The admin can add a passkey from the Account page (a real WebAuthn registration)
AC-3	The admin can create a user (choosing only roles below their own); the invite is emailed (and the link shown)
AC-4	A newly created user can enrol at /{GUID} (the invite path)
AC-5	A signed-in user without a passkey sees the Add-a-passkey banner; it clears after adding one or opting out (D-041)
AC-6	A non-admin cannot reach /users (role gate → 403)
AC-7	routing stays pure; the binary stays static; no inline scripts

---

8. Implementation notes (built 2026-10-15)

go build · go vet · go test -race green (all packages) · static CGO-free binary (CGO_ENABLED=0) · internal/core/routing untouched (purity intact) · no inline scripts on the two new screens. AC-1…AC-7 are asserted without a browser; the WebAuthn registration itself stays browser-bound (SPEC-009 §11).

What landed

Path	What
internal/core/account/	the account page (GET /{GUID}/account: factors · Add a passkey · Don't ask again) and the admin Users page (GET /{GUID}/users: list · create + email the invite), both riding the door as core dispatch modules; Register mounts them
internal/core/web/	the shell gains the role-gated core nav (Home · Account · Users · Modules), the passkey banner and PageFor/WithShell/ShellFromContext; layout.html + app.css (the banner, a.button, code/.invite)
internal/core/server/server.go	Deps.Credentials; serveGUID attaches the shell state (admin? · banner?) to the request context; passkeyBanner/originHost
internal/core/auth/	Identities.TOTPEnrolled (the account page's TOTP factor)
internal/core/users/	Users.List (the admin list read)
internal/core/module/registry.go	CoreDispatchNames + account · users (the fail-closed collision guard)
cmd/myday/main.go	wires account.New · passes Credentials · adds the admin-only role requirements for the users functions

The nav. web.navItems = the core entries (Home · Account; Users · Modules only for an admin, per the Admin flag the door computes) plus the registry entries (D-038), with a duplicate target — the discovered home dashboard — collapsed onto the core Home entry. A non-admin sees Home · Account only.

The passkey ceremony is not duplicated. The account page's "Add a passkey" is a link to the existing SPEC-006 §8 / D-041 screen (GET /{GUID}/auth/passkey), which performs the begin and whose single passkey.add action finishes it — the one WebAuthn implementation.

The banner. While the signed-in user has no passkey, has not opted out and the origin is not loopback, the shell shows the prompt. The condition is the door's (serveGUID already holds the session, the identity and the user); it is attached to the request context and every authenticated page draws it via web.PageFor. This closes the D-041 gap where the wizard's direct session mint bypasses the TOTP-login nudge (SPEC-006 §8) and the admin was never prompted.

How the shell learns the user's role / passkey state. The door attaches (admin, banner) to the request context (web.WithShell); a handler renders an authenticated page with web.Render(w, s, web.PageFor(r, page)). web stays a leaf (it sees only a bool + the GUID); the RequestContext hand-over is untouched, so identification ≠ authorisation (D-003) is unchanged.

9. Deviations & questions for the Architect

#	Item	Why
D-1	module.CoreDispatchNames gained account and users.	The two pages ride the door as core dispatch modules; a discovered module claiming either name would silently lose precedence / shadow the core — the same fail-closed reason the existing four are guarded (SPEC-009 §8). Flagged because it widens a documented list.
D-2	The shell state (role + banner) is attached to the request context by the door and applied with web.PageFor, rather than added to RequestContext.	web.Render takes no request, and the banner must be consistent on every authenticated page (dashboard · Modules · nudge · account · Users), not just the new ones. A request-context value keeps web a leaf and leaves the RequestContext (identification) untouched.
D-3	The account page's "Add a passkey" is a link to /{GUID}/auth/passkey, not an embedded second ceremony.	SPEC-010 §4 says reuse the D-041 ceremony and do not duplicate the WebAuthn flow — the link is the literal reuse.
D-4	auth.Identities gained TOTPEnrolled; users.Users gained List.	The account page reads the TOTP factor; the admin page lists users. Both are natural contract additions on the service that owns the data; the concrete services already had the reads (totp_secrets · a SELECT).
D-5	The banner also appears on the account page itself (linking to the page you are on) and on the passkey screen.	SPEC-010 §6 states the banner shows whenever the three conditions hold and links to the Account page; suppressing it there is a design choice, not a requirement — left as specified.