@b01lers/ctfd-api 1.0.0 → 1.2.0

package/README.md

@@ -1,2 +1,57 @@
 # CTFd API
-A simple, typed API client for the CTFd API.
+A simple, typed client for the CTFd API.
+
+### Installing
+```bash
+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:
+```ts
+import { CTFdClient } from '@b01lers/ctfd-api';
+
+const client = new CTFdClient({
+    url: 'https://demo.ctfd.io/',
+    username: 'user',
+    password: 'password',
+});
+
+// Fetch challenges list
+const challs = await client.getChallenges();
+
+// Fetch scoreboard data
+const scoreboard = await client.getScoreboard();
+console.log(scoreboard.slice(0, 5));
+
+// 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/index.js

@@ -21,7 +21,7 @@ class CTFdClient {
   }
   async submitFlag(id, flag) {
     const { session, nonce } = await this.getAuthedSessionNonce();
-    return await (await fetch(`${this.url}/api/v1/challenges/attempt`, {
+    const res = await (await fetch(`${this.url}/api/v1/challenges/attempt`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -30,12 +30,24 @@ class CTFdClient {
       },
       body: JSON.stringify({ challenge_id: id, submission: flag })
     })).json();
+    return res.data;
   }
   async getChallenges() {
     const { session } = await this.getAuthedSessionNonce();
-    return await (await fetch(`${this.url}/api/v1/challenges`, {
+    const res = await (await fetch(`${this.url}/api/v1/challenges`, {
       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`, {
+      headers: {
+        "Csrf-Token": nonce,
+        cookie: session
+      }
+    })).json();
+    return res.data;
   }
   async getAuthedSessionNonce() {
     if (/* @__PURE__ */ new Date() < this.sessionExpiry && this.cachedSession && this.cachedNonce)

package/dist/types.d.ts

@@ -1,18 +1,28 @@
-type ScoreboardData = {
+type BaseScoreboardEntry = {
     pos: number;
     account_id: number;
     account_url: string;
-    account_type: "user";
     oauth_id: null;
     name: string;
     score: number;
     bracket_id: null;
     bracket_name: null;
 };
-type ChallengesResponse = {
-    success: true;
-    data: ChallengeData[];
+type ScoreboardUserEntry = BaseScoreboardEntry & {
+    account_type: "user";
+};
+type ScoreboardTeamEntry = BaseScoreboardEntry & {
+    account_type: "team";
+    members: {
+        id: number;
+        oauth_id: null;
+        name: string;
+        score: number;
+        bracket_id: null;
+        bracket_name: null;
+    }[];
 };
+type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
 type ChallengeData = {
     id: number;
     type: 'standard' | 'multiple_choice' | 'code';
@@ -25,13 +35,6 @@ type ChallengeData = {
     template: string;
     value: number;
 };
-type FlagSubmissionResponse = {
-    success: true;
-    data: {
-        status: "incorrect";
-        message: "Incorrect";
-    };
-};
 
 type ClientOptions = {
     url: string;
@@ -46,9 +49,16 @@ declare class CTFdClient {
     private cachedNonce;
     private sessionExpiry;
     constructor(options: ClientOptions);
-    submitFlag(id: number, flag: string): Promise<FlagSubmissionResponse>;
-    getChallenges(): Promise<ChallengesResponse>;
+    submitFlag(id: number, flag: string): Promise<{
+        status: "incorrect";
+        message: "Incorrect";
+    } | {
+        status: "correct";
+        message: "Correct";
+    }>;
+    getChallenges(): Promise<ChallengeData[]>;
+    getScoreboard(): Promise<ScoreboardEntry[]>;
     private getAuthedSessionNonce;
 }
 
-export { CTFdClient, type ChallengeData, type ScoreboardData };
+export { CTFdClient, type ChallengeData, type ScoreboardEntry };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@b01lers/ctfd-api",
-  "version": "1.0.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 } from './types';
+import type {
+    ChallengeDetailsResponse,
+    ChallengesResponse,
+    FlagSubmissionResponse,
+    ScoreboardResponse
+} from './types';
 
 
 type ClientOptions = {
@@ -26,7 +31,7 @@ export class CTFdClient {
     public async submitFlag(id: number, flag: string) {
         const { session, nonce } = await this.getAuthedSessionNonce();
 
-        return await (await fetch(`${this.url}/api/v1/challenges/attempt`, {
+        const res = await (await fetch(`${this.url}/api/v1/challenges/attempt`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -35,14 +40,41 @@ export class CTFdClient {
             },
             body: JSON.stringify({ challenge_id: id, submission: flag }),
         })).json() as FlagSubmissionResponse;
+
+        return res.data;
     }
 
     public async getChallenges() {
         const { session } = await this.getAuthedSessionNonce();
 
-        return await (await fetch(`${this.url}/api/v1/challenges`, {
+        const res = await (await fetch(`${this.url}/api/v1/challenges`, {
             headers: { cookie: session }
         })).json() as ChallengesResponse;
+
+        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();
+
+        const res = await (await fetch(`${this.url}/api/v1/scoreboard`, {
+            headers: {
+                'Csrf-Token': nonce,
+                cookie: session,
+            },
+        })).json() as ScoreboardResponse;
+
+        return res.data;
     }
 
     private async getAuthedSessionNonce() {
@@ -84,9 +116,3 @@ export class CTFdClient {
         };
     }
 }
-
-// export async function getScoreboard() {
-//     return await (await fetch('https://ectf.ctfd.io/api/v1/scoreboard', {
-//         headers: { 'Authorization': CTFD_API_KEY }
-//     })).json() as ScoreboardResponse;
-// }

package/src/index.ts

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

package/src/types.ts

@@ -1,13 +1,14 @@
-export type ScoreboardResponse = {
+type APISuccess<T> = {
     success: true,
-    data: ScoreboardData[],
+    data: T
 }
 
-export type ScoreboardData = {
+export type ScoreboardResponse = APISuccess<ScoreboardEntry[]>
+
+type BaseScoreboardEntry = {
     pos: number,
     account_id: number,
     account_url: string,
-    account_type: "user",
     oauth_id: null,
     name: string,
     score: number,
@@ -15,14 +16,30 @@ export type ScoreboardData = {
     bracket_name: null
 }
 
-export type ChallengesResponse = {
-    success: true,
-    data: ChallengeData[]
+type ScoreboardUserEntry = BaseScoreboardEntry & {
+    account_type: "user",
+}
+
+type ScoreboardTeamEntry = BaseScoreboardEntry & {
+    account_type: "team",
+    members: {
+        id: number,
+        oauth_id: null,
+        name: string,
+        score: number,
+        bracket_id: null,
+        bracket_name: null
+    }[]
 }
 
+export type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
+
+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,
@@ -33,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/build.js

@@ -8,9 +8,12 @@ const { CTFdClient } = require('../dist/index.js');
     });
 
     const challs = await client.getChallenges();
-    console.log(challs.data);
+    console.log(challs);
 
-    const chall = challs.data.find((c) => c.name === 'The Lost Park');
+    const scoreboard = await client.getScoreboard();
+    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}');
     console.log(res);
 })()

package/tests/demo.ts

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