icoa-cli 1.0.0

package/dist/lib/ctfd-client.js

@@ -0,0 +1,161 @@
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+export class CTFdClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}/api/v1${path}`;
+        const headers = {
+            Authorization: `Token ${this.token}`,
+            'Content-Type': 'application/json',
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => 'Unknown error');
+            throw new Error(`CTFd API error (${res.status}): ${text}`);
+        }
+        const json = (await res.json());
+        if (json.success === false) {
+            throw new Error(`CTFd error: ${json.errors?.join(', ') || 'Unknown error'}`);
+        }
+        return json.data;
+    }
+    async testConnection() {
+        return this.request('GET', '/users/me');
+    }
+    async getChallenges() {
+        return this.request('GET', '/challenges');
+    }
+    async getChallenge(id) {
+        return this.request('GET', `/challenges/${id}`);
+    }
+    async submitFlag(challengeId, submission) {
+        const res = await fetch(`${this.baseUrl}/api/v1/challenges/attempt`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Token ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ challenge_id: challengeId, submission }),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => 'Unknown error');
+            throw new Error(`CTFd API error (${res.status}): ${text}`);
+        }
+        const json = (await res.json());
+        return json.data;
+    }
+    async getScoreboard() {
+        return this.request('GET', '/scoreboard');
+    }
+    async getTeam() {
+        return this.request('GET', '/teams/me');
+    }
+    async getCompetitionMeta() {
+        const res = await fetch(this.baseUrl);
+        const html = await res.text();
+        const startMatch = html.match(/'start'\s*:\s*(\d+)/);
+        const endMatch = html.match(/'end'\s*:\s*(\d+)/);
+        const modeMatch = html.match(/'userMode'\s*:\s*"([^"]+)"/);
+        const csrfMatch = html.match(/'csrfNonce'\s*:\s*"([^"]+)"/);
+        return {
+            start: startMatch ? parseInt(startMatch[1]) : null,
+            end: endMatch ? parseInt(endMatch[1]) : null,
+            userMode: modeMatch?.[1] || 'users',
+            csrfNonce: csrfMatch?.[1] || '',
+        };
+    }
+    async getChallengeFiles(id) {
+        const challenge = await this.getChallenge(id);
+        return challenge.files || [];
+    }
+    async downloadFile(filePath, destDir) {
+        mkdirSync(destDir, { recursive: true });
+        const url = filePath.startsWith('http')
+            ? filePath
+            : `${this.baseUrl}/${filePath.replace(/^\//, '')}`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Token ${this.token}` },
+            redirect: 'follow',
+        });
+        if (!res.ok || !res.body) {
+            throw new Error(`Failed to download: ${url}`);
+        }
+        // Extract clean filename (strip query params like ?token=xxx)
+        const rawName = filePath.split('/').pop() || 'file';
+        const fileName = rawName.split('?')[0];
+        const destPath = join(destDir, fileName);
+        const fileStream = createWriteStream(destPath);
+        await pipeline(Readable.fromWeb(res.body), fileStream);
+        return destPath;
+    }
+    async loginWithCredentials(username, password) {
+        // Step 1: GET /login to get nonce
+        const loginPageRes = await fetch(`${this.baseUrl}/login`);
+        const loginHtml = await loginPageRes.text();
+        // Try multiple nonce patterns (CTFd versions differ)
+        const nonceMatch = loginHtml.match(/name="nonce"[^>]*value="([^"]+)"/) ||
+            loginHtml.match(/value="([^"]+)"[^>]*name="nonce"/) ||
+            loginHtml.match(/id="nonce"[^>]*value="([^"]+)"/) ||
+            loginHtml.match(/csrfNonce['":\s]+['"]([^'"]+)['"]/);
+        const nonce = nonceMatch?.[1] || '';
+        if (!nonce) {
+            throw new Error('Could not extract CSRF nonce from login page.');
+        }
+        // Extract cookies
+        const cookies = loginPageRes.headers.getSetCookie?.() || [];
+        const cookieStr = cookies.map((c) => c.split(';')[0]).join('; ');
+        // Step 2: POST /login with credentials
+        const loginRes = await fetch(`${this.baseUrl}/login`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Cookie: cookieStr,
+            },
+            body: new URLSearchParams({ name: username, password, nonce, _submit: 'Submit' }),
+            redirect: 'manual',
+        });
+        const loginCookies = loginRes.headers.getSetCookie?.() || [];
+        const allCookies = [...cookies, ...loginCookies].map((c) => c.split(';')[0]).join('; ');
+        // Check if login was successful (redirect to /challenges or /, not back to /login)
+        const location = loginRes.headers.get('location') || '';
+        if (location.includes('/login')) {
+            throw new Error('Invalid username or password.');
+        }
+        // Step 3: Generate API token
+        // First get CSRF nonce from settings page
+        const settingsRes = await fetch(`${this.baseUrl}/settings`, {
+            headers: { Cookie: allCookies },
+        });
+        const settingsHtml = await settingsRes.text();
+        const csrfMatch = settingsHtml.match(/csrfNonce['":\s]+['"]([^'"]+)['"]/);
+        const csrfNonce = csrfMatch?.[1] || nonce;
+        const tokenRes = await fetch(`${this.baseUrl}/api/v1/tokens`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Cookie: allCookies,
+                'CSRF-Token': csrfNonce,
+            },
+            body: JSON.stringify({ expiration: '2026-12-31T23:59:59+00:00' }),
+        });
+        if (!tokenRes.ok) {
+            throw new Error('Failed to generate API token. Please use a manual access token instead.');
+        }
+        const tokenJson = (await tokenRes.json());
+        if (tokenJson.success && tokenJson.data?.value) {
+            return tokenJson.data.value;
+        }
+        throw new Error('Failed to generate API token. Response: ' + JSON.stringify(tokenJson));
+    }
+}

