termi-kids 0.1.0

package/dist/config/pin.js

@@ -0,0 +1,150 @@
+/**
+ * Parent PIN: scrypt hashed in the keychain, with a lockout after repeated
+ * failures and a reset path that wipes provider credentials.
+ *
+ * Storage:
+ *   - keychain "pin-hash": "<saltHex>:<hashHex>" (16-byte salt, scrypt
+ *     N=16384 r=8 p=1, 64-byte key)
+ *   - keychain "setup-marker": set when the wizard completes; survives
+ *     deletion of the TERMI_HOME directory so recovery stays PIN gated
+ *   - TERMI_HOME/pin.lock: JSON { failures, lockedUntil } tracking
+ *     consecutive failures and the active lockout, shared across processes
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { API_KEY_ACCOUNTS, deleteSecret, getSecret, setSecret, } from '../auth/keychain.js';
+import { atomicWriteFileSync, authJsonPath, termiHome } from './paths.js';
+const PIN_ACCOUNT = 'pin-hash';
+const SETUP_MARKER_ACCOUNT = 'setup-marker';
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SALT_BYTES = 16;
+const KEY_BYTES = 64;
+const MAX_FAILURES = 5;
+const LOCKOUT_MS = 5 * 60 * 1000;
+function lockFilePath() {
+    return path.join(termiHome(), 'pin.lock');
+}
+function readLockState() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockFilePath(), 'utf8'));
+        if (parsed !== null && typeof parsed === 'object') {
+            const candidate = parsed;
+            const failures = typeof candidate.failures === 'number' ? candidate.failures : 0;
+            const lockedUntil = typeof candidate.lockedUntil === 'number' ? candidate.lockedUntil : null;
+            return { failures, lockedUntil };
+        }
+    }
+    catch {
+        // Missing or unreadable lock file means a clean slate.
+    }
+    return { failures: 0, lockedUntil: null };
+}
+function writeLockState(state) {
+    atomicWriteFileSync(lockFilePath(), JSON.stringify(state), 0o600);
+}
+function clearLockState() {
+    try {
+        fs.rmSync(lockFilePath(), { force: true });
+    }
+    catch {
+        // Best effort; a stale zero-failure file is harmless.
+    }
+}
+function hashPin(pin, salt) {
+    return crypto.scryptSync(pin, salt, KEY_BYTES, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P });
+}
+/** Stores the PIN hash and clears any previous lockout state. */
+export function setPin(pin) {
+    const salt = crypto.randomBytes(SALT_BYTES);
+    const hash = hashPin(pin, salt);
+    setSecret(PIN_ACCOUNT, `${salt.toString('hex')}:${hash.toString('hex')}`);
+    clearLockState();
+}
+export function hasPin() {
+    return getSecret(PIN_ACCOUNT) !== null;
+}
+function pinMatches(pin, stored) {
+    const parts = stored.split(':');
+    if (parts.length !== 2) {
+        return false;
+    }
+    const [saltHex, hashHex] = parts;
+    if (!saltHex || !hashHex) {
+        return false;
+    }
+    const salt = Buffer.from(saltHex, 'hex');
+    const expected = Buffer.from(hashHex, 'hex');
+    if (salt.length !== SALT_BYTES || expected.length !== KEY_BYTES) {
+        return false;
+    }
+    const actual = hashPin(pin, salt);
+    return crypto.timingSafeEqual(actual, expected);
+}
+/**
+ * Verifies the PIN with constant-time comparison.
+ * Five consecutive failures lock verification for five minutes.
+ */
+export function verifyPin(pin) {
+    const now = Date.now();
+    let lock = readLockState();
+    if (lock.lockedUntil !== null) {
+        if (now < lock.lockedUntil) {
+            return {
+                ok: false,
+                lockedForSeconds: Math.ceil((lock.lockedUntil - now) / 1000),
+            };
+        }
+        // Lockout expired: start a fresh counting window.
+        lock = { failures: 0, lockedUntil: null };
+        writeLockState(lock);
+    }
+    const stored = getSecret(PIN_ACCOUNT);
+    if (stored === null) {
+        return { ok: false };
+    }
+    if (pinMatches(pin, stored)) {
+        clearLockState();
+        return { ok: true };
+    }
+    const failures = lock.failures + 1;
+    if (failures >= MAX_FAILURES) {
+        const lockedUntil = now + LOCKOUT_MS;
+        writeLockState({ failures, lockedUntil });
+        return { ok: false, lockedForSeconds: Math.ceil(LOCKOUT_MS / 1000) };
+    }
+    writeLockState({ failures, lockedUntil: null });
+    return { ok: false };
+}
+/**
+ * Forgot-PIN path: wipes the PIN hash, every provider API key, and the OAuth
+ * token file, so resetting gains the kid nothing. Returns the wiped item
+ * names. The caller writes the audit entry and reverts settings to strict.
+ */
+export function resetPin() {
+    const wiped = [];
+    if (deleteSecret(PIN_ACCOUNT)) {
+        wiped.push(PIN_ACCOUNT);
+    }
+    for (const account of API_KEY_ACCOUNTS) {
+        if (deleteSecret(account)) {
+            wiped.push(account);
+        }
+    }
+    const authFile = authJsonPath();
+    if (fs.existsSync(authFile)) {
+        fs.rmSync(authFile, { force: true });
+        wiped.push(path.basename(authFile));
+    }
+    clearLockState();
+    return wiped;
+}
+/** Records that the setup wizard finished. Lives in the keychain on purpose. */
+export function markSetupComplete() {
+    setSecret(SETUP_MARKER_ACCOUNT, new Date().toISOString());
+}
+export function isSetupComplete() {
+    return getSecret(SETUP_MARKER_ACCOUNT) !== null;
+}

