@b01lers/ctfd-api 1.1.0 → 1.2.1

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 submit a flag
 const chall = challs.find((c) => c.name === 'The Lost Park')!;
-await client.submitFlag(chall.id, 'cftd{test_flag}');
+const details = await client.getChallengeDetails(chall.id);
+console.log(details.description);
+
+await client.submitFlag(chall.id, 'ctfd{test_flag}');
 ```

package/dist/index.js

@@ -39,6 +39,13 @@ class CTFdClient {
     })).json();
     return res.data;
   }
+  async getChallengeDetails(id) {
+    const { session } = await this.getAuthedSessionNonce();
+    const res = await (await fetch(`${this.url}/api/v1/challenges/${id}`, {
+      headers: { cookie: session }
+    })).json();
+    return res.data;
+  }
   async getScoreboard() {
     const { session, nonce } = await this.getAuthedSessionNonce();
     const res = await (await fetch(`${this.url}/api/v1/scoreboard`, {

package/dist/types.d.ts

@@ -5,8 +5,8 @@ type BaseScoreboardEntry = {
     oauth_id: null;
     name: string;
     score: number;
-    bracket_id: null;
-    bracket_name: null;
+    bracket_id: number | null;
+    bracket_name: string | null;
 };
 type ScoreboardUserEntry = BaseScoreboardEntry & {
     account_type: "user";
@@ -23,9 +23,10 @@ type ScoreboardTeamEntry = BaseScoreboardEntry & {
     }[];
 };
 type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
+type ChallengeType = 'standard' | 'multiple_choice' | 'code';
 type ChallengeData = {
     id: number;
-    type: 'standard' | 'multiple_choice' | 'code';
+    type: ChallengeType;
     name: string;
     category: string;
     script: string;
@@ -35,6 +36,49 @@ type ChallengeData = {
     template: string;
     value: number;
 };
+type BaseChallengeDetails = {
+    id: number;
+    name: string;
+    value: number;
+    description: string;
+    category: string;
+    state: "visible";
+    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;
+};
+type ChallengeDetails = StandardChallengeDetails | ProgrammingChallengeDetails;
 
 type ClientOptions = {
     url: string;
@@ -52,10 +96,23 @@ declare class CTFdClient {
     submitFlag(id: number, flag: string): Promise<{
         status: "incorrect";
         message: "Incorrect";
+    } | {
+        status: "correct";
+        message: "Correct";
+    } | {
+        status: "already_solved";
+        message: "You already solved this";
+    } | {
+        status: "paused";
+        message: `${string} is paused`;
+    } | {
+        status: "ratelimited";
+        message: "You're submitting flags too fast. Slow down.";
     }>;
     getChallenges(): Promise<ChallengeData[]>;
+    getChallengeDetails(id: number): Promise<ChallengeDetails>;
     getScoreboard(): Promise<ScoreboardEntry[]>;
     private getAuthedSessionNonce;
 }
 
-export { CTFdClient, type ChallengeData, type ScoreboardEntry };
+export { CTFdClient, type ChallengeData, type ChallengeDetails, type ChallengeType, type ScoreboardEntry };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@b01lers/ctfd-api",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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,
@@ -10,8 +12,8 @@ type BaseScoreboardEntry = {
     oauth_id: null,
     name: string,
     score: number,
-    bracket_id: null,
-    bracket_name: null
+    bracket_id: number | null,
+    bracket_name: string | null  // e.g. "Open Bracket"
 }
 
 type ScoreboardUserEntry = BaseScoreboardEntry & {
@@ -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,60 @@ 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'
+} | {
+    status: 'paused',
+    message: `${string} is paused`
+} | {
+    status: 'ratelimited',
+    message: 'You\'re submitting flags too fast. Slow down.'
+}>

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);
 })()

package/tests/rate-limit.ts

@@ -0,0 +1,19 @@
+import { CTFdClient } from '../src/client';
+
+
+;(async () => {
+    const client = new CTFdClient({
+        url: 'https://demo.ctfd.io/',
+        username: 'user',
+        password: 'password',
+    });
+
+    const chall = (await client.getChallenges()).find((c) => c.name === 'Too Many Puppers')!;
+
+    const res = await client.submitFlag(chall.id, 'test');
+    console.log(res);
+
+    for (let i = 0; i < 20; i++) {
+        console.log(await client.submitFlag(chall.id, 'test'));
+    }
+})()