@b01lers/ctfd-api 1.1.0 → 1.2.0

package/README.md

@@ -6,6 +6,29 @@ A simple, typed client for the CTFd API.
 npm i @b01lers/ctfd-api
 ```
 
+### Motivation
+Nominally, CTFd maintains documentation about their API endpoints through their
+[API docs site](https://docs.ctfd.io/docs/api/redoc/). However, many response fields and request parameters remain
+undocumented.
+
+Furthermore, not every API endpoint is actually accessible through the `AccessToken`-based authorization
+documented on the site, and certain endpoints have missing or incorrect data when accessed with an `AccessToken`;
+notably,
+- The [flag submission endpoint](https://docs.ctfd.io/docs/api/redoc/#tag/challenges/operation/post_challenge_attempt) always returns 403 when requested without an authenticated session cookie.
+- The [challenge list endpoint](https://docs.ctfd.io/docs/api/redoc/#tag/challenges/operation/get_challenge_list) doesn't populate the `solved_by_me` field correctly when quested without an authenticated session cookie.
+
+Therefore, the client provided by this library is a "user bot" that uses your credentials to authenticate the way a
+regular user would.
+```ts
+const client = new CTFdClient({
+    url: 'https://demo.ctfd.io/',
+    username: 'user',
+    password: 'password',
+});
+```
+Many of the types used and exported by this library are reverse engineered from CTFd's client requests as well, and may
+likely be more comprehensive than what is documented on their official API docs above.
+
 ### Usage
 <!-- TODO: docs -->
 Example usage that fetches challenges from the CTFd demo instance and attempts to submit a flag for a challenge:
@@ -25,7 +48,10 @@ const challs = await client.getChallenges();
 const scoreboard = await client.getScoreboard();
 console.log(scoreboard.slice(0, 5));
 
-// Submit a flag for a challenge
+// Get details about a challenge, and submits a flag
 const chall = challs.find((c) => c.name === 'The Lost Park')!;
+const details = await client.getChallengeDetails(chall.id);
+console.log(details.description);
+
 await client.submitFlag(chall.id, 'cftd{test_flag}');
 ```

package/dist/types.d.ts

@@ -52,6 +52,9 @@ declare class CTFdClient {
     submitFlag(id: number, flag: string): Promise<{
         status: "incorrect";
         message: "Incorrect";
+    } | {
+        status: "correct";
+        message: "Correct";
     }>;
     getChallenges(): Promise<ChallengeData[]>;
     getScoreboard(): Promise<ScoreboardEntry[]>;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@b01lers/ctfd-api",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "An API client for CTFd.",
   "main": "dist/index.js",
   "types": "dist/types.d.ts",
+  "repository": "https://github.com/b01lers/ctfd-api.git",
   "scripts": {
     "build": "rollup --config"
   },

package/src/client.ts

@@ -1,5 +1,10 @@
 import { extractNonce } from './util';
-import type { ChallengesResponse, FlagSubmissionResponse, ScoreboardResponse } from './types';
+import type {
+    ChallengeDetailsResponse,
+    ChallengesResponse,
+    FlagSubmissionResponse,
+    ScoreboardResponse
+} from './types';
 
 
 type ClientOptions = {
@@ -49,6 +54,16 @@ export class CTFdClient {
         return res.data;
     }
 
+    public async getChallengeDetails(id: number) {
+        const { session } = await this.getAuthedSessionNonce();
+
+        const res = await (await fetch(`${this.url}/api/v1/challenges/${id}`, {
+            headers: { cookie: session }
+        })).json() as ChallengeDetailsResponse;
+
+        return res.data;
+    }
+
     public async getScoreboard() {
         const { session, nonce } = await this.getAuthedSessionNonce();
 

package/src/index.ts

@@ -1,2 +1,2 @@
 export { CTFdClient } from './client';
-export type { ScoreboardEntry, ChallengeData } from './types';
+export type { ScoreboardEntry, ChallengeType, ChallengeData, ChallengeDetails } from './types';

package/src/types.ts

@@ -1,8 +1,10 @@
-export type ScoreboardResponse = {
+type APISuccess<T> = {
     success: true,
-    data: ScoreboardEntry[],
+    data: T
 }
 
+export type ScoreboardResponse = APISuccess<ScoreboardEntry[]>
+
 type BaseScoreboardEntry = {
     pos: number,
     account_id: number,
@@ -32,14 +34,12 @@ type ScoreboardTeamEntry = BaseScoreboardEntry & {
 
 export type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
 
-export type ChallengesResponse = {
-    success: true,
-    data: ChallengeData[]
-}
+export type ChallengesResponse = APISuccess<ChallengeData[]>
 
+export type ChallengeType = 'standard' | 'multiple_choice' | 'code';
 export type ChallengeData = {
     id: number,
-    type: 'standard' | 'multiple_choice' | 'code',
+    type: ChallengeType,
     name: string,
     category: string,
     script: string,
@@ -50,10 +50,54 @@ export type ChallengeData = {
     value: number,
 }
 
-export type FlagSubmissionResponse = {
-    success: true,
-    data: {
-        status: "incorrect", // TODO
-        message: "Incorrect"
-    }
+export type ChallengeDetailsResponse = APISuccess<ChallengeDetails>;
+
+type BaseChallengeDetails = {
+    id: number,
+    name: string,
+    value: number,
+    description: string,
+    category: string,
+    state: "visible", // TODO
+    max_attempts: number,
+    type_data: {
+        id: ChallengeType,
+        name: ChallengeType,
+        templates: { create: string, update: string, view: string },
+        scripts: { create: string, update: string, view: string }
+    },
+    solves: number,
+    solved_by_me: boolean,
+    attempts: number,
+    files: string[],
+    tags: string[],
+    hints: string[],
+    view: string
+}
+
+type StandardChallengeDetails = BaseChallengeDetails & {
+    type: Exclude<ChallengeType, 'code'>
+    attribution: string | null,
+    connection_info: string | null,
+    next_id: number | null,
 }
+
+type ProgrammingChallengeDetails = BaseChallengeDetails & {
+    type: Extract<ChallengeType, 'code'>
+    language: string,
+    version: null,
+    output_enabled: null,
+}
+
+export type ChallengeDetails = StandardChallengeDetails | ProgrammingChallengeDetails;
+
+export type FlagSubmissionResponse = APISuccess<{
+    status: 'incorrect',
+    message: 'Incorrect'
+} | {
+    status: 'correct',
+    message: 'Correct'
+} | {
+    status: 'already_solved',
+    message: 'You already solved this'
+}>

package/tests/demo.ts

@@ -15,6 +15,9 @@ import { CTFdClient } from '../src/client';
     console.log(scoreboard.slice(0, 5));
 
     const chall = challs.find((c) => c.name === 'The Lost Park')!;
-    const res = await client.submitFlag(chall.id, 'cftd{test_flag}');
+    const details = await client.getChallengeDetails(chall.id);
+    console.log(details);
+
+    const res = await client.submitFlag(chall.id, 'Major Mark Park');
     console.log(res);
 })()