icoa-cli 2.19.84 → 2.19.86

package/dist/commands/exam.js

@@ -1045,6 +1045,9 @@ export function registerExamCommand(program) {
         state.answers[num] = c;
         state._lastQ = num;
         saveExamState(state);
+        // UX: visible "saved" indicator reassures beginners their answer is safe
+        // even if they Ctrl+C or lose network. Neutral — doesn't reveal correctness.
+        console.log(chalk.gray('    ✓ saved'));
         // Per-question sync to server (real exam only). Best-effort, fire-and-forget.
         // If timer expires or network drops before final submit, the server still
         // has the answer. Final submit is authoritative and overwrites this.
@@ -1731,6 +1734,35 @@ export function registerExamCommand(program) {
             // means the token alone is useless on another machine, so keeping
             // it in exam-state.json is safe.
             session.token = code.trim();
+            // Best-effort server-time sync. Corrects client clock drift (NTP-less
+            // Kali live-boots, timezone misconfigs) so the displayed countdown
+            // matches the server's authoritative deadline. Silent on failure —
+            // old servers (no endpoint) or offline clients fall back to the
+            // local-clock-only deadline (see getExamDeadline in exam-state.ts).
+            try {
+                const t0 = Date.now();
+                const tRes = await fetch(`${serverUrl}/api/icoa/server-time`, {
+                    method: 'GET',
+                    signal: AbortSignal.timeout(3000),
+                });
+                if (tRes.ok) {
+                    const tJson = await tRes.json();
+                    const serverMs = tJson?.data?.server_time_ms;
+                    if (typeof serverMs === 'number' && serverMs > 0) {
+                        // Offset is measured at the midpoint of the request window to
+                        // halve the latency bias (serverMs reflects when the server
+                        // read its clock; midpoint of our send/receive window is the
+                        // best single-sample approximation of when that reading aligns
+                        // with our clock).
+                        const clientMs = (t0 + Date.now()) / 2;
+                        session.clockOffsetMs = Math.round(serverMs - clientMs);
+                        session.deadlineServerMs = serverMs + session.durationMinutes * 60 * 1000;
+                    }
+                }
+            }
+            catch {
+                // Offline or old server — keep fallback (confirmedAt + duration local).
+            }
             saveExamState({ session, questions, answers: {}, interactions: [], aiUsage: { ai4ctf: 0, ctf4ai: 0 } });
             console.log();
             printSuccess('Exam started! Timer is running.');

package/dist/lib/demo-flags.d.ts

@@ -0,0 +1,8 @@
+export declare const DEMO_AI4CTF_FLAG_B64 = "aWNvYXt3M2xjMG1lXzJfYWk0Y3RmfQ==";
+export declare const DEMO_AI4CTF_FLAG_DECODED = "icoa{w3lc0me_2_ai4ctf}";
+/**
+ * Runtime verification that the b64 constant decodes to the expected plaintext.
+ * Catches hand-edit drift between the two constants above.
+ * Throws if they disagree. Safe to call at module load or from tests.
+ */
+export declare function verifyDemoAi4ctfFlag(): void;

package/dist/lib/demo-flags.js

@@ -0,0 +1,27 @@
+// Single source of truth for the demo AI4CTF flag.
+// i18n.ts (EN) and the i18n translations must reference this constant
+// rather than hand-copying the base64 string — hand-copying created the
+// BUG-002 class drift where Q33 base64 was written as "ISOA{...}" in one
+// place and "ICOA{...}" in another. This file exists so every translation
+// picks up the correct value from one place.
+//
+// The matching unit test (test/demo-flags-consistency.test.js) scans
+// compiled i18n.js for any base64-looking string that starts with
+// "aWNvYX" (= "icoa{") and asserts they ALL equal DEMO_AI4CTF_FLAG_B64.
+// That's the drift protection: if someone hand-edits one translation's
+// b64, the scan finds two distinct values and the test fails.
+export const DEMO_AI4CTF_FLAG_B64 = 'aWNvYXt3M2xjMG1lXzJfYWk0Y3RmfQ==';
+export const DEMO_AI4CTF_FLAG_DECODED = 'icoa{w3lc0me_2_ai4ctf}';
+/**
+ * Runtime verification that the b64 constant decodes to the expected plaintext.
+ * Catches hand-edit drift between the two constants above.
+ * Throws if they disagree. Safe to call at module load or from tests.
+ */
+export function verifyDemoAi4ctfFlag() {
+    const decoded = Buffer.from(DEMO_AI4CTF_FLAG_B64, 'base64').toString('utf-8');
+    if (decoded !== DEMO_AI4CTF_FLAG_DECODED) {
+        throw new Error(`Demo flag drift: base64 '${DEMO_AI4CTF_FLAG_B64}' decodes to '${decoded}' ` +
+            `but DEMO_AI4CTF_FLAG_DECODED constant is '${DEMO_AI4CTF_FLAG_DECODED}'. ` +
+            `Fix demo-flags.ts so both halves agree.`);
+    }
+}

package/dist/lib/exam-state.js

@@ -87,7 +87,16 @@ export function getExamDeadline() {
         return null;
     if (!state.session.durationMinutes)
         return null; // 0 = no time limit
-    // Use confirmedAt (when user pressed Enter) as the real start, fallback to startedAt
+    // Preferred path: server-time sync succeeded at exam start. deadlineServerMs
+    // is the authoritative server-time moment of expiry. Convert back to local
+    // clock domain so existing callers (which compare against Date.now()) stay
+    // correct even if the local clock drifts from server.
+    const { deadlineServerMs, clockOffsetMs } = state.session;
+    if (typeof deadlineServerMs === 'number' && typeof clockOffsetMs === 'number') {
+        return new Date(deadlineServerMs - clockOffsetMs);
+    }
+    // Fallback: local-clock-only (pre-v2.19.85 behavior). Accurate as long as
+    // client and server clocks agree; off by the clock skew otherwise.
     const startTime = state.session.confirmedAt || state.session.startedAt;
     const start = new Date(startTime).getTime();
     return new Date(start + state.session.durationMinutes * 60 * 1000);

package/dist/lib/i18n.js

@@ -1,4 +1,5 @@
 import { getConfig } from './config.js';
+import { DEMO_AI4CTF_FLAG_B64 } from './demo-flags.js';
 export const EN = {
     // How to play
     howToPlay: 'How to play:',
@@ -72,7 +73,7 @@ export const EN = {
     ai4ctfHintC: 'Critical assist — Nearly gives you the answer',
     ai4ctfHintCUses: '2 uses only. Last resort!',
     ai4ctfTryNow: 'Try now: ask the AI anything about the challenge above.',
-    ai4ctfExample: 'Example: "What encoding is aWNvYXt3M2xjMG1lXzJfYWk0Y3RmfQ==?"',
+    ai4ctfExample: `Example: "What encoding is ${DEMO_AI4CTF_FLAG_B64}?"`,
     ai4ctfFreeChat: 'Or just chat freely! You can also try hint a, hint b, hint c.',
     ai4ctfExit: 'Type "exit" when done.',
     ai4ctfReport: 'AI4CTF Session Report',
@@ -201,7 +202,7 @@ export const EN = {
         '  2. Run a shell command directly. Shell commands inside ai4ctf\n' +
         '     must start with "!", otherwise your text goes to the AI. Example:\n' +
         '\n' +
-        '         !echo aWNvYXt3M2xjMG1lXzJfYWk0Y3RmfQ== | base64 -d',
+        `         !echo ${DEMO_AI4CTF_FLAG_B64} | base64 -d`,
     ai4ctfHintNextA: 'Stuck? Try:',
     ai4ctfHintNextB: 'Really stuck? Try:',
     // Post-solve wrap-up (v2.19.32)

package/dist/repl.js

@@ -192,6 +192,14 @@ function printSelectionMenu() {
         console.log(chalk.white('     lang es') + chalk.gray('         Switch language (17 supported)'));
         console.log(chalk.gray('   ─────────────────────────────────────────────'));
     }
+    // Beginner-friendly safety net: make it obvious how to pause / exit / get help.
+    // This is the first place a new K-12 user lands, so the three escape hatches
+    // need to be visible without cluttering the main command list above.
+    console.log(chalk.gray('   ') +
+        chalk.gray('Tip: ') + chalk.cyan('help') + chalk.gray(' for commands · ') +
+        chalk.cyan('Ctrl+C') + chalk.gray(' pauses · ') +
+        chalk.cyan('exit') + chalk.gray(' → menu · ') +
+        chalk.cyan('quit') + chalk.gray(' closes CLI'));
     console.log();
 }
 export async function startRepl(program, resumeMode) {
@@ -975,6 +983,28 @@ export async function startRepl(program, resumeMode) {
         console.log();
         rl.prompt();
     });
+    // SIGINT (Ctrl+C) — intercept gracefully so beginners don't lose confidence.
+    // Without this listener, readline's default is to raise SIGINT which our
+    // theme.ts handler converts to process.exit(130). Installing this listener
+    // swallows that path and lets the user get oriented. If they want to exit,
+    // they type `quit` or hit Ctrl+D (sends EOF → 'close' event below).
+    rl.on('SIGINT', () => {
+        console.log();
+        if (isChatActive() || isCtf4aiActive()) {
+            console.log(chalk.yellow('  Type ') + chalk.bold.cyan('exit') + chalk.yellow(' to leave chat, or Ctrl+D to close ICOA CLI.'));
+        }
+        else if (getExamState()) {
+            console.log(chalk.yellow('  Exam paused. Your answers are auto-saved.'));
+            console.log(chalk.white('  Resume: ') + chalk.cyan('exam q 1') +
+                chalk.gray('  ·  Back to menu: ') + chalk.cyan('back') +
+                chalk.gray('  ·  Close CLI: ') + chalk.cyan('quit'));
+        }
+        else {
+            console.log(chalk.yellow('  Press Ctrl+D or type ') + chalk.bold.cyan('quit') + chalk.yellow(' to close. ') + chalk.bold.cyan('help') + chalk.yellow(' for commands.'));
+        }
+        console.log();
+        rl.prompt();
+    });
     rl.on('close', () => {
         stopLogSync();
         recordExit();

package/dist/types/index.d.ts

@@ -167,6 +167,8 @@ export interface ExamSession {
     passingScore?: number;
     country: string;
     token?: string;
+    clockOffsetMs?: number;
+    deadlineServerMs?: number;
 }
 export interface ExamInteraction {
     ts: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icoa-cli",
-  "version": "2.19.84",
+  "version": "2.19.86",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
+    "test": "tsc && node --test test/*.test.js",
     "postinstall": "node -e \"try{require('./dist/postinstall.js')}catch(e){}\""
   },
   "keywords": [
@@ -24,7 +25,7 @@
     "icoa",
     "competition"
   ],
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "BUSL-1.1",
   "dependencies": {
     "@google/genai": "^1.48.0",
     "@inquirer/prompts": "^7.5.0",