cotutor 0.2.0 → 0.4.0

package/dist/app/http/access.js

@@ -0,0 +1,180 @@
+/**
+ * 家长端与工作台的锁:一个机器级 PIN,孩子端永远不要。
+ * - **没设 PIN:行为和以前一字不差**,局域网全开。家长在旁边、用完收回 iPad 的家可以不设;doctor 的 server.access 提一句,不算错。
+ * - 设了:孩子端的路径(下面的白名单)照旧开;其余页面与接口要凭证。**本机(127.0.0.1 / ::1)免密**,所以电脑上开工作台、
+ *   探针脚本、测试都不用改;别的设备在 /parent、/dev 上输一次 PIN,拿一枚 HttpOnly cookie:HMAC 签的过期时间(90 天),不存会话表,重启 serve 还在。
+ * - PIN 存 ~/.config/cotutor/pin.json(scrypt 哈希,不存明文),签 cookie 的密钥在同目录 secret;**改 PIN 换密钥**,所有设备重输。连错 5 次锁 60 秒(挡孩子的好奇心够了)。
+ * - 白名单而不是黑名单:漏一条孩子端坏,马上看得见;黑名单漏一条就是又一个洞。
+ * - PIN 不放 cotutor.json:它能被工作台的 PATCH /api/config 改;放机器级和证书一样,几个孩子的 workspace 共用一个。
+ * 想想为什么不是「只许 loopback」:家长的主设备是 iPad(扫码进 /parent,打星、记账、删话题都在上面),工作台在手机上也要能开(侧栏收成顶上一条)。
+ */
+import { createHmac, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { USER_CONFIG } from "../workspace.js";
+import { DEV_CSS } from "../../ui/dev/dev-theme.js";
+import { BRAND_FOOTER } from "../../ui/shared/brand.js";
+export const USER_PIN_FILE = join(dirname(USER_CONFIG), 'pin.json');
+export const USER_SECRET_FILE = join(dirname(USER_CONFIG), 'secret');
+export const COOKIE_NAME = 'cotutor_parent';
+/** cookie 活多久:90 天;到了在 iPad 上再输一次 */
+export const COOKIE_DAYS = 90;
+export const PIN_RE = /^\d{4,8}$/;
+const MAX_FAILS = 5;
+const LOCK_MS = 60_000;
+/** 孩子端的路径:设了 PIN 也开;别的都要凭证。改孩子端加了新接口要来这里登记(tests/access.test.ts 盯着孩子端页面源码里用到的每条) */
+const KID_EXACT = new Set(['/', '/manifest.webmanifest', '/favicon.svg', '/favicon-32.png', '/favicon.ico', '/api/health', '/api/auth', '/dictation', '/dictation/', '/talk', '/talk/', '/api/dictation', '/api/talk']);
+const KID_PREFIX = ['/kid/', '/stage/', '/api/kid/', '/api/audio/', '/api/bundles/', '/api/dictation/', '/api/talk/', '/api/live/'];
+export function isKidPath(p) {
+    return KID_EXACT.has(p) || KID_PREFIX.some((x) => p.startsWith(x)) || /^\/icon-\d{2,4}\.png$/.test(p);
+}
+export async function readPin(file = USER_PIN_FILE) {
+    try {
+        const j = JSON.parse(await readFile(file, 'utf8'));
+        return typeof j.salt === 'string' && typeof j.hash === 'string' ? { salt: j.salt, hash: j.hash, at: j.at ?? '' } : null;
+    }
+    catch {
+        return null;
+    }
+}
+const hashPin = (pin, salt) => scryptSync(pin, salt, 32).toString('hex');
+/** 设 PIN(4–8 位数字):写哈希,换签 cookie 的密钥(所有设备重输) */
+export async function setPin(pin, files = {}) {
+    if (!PIN_RE.test(pin))
+        throw new Error('PIN 要 4 到 8 位数字');
+    const pinFile = files.pin ?? USER_PIN_FILE;
+    await mkdir(dirname(pinFile), { recursive: true });
+    const salt = randomBytes(16).toString('hex');
+    await writeFile(pinFile, `${JSON.stringify({ salt, hash: hashPin(pin, salt), at: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+    await writeFile(files.secret ?? USER_SECRET_FILE, randomBytes(32).toString('hex'), { mode: 0o600 });
+}
+/** 撤掉 PIN:回到全开 */
+export async function clearPin(files = {}) {
+    await rm(files.pin ?? USER_PIN_FILE, { force: true });
+    await rm(files.secret ?? USER_SECRET_FILE, { force: true });
+}
+export function verifyPin(pin, rec) {
+    if (!PIN_RE.test(pin))
+        return false;
+    const a = Buffer.from(hashPin(pin, rec.salt), 'hex');
+    const b = Buffer.from(rec.hash, 'hex');
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+const sign = (secret, exp) => createHmac('sha256', secret).update(String(exp)).digest('hex');
+/** 令牌 = 过期时刻.签名;只认签名对、没过期的 */
+export function signToken(secret, exp) {
+    return `${exp}.${sign(secret, exp)}`;
+}
+export function verifyToken(secret, token, now) {
+    const m = /^(\d{1,16})\.([0-9a-f]{64})$/.exec(token);
+    if (!m)
+        return false;
+    const exp = Number(m[1]);
+    if (!(exp > now))
+        return false;
+    const a = Buffer.from(m[2], 'hex');
+    const b = Buffer.from(sign(secret, exp), 'hex');
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export function cookieOf(header, name = COOKIE_NAME) {
+    for (const part of (header ?? '').split(';')) {
+        const i = part.indexOf('=');
+        if (i > 0 && part.slice(0, i).trim() === name)
+            return part.slice(i + 1).trim();
+    }
+    return null;
+}
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+export const isLoopback = (addr) => LOOPBACK.has(addr ?? '');
+export function createAccess(opts = {}) {
+    const now = () => (opts.now ?? (() => new Date()))().getTime();
+    const files = { pin: opts.files?.pin ?? USER_PIN_FILE, secret: opts.files?.secret ?? USER_SECRET_FILE };
+    let fails = 0;
+    let lockedUntil = 0;
+    const secret = async () => readFile(files.secret, 'utf8').then((s) => s.trim() || null, () => null);
+    return {
+        pinSet: async () => (await readPin(files.pin)) !== null,
+        async login(pin, o = {}) {
+            const rec = await readPin(files.pin);
+            if (!rec)
+                return { ok: false };
+            const t = now();
+            if (t < lockedUntil)
+                return { ok: false, retryMs: lockedUntil - t };
+            if (!verifyPin(pin, rec)) {
+                fails++;
+                if (fails >= MAX_FAILS) {
+                    fails = 0;
+                    lockedUntil = t + LOCK_MS;
+                    return { ok: false, retryMs: LOCK_MS };
+                }
+                return { ok: false };
+            }
+            fails = 0;
+            const key = await secret();
+            if (!key)
+                return { ok: false };
+            const maxAge = COOKIE_DAYS * 86400;
+            const token = signToken(key, t + maxAge * 1000);
+            return { ok: true, cookie: `${COOKIE_NAME}=${token}; Path=/; Max-Age=${maxAge}; HttpOnly; SameSite=Lax${o.secure ? '; Secure' : ''}` };
+        },
+        async whoOf(req) {
+            if (isLoopback(req.socket.remoteAddress))
+                return 'local';
+            const token = cookieOf(req.headers.cookie);
+            if (!token)
+                return 'anon';
+            const key = await secret();
+            return key && verifyToken(key, token, now()) ? 'parent' : 'anon';
+        },
+    };
+}
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** 没凭证的设备开家长端 / 工作台看到的那页:输 PIN,对了原地重载。孩子端的源码里没有它;mock 不接 */
+export function gatePage(title) {
+    return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>${esc(title)} · 家长</title>
+<style>
+${DEV_CSS}
+  body { min-height:100vh; display:flex; flex-direction:column; align-items:center; justify-content:center; padding:24px 16px; }
+  .gate { width:100%; max-width:360px; padding:28px 24px; box-shadow:var(--lift); }
+  .gate h1 { margin:0 0 4px; font:600 18px/1.3 var(--sans); }
+  .gate p { margin:0 0 18px; color:var(--muted); font-size:13px; }
+  .gate input { width:100%; height:48px; padding:0 14px; border:0; border-radius:var(--r-ctl); background:var(--sunk); font:600 22px/1 var(--mono); letter-spacing:.3em; text-align:center; }
+  .gate .btn { width:100%; height:44px; margin-top:12px; justify-content:center; font-size:15px; }
+  .gate .msg { min-height:20px; margin-top:10px; font-size:13px; color:var(--err); }
+  .gate small { display:block; margin-top:16px; color:var(--faint); font-size:12px; }
+</style>
+</head>
+<body>
+<form class="gate card-w" id="gate" autocomplete="off">
+  <h1>家长的页</h1>
+  <p>${esc(title)}:输一次这台电脑上设的 PIN,这台设备以后就不用再输。</p>
+  <input id="pin" type="password" inputmode="numeric" pattern="[0-9]*" autocomplete="one-time-code" maxlength="8" aria-label="家长 PIN" autofocus>
+  <button class="btn primary" type="submit">进去</button>
+  <div class="msg" id="msg" role="alert"></div>
+  <small>忘了?在电脑上重设:<code>cotutor pin</code>;不想要锁:<code>cotutor pin off</code>。</small>
+</form>
+${BRAND_FOOTER}
+<script>
+(() => {
+  const f = document.getElementById('gate'), pin = document.getElementById('pin'), msg = document.getElementById('msg');
+  f.addEventListener('submit', async (e) => {
+    e.preventDefault();
+    msg.textContent = '';
+    const r = await fetch('/api/auth', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ pin: pin.value }) }).catch(() => null);
+    if (r && r.ok) { location.reload(); return; }
+    let j = null; try { j = r ? await r.json() : null; } catch {}
+    msg.textContent = j && j.retryMs ? '连错几次了,等 ' + Math.ceil(j.retryMs / 1000) + ' 秒再试' : '不对,再试一次';
+    pin.value = ''; pin.focus();
+  });
+})();
+</script>
+</body>
+</html>
+`;
+}

package/dist/app/http/app.d.ts

@@ -0,0 +1,241 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type TranscriptRow } from '../../brain/transcript.ts';
+import { type KidMessage, type KidThread, type ParentMessage } from '../../runtime/kid-view.ts';
+import { type BoardMarkId } from '../../ui/kid/board-mark.ts';
+import { type Reel } from '../../ui/kid/reel.ts';
+import { type ConversationIndex, type ConversationMessage, type TutorExtra } from '../../schema/index.ts';
+import type { BoardCard, Device } from '../../board/presentation.ts';
+import type { Workspace } from '../../schema/index.ts';
+import { type Access, type Who } from './access.ts';
+import { type ListenInfo } from '../../ui/parent/qr-page.ts';
+import { Runner } from '../../runtime/runner.ts';
+import { type Bailian } from '../machine/bailian.ts';
+import { type VaultWrite } from '../../runtime/journal/store.ts';
+import type { Draw } from '../../media/draw.ts';
+export interface RouteResult {
+    status: number;
+    json?: unknown;
+    html?: string;
+    /** 静态文件(配音);handler 流式发 */
+    file?: string;
+    /** 现生成的二进制(主屏幕图标、网页图标) */
+    body?: Uint8Array;
+    contentType?: string;
+    /** file / body 的缓存策略;不给 = 一天(配音、课包这些不会变);头像会被 figshot 换掉,给 no-cache。json 不给 = no-store(笔顺数据例外,给一天) */
+    cacheControl?: string;
+    /** 要种的 cookie(/api/auth 对了 PIN) */
+    setCookie?: string;
+}
+export interface AppContext {
+    ws: Workspace;
+    runner: Runner;
+    /** 当前时间(测试可注入;孩子端「今天」与 today 别名都按它) */
+    now: () => Date;
+    /** 上次重载失败的原因(配置改坏了),健康接口回报 */
+    configError: string | null;
+    /** 在哪个地址上听着(serve 在 listen 之后填;扫码页 /qr 每次现问——局域网 IP 会在服务跑着的时候变)。没起端口(测试走 route)→ null */
+    listen: (() => ListenInfo) | null;
+    /** 现在开着几通电话(serve 接 ws 那边的数;没起端口 → null) */
+    openCalls: (() => number) | null;
+    /** 重读 cotutor.json(改了才读) */
+    reload(): Promise<void>;
+    /** 家长端与工作台的锁(access.ts):机器级 PIN,没设就全开;测试可注入 */
+    access: Access;
+    /** 百炼(bailian.ts):孩子端要它才打得开,家长端配;测试可注入 */
+    bailian: Bailian;
+}
+export declare function createContext(ws: Workspace, opts?: {
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+    draw?: Draw;
+    access?: Access;
+    bailian?: Bailian;
+}): AppContext;
+/** 一天的家长视图:索引 + 每条消息的转录行(主线 + 子代理折叠)+ 出错时的 err.log 尾巴 */
+export interface DayView {
+    index: ConversationIndex;
+    running: string | null;
+    runs: Record<string, TranscriptRow[]>;
+    errors: Record<string, string>;
+}
+export declare function dayView(ctx: AppContext, tutor: string, date: string): Promise<DayView>;
+/** 孩子端看到的老师:enabled 且不 hidden */
+export interface KidTutor {
+    name: string;
+    display: string;
+    avatar: string | null;
+    subject: string | null;
+    /** 学科色(服务端定好,src/ui/shared/tutor-color.ts;页面不自己算) */
+    color: string;
+    /** 板书底纹上写哪个学科字(board-mark.ts):三门主科各一个,别的老师 null 不写字 */
+    mark: BoardMarkId | null;
+    /** 他的听写写哪种:学科是英语(含别名)= en */
+    lang: 'zh' | 'en';
+    hasVoice: boolean;
+    /** 卡上的常驻入口:dictation 听写与拍照听写、talk 口语课(要 talk.enabled) */
+    extras: TutorExtra[];
+    /** 实时老师页缺省怎么说话(live.listen):hold 按住说、open 一直听;孩子切过的记在设备上,以那个为准 */
+    listen: 'hold' | 'open';
+}
+export declare function kidTutors(ctx: AppContext): Promise<KidTutor[]>;
+export interface KidHome {
+    title: string;
+    date: string;
+    tutors: KidTutor[];
+    /** 发布的首页 id(孩子点按钮时带回来);缺省首页 / 预览 = null */
+    home: string | null;
+    /** 首页的卡:老师卡在前,props.buttons 是孩子端的按钮;其余卡照文件顺序 */
+    cards: BoardCard[];
+    /** 「给老师们换个样子」的入口(figshot pick 在这台电脑的哪个端口);cotutor.json 没配 figshot 就是 null */
+    figshot: {
+        port: number;
+    } | null;
+    /** 按住说话那一栏在哪边(cotutor.json 的 kid.hand,家长端设置页改;缺省 right = 在左边):left = 平板横屏实时老师页的那一栏挪到右边 */
+    hand: 'right' | 'left';
+    /** 百炼配好了:没配孩子端只出「老师们还没到」,家长端配 */
+    ready: boolean;
+}
+export declare function kidHome(ctx: AppContext, now: Date): Promise<KidHome>;
+export interface KidDay {
+    tutor: string;
+    date: string;
+    messages: KidMessage[];
+    /** 老师正在回的那条 job */
+    pending: string | null;
+    /** 当前话题(末条消息所在);还没说过话 → null */
+    thread: string | null;
+}
+/** 「以前的」:最近 days 天每天的话题列表(今天也在),新的在前;没有孩子问过的话题不列 */
+export interface KidHistory {
+    tutor: string;
+    today: string;
+    days: {
+        date: string;
+        threads: KidThread[];
+    }[];
+}
+export declare function kidHistory(ctx: AppContext, tutor: string, days: number): Promise<KidHistory>;
+export declare function kidDay(ctx: AppContext, tutor: string, date: string): Promise<KidDay>;
+/** 家长板书页的一天:形状同 KidDay;答案不剥,系统发的也在 */
+export interface ParentDay {
+    tutor: string;
+    date: string;
+    messages: ParentMessage[];
+    pending: string | null;
+    thread: string | null;
+}
+export declare function parentDay(ctx: AppContext, tutor: string, date: string): Promise<ParentDay>;
+/**
+ * 家长端看录像:这个话题的轨道(ui/kid/reel.ts 排)+ 这个话题的家长条目(录像栏的说明用)+ 孩子端条目(孩子的屏幕照它画,
+ * 和 /api/kid 一样剥了答案)+ 孩子那台设备(屏幕多大)与老师的脸(孩子屏幕左上角)。话题一轮都没有 → null;孩子没开过口的也有(只有老师一轨)
+ */
+export interface ParentReel {
+    tutor: string;
+    date: string;
+    thread: string;
+    reel: Reel;
+    messages: ParentMessage[];
+    kid: KidMessage[];
+    /** 孩子发这个话题最后一句时的设备;没记 → null(页面按 iPad 横屏) */
+    device: Device | null;
+    /** 今天的话题:还会长(老师在写、孩子还会接着说),录像停在最后时隔几秒重拿 */
+    live: boolean;
+    /** 这个话题有实时的轮:孩子的屏幕是实时老师页的样子(左栏大头像 + 字幕、卡角没有钮) */
+    realtime: boolean;
+    face: {
+        name: string;
+        display: string;
+        avatar: string | null;
+        subject: string | null;
+        color: string;
+    };
+}
+export declare function parentReel(ctx: AppContext, tutor: string, date: string, thread: string): Promise<ParentReel | null>;
+/** 家长板书页的清单:这一天每位有脸的老师几轮、几个话题、停在哪 */
+export interface OverviewThread {
+    thread: string;
+    at: string;
+    /** 第一句:孩子的话截 20 字;首页按钮进来的是「首页 · 按钮字」;系统起的话题标出来 */
+    title: string;
+    from: ConversationMessage['from'];
+    via: string | null;
+    /**
+     * 孩子是点哪颗进来的(记录的卡照搬孩子端那颗):new 新话题(或没从首页进来)、start 开场、continue 接着、lecture 小课堂、activity、system 系统起的;
+     * label = 按钮上的字(new 是「新话题」)
+     */
+    start: {
+        kind: 'new' | 'start' | 'continue' | 'lecture' | 'activity' | 'system';
+        label: string;
+    };
+    /** 孩子自己说的第一句(截 30 字;按钮发的那句不算):新话题气泡上的小字 */
+    said: string | null;
+    /** 最后一轮老师写完(配好音)的时刻(ISO);没有计时的老数据 null */
+    endAt: string | null;
+    /** 看过小课堂:海报用 */
+    lecture?: {
+        bundle: string;
+        title: string;
+        video?: true;
+        watchedMs: number;
+        finished: boolean;
+        marks: number;
+    };
+    /** 各轮给家长的(去掉「## 家长」)与记住了:宽屏右栏「这一天老师跟你说的」 */
+    notes: string[];
+    remembered: string[];
+    /** 这个话题写进 vault 的每一笔(2026-10-30,《vault重构方案》§8):家长过目、单行撤回(job / kind / n 交给撤回接口);quote = 对上了的孩子原话 */
+    writes: {
+        job: string;
+        kind: VaultWrite['kind'];
+        n: number;
+        text: string;
+        quote?: string;
+    }[];
+    sections: number;
+    cards: number;
+    /** 老师还在写 / 末句问句停下等孩子 / 没停 */
+    stoppedAt: 'writing' | 'ask' | null;
+    rating: number | null;
+    booked: boolean;
+    /** 换过运行时(2026-10-31):这个话题是在哪个运行时下聊的;老师现在用别的,接不上那时的对话,不记账 */
+    oldRuntime?: string;
+    /** 按住说话连着几次没发出去(最长的一串,够 REEL_MISS_STREAK 才有) */
+    misses?: number;
+}
+export interface OverviewTutor {
+    name: string;
+    display: string;
+    avatar: string | null;
+    subject: string | null;
+    color: string;
+    turns: number;
+    threads: OverviewThread[];
+    /** 正在记账(记账或整理记忆的轮还在跑):家长端清单上的「记账」灰掉、行上写「记账中」 */
+    booking: boolean;
+    /** 卡上的常驻入口:家长端「记录」把听写、口语课挂在常驻它们的老师下面 */
+    extras: TutorExtra[];
+}
+export interface Overview {
+    title: string;
+    date: string;
+    today: string;
+    tutors: OverviewTutor[];
+    /** 七天日期条:date 所在的七天,每天有话题的老师(听写、口语课页面自己从模块接口补) */
+    week: {
+        date: string;
+        tutors: string[];
+    }[];
+    /** 百炼配好了;没配清单顶上一行叫家长去「首页」配 */
+    ready: boolean;
+}
+export declare function overview(ctx: AppContext, date: string): Promise<Overview>;
+/** 作业照片一张最多这么大(解码后;页面先缩到长边 PHOTO_MAX_SIDE 的 jpeg,通常几百 KB) */
+export declare const PHOTO_MAX_BYTES = 3000000;
+/** 请求从哪来(createHandler 从请求头取):设备 cookie、来源地址 */
+export interface RouteClient {
+    device?: string | null;
+    ip?: string;
+}
+/** who:请求是谁发的(createHandler 按来源地址与 cookie 算);直接调 route 的测试与 CLI 缺省 local = 本机免密 */
+export declare function route(method: string, path: string, ctx: AppContext, body?: unknown, who?: Who, client?: RouteClient): Promise<RouteResult>;
+export declare function createHandler(ctx: AppContext): (req: IncomingMessage, res: ServerResponse) => void;