termi-kids 0.1.0

package/dist/providers/index.js

@@ -0,0 +1,316 @@
+/**
+ * Provider client factory. One place that knows how to talk to each
+ * AI helper account: the ChatGPT sign-in backend, the OpenAI platform
+ * API, Anthropic, and xAI. Secrets come from the keychain (API keys)
+ * or from tokens.ts (the ChatGPT sign-in). fetch is injectable so the
+ * tests never touch the network.
+ */
+import { createHash } from 'node:crypto';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createXai } from '@ai-sdk/xai';
+import { getSecret } from '../auth/keychain.js';
+import { loadSettings } from '../config/settings.js';
+import { PROTOCOL_ORIGINATOR } from '../auth/oauth.js';
+import { getValidAccessToken, loadTokens } from '../auth/tokens.js';
+import { resolveModelId } from './models.js';
+/** Base URL of the ChatGPT coding backend (Responses wire shape, SSE). */
+export const CHATGPT_BACKEND_BASE_URL = 'https://chatgpt.com/backend-api/codex';
+function isSystemLikeMessage(item) {
+    if (item === null || typeof item !== 'object') {
+        return false;
+    }
+    const role = item.role;
+    return role === 'developer' || role === 'system';
+}
+function messageText(item) {
+    if (item === null || typeof item !== 'object') {
+        return null;
+    }
+    const content = item.content;
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const part of content) {
+            if (part !== null && typeof part === 'object') {
+                const text = part.text;
+                if (typeof text === 'string') {
+                    parts.push(text);
+                }
+            }
+        }
+        if (parts.length > 0) {
+            return parts.join('\n');
+        }
+    }
+    return null;
+}
+/**
+ * Sent as instructions when a request carries no system message at all
+ * (for example a prompted classifier call). The backend rejects requests
+ * without a top-level instructions string.
+ */
+export const CHATGPT_FALLBACK_INSTRUCTIONS = 'Follow the latest user message exactly.';
+/**
+ * Body params the ChatGPT coding backend rejects with a 400
+ * ("Unsupported parameter"). Verified live against the backend.
+ */
+const CHATGPT_REJECTED_PARAMS = ['max_output_tokens'];
+/**
+ * The load-bearing body shim for the ChatGPT backend. The backend requires
+ * a top-level "instructions" string and store set to false on every call.
+ * The AI SDK emits the system prompt as a developer message inside input[],
+ * so promote it and drop the message. Requests without any system message
+ * (for example classifier calls) get a neutral fallback instruction, and
+ * store defaults to false when the caller did not set it.
+ * Returns null when the body needs no change.
+ */
+function promoteInstructions(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    let changed = false;
+    if (obj.store === undefined || obj.store === null) {
+        obj.store = false;
+        changed = true;
+    }
+    for (const param of CHATGPT_REJECTED_PARAMS) {
+        if (param in obj) {
+            delete obj[param];
+            changed = true;
+        }
+    }
+    const hasInstructions = 'instructions' in obj && obj.instructions !== null && obj.instructions !== undefined;
+    const input = obj.input;
+    if (!hasInstructions && Array.isArray(input)) {
+        const index = input.findIndex((item) => isSystemLikeMessage(item));
+        const text = index >= 0 ? messageText(input[index]) : null;
+        if (index >= 0 && text !== null) {
+            obj.instructions = text;
+            obj.input = [...input.slice(0, index), ...input.slice(index + 1)];
+        }
+        else {
+            obj.instructions = CHATGPT_FALLBACK_INSTRUCTIONS;
+        }
+        changed = true;
+    }
+    return changed ? JSON.stringify(obj) : null;
+}
+/**
+ * Wraps fetch for the ChatGPT backend: fetches a fresh access token and
+ * injects the Authorization header per request, applies the instructions
+ * promotion shim to JSON bodies, and passes everything else through.
+ */
+export function makeChatgptFetch(getToken, baseFetch = globalThis.fetch) {
+    const wrapped = async (input, init) => {
+        const token = await getToken();
+        const nextInit = { ...(init ?? {}) };
+        const headers = new Headers(init?.headers);
+        headers.set('authorization', `Bearer ${token}`);
+        nextInit.headers = headers;
+        const body = init?.body;
+        if (typeof body === 'string') {
+            const shimmed = promoteInstructions(body);
+            if (shimmed !== null) {
+                nextInit.body = shimmed;
+            }
+        }
+        return baseFetch(input, nextInit);
+    };
+    return wrapped;
+}
+/**
+ * Hashes the install id into an anonymous, stable safety identifier.
+ * Sent on OpenAI platform API calls so any abuse flag lands on this
+ * one install instead of the whole account, per the provider's
+ * guidance for products used by minors. Never reversible to the id.
+ */
+export function hashedSafetyIdentifier(installId) {
+    return createHash('sha256').update(`termi:${installId}`).digest('hex').slice(0, 40);
+}
+/**
+ * Wraps fetch for the OpenAI platform API: injects safety_identifier
+ * into JSON request bodies that do not already carry one. Bodies that
+ * are not JSON objects pass through untouched.
+ */
+export function makeSafetyIdFetch(getInstallId, baseFetch = globalThis.fetch) {
+    const wrapped = async (input, init) => {
+        const body = init?.body;
+        const installId = getInstallId();
+        if (typeof body === 'string' && installId !== null && installId.length > 0) {
+            try {
+                const obj = JSON.parse(body);
+                if (obj !== null && typeof obj === 'object' && !Array.isArray(obj)) {
+                    const record = obj;
+                    if (!('safety_identifier' in record)) {
+                        record.safety_identifier = hashedSafetyIdentifier(installId);
+                        return baseFetch(input, { ...(init ?? {}), body: JSON.stringify(record) });
+                    }
+                }
+            }
+            catch {
+                // Not JSON: pass through unchanged.
+            }
+        }
+        return baseFetch(input, init);
+    };
+    return wrapped;
+}
+/**
+ * The free moderation endpoint needs an OpenAI platform key: either the
+ * parent-supplied one in the keychain or a key minted at sign-in.
+ */
+export function moderationKeyAccessor(readSecret = getSecret) {
+    const key = readSecret('api-key-openai-api');
+    if (key !== null && key.trim().length > 0) {
+        return key;
+    }
+    const minted = loadTokens()?.minted_api_key;
+    return minted !== undefined && minted.length > 0 ? minted : null;
+}
+/** Builds the client for one provider. Throws when it is not set up yet. */
+export function createProviderClient(providerId, deps = {}) {
+    const readSecret = deps.readSecret ?? getSecret;
+    const fetchImpl = deps.fetchImpl;
+    const moderationEndpoint = moderationKeyAccessor(readSecret) !== null;
+    switch (providerId) {
+        case 'openai-chatgpt': {
+            const stored = loadTokens();
+            if (stored === null) {
+                throw new Error('provider-not-configured:openai-chatgpt');
+            }
+            const getToken = deps.getAccessToken ?? (() => getValidAccessToken(fetchImpl));
+            const shimFetch = makeChatgptFetch(getToken, fetchImpl ?? globalThis.fetch);
+            const provider = createOpenAI({
+                baseURL: CHATGPT_BACKEND_BASE_URL,
+                apiKey: 'unused',
+                headers: {
+                    'chatgpt-account-id': stored.account_id,
+                    'OpenAI-Beta': 'responses=experimental',
+                    originator: PROTOCOL_ORIGINATOR,
+                    accept: 'text/event-stream',
+                },
+                fetch: shimFetch,
+            });
+            return {
+                id: providerId,
+                languageModel: (role, alias) => provider.responses(resolveModelId(providerId, role, alias)),
+                moderationEndpoint,
+            };
+        }
+        case 'openai-api': {
+            const key = readSecret('api-key-openai-api') ?? loadTokens()?.minted_api_key ?? null;
+            if (key === null || key.length === 0) {
+                throw new Error('provider-not-configured:openai-api');
+            }
+            // Resolved once per client, not per request: the id never changes
+            // mid-session and loadSettings costs a disk read plus an HMAC check.
+            let resolvedInstallId;
+            if (deps.installId !== undefined) {
+                resolvedInstallId = deps.installId;
+            }
+            else {
+                const id = loadSettings().settings.installId;
+                resolvedInstallId = id.length > 0 ? id : null;
+            }
+            const provider = createOpenAI({
+                apiKey: key,
+                fetch: makeSafetyIdFetch(() => resolvedInstallId, fetchImpl ?? globalThis.fetch),
+            });
+            return {
+                id: providerId,
+                languageModel: (role, alias) => provider.responses(resolveModelId(providerId, role, alias)),
+                moderationEndpoint,
+            };
+        }
+        case 'anthropic': {
+            const key = readSecret('api-key-anthropic');
+            if (key === null || key.length === 0) {
+                throw new Error('provider-not-configured:anthropic');
+            }
+            const provider = createAnthropic({
+                apiKey: key,
+                ...(fetchImpl !== undefined ? { fetch: fetchImpl } : {}),
+            });
+            return {
+                id: providerId,
+                languageModel: (role, alias) => provider(resolveModelId(providerId, role, alias)),
+                moderationEndpoint,
+            };
+        }
+        case 'xai': {
+            const key = readSecret('api-key-xai');
+            if (key === null || key.length === 0) {
+                throw new Error('provider-not-configured:xai');
+            }
+            // The adults-only acknowledgment is enforced here, not only in the
+            // wizard UI: a key dropped into the keychain by any other path still
+            // refuses to run until a parent has confirmed.
+            const ack = deps.xaiParentAck ?? loadSettings().settings.xaiParentAck;
+            if (!ack) {
+                throw new Error('provider-not-configured:xai');
+            }
+            const provider = createXai({
+                apiKey: key,
+                ...(fetchImpl !== undefined ? { fetch: fetchImpl } : {}),
+            });
+            return {
+                id: providerId,
+                languageModel: (role, alias) => provider(resolveModelId(providerId, role, alias)),
+                moderationEndpoint,
+            };
+        }
+    }
+}
+function safeCreate(providerId, deps) {
+    try {
+        return createProviderClient(providerId, deps);
+    }
+    catch {
+        return null;
+    }
+}
+/** First prompted-classifier client that builds, in preference order. */
+function promptedClassifierClient(availability, deps) {
+    const order = ['anthropic', 'openai-chatgpt', 'xai'];
+    for (const id of order) {
+        if (availability[id]) {
+            const client = safeCreate(id, deps);
+            if (client !== null) {
+                return client;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Picks the safety classifier backend, independent of the active main
+ * provider. Preference order: OpenAI moderation (any platform key,
+ * including a minted one), then Anthropic haiku, then the ChatGPT mini
+ * on quota, then xAI as the last resort. When the moderation key exists
+ * but the openai-api client will not build, the prompted kid-check falls
+ * through the same chain so grooming, pii, and jailbreak stay covered.
+ */
+export function pickClassifierBackend(settings, availability, deps = {}) {
+    // The on-device guard is not chosen here: it is wired straight into the
+    // safety pipeline (localGuard dep) and runs alongside whichever cloud
+    // backends this picker selects. settings stays for future cloud toggles.
+    void settings;
+    const readSecret = deps.readSecret ?? getSecret;
+    const moderationKey = moderationKeyAccessor(readSecret);
+    if (moderationKey !== null) {
+        const client = safeCreate('openai-api', deps) ?? promptedClassifierClient(availability, deps);
+        return { moderationKey, classifierClient: client };
+    }
+    return { moderationKey: null, classifierClient: promptedClassifierClient(availability, deps) };
+}

package/dist/providers/models.js

@@ -0,0 +1,38 @@
+/**
+ * The single home for model ids. Everything else uses aliases.
+ * "zippy" is the fast default, "smart" is the careful one, and
+ * "classifier" is the model the safety checks call when prompted.
+ */
+export const MODELS = {
+    'openai-chatgpt': {
+        zippy: 'gpt-5.4-mini',
+        smart: 'gpt-5.5',
+        classifier: 'gpt-5.4-mini',
+    },
+    'openai-api': {
+        zippy: 'gpt-5.4-mini',
+        smart: 'gpt-5.5',
+        classifier: 'gpt-5.4-mini',
+    },
+    anthropic: {
+        zippy: 'claude-sonnet-4-6',
+        smart: 'claude-opus-4-8',
+        classifier: 'claude-haiku-4-5',
+    },
+    xai: {
+        zippy: 'grok-4.3',
+        smart: 'grok-4.5',
+        classifier: 'grok-4.3',
+    },
+};
+/** The free dedicated moderation model on the OpenAI platform API. */
+export const MODERATION_MODEL_ID = 'omni-moderation-latest';
+/** Kid copy for the model picker. */
+export function modelLabel(alias) {
+    return alias === 'zippy' ? 'Zippy' : 'Extra smart';
+}
+/** Resolves an alias to the concrete model id for a provider and role. */
+export function resolveModelId(providerId, role, alias) {
+    const set = MODELS[providerId];
+    return role === 'classifier' ? set.classifier : set[alias];
+}

package/dist/safety/audit.js

@@ -0,0 +1,195 @@
+/**
+ * Tamper-evident audit log: JSONL with a forward HMAC chain.
+ *
+ * Each line is {...event, prevMac, mac} where
+ * mac = HMAC-SHA256(key, prevMac + canonicalJson(event)).
+ * The key is the shared "hmac-key" keychain secret (created on first use).
+ * Appends are single appendFileSync lines, so concurrent writers interleave
+ * whole entries. Rotation at 5 MB renames to audit.log.1 and starts the new
+ * file with an anchor line that carries the old file's last mac.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { getSecret, setSecret } from '../auth/keychain.js';
+import { auditLogPath, ensureDirs, termiHome } from '../config/paths.js';
+export const AUDIT_MAX_BYTES = 5 * 1024 * 1024;
+const GENESIS = 'genesis';
+const HMAC_ACCOUNT = 'hmac-key';
+/** Where the rotated previous log lands. */
+export function rotatedAuditLogPath() {
+    return `${auditLogPath()}.1`;
+}
+/**
+ * The key and the chain tip are cached between appends: without this,
+ * every audit event pays a keychain round trip plus a full read of the
+ * log just to find the last mac. Both caches self-invalidate when the
+ * state home or the file changes underneath them.
+ */
+let keyCache = null;
+let tipCache = null;
+/** Loads (or creates once) the shared HMAC key. */
+function hmacKey() {
+    const home = termiHome();
+    if (keyCache !== null && keyCache.home === home) {
+        return keyCache.key;
+    }
+    let hex = getSecret(HMAC_ACCOUNT);
+    if (!hex) {
+        hex = crypto.randomBytes(32).toString('hex');
+        setSecret(HMAC_ACCOUNT, hex);
+    }
+    const key = Buffer.from(hex, 'hex');
+    keyCache = { home, key };
+    return key;
+}
+/** JSON with recursively sorted keys, so the MAC input is stable. */
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function computeMac(key, prevMac, entryCanonical) {
+    return crypto.createHmac('sha256', key).update(prevMac).update(entryCanonical).digest('hex');
+}
+/** Reads the mac of the last line, or null for a fresh chain. */
+function lastMac(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+    const last = lines[lines.length - 1];
+    if (!last) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(last);
+        return typeof parsed.mac === 'string' ? parsed.mac : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Strips chain fields so the original entry can be re-canonicalized. */
+function entryWithoutChain(line) {
+    const copy = { ...line };
+    delete copy['prevMac'];
+    delete copy['mac'];
+    return copy;
+}
+function appendLine(file, entry, prevMac, key) {
+    const mac = computeMac(key, prevMac, canonicalJson(entry));
+    const full = { ...entry, prevMac, mac };
+    fs.appendFileSync(file, `${JSON.stringify(full)}\n`, { mode: 0o600 });
+    return mac;
+}
+/**
+ * Rotates when the file passed maxBytes: rename to audit.log.1 and start the
+ * new file with an anchor entry carrying the rotated file's last mac.
+ */
+function maybeRotate(file, key, maxBytes) {
+    let size = 0;
+    try {
+        size = fs.statSync(file).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= maxBytes) {
+        return;
+    }
+    const carried = lastMac(file) ?? GENESIS;
+    fs.rmSync(rotatedAuditLogPath(), { force: true });
+    fs.renameSync(file, rotatedAuditLogPath());
+    const anchor = {
+        ts: new Date().toISOString(),
+        layer: 'system',
+        anchor: true,
+        rotatedFrom: 'audit.log.1',
+    };
+    // The anchor chains off the rotated file's last mac, preserving continuity.
+    appendLine(file, anchor, carried, key);
+}
+/** Appends one audit event to the chained log. */
+export function appendAudit(event, opts) {
+    ensureDirs();
+    const file = auditLogPath();
+    const key = hmacKey();
+    maybeRotate(file, key, opts?.maxBytes ?? AUDIT_MAX_BYTES);
+    let size = 0;
+    try {
+        size = fs.statSync(file).size;
+    }
+    catch {
+        size = 0;
+    }
+    // The cached tip is only trusted while the file is exactly as we left
+    // it; any outside change falls back to reading the real last line.
+    const prevMac = tipCache !== null && tipCache.file === file && tipCache.size === size && size > 0
+        ? tipCache.mac
+        : (lastMac(file) ?? GENESIS);
+    const mac = appendLine(file, { ...event }, prevMac, key);
+    try {
+        tipCache = { file, size: fs.statSync(file).size, mac };
+    }
+    catch {
+        tipCache = null;
+    }
+}
+/**
+ * Walks the audit log and verifies the HMAC chain. A leading anchor line may
+ * carry a prevMac from a rotated file; its own mac must still verify.
+ */
+export function verifyAuditChain(file = auditLogPath()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return { ok: true, entries: 0, firstBadLine: null };
+    }
+    const key = hmacKey();
+    const lines = raw.split('\n');
+    let expectedPrev = null; // null until the first line fixes it
+    let entries = 0;
+    let lineNo = 0;
+    for (const line of lines) {
+        lineNo++;
+        if (!line.trim()) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return { ok: false, entries, firstBadLine: lineNo };
+        }
+        if (typeof parsed.mac !== 'string' || typeof parsed.prevMac !== 'string') {
+            return { ok: false, entries, firstBadLine: lineNo };
+        }
+        if (expectedPrev !== null && parsed.prevMac !== expectedPrev) {
+            return { ok: false, entries, firstBadLine: lineNo };
+        }
+        if (expectedPrev === null && !(parsed.prevMac === GENESIS || parsed['anchor'] === true)) {
+            return { ok: false, entries, firstBadLine: lineNo };
+        }
+        const recomputed = computeMac(key, parsed.prevMac, canonicalJson(entryWithoutChain(parsed)));
+        if (recomputed !== parsed.mac) {
+            return { ok: false, entries, firstBadLine: lineNo };
+        }
+        expectedPrev = parsed.mac;
+        entries++;
+    }
+    return { ok: true, entries, firstBadLine: null };
+}

package/dist/safety/blocks.js

@@ -0,0 +1,29 @@
+/**
+ * L5: turns a block verdict into the screen the kid sees.
+ * Never echoes blocked content. Always offers a way forward.
+ */
+import { T } from '../ui/text.js';
+import { blockMessage } from './taxonomy.js';
+/** Maps a blocking verdict to the kid-facing screen. */
+export function verdictToScreen(verdict) {
+    if (verdict.selfHarmConcern) {
+        return {
+            title: 'Thank you for telling me.',
+            body: T.selfHarmSupport.message,
+            mascotExpression: 'gentleNo',
+        };
+    }
+    if (verdict.failClosed) {
+        return {
+            title: 'Quick break time.',
+            body: T.errors.failClosed,
+            mascotExpression: 'oops',
+        };
+    }
+    const message = verdict.kidMessage ?? blockMessage(verdict.categories);
+    return {
+        title: 'Let us try that another way.',
+        body: `${message}\n${T.blocks.rephraseTip}`,
+        mascotExpression: 'gentleNo',
+    };
+}