148 lines
6.7 KiB
Markdown
148 lines
6.7 KiB
Markdown
# Implementation Plan: Job 848 — First-Start Create Admin Modal 1.07
|
|
|
|
## Status
|
|
|
|
**[ALREADY_IMPLEMENTED]**
|
|
|
|
The First-Start Create Admin Modal feature is fully implemented end-to-end in
|
|
this repository. The user-facing symptom reported in the job ("HIPCTF heading +
|
|
'Frontend not built.' paragraph, no bootstrap dialog, no form controls, no
|
|
submit button") is produced by the SPA fallback in
|
|
`backend/src/frontend/spa.controller.ts:27` whenever
|
|
`frontend/dist/browser/index.html` does not exist on disk at the moment
|
|
the request is served.
|
|
|
|
That `dist/browser/index.html` is now present (rebuilt during the current
|
|
session), so navigating to `http://localhost:3000/` will serve the Angular
|
|
SPA, which redirects to `/bootstrap` and renders the create-admin modal.
|
|
|
|
No source code changes, no schema changes, and no new tests are required.
|
|
|
|
## 1. Architectural Reconnaissance
|
|
|
|
- **Codebase style & conventions:**
|
|
- Monorepo with npm workspaces (`backend/`, `frontend/`).
|
|
- Backend: NestJS controllers + services, TypeORM repositories,
|
|
`@nestjs/config`, argon2 for password hashing, class-validator /
|
|
`ZodValidationPipe` for input, `ApiError` + `GlobalExceptionFilter`
|
|
for the uniform `{ code, message }` error envelope.
|
|
- Frontend: Angular 17+ standalone components, `ChangeDetectionStrategy.OnPush`,
|
|
Angular Signals, reactive forms (`ReactiveFormsModule`), HTTP via
|
|
`HttpClient` with `withCredentials: true`, separate
|
|
`BootstrapService` (initialised flag) and `AuthService` (session token).
|
|
- Persistence: SQLite via TypeORM, file path comes from
|
|
`process.env.DATABASE_PATH` (default `/data/hipctf/hipctf.db`),
|
|
`FRONTEND_DIST` env var names the built SPA directory.
|
|
- **Data Layer:** SQLite (TypeORM). No schema change is needed.
|
|
- **Test Framework & Structure:**
|
|
- Jest with two projects (`backend`, `frontend`) configured in
|
|
`tests/jest.config.js`.
|
|
- Backend tests use `ts-jest` against an in-memory SQLite DB
|
|
(`process.env.DATABASE_PATH = ':memory:'`) via
|
|
`tests/backend/db-helper.ts`.
|
|
- Frontend tests use `jest-environment-jsdom` with
|
|
`tests/frontend/jest.setup.ts` providing Angular `TestBed` +
|
|
`provideHttpClientTesting`.
|
|
- All tests live under `tests/` and run via a single root command:
|
|
`npm test` (alias for `jest --config tests/jest.config.js`).
|
|
- **Required Tools & Dependencies:** No new tools. Existing `npm run build`
|
|
in `setup.sh` rebuilds `frontend/dist/browser/index.html`, which is the
|
|
actual fix for the symptom. No new packages are required.
|
|
|
|
## 2. Impacted Files
|
|
|
|
- **To Modify:** None.
|
|
- **To Create:** None.
|
|
|
|
### Where the feature already lives (for reference / verification)
|
|
|
|
Backend:
|
|
- `backend/src/modules/setup/setup.module.ts`
|
|
- `backend/src/modules/setup/setup.controller.ts` — `POST /api/v1/setup/create-admin`.
|
|
- `backend/src/modules/setup/setup.service.ts:39-97` — `createAdmin()` inside a
|
|
TypeORM transaction with serialized bootstrap via `runBootstrap()`
|
|
(lines 99-130) — guarantees that two concurrent callers cannot both
|
|
observe an empty admin table; the loser gets
|
|
`409 SYSTEM_INITIALIZED`.
|
|
- `backend/src/modules/setup/dto/create-admin.dto.ts`
|
|
- `backend/src/common/errors/error-codes.ts` — `SYSTEM_INITIALIZED`,
|
|
`USERNAME_TAKEN`, `WEAK_PASSWORD`, `VALIDATION_FAILED`, `RATE_LIMITED`.
|
|
- `backend/src/frontend/spa.controller.ts:11-28` — SPA fallback that emits
|
|
the placeholder HTML **only** when no built `index.html` is found.
|
|
|
|
Frontend:
|
|
- `frontend/src/app/features/setup/setup-create-admin.component.ts` — the
|
|
modal component (`data-testid="setup-submit"`, `setup-retry`, etc.).
|
|
- `frontend/src/app/features/setup/setup-create-admin.component.html`
|
|
- `frontend/src/app/features/setup/setup-create-admin.component.css`
|
|
- `frontend/src/app/features/setup/setup-create-admin.service.ts` —
|
|
`POST /api/v1/setup/create-admin` with CSRF preflight + error mapping.
|
|
- `frontend/src/app/features/setup/setup-create-admin.validators.ts` —
|
|
`passwordMatchValidator`.
|
|
- `frontend/src/app/features/setup/setup-create-admin.field-errors.ts` —
|
|
pure helpers `usernameError`, `passwordError`, `confirmError`.
|
|
- `frontend/src/app/core/services/bootstrap.service.ts` — exposes
|
|
`initialized()`, `markInitialized()`, and `passwordPolicy()`.
|
|
- `frontend/src/app/core/services/auth.service.ts` — `setSession()` used
|
|
on success.
|
|
- `frontend/src/app/app.routes.ts` — `/bootstrap` route, guarded by
|
|
`authGuard` which redirects to `/bootstrap` while `initialized() === false`.
|
|
|
|
Existing tests that already cover this Job:
|
|
- `tests/backend/setup-create-admin.spec.ts`
|
|
- `tests/backend/bootstrap.integration.spec.ts`
|
|
- `tests/backend/registration-rate-limit.spec.ts`
|
|
- `tests/backend/api-error.spec.ts`
|
|
- `tests/frontend/setup-create-admin.spec.ts`
|
|
- `tests/frontend/guard-bootstrap-race.spec.ts`
|
|
- `tests/frontend/auth-restore.spec.ts`
|
|
|
|
## 3. Proposed Changes
|
|
|
|
No code changes. The only operational fix is to keep
|
|
`frontend/dist/browser/index.html` in place.
|
|
|
|
If a fresh container runs without it, `setup.sh` already invokes
|
|
`npm --workspace frontend run build` (line 11) which produces the Angular
|
|
bundle under `frontend/dist/browser/index.html`. The
|
|
`SpaFallbackMiddleware` looks for the file in both
|
|
`frontend/dist/index.html` and `frontend/dist/browser/index.html`, so the
|
|
standard build output is resolved without any extra wiring.
|
|
|
|
## 4. Test Strategy
|
|
|
|
No new tests. The relevant behaviour is already covered:
|
|
|
|
- **Backend:** `tests/backend/setup-create-admin.spec.ts` exercises
|
|
`POST /api/v1/setup/create-admin` happy path + each documented error
|
|
(`SYSTEM_INITIALIZED`, `USERNAME_TAKEN`, `WEAK_PASSWORD`,
|
|
`VALIDATION_FAILED`, `RATE_LIMITED`).
|
|
- **Backend concurrency:** the `runBootstrap()` chain in
|
|
`SetupService` is what serializes concurrent first-admin requests;
|
|
`tests/backend/bootstrap.integration.spec.ts` exercises the bootstrap
|
|
endpoint end-to-end.
|
|
- **Frontend:** `tests/frontend/setup-create-admin.spec.ts` covers the
|
|
modal's reactive form, server-error states, retry button, and the
|
|
post-success navigation. `tests/frontend/guard-bootstrap-race.spec.ts`
|
|
covers the `authGuard` redirect race with `BootstrapService`.
|
|
|
|
Run the existing suite from the repo root with:
|
|
|
|
```
|
|
npm test
|
|
```
|
|
|
|
## 5. Why this is reported as "not built"
|
|
|
|
`SpaFallbackMiddleware` (`backend/src/frontend/spa.controller.ts:27`)
|
|
sends:
|
|
|
|
```
|
|
<!doctype html><html><body><h1>HIPCTF</h1><p>Frontend not built.</p></body></html>
|
|
```
|
|
|
|
when neither `frontend/dist/index.html` nor `frontend/dist/browser/index.html`
|
|
exists. The Angular CLI's `application` builder writes to
|
|
`dist/browser/index.html`, so after `npm --workspace frontend run build`
|
|
the file is present and the SPA is served. The reported symptom was a
|
|
snapshot taken before the build artefact existed; rebuilding resolves it. |