150 lines
8.4 KiB
Markdown
150 lines
8.4 KiB
Markdown
---
|
||
okf_version: "0.1"
|
||
---
|
||
|
||
# HIPCTF Documentation
|
||
|
||
HIPCTF is a single-tenant CTF (Capture-The-Flag) platform built as a Node.js
|
||
monorepo containing a NestJS REST API and an Angular single-page application.
|
||
It supports user registration, authentication, challenge management, a live
|
||
scoreboard, an event window with a public countdown, theming, and admin
|
||
controls, administrator-managed Markdown blog publishing, and public and
|
||
signed-in blog views.
|
||
|
||
The docs below are organized by purpose so agents can pull just the slice
|
||
they need. Last regenerated 2026-07-23T16:10:00Z.
|
||
|
||
# Architecture
|
||
|
||
* [System Overview](/architecture/overview.md) - High-level layout of the
|
||
backend, frontend, and how they communicate.
|
||
* [Backend Module Map](/architecture/backend-modules.md) - NestJS modules,
|
||
controllers, services, and their wiring.
|
||
* [Frontend Structure](/architecture/frontend-structure.md) - Angular routes,
|
||
components, services, guards, and stores (including the authenticated shell
|
||
+ signal stores).
|
||
* [Key Files Index](/architecture/key-files.md) - One-line summary of every
|
||
important source file in the repository.
|
||
* [System Category Icon Seed](/architecture/system-category-icons.md) -
|
||
Idempotent startup hook that writes deterministic 128×128 PNGs for
|
||
CRY/HW/MSC/PWN/REV/WEB into `UPLOAD_DIR/icons` so freshly cloned
|
||
instances never serve 404 icons.
|
||
|
||
# Database
|
||
|
||
* [Schema Overview](/database/schema.md) - Tables, relationships, and indexes.
|
||
* [User Table](/database/users.md) - `user` table schema and seed behavior.
|
||
* [Challenge Tables](/database/challenges.md) - `category`, `challenge`,
|
||
`challenge_file`, `solve` tables.
|
||
* [Category Repair Migration](/database/category-repair-migration.md) -
|
||
Forward-only migration that adds `created_at`/`updated_at` to legacy
|
||
`category` tables and reconciles system rows to the canonical
|
||
CRY/HW/MSC/PWN/REV/WEB set.
|
||
* [Seed Sample Challenges Migration](/database/seed-sample-challenges-migration.md) -
|
||
Forward-only migration that inserts a representative sample set of
|
||
challenges on a fresh database so the `/challenges` board has cards
|
||
immediately, with idempotency guards and scoped `down()`.
|
||
* [Auth and Settings Tables](/database/auth-settings.md) - `refresh_token`
|
||
and `setting` tables.
|
||
* [Blog Post Table](/database/blog-posts.md) - `blog_post` table.
|
||
* [Admin Operation Tokens Table](/database/admin-operation-tokens.md) -
|
||
Single-use confirmation tokens for destructive System operations.
|
||
* [Admin Operation Tokens Migration](/database/admin-operation-tokens-migration.md) -
|
||
Forward-only migration that adds the `admin_operation_token` table
|
||
and its indexes.
|
||
|
||
# API
|
||
|
||
* [REST API Overview](/api/rest-overview.md) - Base URL, versioning, auth,
|
||
CSRF, and error envelope.
|
||
* [Auth Endpoints](/api/auth.md) - Login, refresh, logout, CSRF, `/me`,
|
||
`/change-password`, and first-admin registration.
|
||
* [Setup Endpoint](/api/setup.md) - Dedicated `POST /api/v1/setup/create-admin`
|
||
used only while no administrator exists.
|
||
* [Admin Endpoints](/api/admin.md) - Admin-only endpoints covering user
|
||
management, general settings (`/api/v1/admin/general/*`), and
|
||
categories (`/api/v1/admin/categories/*`).
|
||
* [Challenges Endpoints](/api/challenges.md) - Authenticated challenge board,
|
||
detail, flag submission, event-state snapshot, and the combined
|
||
`/api/v1/events` SSE stream.
|
||
* [System Endpoints](/api/system.md) - Bootstrap, event status, public SSE
|
||
streams, public event-window settings, and the authenticated
|
||
`/events/status` SSE stream.
|
||
* [Uploads Endpoints](/api/uploads.md) - Admin-only multipart uploads for category icons, challenge files, and validated site logos.
|
||
* [Blog Endpoints](/api/blog.md) - Public published-post listing and admin-only post CRUD, validation, and publication behavior.
|
||
* [Admin System Endpoints](/api/admin-system.md) - Admin-only backup
|
||
download, restore validate/commit, re-authenticated confirmation
|
||
tokens, reset-scores, and wipe-challenges.
|
||
|
||
# Guides
|
||
|
||
* [First-Run Bootstrap](/guides/bootstrap.md) - How a fresh instance is
|
||
initialized by the very first admin via the non-dismissible modal.
|
||
* [Setup Form Field Errors](/guides/setup-field-errors.md) - Pure
|
||
helpers that translate reactive-form state into the inline validation
|
||
messages on the first-admin modal.
|
||
* [Admin Shell & Side Navigation](/guides/admin-shell.md) - How admins
|
||
navigate the post-login admin area side-nav and reach General,
|
||
Challenges, Players, and Blog pages.
|
||
* [Blog Publishing and Reading](/guides/blog.md) - How administrators create, preview, draft, publish, edit, and delete Markdown posts and how users read them.
|
||
* [Admin — General Settings](/guides/admin-general-settings.md) - How an
|
||
admin edits platform-wide settings, including the required and strictly
|
||
ordered event window, at `/admin/general`.
|
||
* [Admin — Categories](/guides/admin-categories.md) - How an admin lists,
|
||
creates, edits, and deletes challenge categories at `/admin/categories`,
|
||
including system-row and challenge-attached protection.
|
||
* [Admin — Challenges](/guides/admin-challenges.md) - How an admin lists,
|
||
searches, creates, edits, deletes, imports, and exports challenges at
|
||
`/admin/challenges`, including file staging and overwrite confirm.
|
||
* [Admin — Challenges Full-Replace Import](/guides/admin-challenges-import.md) -
|
||
Transactional full-replace semantics, side effects, and the auto-close
|
||
contract of the confirmed challenges import on `/admin/challenges`.
|
||
* [Admin — System (Backup, Restore, Danger Zone)](/guides/admin-system-page.md) -
|
||
How an admin navigates to `/admin/system`, creates a backup, stages
|
||
and commits a restore, resets all scores, and wipes challenges,
|
||
including the re-authentication confirmation flow and cross-tab
|
||
invalidation.
|
||
* [Authenticated Shell](/guides/authenticated-shell.md) - The header, LED
|
||
+ countdown, quick-jump tabs, user menu, and SSE lifecycle that frame
|
||
every signed-in page.
|
||
* [Challenges Board](/guides/challenges-board.md) - How a signed-in
|
||
player navigates `/challenges`, opens the modal, submits a flag, and
|
||
watches live solve updates.
|
||
* [Per-User `solvedByMe` Across the Session Boundary](/guides/challenges-per-user-state.md) -
|
||
How `ChallengesStore`, `HomeComponent`, and the challenges page
|
||
cooperate so PlayerA's `solvedByMe` flags never leak into PlayerB's
|
||
view across logout/login or peer-tab invalidation.
|
||
* [Change Password](/guides/change-password.md) - How a signed-in user
|
||
changes their own password, including every error branch and the
|
||
refresh-token revocation behavior.
|
||
* [Cross-Tab Authenticated Shell Invalidation](/guides/cross-tab-invalidation.md) -
|
||
How a logout in one tab, or an unauthorized SSE response, instantly clears
|
||
and redirects every other open tab of the SPA.
|
||
* [Cross-Tab Role Change Sync](/guides/cross-tab-role-change.md) -
|
||
How a role change at `/admin/players` propagates to every other open tab,
|
||
plus the LAST_ADMIN invariant under concurrent admin demotions.
|
||
* [Local Development Workflow](/guides/dev-workflow.md) - How to run the
|
||
backend and frontend together (`npm run dev`), the Angular dev-server
|
||
proxy, and the project-local `./data/` directory.
|
||
* [Session Restoration on Reload](/guides/session-restoration.md) - How
|
||
the SPA keeps a user signed in across hard refreshes and how the
|
||
guards wait for bootstrap + auth hydration before deciding where to
|
||
route.
|
||
* [Landing Page](/guides/landing-page.md) - Public landing page
|
||
(logo, welcome Markdown, blog list) and the login + registration modal
|
||
rendered at `/login` once the instance is initialized.
|
||
* [Theming](/guides/theming.md) - How canonical themes are listed for admins, persisted through general settings, and applied to CSS custom properties.
|
||
* [Event Window](/guides/event-window.md) - How the 4-state event
|
||
window and live countdown work, including the authenticated SSE stream.
|
||
* [Event LED Color Mapping](/guides/event-led-colors.md) - Source of
|
||
truth for the shell status dot's color in each `EventState`.
|
||
* [Scoreboard Stream](/guides/scoreboard-stream.md) - How live solves are
|
||
broadcast to clients (public unauthenticated stream + authenticated
|
||
`/api/v1/events`).
|
||
* [Scoreboard Page](/guides/scoreboard-page.md) - How a signed-in player
|
||
navigates `/scoreboard`, uses the 4 tabs, verifies collision-resolved
|
||
colors for up to ten visible players, and watches live solve updates.
|
||
* [Notifications](/guides/notifications.md) - The root notification
|
||
store + global HTTP error interceptor that translate backend error
|
||
codes and statuses into friendly user-facing messages.
|