HIPCTF2/docs/index.md

okf_version

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-23T15:46:55Z.

Architecture

• System Overview - High-level layout of the backend, frontend, and how they communicate.
• Backend Module Map - NestJS modules, controllers, services, and their wiring.
• Frontend Structure - Angular routes, components, services, guards, and stores (including the authenticated shell
  • signal stores).
• Key Files Index - One-line summary of every important source file in the repository.

Database

• Schema Overview - Tables, relationships, and indexes.
• User Table - user table schema and seed behavior.
• Challenge Tables - category, challenge, challenge_file, solve tables.
• Category Repair Migration - 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 - 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 - refresh_token and setting tables.
• Blog Post Table - blog_post table.
• Admin Operation Tokens Table - Single-use confirmation tokens for destructive System operations.
• Admin Operation Tokens Migration - Forward-only migration that adds the admin_operation_token table and its indexes.

API

• REST API Overview - Base URL, versioning, auth, CSRF, and error envelope.
• Auth Endpoints - Login, refresh, logout, CSRF, /me, /change-password, and first-admin registration.
• Setup Endpoint - Dedicated POST /api/v1/setup/create-admin used only while no administrator exists.
• Admin Endpoints - Admin-only endpoints covering user management, general settings (/api/v1/admin/general/*), and categories (/api/v1/admin/categories/*).
• Challenges Endpoints - Authenticated challenge board, detail, flag submission, event-state snapshot, and the combined /api/v1/events SSE stream.
• System Endpoints - Bootstrap, event status, public SSE streams, public event-window settings, and the authenticated /events/status SSE stream.
• Uploads Endpoints - Admin-only multipart uploads for category icons, challenge files, and validated site logos.
• Blog Endpoints - Public published-post listing and admin-only post CRUD, validation, and publication behavior.
• Admin System Endpoints - Admin-only backup download, restore validate/commit, re-authenticated confirmation tokens, reset-scores, and wipe-challenges.

Guides

• First-Run Bootstrap - How a fresh instance is initialized by the very first admin via the non-dismissible modal.
• Setup Form Field Errors - Pure helpers that translate reactive-form state into the inline validation messages on the first-admin modal.
• Admin Shell & Side Navigation - How admins navigate the post-login admin area side-nav and reach General, Challenges, Players, and Blog pages.
• Blog Publishing and Reading - How administrators create, preview, draft, publish, edit, and delete Markdown posts and how users read them.
• Admin — General Settings - How an admin edits platform-wide settings, including the required and strictly ordered event window, at /admin/general.
• Admin — Categories - How an admin lists, creates, edits, and deletes challenge categories at /admin/categories, including system-row and challenge-attached protection.
• Admin — Challenges - 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 - 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) - 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 - The header, LED
  • countdown, quick-jump tabs, user menu, and SSE lifecycle that frame every signed-in page.
• Challenges Board - 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 - 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 - How a signed-in user changes their own password, including every error branch and the refresh-token revocation behavior.
• Cross-Tab Authenticated Shell Invalidation - 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 - 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 - 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 - 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 - Public landing page (logo, welcome Markdown, blog list) and the login + registration modal rendered at /login once the instance is initialized.
• Theming - How canonical themes are listed for admins, persisted through general settings, and applied to CSS custom properties.
• Event Window - How the 4-state event window and live countdown work, including the authenticated SSE stream.
• Event LED Color Mapping - Source of truth for the shell status dot's color in each EventState.
• Scoreboard Stream - How live solves are broadcast to clients (public unauthenticated stream + authenticated /api/v1/events).
• Scoreboard Page - 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 - The root notification store + global HTTP error interceptor that translate backend error codes and statuses into friendly user-facing messages.