|
|
|
@@ -0,0 +1,133 @@
|
|
|
|
|
---
|
|
|
|
|
type: database
|
|
|
|
|
title: Seed Sample Challenges Migration (1700000000600)
|
|
|
|
|
description: Forward-only migration that inserts a representative sample set of challenges on a fresh database so the /challenges board renders cards without manual admin action.
|
|
|
|
|
tags: [database, migration, challenge, seed, sample]
|
|
|
|
|
timestamp: 2026-07-23T02:23:34Z
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Purpose
|
|
|
|
|
|
|
|
|
|
A brand-new HIPCTF database (default path
|
|
|
|
|
[`./data/db.sqlite`](/database/schema.md)) has no `challenge` rows until
|
|
|
|
|
an admin imports or creates them. The
|
|
|
|
|
`SeedSampleChallenges1700000000600` migration bridges that gap by
|
|
|
|
|
inserting a small, representative sample set so the authenticated
|
|
|
|
|
`/challenges` board (see [Challenges Board](/guides/challenges-board.md))
|
|
|
|
|
already has cards on the very first visit and the public landing can
|
|
|
|
|
demonstrate the platform with real content.
|
|
|
|
|
|
|
|
|
|
The migration runs at the end of the `MIGRATIONS` array in
|
|
|
|
|
[`DatabaseModule`](/architecture/backend-modules.md) so every other
|
|
|
|
|
category / challenge schema migration has already landed and the
|
|
|
|
|
`category` rows it joins against are present.
|
|
|
|
|
|
|
|
|
|
# File
|
|
|
|
|
|
|
|
|
|
`backend/src/database/migrations/1700000000600-SeedSampleChallenges.ts`
|
|
|
|
|
|
|
|
|
|
Registered last in `backend/src/database/database.module.ts` so it
|
|
|
|
|
runs after `UpgradeChallengeAdminSchema1700000000500`.
|
|
|
|
|
|
|
|
|
|
# Sample set
|
|
|
|
|
|
|
|
|
|
Eight challenges, one or more per canonical system category. Source
|
|
|
|
|
of truth is the typed `SAMPLE_CHALLENGES` array exported by the
|
|
|
|
|
migration:
|
|
|
|
|
|
|
|
|
|
| Name | `system_key` | Difficulty | `initial_points` | `minimum_points` | `decay_solves` | Flag |
|
|
|
|
|
|-------------------|--------------|------------|------------------|------------------|----------------|--------------|
|
|
|
|
|
| Alpha Cipher | `CRY` | `LOW` | 200 | 100 | 5 | `flag{alpha}` |
|
|
|
|
|
| Beta Cipher | `CRY` | `MEDIUM` | 300 | 100 | 10 | `flag{beta}` |
|
|
|
|
|
| Zeta Key | `CRY` | `HIGH` | 500 | 100 | 10 | `flag{zeta}` |
|
|
|
|
|
| Web Welcome | `WEB` | `LOW` | 100 | 50 | 10 | `flag{web1}` |
|
|
|
|
|
| Mobile Mayhem | `PWN` | `MEDIUM` | 300 | 100 | 10 | `flag{mob1}` |
|
|
|
|
|
| Hardware Hello | `HW` | `LOW` | 100 | 50 | 10 | `flag{hw1}` |
|
|
|
|
|
| Markdown Mystery | `MSC` | `LOW` | 100 | 50 | 10 | `flag{md}` |
|
|
|
|
|
| Reverse Ranger | `REV` | `MEDIUM` | 300 | 100 | 10 | `flag{rev1}` |
|
|
|
|
|
|
|
|
|
|
All rows are inserted with `protocol='WEB'`, `port=NULL`,
|
|
|
|
|
`ip_address=''`, and `enabled=1` so they appear on the board the
|
|
|
|
|
moment the event window opens (see [Event Window](/guides/event-window.md)).
|
|
|
|
|
Categories are resolved by `system_key` rather than UUID so the seed
|
|
|
|
|
works regardless of the UUIDs the category migration assigned at
|
|
|
|
|
install time. Sample flags follow the `flag{<token>}` convention and
|
|
|
|
|
are exposed only inside admin views — the public challenge DTO
|
|
|
|
|
continues to strip them (see [Challenges Endpoints](/api/challenges.md)).
|
|
|
|
|
|
|
|
|
|
# What the `up()` does
|
|
|
|
|
|
|
|
|
|
1. **Idempotency guard** — `SELECT COUNT(*) FROM "challenge"`. If the
|
|
|
|
|
table already contains rows the migration returns immediately; an
|
|
|
|
|
admin that imported a custom challenge set first is never
|
|
|
|
|
overwritten.
|
|
|
|
|
2. **System-category lookup** —
|
|
|
|
|
`SELECT id, system_key FROM "category" WHERE system_key IS NOT NULL`
|
|
|
|
|
and builds an in-memory `Map<system_key, id>`. If fewer than six
|
|
|
|
|
canonical keys are present (the seed cannot bind) the migration
|
|
|
|
|
aborts as a no-op rather than inserting challenges into the wrong
|
|
|
|
|
category.
|
|
|
|
|
3. **Insert sample rows** — for each entry in `SAMPLE_CHALLENGES`, an
|
|
|
|
|
`INSERT INTO "challenge"` with a fresh UUID v4, ISO 8601
|
|
|
|
|
`created_at` / `updated_at` via `strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
|
|
|
|
|
and `enabled=1`. Categories without a matching `system_key` are
|
|
|
|
|
silently skipped (defensive — only happens if the canonical six
|
|
|
|
|
are missing).
|
|
|
|
|
|
|
|
|
|
# Idempotency
|
|
|
|
|
|
|
|
|
|
* Running the migration twice (or restarting after it has been
|
|
|
|
|
recorded) leaves the same eight rows. The early-return count
|
|
|
|
|
guard skips the second run.
|
|
|
|
|
* Re-running the migration after a custom `challenge` row exists also
|
|
|
|
|
no-ops, so manually-imported content from the
|
|
|
|
|
[Admin — Challenges Full-Replace Import](/guides/admin-challenges-import.md)
|
|
|
|
|
flow is preserved.
|
|
|
|
|
|
|
|
|
|
# `down()`
|
|
|
|
|
|
|
|
|
|
Scoped to the seeded set: `DELETE FROM "challenge" WHERE "name" IN (...)`
|
|
|
|
|
using the eight fixed names from `SAMPLE_CHALLENGES`. It deliberately
|
|
|
|
|
matches **only** the sample names so unrelated admin rows are not
|
|
|
|
|
removed.
|
|
|
|
|
|
|
|
|
|
# Tests
|
|
|
|
|
|
|
|
|
|
| File | What it asserts |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `tests/backend/migrations.spec.ts` — *"seeds sample challenges on a fresh database (Job 906)"* | After all migrations run on an in-memory SQLite DB, the eight expected sample names are present. |
|
|
|
|
|
| `tests/backend/migrations.spec.ts` — *"seeded sample challenges are enabled, schema-compatible, and point at the right categories (Job 906)"* | Every seeded row has `enabled=true`, a valid `difficulty`, `initial_points >= minimum_points`, a non-empty `flag`, and a `category_id` that resolves to one of the six canonical system categories. |
|
|
|
|
|
| `tests/backend/migrations.spec.ts` — *"SeedSampleChallenges down() scope (Job 906)"* | `down()` removes only rows whose name is in the seed list and leaves manually-inserted rows of similar names (e.g. `Other`) intact. |
|
|
|
|
|
| `tests/backend/challenges-board.spec.ts` | Board-listing test now allows extra seeded cards inside the CRY column (`Alpha Cipher`, `Beta Cipher`, `Zeta Key`) while still asserting that the hand-inserted `alphacipher` LOW and `Zeta-key` HIGH rows occupy the bookended slots and that the disabled `hidden` row is excluded. |
|
|
|
|
|
|
|
|
|
|
# Operational notes
|
|
|
|
|
|
|
|
|
|
* On a fresh database the seed fires before the first app boot, so
|
|
|
|
|
[`GET /api/v1/challenges/board`](/api/challenges.md) returns the
|
|
|
|
|
sample columns immediately and the player-facing [Challenges Board](/guides/challenges-board.md)
|
|
|
|
|
shows eight cards. An admin deleting every challenge is the only
|
|
|
|
|
way to reach an empty board.
|
|
|
|
|
* To confirm on the command line after `npm run setup`:
|
|
|
|
|
```
|
|
|
|
|
sqlite3 ./data/db.sqlite 'SELECT COUNT(*) FROM challenge;'
|
|
|
|
|
```
|
|
|
|
|
Expected count: `8`. Re-running setup on a populated DB leaves the
|
|
|
|
|
count unchanged (idempotent guard).
|
|
|
|
|
* Played flags are usable for end-to-end demos: e.g. submitting
|
|
|
|
|
`flag{alpha}` against the Alpha Cipher card immediately awards
|
|
|
|
|
points and broadcasts the solve on the
|
|
|
|
|
[Scoreboard Stream](/guides/scoreboard-stream.md).
|
|
|
|
|
|
|
|
|
|
# See also
|
|
|
|
|
|
|
|
|
|
* [Database Schema Overview](/database/schema.md) — full migration list
|
|
|
|
|
and bootstrap behavior.
|
|
|
|
|
* [Challenge Tables](/database/challenges.md) — `challenge` schema,
|
|
|
|
|
indexes, and provenance.
|
|
|
|
|
* [Challenges Endpoints](/api/challenges.md) — board query and flag
|
|
|
|
|
submission.
|
|
|
|
|
* [Challenges Board](/guides/challenges-board.md) — user-facing guide.
|
|
|
|
|
* [Admin — Challenges](/guides/admin-challenges.md) — how an admin
|
|
|
|
|
replaces or extends the sample set.
|
|
|
|
|
* [Category Repair Migration](/database/category-repair-migration.md)
|
|
|
|
|
— earlier canonical-six migration this seed depends on.
|
OpenVelo Agent