@b01lers/ctfd-api 1.0.0 → 1.1.0

package/README.md

@@ -1,2 +1,31 @@
 # 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
+```
+
+### 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));
+
+// Submit a flag for a challenge
+const chall = challs.find((c) => c.name === 'The Lost Park')!;
+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,13 @@ 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";
+    }>;
+    getChallenges(): Promise<ChallengeData[]>;
+    getScoreboard(): Promise<ScoreboardEntry[]>;
     private getAuthedSessionNonce;
 }
 
-export { CTFdClient, type ChallengeData, type ScoreboardData };
+export { CTFdClient, type ChallengeData, type ScoreboardEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b01lers/ctfd-api",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "An API client for CTFd.",
   "main": "dist/index.js",
   "types": "dist/types.d.ts",

package/src/client.ts

@@ -1,5 +1,5 @@
 import { extractNonce } from './util';
-import type { ChallengesResponse, FlagSubmissionResponse } from './types';
+import type { ChallengesResponse, FlagSubmissionResponse, ScoreboardResponse } from './types';
 
 
 type ClientOptions = {
@@ -26,7 +26,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 +35,31 @@ 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 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 +101,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, ChallengeData } from './types';

package/src/types.ts

@@ -1,13 +1,12 @@
 export type ScoreboardResponse = {
     success: true,
-    data: ScoreboardData[],
+    data: ScoreboardEntry[],
 }
 
-export type ScoreboardData = {
+type BaseScoreboardEntry = {
     pos: number,
     account_id: number,
     account_url: string,
-    account_type: "user",
     oauth_id: null,
     name: string,
     score: number,
@@ -15,6 +14,24 @@ export type ScoreboardData = {
     bracket_name: null
 }
 
+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 = {
     success: true,
     data: ChallengeData[]

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