termi-kids 0.1.0

package/dist/safety/classifier.js

@@ -0,0 +1,337 @@
+/**
+ * The safety pipeline (L0 + L2 + L4 wiring). FAIL CLOSED is the law here:
+ * any timeout, HTTP error, rate limit, or malformed verdict becomes a block
+ * with failClosed set. The main model's output is never revealed and writes
+ * never land without a clean pass.
+ *
+ * Backends:
+ * - With an OpenAI moderation key: the free moderation endpoint covers the
+ *   broad taxonomy while a compact prompted kid-check (grooming, pii,
+ *   jailbreak) runs in parallel on the classifier model.
+ * - Without one: a single prompted classifier covers the full taxonomy.
+ */
+import { createHash } from 'node:crypto';
+import { streamText } from 'ai';
+import { T } from '../ui/text.js';
+import { scanCode } from './codescan.js';
+import { normalizeText, prefilterContext as prefilterContextImpl, prefilterInput as prefilterInputImpl, } from './prefilter.js';
+import { bumpCounters, groomingEscalation, windowText } from './session.js';
+import { blockMessage, buildClassifierPrompt, failClosedVerdict, MODERATION_CUTOFFS, parseVerdict, primaryCategory, severityBlocks, } from './taxonomy.js';
+import { extractVisibleText } from './textextract.js';
+export const DEFAULT_TIMEOUT_MS = 8000;
+const MODERATION_URL = 'https://api.openai.com/v1/moderations';
+const MODERATION_MODEL = 'omni-moderation-latest';
+/** Chars of judged text per prompted-check call (token efficiency). */
+export const JUDGE_TEXT_CAP = 2000;
+/**
+ * Verdict budget for one prompted check. Reasoning models spend thinking
+ * tokens from this budget before any visible text; too small a cap starves
+ * the verdict, which fails closed and blocks everything. Keep it roomy.
+ */
+export const CLASSIFIER_MAX_OUTPUT_TOKENS = 600;
+/** Most allow verdicts remembered per session for unchanged file text. */
+const FILE_VERDICT_CACHE_CAP = 200;
+/** Rejects when the wrapped promise takes longer than ms. */
+async function withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('safety check timed out')), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function maxSeverity(a, b) {
+    return a >= b ? a : b;
+}
+/** Merges parallel verdicts: most severe wins, any failure stays a block. */
+function mergeVerdicts(verdicts) {
+    if (verdicts.length === 0) {
+        return failClosedVerdict();
+    }
+    const categories = [];
+    let severity = 0;
+    let selfHarmConcern = false;
+    let anyFailClosed = false;
+    let allAllowed = true;
+    for (const v of verdicts) {
+        for (const c of v.categories) {
+            if (!categories.includes(c)) {
+                categories.push(c);
+            }
+        }
+        severity = maxSeverity(severity, v.severity);
+        selfHarmConcern = selfHarmConcern || v.selfHarmConcern;
+        anyFailClosed = anyFailClosed || v.failClosed;
+        allAllowed = allAllowed && v.allowed;
+    }
+    const blocked = anyFailClosed || !allAllowed || severityBlocks(categories, severity);
+    if (!blocked) {
+        return { allowed: true, categories, severity, selfHarmConcern, failClosed: false, kidMessage: null };
+    }
+    return {
+        allowed: false,
+        categories,
+        severity,
+        selfHarmConcern,
+        failClosed: anyFailClosed,
+        kidMessage: categories.length > 0 ? blockMessage(categories) : T.errors.failClosed,
+    };
+}
+async function moderationCheck(key, text, fetchImpl) {
+    const res = await fetchImpl(MODERATION_URL, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${key}`,
+        },
+        body: JSON.stringify({ model: MODERATION_MODEL, input: text }),
+    });
+    if (!res.ok) {
+        throw new Error(`moderation endpoint returned ${res.status}`);
+    }
+    const data = (await res.json());
+    const scores = data.results?.[0]?.category_scores;
+    if (!scores || typeof scores !== 'object') {
+        throw new Error('moderation response malformed');
+    }
+    // An empty or unrecognized scores object must not read as "all clear".
+    if (!MODERATION_CUTOFFS.some((cutoff) => typeof scores[cutoff.score] === 'number')) {
+        throw new Error('moderation response malformed');
+    }
+    const categories = [];
+    let severity = 0;
+    let selfHarmConcern = false;
+    for (const cutoff of MODERATION_CUTOFFS) {
+        const value = scores[cutoff.score];
+        if (typeof value === 'number' && value >= cutoff.min) {
+            if (!categories.includes(cutoff.category)) {
+                categories.push(cutoff.category);
+            }
+            severity = maxSeverity(severity, cutoff.severity);
+            if (cutoff.selfHarmConcern) {
+                selfHarmConcern = true;
+            }
+        }
+    }
+    const blocked = severityBlocks(categories, severity);
+    return {
+        allowed: !blocked,
+        categories,
+        severity,
+        selfHarmConcern,
+        failClosed: false,
+        kidMessage: blocked ? blockMessage(categories) : null,
+    };
+}
+async function promptedCheck(model, direction, composedWindow, scope) {
+    // streamText, not generateText: the ChatGPT coding backend requires
+    // stream true on every call. The text is collected, never revealed.
+    let streamError = null;
+    const result = streamText({
+        model,
+        prompt: buildClassifierPrompt(direction, composedWindow, scope),
+        temperature: 0,
+        maxOutputTokens: CLASSIFIER_MAX_OUTPUT_TOKENS,
+        onError: ({ error }) => {
+            if (streamError === null) {
+                streamError = error;
+            }
+        },
+    });
+    let text;
+    try {
+        text = await result.text;
+    }
+    catch (err) {
+        throw streamError ?? err;
+    }
+    if (streamError !== null) {
+        throw streamError;
+    }
+    return parseVerdict(text);
+}
+/**
+ * Judged text is data. Braces are swapped for parentheses before the text
+ * enters a classifier prompt, so an echo of judged content can never form
+ * the JSON object that parseVerdict looks for (verdict forgery).
+ */
+function neutralizeJudged(text) {
+    return text.replace(/\{/g, '(').replace(/\}/g, ')');
+}
+/** Splits normalized judged text into prompt-sized chunks (at least one). */
+function judgeChunks(normalized) {
+    if (normalized.length <= JUDGE_TEXT_CAP) {
+        return [normalized];
+    }
+    const chunks = [];
+    for (let i = 0; i < normalized.length; i += JUDGE_TEXT_CAP) {
+        chunks.push(normalized.slice(i, i + JUDGE_TEXT_CAP));
+    }
+    return chunks;
+}
+export function createSafetyPipeline(deps) {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    // Session-scoped allow cache for file text: the same visible text is never
+    // re-judged remotely twice. Blocks and failures are never cached.
+    const fileAllowCache = new Set();
+    function auditVerdict(verdict, direction, text, groomingFlag) {
+        if (verdict.allowed) {
+            return;
+        }
+        deps.audit({
+            ts: new Date().toISOString(),
+            layer: direction === 'input' ? 'L2' : 'L4',
+            event: groomingFlag ? 'grooming_flag' : verdict.failClosed ? 'fail_closed' : 'block',
+            category: primaryCategory(verdict.categories) ?? undefined,
+            severity: verdict.severity,
+            direction,
+            excerpt: text.slice(0, 80),
+        });
+    }
+    async function check(direction, text, state, source) {
+        try {
+            const normalized = normalizeText(text);
+            const cacheKey = source === 'file'
+                ? createHash('sha256').update(normalized).digest('hex')
+                : null;
+            if (cacheKey !== null && fileAllowCache.has(cacheKey)) {
+                return {
+                    allowed: true,
+                    categories: [],
+                    severity: 0,
+                    selfHarmConcern: false,
+                    failClosed: false,
+                    kidMessage: null,
+                };
+            }
+            // Every chunk of the judged text gets its own prompted check, so
+            // nothing past the per-call cap goes unjudged. Braces in judged text
+            // are neutralized so an echo cannot forge a verdict.
+            const window = neutralizeJudged(windowText(state));
+            const chunks = judgeChunks(neutralizeJudged(normalized));
+            const tasks = [];
+            const key = deps.moderationKey();
+            const model = deps.classifierModel();
+            const guard = deps.localGuard?.() ?? null;
+            if (key) {
+                tasks.push(withTimeout(moderationCheck(key, text, fetchImpl), timeoutMs));
+            }
+            if (guard) {
+                // The on-device guard judges every chunk across its full taxonomy,
+                // for input and output alike. On output checks it also sees the
+                // kid's last message, the exchange shape it was trained on. No
+                // withTimeout wrapper here: the runner bounds its own load and each
+                // generation, and chunks queue behind one another, so an outer timer
+                // started at task creation would fail-closed on long files for
+                // nothing more than waiting their turn.
+                const lastKid = [...state.recentTurns].reverse().find((turn) => turn.role === 'kid')?.text ?? '';
+                for (const chunk of chunks) {
+                    tasks.push(direction === 'input'
+                        ? guard.classifyInput(chunk)
+                        : guard.classifyOutput(lastKid, chunk));
+                }
+            }
+            if (model) {
+                // Only the moderation endpoint narrows the prompted check to the
+                // kid-specific categories: its taxonomy covers hate and harassment.
+                // The on-device guard does NOT narrow it. The guard has no
+                // hate_harassment or profanity category, so with the guard as the
+                // only broad backend the full prompted scope must keep running or
+                // those two categories would silently lose their model coverage.
+                const scope = key ? 'kidcheck' : 'full';
+                for (const chunk of chunks) {
+                    const composedWindow = `${window}\nTEXT TO JUDGE:\n${chunk}`;
+                    tasks.push(withTimeout(promptedCheck(model, direction, composedWindow, scope), timeoutMs));
+                }
+            }
+            let merged;
+            if (tasks.length === 0) {
+                // No classifier backend available: never fail open.
+                merged = failClosedVerdict();
+            }
+            else {
+                const settled = await Promise.all(tasks.map((t) => t.catch(() => failClosedVerdict())));
+                merged = mergeVerdicts(settled);
+            }
+            // Cross-turn grooming escalation off cumulative session counters.
+            // File text never bumps: counters track the conversation (what the
+            // kid types and what Termi says), not the kid's own game content.
+            if (source === 'chat') {
+                bumpCounters(state, merged.categories, text);
+            }
+            let groomingFlag = false;
+            if (source === 'chat' && groomingEscalation(state)) {
+                groomingFlag = true;
+                const categories = merged.categories.includes('grooming')
+                    ? merged.categories
+                    : ['grooming', ...merged.categories];
+                merged = {
+                    allowed: false,
+                    categories,
+                    severity: maxSeverity(merged.severity, 2),
+                    selfHarmConcern: merged.selfHarmConcern,
+                    failClosed: merged.failClosed,
+                    kidMessage: blockMessage(categories),
+                };
+            }
+            if (cacheKey !== null && merged.allowed && !merged.failClosed) {
+                if (fileAllowCache.size >= FILE_VERDICT_CACHE_CAP) {
+                    fileAllowCache.clear();
+                }
+                fileAllowCache.add(cacheKey);
+            }
+            auditVerdict(merged, direction, text, groomingFlag);
+            return merged;
+        }
+        catch {
+            // Belt and suspenders: nothing in this pipeline may throw upward.
+            const verdict = failClosedVerdict();
+            auditVerdict(verdict, direction, text, false);
+            return verdict;
+        }
+    }
+    return {
+        prefilterInput(text) {
+            const result = prefilterInputImpl(text);
+            if (result.block) {
+                deps.audit({
+                    ts: new Date().toISOString(),
+                    layer: 'L0',
+                    event: 'block',
+                    category: result.block.categories[0],
+                    severity: result.block.severity,
+                    direction: 'input',
+                    excerpt: text.slice(0, 80),
+                });
+            }
+            else if (result.notice) {
+                deps.audit({
+                    ts: new Date().toISOString(),
+                    layer: 'L0',
+                    event: 'redact',
+                    category: 'pii',
+                    direction: 'input',
+                    // The excerpt comes from the redacted text so PII never lands in the log.
+                    excerpt: result.redacted.slice(0, 80),
+                });
+            }
+            return result;
+        },
+        prefilterContext(text) {
+            return prefilterContextImpl(text);
+        },
+        checkInput(text, s) {
+            return check('input', text, s, 'chat');
+        },
+        checkOutputText(text, s, source = 'reply') {
+            return check('output', text, s, source === 'file' ? 'file' : 'chat');
+        },
+        scanCode,
+        extractVisibleText,
+    };
+}

package/dist/safety/codescan.js

@@ -0,0 +1,168 @@
+/**
+ * L4c: static code scan, defense in depth only. The sound egress control is
+ * the preview server CSP; this scanner catches the obvious tricks early and
+ * explains them in plain engineering terms the model can act on.
+ *
+ * Only JS, HTML, and CSS files are scanned. Markdown and plain text go
+ * through text classification instead. Relative and local references pass.
+ */
+import path from 'node:path';
+function fileKind(relPath) {
+    const ext = path.extname(relPath).toLowerCase();
+    switch (ext) {
+        case '.js':
+        case '.mjs':
+        case '.cjs':
+            return 'js';
+        case '.html':
+        case '.htm':
+            return 'html';
+        case '.css':
+            return 'css';
+        default:
+            return 'skip';
+    }
+}
+const EXTERNAL_URL = 'https?:|//';
+const RULES = [
+    // Network APIs. Termi projects must work with zero network.
+    {
+        kinds: ['js', 'html'],
+        regex: /\bfetch\s*\(/,
+        reason: 'uses fetch, a network call. Projects must work fully offline.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /\bXMLHttpRequest\b/,
+        reason: 'uses XMLHttpRequest, a network call. Projects must work fully offline.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /\bnew\s+WebSocket\s*\(|\bWebSocket\s*\(/,
+        reason: 'opens a WebSocket, a live network connection. Not allowed.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /\bnew\s+EventSource\s*\(|\bEventSource\s*\(/,
+        reason: 'opens an EventSource, a network stream. Not allowed.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /\bsendBeacon\s*\(/,
+        reason: 'uses sendBeacon, which sends data out. Not allowed.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /\bRTCPeerConnection\b/,
+        reason: 'uses RTCPeerConnection, a network channel. Not allowed.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: new RegExp(`\\.src\\s*=\\s*["'\`]\\s*(?:${EXTERNAL_URL})`),
+        reason: 'sets a src to an outside web address. Use local files only.',
+    },
+    {
+        kinds: ['js'],
+        regex: new RegExp(`\\bimport\\s*\\(\\s*["'\`](?:${EXTERNAL_URL})`),
+        reason: 'imports code from the internet. Import local files only.',
+    },
+    {
+        kinds: ['js'],
+        regex: new RegExp(`\\bimport\\b[^'"\`\\n]*["'\`](?:${EXTERNAL_URL})`),
+        reason: 'imports code from the internet. Import local files only.',
+    },
+    {
+        kinds: ['html'],
+        regex: new RegExp(`<script[^>]+src\\s*=\\s*["']?\\s*(?:${EXTERNAL_URL})`, 'i'),
+        reason: 'loads a script from the internet. Use local script files only.',
+    },
+    {
+        kinds: ['html'],
+        regex: new RegExp(`<(?:link|img|iframe|audio|video|source|embed|object)[^>]+(?:href|src|data)\\s*=\\s*["']?\\s*(?:${EXTERNAL_URL})`, 'i'),
+        reason: 'loads something from an outside web address. Use local files only.',
+    },
+    {
+        kinds: ['html'],
+        regex: new RegExp(`<form[^>]+action\\s*=\\s*["']?\\s*(?:${EXTERNAL_URL})`, 'i'),
+        reason: 'sends a form to an outside web address. Forms must stay local.',
+    },
+    {
+        kinds: ['css'],
+        regex: new RegExp(`url\\(\\s*["']?\\s*(?:${EXTERNAL_URL})`, 'i'),
+        reason: 'loads a style resource from the internet. Use local files only.',
+    },
+    {
+        kinds: ['css'],
+        regex: new RegExp(`@import\\s+["']?\\s*(?:${EXTERNAL_URL})`, 'i'),
+        reason: 'imports a stylesheet from the internet. Use local files only.',
+    },
+    // Eval family. Code built from strings is impossible to review.
+    {
+        kinds: ['js', 'html'],
+        regex: /\beval\s*\(/,
+        reason: 'uses eval, which runs code from a string. Write the code directly.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /\bnew\s+Function\s*\(/,
+        reason: 'uses new Function, which runs code from a string. Write the code directly.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /\bset(?:Timeout|Interval)\s*\(\s*["'`]/,
+        reason: 'passes a code string to a timer. Pass a function instead.',
+    },
+    // Storage and document tricks.
+    {
+        kinds: ['js', 'html'],
+        regex: /\bdocument\s*\.\s*cookie\b/,
+        reason: 'touches document.cookie. Use localStorage for saving game data.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /["'`=]\s*javascript:/i,
+        reason: 'uses a javascript: link, which hides code in a URL. Not allowed.',
+    },
+    {
+        kinds: ['js', 'html'],
+        regex: /data:text\/html/i,
+        reason: 'uses a data:text/html URL, which hides a page in a URL. Not allowed.',
+    },
+    {
+        kinds: ['html'],
+        regex: /\bsrcdoc\s*=/i,
+        reason: 'uses iframe srcdoc, which embeds a hidden page. Not allowed.',
+    },
+    {
+        kinds: ['html'],
+        regex: /<base\b/i,
+        reason: 'uses a base tag, which redirects where files load from. Not allowed.',
+    },
+    {
+        kinds: ['html'],
+        regex: /<meta[^>]+http-equiv\s*=\s*["']?refresh[^>]*url\s*=/i,
+        reason: 'uses a meta refresh that jumps to another page. Not allowed.',
+    },
+];
+/**
+ * Scans one project file. Returns ok plus plain-language reasons for each
+ * finding. TERMI.md and .txt files skip the scan: they are prose and go
+ * through text classification.
+ */
+export function scanCode(relPath, content) {
+    const kind = fileKind(relPath);
+    if (kind === 'skip') {
+        return { ok: true, reasons: [] };
+    }
+    const reasons = [];
+    for (const rule of RULES) {
+        if (!rule.kinds.includes(kind)) {
+            continue;
+        }
+        rule.regex.lastIndex = 0;
+        if (rule.regex.test(content)) {
+            reasons.push(`${relPath}: ${rule.reason}`);
+        }
+    }
+    return { ok: reasons.length === 0, reasons };
+}

package/dist/safety/guarddownload.js

@@ -0,0 +1,79 @@
+/**
+ * Background fetcher for the on-device classifier model.
+ *
+ * One in-flight download per process, kicked off without blocking whatever
+ * the kid or parent is doing. Progress is observable (the home menu and the
+ * grown-ups panel render it as a bar), completion is auditable, and the
+ * safety pipeline hot-attaches the classifier on its next check once the
+ * verified file lands. Interrupted transfers resume on the next kickoff.
+ */
+import { appendAudit } from './audit.js';
+import { downloadGuardModel, GUARD_MODEL, guardModelReady, } from './modelstore.js';
+let state = { status: 'idle', written: 0, total: GUARD_MODEL.bytes };
+let inFlight = null;
+/** Snapshot of the background fetch. 'ready' wins once the file exists. */
+export function guardFetchState() {
+    if (state.status !== 'downloading' && guardModelReady()) {
+        return { status: 'ready', written: GUARD_MODEL.bytes, total: GUARD_MODEL.bytes };
+    }
+    return { ...state };
+}
+function audit(excerpt) {
+    try {
+        appendAudit({ ts: new Date().toISOString(), layer: 'system', event: 'settings_change', excerpt });
+    }
+    catch {
+        // The fetcher never falls over because the audit disk write failed.
+    }
+}
+/**
+ * Starts the background download when the model is missing and nothing is
+ * already in flight. Returns the in-flight promise (true = model ready) so
+ * blocking callers, like the grown-ups panel, can await it; fire-and-forget
+ * callers just ignore it.
+ */
+export function ensureGuardFetch(opts = {}) {
+    if (guardModelReady()) {
+        state = { status: 'ready', written: GUARD_MODEL.bytes, total: GUARD_MODEL.bytes };
+        return Promise.resolve(true);
+    }
+    if (inFlight !== null) {
+        return inFlight;
+    }
+    state = { status: 'downloading', written: 0, total: opts.artifact?.bytes ?? GUARD_MODEL.bytes };
+    inFlight = downloadGuardModel({
+        ...opts,
+        onProgress: (written, total) => {
+            state.written = written;
+            state.total = total;
+            opts.onProgress?.(written, total);
+        },
+    })
+        .then(() => {
+        state = { ...state, status: 'ready', written: state.total };
+        audit('local classifier model downloaded');
+        return true;
+    })
+        .catch(() => {
+        state = { ...state, status: 'failed' };
+        audit('local classifier model download failed');
+        return false;
+    })
+        .finally(() => {
+        inFlight = null;
+    });
+    return inFlight;
+}
+/** Resets module state (tests only). */
+export function resetGuardFetchForTests() {
+    state = { status: 'idle', written: 0, total: GUARD_MODEL.bytes };
+    inFlight = null;
+}
+const BAR_SLOTS = 10;
+/** A kid-friendly progress bar: [####______] 42% of 623 MB. */
+export function guardProgressBar(snapshot = guardFetchState()) {
+    const share = snapshot.total > 0 ? Math.min(1, snapshot.written / snapshot.total) : 0;
+    const filled = Math.floor(share * BAR_SLOTS);
+    const bar = '#'.repeat(filled) + '_'.repeat(BAR_SLOTS - filled);
+    return `[${bar}] ${Math.floor(share * 100)}% of ${GUARD_MODEL.displaySize}`;
+}