package/dist/lib/gemini.d.ts

@@ -0,0 +1,7 @@
+import type { HintLevel, ChallengeContext } from '../types/index.js';
+export declare function generateHint(level: HintLevel, question: string, context?: ChallengeContext): Promise<{
+    text: string;
+    tokensUsed: number;
+}>;
+export declare function translateText(text: string, targetLang: string): Promise<string>;
+export declare function setApiKey(key: string): void;

package/dist/lib/gemini.js

@@ -0,0 +1,108 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { getConfig, saveConfig } from './config.js';
+const SYSTEM_PROMPTS = {
+    A: `You are an AI assistant in a cybersecurity CTF competition called ICOA.
+You are providing Level A (General Guidance) to a competitor.
+
+STRICT RULES:
+- Only answer conceptual questions
+- Do NOT mention specific vulnerability names
+- Do NOT provide any code, commands, or tool usage
+- Do NOT mention specific attack techniques
+- Use questions to guide the competitor toward their own discovery
+- If the competitor asks you to solve the challenge, refuse and redirect
+- Never output anything matching flag format: icoa{...}`,
+    B: `You are an AI assistant in ICOA CTF, providing Level B (Deep Analysis).
+
+RULES:
+- You MAY identify specific vulnerability types (e.g., "buffer overflow")
+- You MAY suggest which category of tool to use (e.g., "a debugger")
+- Do NOT provide complete commands or working code
+- Do NOT provide exploit code or payloads
+- Do NOT provide flags or flag fragments
+- Never output anything matching: icoa{...}`,
+    C: `You are an AI assistant in ICOA CTF, providing Level C (Critical Assist).
+
+RULES:
+- You MAY provide the key conceptual breakthrough
+- You MAY name specific algorithms or approaches
+- Do NOT provide complete exploit code
+- Do NOT provide the flag
+- Never output anything matching: icoa{...}`,
+};
+function buildSystemPrompt(level, context) {
+    let prompt = SYSTEM_PROMPTS[level];
+    if (context) {
+        prompt += `\n\nThe competitor is currently working on:\nChallenge: ${context.name}\nCategory: ${context.category}`;
+    }
+    return prompt;
+}
+function filterFlagPatterns(text) {
+    return text.replace(/icoa\{[^}]*\}/gi, '[FLAG REDACTED]');
+}
+function getApiKey() {
+    // Priority: env var > config
+    const envKey = process.env.GEMINI_API_KEY;
+    if (envKey)
+        return envKey;
+    const config = getConfig();
+    if (config.geminiApiKey)
+        return config.geminiApiKey;
+    return '';
+}
+export async function generateHint(level, question, context) {
+    let apiKey = getApiKey();
+    if (!apiKey) {
+        // Try to prompt for key interactively
+        try {
+            const { input } = await import('@inquirer/prompts');
+            console.log();
+            console.log('  Gemini API key not configured.');
+            console.log('  Get one free at: https://aistudio.google.com/apikey');
+            console.log();
+            apiKey = await input({ message: 'Enter your Gemini API Key:' });
+            if (apiKey.trim()) {
+                apiKey = apiKey.trim();
+                saveConfig({ geminiApiKey: apiKey });
+                console.log('  Key saved for future use.');
+                console.log();
+            }
+            else {
+                throw new Error('No API key provided.');
+            }
+        }
+        catch {
+            throw new Error('Gemini API key not configured.\n' +
+                'Set GEMINI_API_KEY environment variable, or run: icoa setup');
+        }
+    }
+    const genAI = new GoogleGenerativeAI(apiKey);
+    const model = genAI.getGenerativeModel({
+        model: 'gemini-2.5-pro-preview-05-06',
+        systemInstruction: buildSystemPrompt(level, context),
+    });
+    const result = await model.generateContent(question);
+    const response = result.response;
+    const text = filterFlagPatterns(response.text());
+    const usage = response.usageMetadata;
+    const tokensUsed = (usage?.promptTokenCount || 0) + (usage?.candidatesTokenCount || 0);
+    return { text, tokensUsed };
+}
+export async function translateText(text, targetLang) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        throw new Error('Gemini API key not configured for translation.');
+    }
+    const genAI = new GoogleGenerativeAI(apiKey);
+    const model = genAI.getGenerativeModel({ model: 'gemini-2.5-pro-preview-05-06' });
+    const prompt = `Translate the following CTF challenge description to ${targetLang}.
+Keep all technical terms, code, commands, URLs, and flag formats in English.
+Only translate the narrative/descriptive text.
+
+${text}`;
+    const result = await model.generateContent(prompt);
+    return result.response.text();
+}
+export function setApiKey(key) {
+    saveConfig({ geminiApiKey: key });
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,6 @@
+import type { LogEntry, HintLevel } from '../types/index.js';
+export declare function logEntry(entry: LogEntry): void;
+export declare function logCommand(command: string): void;
+export declare function logHint(level: HintLevel, question: string, challengeId?: number): void;
+export declare function logSubmission(challengeId: number, flag: string): void;
+export declare function getSessionLog(): LogEntry[];

package/dist/lib/logger.js

@@ -0,0 +1,59 @@
+import { appendFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfig, getIcoaDir } from './config.js';
+function getLogPath() {
+    return join(getIcoaDir(), 'session.log');
+}
+export function logEntry(entry) {
+    try {
+        appendFileSync(getLogPath(), JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Silently fail — logging should never break the CLI
+    }
+}
+export function logCommand(command) {
+    const config = getConfig();
+    logEntry({
+        timestamp: new Date().toISOString(),
+        level: 'command',
+        input: command,
+        sessionId: config.sessionId,
+    });
+}
+export function logHint(level, question, challengeId) {
+    const config = getConfig();
+    logEntry({
+        timestamp: new Date().toISOString(),
+        level: level,
+        input: question,
+        challengeId,
+        sessionId: config.sessionId,
+    });
+}
+export function logSubmission(challengeId, flag) {
+    const config = getConfig();
+    logEntry({
+        timestamp: new Date().toISOString(),
+        level: 'submit',
+        input: flag,
+        challengeId,
+        sessionId: config.sessionId,
+    });
+}
+export function getSessionLog() {
+    const logPath = getLogPath();
+    if (!existsSync(logPath))
+        return [];
+    try {
+        const raw = readFileSync(logPath, 'utf-8');
+        return raw
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/translation.d.ts

@@ -0,0 +1 @@
+export declare function getTranslation(text: string, challengeId: number, targetLang: string): Promise<string>;

package/dist/lib/translation.js

@@ -0,0 +1,40 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getIcoaDir } from './config.js';
+import { translateText } from './gemini.js';
+function getCachePath(lang, challengeId) {
+    const dir = join(getIcoaDir(), 'translations', lang);
+    mkdirSync(dir, { recursive: true });
+    return join(dir, `${challengeId}.json`);
+}
+export async function getTranslation(text, challengeId, targetLang) {
+    if (targetLang === 'en')
+        return text;
+    const cachePath = getCachePath(targetLang, challengeId);
+    // Check cache
+    if (existsSync(cachePath)) {
+        try {
+            const cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
+            if (cached.translation)
+                return cached.translation;
+        }
+        catch {
+            // Cache corrupt, regenerate
+        }
+    }
+    // Translate via Gemini
+    const translation = await translateText(text, getLangName(targetLang));
+    // Cache result
+    writeFileSync(cachePath, JSON.stringify({ original: text, translation, timestamp: new Date().toISOString() }));
+    return translation;
+}
+function getLangName(code) {
+    const names = {
+        en: 'English',
+        zh: 'Chinese (Simplified)',
+        ja: 'Japanese',
+        ko: 'Korean',
+        es: 'Spanish',
+    };
+    return names[code] || 'English';
+}

package/dist/lib/ui.d.ts

@@ -0,0 +1,10 @@
+export declare function printSuccess(msg: string): void;
+export declare function printError(msg: string): void;
+export declare function printWarning(msg: string): void;
+export declare function printInfo(msg: string): void;
+export declare function printTable(headers: string[], rows: string[][]): void;
+export declare function printMarkdown(text: string): void;
+export declare function createSpinner(text: string): import("ora").Ora;
+export declare function formatCountdown(targetDate: Date): string;
+export declare function printHeader(title: string): void;
+export declare function printKeyValue(key: string, value: string): void;

package/dist/lib/ui.js

@@ -0,0 +1,59 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import ora from 'ora';
+import { Marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
+const marked = new Marked(markedTerminal());
+export function printSuccess(msg) {
+    console.log(chalk.green('✓ ') + msg);
+}
+export function printError(msg) {
+    console.log(chalk.red('✗ ') + msg);
+}
+export function printWarning(msg) {
+    console.log(chalk.yellow('⚠ ') + msg);
+}
+export function printInfo(msg) {
+    console.log(chalk.blue('ℹ ') + msg);
+}
+export function printTable(headers, rows) {
+    const table = new Table({
+        head: headers.map((h) => chalk.cyan.bold(h)),
+        style: { head: [], border: [] },
+    });
+    for (const row of rows) {
+        table.push(row);
+    }
+    console.log(table.toString());
+}
+export function printMarkdown(text) {
+    const rendered = marked.parse(text);
+    if (typeof rendered === 'string') {
+        console.log(rendered);
+    }
+}
+export function createSpinner(text) {
+    return ora({ text, color: 'cyan' });
+}
+export function formatCountdown(targetDate) {
+    const now = new Date();
+    const diff = targetDate.getTime() - now.getTime();
+    if (diff <= 0)
+        return '00:00:00';
+    const hours = Math.floor(diff / (1000 * 60 * 60));
+    const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60));
+    const seconds = Math.floor((diff % (1000 * 60)) / 1000);
+    return [
+        hours.toString().padStart(2, '0'),
+        minutes.toString().padStart(2, '0'),
+        seconds.toString().padStart(2, '0'),
+    ].join(':');
+}
+export function printHeader(title) {
+    console.log();
+    console.log(chalk.cyan.bold(`  ${title}`));
+    console.log(chalk.cyan('  ' + '─'.repeat(title.length + 4)));
+}
+export function printKeyValue(key, value) {
+    console.log(`  ${chalk.gray(key + ':')} ${value}`);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,125 @@
+export interface CTFdChallenge {
+    id: number;
+    name: string;
+    description: string;
+    category: string;
+    value: number;
+    type: string;
+    state: string;
+    max_attempts: number;
+    tags: string[];
+    files: string[];
+    hints: {
+        id: number;
+        cost: number;
+    }[];
+    solves: number;
+    solved_by_me: boolean;
+    connection_info?: string;
+}
+export interface CTFdChallengeListItem {
+    id: number;
+    name: string;
+    category: string;
+    value: number;
+    type: string;
+    solves: number;
+    solved_by_me: boolean;
+    tags: string[];
+}
+export interface CTFdUser {
+    id: number;
+    name: string;
+    email: string;
+    team_id: number | null;
+    country: string | null;
+    score: number;
+    place: string | null;
+}
+export interface CTFdTeam {
+    id: number;
+    name: string;
+    score: number;
+    place: string | null;
+    members: {
+        id: number;
+        name: string;
+    }[];
+}
+export interface CTFdScoreboardEntry {
+    pos: number;
+    account_id: number;
+    account_url: string;
+    account_type: string;
+    name: string;
+    score: number;
+    members?: {
+        id: number;
+        name: string;
+    }[];
+}
+export interface CTFdAttemptResponse {
+    success: boolean;
+    data: {
+        status: 'correct' | 'incorrect' | 'already_solved' | 'paused' | 'ratelimited';
+        message: string;
+    };
+}
+export interface CTFdApiResponse<T> {
+    success: boolean;
+    data: T;
+    errors?: string[];
+}
+export interface CTFdTokenResponse {
+    success: boolean;
+    data: {
+        id: number;
+        type: string;
+        value: string;
+        created: string;
+        expiration: string;
+    };
+}
+export interface IcoaConfig {
+    ctfdUrl: string;
+    token: string;
+    language: string;
+    sessionId: string;
+    competitionCode: string;
+    teamId: number | null;
+    userId: number | null;
+    userName: string;
+    teamName: string;
+    currentChallengeId: number | null;
+    currentChallengeName: string;
+    currentChallengeCategory: string;
+    competitionState: CompetitionState;
+    competitionStartsAt: string;
+    competitionEndsAt: string;
+    geminiApiKey: string;
+}
+export type CompetitionState = 'pre_competition' | 'demo' | 'live' | 'finished' | 'unknown';
+export type HintLevel = 'A' | 'B' | 'C';
+export interface HintBudget {
+    a: number;
+    b: number;
+    c: number;
+    tokensUsed: number;
+    tokenCap: number;
+}
+export interface LogEntry {
+    timestamp: string;
+    level: 'A' | 'B' | 'C' | 'command' | 'submit';
+    input: string;
+    challengeId?: number;
+    sessionId: string;
+}
+export interface ChallengeContext {
+    name: string;
+    category: string;
+    description?: string;
+}
+export declare const DEFAULT_BUDGET: HintBudget;
+export declare const DEFAULT_CONFIG: IcoaConfig;
+export declare const SUPPORTED_LANGUAGES: readonly ["en", "zh", "ja", "ko", "es"];
+export type SupportedLanguage = typeof SUPPORTED_LANGUAGES[number];

package/dist/types/index.js

@@ -0,0 +1,29 @@
+// ========================
+// CTFd API Response Types
+// ========================
+export const DEFAULT_BUDGET = {
+    a: 50,
+    b: 10,
+    c: 2,
+    tokensUsed: 0,
+    tokenCap: 50000,
+};
+export const DEFAULT_CONFIG = {
+    ctfdUrl: '',
+    token: '',
+    language: 'en',
+    sessionId: '',
+    competitionCode: '',
+    teamId: null,
+    userId: null,
+    userName: '',
+    teamName: '',
+    currentChallengeId: null,
+    currentChallengeName: '',
+    currentChallengeCategory: '',
+    competitionState: 'unknown',
+    competitionStartsAt: '',
+    competitionEndsAt: '',
+    geminiApiKey: '',
+};
+export const SUPPORTED_LANGUAGES = ['en', 'zh', 'ja', 'ko', 'es'];

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "icoa-cli",
+  "version": "1.0.0",
+  "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
+  "type": "module",
+  "bin": {
+    "icoa": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "refs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "ctf",
+    "cli",
+    "cybersecurity",
+    "icoa",
+    "competition"
+  ],
+  "license": "SEE LICENSE IN licenses/apache-2.0.txt",
+  "dependencies": {
+    "@google/generative-ai": "^0.24.0",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "@inquirer/prompts": "^7.5.0",
+    "marked": "^15.0.7",
+    "marked-terminal": "^7.3.0",
+    "ora": "^8.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}