docs: update documentation to OKF v0.1 format

2026-07-22 20:26:26 +00:00
parent 1a40e5708a
commit 6c18603a7d
8 changed files with 292 additions and 40 deletions
@@ -79,6 +79,107 @@ See [Admin — General Settings](/guides/admin-general-settings.md).
 | `PUT`    | `/api/v1/admin/categories/:id`      | Same.                                                           |
 | `DELETE` | `/api/v1/admin/categories/:id`      | Same.                                                           |

+See [Admin — Categories](/guides/admin-categories.md).
+
+## Challenges — `/api/v1/admin/challenges`
+
+| Method   | Path                                       | Source                                                                               |
+|----------|--------------------------------------------|--------------------------------------------------------------------------------------|
+| `GET`    | `/api/v1/admin/challenges`                 | `backend/src/modules/admin/admin-challenges.controller.ts`                           |
+| `GET`    | `/api/v1/admin/challenges/:id`             | Same.                                                                                |
+| `POST`   | `/api/v1/admin/challenges`                 | Same.                                                                                |
+| `PUT`    | `/api/v1/admin/challenges/:id`             | Same.                                                                                |
+| `DELETE` | `/api/v1/admin/challenges/:id`             | Same.                                                                                |
+| `GET`    | `/api/v1/admin/challenges/export`          | Same — JSON attachment `challenges-export-<ISO-date>.json`.                          |
+| `POST`   | `/api/v1/admin/challenges/import`          | Same — preview by default, `?confirm=overwrite` to commit.                            |
+| `POST`   | `/api/v1/admin/challenges/files/stage`     | Same — multipart upload that returns an opaque staging token.                        |
+| `DELETE` | `/api/v1/admin/challenges/files/stage/:token` | Same — discards a previously staged file.                                          |
+
+List response (admin-only, **never includes the secret flag**):
+
+```json
+{
+  "id": "uuid",
+  "name": "Welcome",
+  "categoryAbbreviation": "CRY",
+  "categoryIconPath": "/uploads/icons/CRY.png",
+  "difficulty": "MEDIUM",
+  "protocol": "WEB",
+  "enabled": true,
+  "createdAt": "2026-07-22T20:00:00.000Z",
+  "updatedAt": "2026-07-22T20:00:00.000Z",
+  "fileCount": 1,
+  "solveCount": 0
+}
+```
+
+Optional list query: `?q=substring&categoryId=uuid` (both optional).
+
+Detail response (admin-only, **may include plaintext `flag`**):
+
+```json
+{
+  "id": "uuid",
+  "name": "Welcome",
+  "descriptionMd": "...",
+  "categoryId": "uuid",
+  "categoryAbbreviation": "CRY",
+  "categoryIconPath": "/uploads/icons/CRY.png",
+  "difficulty": "MEDIUM",
+  "initialPoints": 100,
+  "minimumPoints": 50,
+  "decaySolves": 10,
+  "flag": "flag{...}",
+  "protocol": "WEB",
+  "port": null,
+  "ipAddress": "",
+  "enabled": true,
+  "createdAt": "...",
+  "updatedAt": "...",
+  "files": [
+    { "id": "uuid", "originalFilename": "readme.txt", "mimeType": "text/plain", "sizeBytes": 123, "createdAt": "..." }
+  ]
+}
+```
+
+Import document shape:
+
+```json
+{
+  "format": "hipctf-challenges",
+  "version": 1,
+  "exportedAt": "2026-07-22T20:00:00Z",
+  "challenges": [
+    {
+      "name": "...",
+      "descriptionMd": "...",
+      "categorySystemKey": "CRY",
+      "difficulty": "LOW|MEDIUM|HIGH",
+      "initialPoints": 100,
+      "minimumPoints": 50,
+      "decaySolves": 10,
+      "flag": "plaintext",
+      "protocol": "NC|WEB",
+      "port": 1337,
+      "ipAddress": "",
+      "files": [
+        { "originalFilename": "...", "mimeType": "...", "sizeBytes": 123, "dataBase64": "..." }
+      ]
+    }
+  ]
+}
+```
+
+Validation errors return `400 VALIDATION_FAILED` with stable codes
+(`CHALLENGE_NAME_TAKEN`, `CHALLENGE_INVALID_CATEGORY`,
+`IMPORT_VALIDATION_FAILED`, `IMPORT_PARTIAL_FAILURE`) and a
+`details[]` array of `{ path, message }` entries. Delete cascades
+`challenge_file` and `solve` rows inside one DB transaction;
+filesystem cleanup of the deleted challenge's files runs best-effort
+after the transaction commits.
+
+See [Admin — Challenges](/guides/admin-challenges.md).
+
 Behavior:

 * `GET` returns all categories sorted by `LOWER(abbreviation)` ascending.
@@ -12,7 +12,7 @@ timestamp: 2026-07-22T19:18:00Z
 |--------|---------------------------------------|-------|---------------------------------------------------------|
 | `POST` | `/api/v1/uploads/logo`                | Admin | `backend/src/modules/uploads/uploads.controller.ts`     |
 | `POST` | `/api/v1/uploads/category-icon`       | Admin | Same.                                                   |
-| `POST` | `/api/v1/uploads/challenge-file`      | Admin | Same.                                                   |
+| `POST` | `/api/v1/uploads/challenge-file`      | Admin | Same. *(Removed in Job 861 — challenge attachments now flow through `POST /api/v1/admin/challenges/files/stage` so they are only persisted on challenge save.)* |

 # Guard chain