AI Implementation feature(842): First-Start Create Admin Modal 1.01 (#4)

2026-07-21 15:32:51 +00:00
parent 960516a7bc
commit 6feaf08bdb
17 changed files with 834 additions and 217 deletions
@@ -25,7 +25,7 @@ All components are standalone (no NgModules). Each component imports

 | Component              | Path                                                            | Purpose                                         |
 |------------------------|-----------------------------------------------------------------|-------------------------------------------------|
-| `AppComponent`         | `frontend/src/app/app.component.ts`                             | Root; renders `<router-outlet>` and calls `BootstrapService.load()`. |
+| `AppComponent`         | `frontend/src/app/app.component.ts`                             | Root; renders `<router-outlet>`, calls `BootstrapService.load()` then `AuthService.restoreSession()`. |
 | `HomeComponent`        | `frontend/src/app/features/home/home.component.ts`              | Authenticated shell with header, conditional admin nav, and `<router-outlet>` for children. |
 | `AdminUsersComponent`  | `frontend/src/app/features/admin/admin-users.component.ts`      | Admin-only user list rendered inside the home shell. |
 | `LoginComponent`       | `frontend/src/app/features/auth/login.component.ts`            | Username/password form.                         |
@@ -35,16 +35,18 @@ All components are standalone (no NgModules). Each component imports

 | Service             | Path                                                          | Purpose                                                   |
 |---------------------|---------------------------------------------------------------|-----------------------------------------------------------|
-| `AuthService`       | `frontend/src/app/core/services/auth.service.ts`              | Signal-backed access token + current user.                |
-| `BootstrapService`  | `frontend/src/app/core/services/bootstrap.service.ts`         | Fetches `/api/v1/bootstrap`, applies theme tokens to CSS. |
+| `AuthService`       | `frontend/src/app/core/services/auth.service.ts`              | Signal-backed access token + current user; persists session to `sessionStorage` and exposes `restoreSession()` + `waitUntilHydrated()`. |
+| `BootstrapService`  | `frontend/src/app/core/services/bootstrap.service.ts`         | Fetches `/api/v1/bootstrap`, applies theme tokens to CSS; exposes `ready()` that deduplicates the in-flight load. |
+| `AuthSessionStorage` (helpers) | `frontend/src/app/core/services/auth.session-storage.ts` | Pure `readStoredSession` / `writeStoredSession` / `clearStoredSession` against `sessionStorage` (key `hipctf.auth.v1`). |
 | `AdminService`      | `frontend/src/app/core/services/admin.service.ts`             | `GET /api/v1/admin/users` (typed `AdminUser[]`).          |

 # Guards and interceptors

 | Symbol              | Path                                                          | Purpose                                                   |
 |---------------------|---------------------------------------------------------------|-----------------------------------------------------------|
-| `authGuard`         | `frontend/src/app/core/guards/auth.guard.ts`                  | Redirects to `/bootstrap` when uninitialized, `/login` when not authenticated. |
-| `adminGuard`        | `frontend/src/app/core/guards/admin.guard.ts`                 | Delegates to `decideAdminGuard` (pure). Redirects to `/bootstrap`, `/login`, or `/` based on state; allows only admins. |
+| `authGuard`         | `frontend/src/app/core/guards/auth.guard.ts`                  | Async `CanActivateFn`; awaits `BootstrapService.ready()` and `AuthService.waitUntilHydrated()`, then delegates to `decideAuthRedirect`. |
+| `decideAuthRedirect`| `frontend/src/app/core/guards/auth.guard.decision.ts`         | Pure decision function mirroring `decideAdminGuard`; redirects to `/bootstrap` or `/login`, returns `true` otherwise. |
+| `adminGuard`        | `frontend/src/app/core/guards/admin.guard.ts`                 | Async `CanActivateFn`; awaits bootstrap + auth hydration, then delegates to `decideAdminGuard` (pure). Redirects to `/bootstrap`, `/login`, or `/` based on state; allows only admins. |
 | `decideAdminGuard`  | `frontend/src/app/core/guards/admin.guard.decision.ts`        | Pure decision function: returns `{kind:'allow'}` or `{kind:'redirect', path}`. |
 | `authInterceptor`   | `frontend/src/app/core/interceptors/auth.interceptor.ts`      | Attaches `Authorization: Bearer <accessToken>` header.    |
 | `csrfInterceptor`   | `frontend/src/app/core/interceptors/csrf.interceptor.ts`      | Attaches `X-CSRF-Token` header on POST/PUT/PATCH/DELETE. |
@@ -55,7 +57,10 @@ Both interceptors are wired in `frontend/src/main.ts` via

 # Bootstrap flow

-1. `AppComponent.ngOnInit()` → `BootstrapService.load()`.
+1. `AppComponent.ngOnInit()` → `BootstrapService.load()` then
+   `AuthService.restoreSession()`. Both are deduplicated so concurrent
+   callers share a single in-flight promise (`loadPromise` /
+   `hydrateWaiters`).
 2. `BootstrapService` calls `GET /api/v1/bootstrap` (public, with
   `credentials: 'include'`).
 3. The payload sets `initialized` (true iff any admin user exists),
@@ -64,8 +69,16 @@ Both interceptors are wired in `frontend/src/main.ts` via
 4. Theme tokens are written to CSS custom properties on
   `document.documentElement` (`--color-primary`, `--font-family`,
   `--radius-*`, etc.) consumed by `frontend/src/styles.css`.
-5. The `authGuard` reads `BootstrapService.initialized()` and either
-   allows navigation or redirects to `/bootstrap`.
+5. `AuthService.restoreSession()` rehydrates the in-memory signals from
+   `sessionStorage` (key `hipctf.auth.v1`) and POSTs
+   `/api/v1/auth/refresh` with `withCredentials: true` to mint a fresh
+   access token. On success it persists the new token; on failure it
+   clears storage. Either way it flips `hydrated()` so the guards can
+   unblock.
+6. The `authGuard` (and `adminGuard`) `await` `BootstrapService.ready()`
+   and `AuthService.waitUntilHydrated()` before reading `initialized()`
+   / `isAuthenticated()`, which prevents a flash of `/bootstrap` or
+   `/login` on a hard refresh of a deep link.

 # Home shell flow

@@ -106,13 +106,15 @@ timestamp: 2026-07-21T15:05:00Z
 | `frontend/src/main.ts`                              | Bootstraps the standalone Angular app + registers interceptors.                |
 | `frontend/src/index.html`                           | Root HTML shell.                                                               |
 | `frontend/src/styles.css`                           | Global styles consuming theme CSS custom properties.                           |
-| `frontend/src/app/app.component.ts`                 | Root component; triggers bootstrap on init.                                    |
+| `frontend/src/app/app.component.ts`                 | Root component; triggers bootstrap then `AuthService.restoreSession()` on init. |
 | `frontend/src/app/app.routes.ts`                    | Angular route table (declares `/` shell with `adminGuard`-gated `/admin` child). |
-| `frontend/src/app/core/services/auth.service.ts`    | Signal store for access token + current user.                                 |
-| `frontend/src/app/core/services/bootstrap.service.ts` | Fetches `/api/v1/bootstrap` and applies theme tokens to CSS.                  |
+| `frontend/src/app/core/services/auth.service.ts`    | Signal store for access token + current user; persists to `sessionStorage`, exposes `restoreSession()` and `waitUntilHydrated()`. |
+| `frontend/src/app/core/services/auth.session-storage.ts` | Pure `sessionStorage` helpers (`readStoredSession`, `writeStoredSession`, `clearStoredSession`) under key `hipctf.auth.v1`. |
+| `frontend/src/app/core/services/bootstrap.service.ts` | Fetches `/api/v1/bootstrap`, applies theme tokens to CSS; `load()` / `ready()` deduplicate the in-flight fetch. |
 | `frontend/src/app/core/services/admin.service.ts`  | `GET /api/v1/admin/users` returning `AdminUser[]`.                            |
-| `frontend/src/app/core/guards/auth.guard.ts`        | `CanActivateFn` checking init + auth.                                          |
-| `frontend/src/app/core/guards/admin.guard.ts`       | `CanActivateFn` for admin-only routes; delegates to `decideAdminGuard`.        |
+| `frontend/src/app/core/guards/auth.guard.ts`        | Async `CanActivateFn`; awaits bootstrap + auth hydration, delegates to `decideAuthRedirect`. |
+| `frontend/src/app/core/guards/auth.guard.decision.ts` | Pure decision function for the auth guard (returns `true` or a redirect `UrlTree`). |
+| `frontend/src/app/core/guards/admin.guard.ts`       | Async `CanActivateFn` for admin-only routes; awaits bootstrap + auth hydration, delegates to `decideAdminGuard`. |
 | `frontend/src/app/core/guards/admin.guard.decision.ts` | Pure decision function for the admin guard (returns `allow` / `redirect`). |
 | `frontend/src/app/core/interceptors/auth.interceptor.ts` | Attaches Bearer header.                                                     |
 | `frontend/src/app/core/interceptors/csrf.interceptor.ts` | Attaches `X-CSRF-Token` on unsafe methods.                                  |
@@ -132,6 +134,8 @@ timestamp: 2026-07-21T15:05:00Z
 | `tests/frontend/theme.spec.ts`                 | Jest test for theme token application.                                         |
 | `tests/frontend/admin-shell.spec.ts`          | Unit tests for `shouldShowAdminNav` predicate.                                 |
 | `tests/frontend/admin-navigation.spec.ts`      | Tests for admin guard decision + nav-link rendering.                           |
+| `tests/frontend/auth-restore.spec.ts`         | Round-trips `auth.session-storage` helpers + refresh success/failure paths.    |
+| `tests/frontend/guard-bootstrap-race.spec.ts` | Pins `decideAuthRedirect` so a refresh on a deep link never flashes `/bootstrap` or `/login` while auth is hydrating. |
 | `tests/backend/csrf-client.ts`                 | Test helper for CSRF flow.                                                     |
 | `tests/backend/db-helper.ts`                   | Test helper for spinning up an isolated DB.                                    |

@@ -64,16 +64,23 @@ Browser  ──HTTPS──▶  NestJS process (PORT, default 3000)
   attaches the CSRF header on unsafe methods and the Bearer access
   token on every request.
 2. `provideRouter(APP_ROUTES, withComponentInputBinding())`.
-3. `AppComponent.ngOnInit()` calls `BootstrapService.load()` which
-   fetches `GET /api/v1/bootstrap` and applies the returned theme tokens
-   to CSS custom properties on `document.documentElement`.
+3. `AppComponent.ngOnInit()` calls `BootstrapService.load()` then
+   `AuthService.restoreSession()`. Bootstrap fetches `GET /api/v1/bootstrap`
+   and applies the returned theme tokens to CSS custom properties on
+   `document.documentElement`. Session restore rehydrates the in-memory
+   auth signals from `sessionStorage` and posts `POST /api/v1/auth/refresh`
+   with `withCredentials: true` so a hard refresh does not log the user out.
+4. Guards (`authGuard`, `adminGuard`) are async and `await`
+   `BootstrapService.ready()` + `AuthService.waitUntilHydrated()` before
+   reading state, so refreshing on a deep link never flashes `/bootstrap`
+   or `/login`.

 # Cross-cutting concepts

 | Concern        | Backend                                              | Frontend                                    |
 |----------------|------------------------------------------------------|---------------------------------------------|
-| Authentication | `JwtAuthGuard` (global) + `AuthGuard('jwt')` strategy | `AuthService` signal + `authInterceptor`    |
-| Authorization  | `AdminGuard` + `@Roles('admin')` decorator          | `authGuard` for `/`, `adminGuard` for `/admin` (delegates to pure `decideAdminGuard`) |
+| Authentication | `JwtAuthGuard` (global) + `AuthGuard('jwt')` strategy | `AuthService` signal + `authInterceptor`; session is mirrored to `sessionStorage` and rehydrated on boot via `/api/v1/auth/refresh` |
+| Authorization  | `AdminGuard` + `@Roles('admin')` decorator          | `authGuard` for `/`, `adminGuard` for `/admin` (both async, both delegate to pure decision functions: `decideAuthRedirect` / `decideAdminGuard`) |
 | CSRF           | `CsrfMiddleware` (skips `/api/v1/auth/login` and `/api/v1/auth/register-first-admin`) | `csrfInterceptor` reads `csrf` cookie |
 | Errors         | `ApiError` → `GlobalExceptionFilter` returns `{code, message, details, path, timestamp}` | Components display `error?.error?.message` |
 | Config         | `envSchema` (zod) + `validateEnv`                     | None (consumed via bootstrap)              |