From 6210cdb6de0821449af14451bb3b46f9ea04e8aa Mon Sep 17 00:00:00 2001 From: OpenVelo Agent Date: Tue, 21 Jul 2026 16:25:36 +0000 Subject: [PATCH] docs: update documentation to OKF v0.1 format --- docs/api/setup.md | 2 +- docs/architecture/frontend-structure.md | 6 +++--- docs/guides/bootstrap.md | 20 +++++++++++--------- docs/index.md | 2 +- 4 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/api/setup.md b/docs/api/setup.md index 26ec4f5..d3c1cea 100644 --- a/docs/api/setup.md +++ b/docs/api/setup.md @@ -3,7 +3,7 @@ type: api title: Setup Endpoint description: Dedicated POST /api/v1/setup/create-admin endpoint used only while no administrator exists. tags: [api, setup, bootstrap, first-admin] -timestamp: 2026-07-21T14:43:00Z +timestamp: 2026-07-21T16:23:40Z --- # Endpoint diff --git a/docs/architecture/frontend-structure.md b/docs/architecture/frontend-structure.md index 3ddcdc9..73da60f 100644 --- a/docs/architecture/frontend-structure.md +++ b/docs/architecture/frontend-structure.md @@ -12,7 +12,7 @@ Routes live in `frontend/src/app/app.routes.ts`: | Path | Component | Guard | Notes | |--------------|----------------------------------|---------------|----------------------------------------| -| `/bootstrap` | `SetupCreateAdminComponent` | — | Rendered only when `initialized === false`. Non-dismissible modal overlay. | +| `/bootstrap` | `SetupCreateAdminComponent` | — | Lazy-loaded first-admin creation route. Non-dismissible modal overlay while `initialized === false`; successful creation navigates to `/admin`. | | `/login` | `LoginComponent` | — | Standard login form. | | `/` | `HomeComponent` (shell) | `authGuard` | Requires auth + initialized. Hosts a `` for child routes. | | `/admin` | `AdminUsersComponent` | `adminGuard` | Child of `/`; requires `role === 'admin'`. | @@ -29,7 +29,7 @@ All components are standalone (no NgModules). Each component imports | `HomeComponent` | `frontend/src/app/features/home/home.component.ts` | Authenticated shell with header, conditional admin nav, and `` 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. | -| `SetupCreateAdminComponent` | `frontend/src/app/features/setup/setup-create-admin.component.ts` | First-admin bootstrap modal (non-dismissible, typed reactive forms). | +| `SetupCreateAdminComponent` | `frontend/src/app/features/setup/setup-create-admin.component.ts` | First-admin bootstrap modal with typed reactive form, validation messages, retry handling, session initialization, and redirect to `/admin`. | # Services @@ -38,7 +38,7 @@ All components are standalone (no NgModules). Each component imports | `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[]`). | +| `SetupCreateAdminService` | `frontend/src/app/features/setup/setup-create-admin.service.ts` | Preflights the CSRF cookie, calls `POST /api/v1/setup/create-admin`, and normalizes success/failure responses. | # Guards and interceptors diff --git a/docs/guides/bootstrap.md b/docs/guides/bootstrap.md index 58942aa..c959f2b 100644 --- a/docs/guides/bootstrap.md +++ b/docs/guides/bootstrap.md @@ -3,7 +3,7 @@ type: guide title: First-Run Bootstrap description: How a fresh HIPCTF instance is initialized by the very first administrator. tags: [guide, bootstrap, first-admin, onboarding, tester] -timestamp: 2026-07-21T16:09:53Z +timestamp: 2026-07-21T16:23:40Z --- # When this flow runs @@ -32,16 +32,18 @@ bypassed. 3. The app redirects to `/bootstrap` and shows the **"Welcome to HIPCTF — Create the first administrator"** modal. 4. Fill in the three fields and submit: - - **Username** — 3–32 chars, letters/digits/`.`/`-`/`_` only. Helper - text is shown via `data-testid="setup-username-error"` when the - pattern fails. + - **Username** — 3–32 chars, letters/digits/`.`/`-`/`_` only. The + username field displays inline validation after it is touched. - **Password** — must satisfy the policy shown directly below the field (default: 12 chars with upper, lower, digit, symbol). - - **Confirm Password** — must equal the password above (verified by - the group-level `passwordMatchValidator`; mismatch shows - `data-testid="setup-confirm-error"`). -5. Click **Create admin** (`data-testid="setup-submit"`). The button remains enabled while the form is invalid so this validation flow can be triggered; it is disabled only while a submission is in progress. -6. To verify client-side validation, submit with empty or partial fields. The overlay stays open, the relevant field errors appear, and no administrator is created or setup request is sent. + - **Confirm Password** — must equal the password above; mismatch displays + an inline error. +5. Click **Create admin** (`data-testid="setup-submit"`). The button is + disabled only while a submission is in progress and shows **Creating...** + with a spinner during that request. +6. To verify client-side validation, submit with empty or partial fields. The + overlay stays open, the relevant field errors appear, and no administrator + is created or setup request is sent. # Expected behavior diff --git a/docs/index.md b/docs/index.md index e7c7d5f..0f07ac9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ scoreboard, an event window with a public countdown, theming, and admin controls. The docs below are organized by purpose so agents can pull just the slice -they need. Last regenerated 2026-07-21T16:09:53Z. +they need. Last regenerated 2026-07-21T16:23:40Z. # Architecture