package/dist/config/settings.js

@@ -0,0 +1,131 @@
+/**
+ * Signed settings persistence.
+ *
+ * settings.json holds a SettingsEnvelope: the Settings body plus an
+ * HMAC-SHA256 over its canonical JSON. The HMAC key lives in the keychain
+ * (account "hmac-key", random 32 bytes, created on first use). Any mismatch,
+ * parse failure, or missing-file-while-setup-marker-exists condition fails
+ * closed to the strictest defaults with tampered: true so the caller can
+ * force PIN-gated recovery.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { getSecret, setSecret } from '../auth/keychain.js';
+import { atomicWriteFileSync, settingsPath } from './paths.js';
+const HMAC_KEY_ACCOUNT = 'hmac-key';
+const SETUP_MARKER_ACCOUNT = 'setup-marker';
+/** The strictest possible configuration. Used as the fail-closed baseline. */
+export function defaultSettings() {
+    return {
+        version: 1,
+        installId: '',
+        kidNickname: '',
+        ageBand: 'under13',
+        consentAttestedAt: null,
+        activeProvider: null,
+        configuredProviders: [],
+        modelAlias: 'zippy',
+        safetyLevel: 'strict',
+        xaiParentAck: false,
+        localClassifier: true,
+        lastProjectSlug: null,
+    };
+}
+/**
+ * Fills fields added after a settings file was written and drops retired
+ * ones. Runs after the MAC check (the MAC covers the envelope as written).
+ * Older envelopes predate localClassifier: absent means on, the default.
+ */
+export function normalizeSettings(stored) {
+    const raw = stored;
+    const { ollamaClassifier: _retired, ...kept } = raw;
+    return { ...kept, localClassifier: raw.localClassifier ?? true };
+}
+/** Stable stringify: object keys sorted recursively, array order preserved. */
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            sorted[key] = sortValue(source[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+export function canonicalJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+function hmacKey() {
+    const existing = getSecret(HMAC_KEY_ACCOUNT);
+    if (existing) {
+        const key = Buffer.from(existing, 'hex');
+        if (key.length === 32) {
+            return key;
+        }
+    }
+    const fresh = crypto.randomBytes(32);
+    setSecret(HMAC_KEY_ACCOUNT, fresh.toString('hex'));
+    return fresh;
+}
+function signSettings(settings) {
+    return crypto.createHmac('sha256', hmacKey()).update(canonicalJson(settings)).digest('hex');
+}
+function isEnvelopeShape(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.mac === 'string' &&
+        candidate.settings !== null &&
+        typeof candidate.settings === 'object' &&
+        candidate.settings.version === 1);
+}
+function macMatches(expected, actual) {
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(actual, 'utf8');
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+export function loadSettings() {
+    const file = settingsPath();
+    if (!fs.existsSync(file)) {
+        const setupMarkerExists = getSecret(SETUP_MARKER_ACCOUNT) !== null;
+        if (setupMarkerExists) {
+            // Setup finished before, yet the file is gone. Someone removed state.
+            return { settings: defaultSettings(), tampered: true, firstRun: false };
+        }
+        return { settings: defaultSettings(), tampered: false, firstRun: true };
+    }
+    let envelope;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!isEnvelopeShape(parsed)) {
+            return { settings: defaultSettings(), tampered: true, firstRun: false };
+        }
+        envelope = parsed;
+    }
+    catch {
+        return { settings: defaultSettings(), tampered: true, firstRun: false };
+    }
+    const expectedMac = signSettings(envelope.settings);
+    if (!macMatches(expectedMac, envelope.mac)) {
+        return { settings: defaultSettings(), tampered: true, firstRun: false };
+    }
+    return { settings: normalizeSettings(envelope.settings), tampered: false, firstRun: false };
+}
+/**
+ * Signs and writes settings atomically. Generates installId on first save.
+ * Returns the settings exactly as persisted.
+ */
+export function saveSettings(settings) {
+    const toSave = { ...settings };
+    if (toSave.installId === '') {
+        toSave.installId = crypto.randomUUID();
+    }
+    const envelope = { settings: toSave, mac: signSettings(toSave) };
+    atomicWriteFileSync(settingsPath(), JSON.stringify(envelope, null, 2), 0o600);
+    return toSave;
+}