copilot-operator 0.1.0

package/dist/src/api/saveToDesktop.js

@@ -0,0 +1,157 @@
+/**
+ * A log, on the Desktop, with Explorer already pointing at it.
+ *
+ * The operator does not read these logs in a browser. They run the bot, and then they hand
+ * what came out of it to a separate chat that orchestrates the whole effort. Offering the log
+ * as a page in a new tab was answering a question nobody had: getting it from that tab into
+ * the chat meant save-as, then remembering where the browser put it, then finding it again,
+ * then dragging it. Four steps, every one of them somewhere else on the screen.
+ *
+ * So the log is written as a file instead, and Explorer is opened on it with the file already
+ * selected. One press, and the thing the operator wants to drag is under the cursor. The
+ * browser is not asked to be a file manager, because it is not one.
+ *
+ * The files go into one folder under the Desktop rather than loose on it. A Desktop that
+ * slowly fills with task logs is a worse outcome than the tab ever was, and a folder that is
+ * always the same one is also a place the operator learns, so the second log is found without
+ * being revealed at all.
+ *
+ * Nothing here overwrites. A log that was saved once may already have been dragged into a
+ * chat, attached to a message or renamed by somebody; writing over it because the same button
+ * was pressed twice would destroy a file the bot has no claim on. Every save earns its own
+ * name, and the timestamp in that name is what tells two saves of one attempt apart.
+ *
+ * Revealing is a Windows idea and this module says so plainly anywhere else, in the manner of
+ * `folderPicker.ts`: the file is still written, and the caller is told where, so the feature
+ * degrades to something useful rather than to an error.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { resolveDesktopDir } from '../context/contextFiles.js';
+/** The one folder under the Desktop that every saved log lands in. */
+export const LOGS_FOLDER = 'copilot-operator-logs';
+/** The folder every saved log goes into. */
+export function logsDir(env = process.env) {
+    return join(resolveDesktopDir(env), LOGS_FOLDER);
+}
+/**
+ * One part of a file name, made safe for NTFS.
+ *
+ * Session names and task titles are prose written by a human, so they carry colons, slashes
+ * and quotation marks as a matter of course — every one of them illegal in a Windows file
+ * name. A name Windows refuses is a save that fails for a reason the operator cannot act on,
+ * so the illegal characters become dashes rather than a refusal. The trailing dots and spaces
+ * go too: Windows silently drops them, which would leave the path the caller was told about
+ * and the file actually on disk disagreeing.
+ */
+export function sanitiseNamePart(part, limit = 60) {
+    const cleaned = part
+        .replace(/[<>:"/\\|?*\u0000-\u001f]/g, '-')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, limit)
+        .replace(/[. ]+$/, '');
+    return cleaned.length > 0 ? cleaned : 'unnamed';
+}
+/** The timestamp in a file name: sortable, readable, and legal, so local time with no colons. */
+function stampOf(at) {
+    const two = (n) => String(n).padStart(2, '0');
+    return (`${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())}` +
+        `-${two(at.getHours())}${two(at.getMinutes())}${two(at.getSeconds())}`);
+}
+/**
+ * The name a saved log is given: the session, the task, the attempt and when it was saved.
+ *
+ * All four are there because the operator ends up with a folder of these and has to tell them
+ * apart by sight, in the drag-and-drop list of a chat, without opening any of them.
+ */
+export function logFileName(naming, at = new Date()) {
+    const parts = [sanitiseNamePart(naming.session, 40), sanitiseNamePart(naming.task, 60)];
+    if (naming.attempt !== undefined)
+        parts.push(`attempt ${naming.attempt}`);
+    // A task's own file keeps its extension; the consolidated log is text and says so.
+    const extension = naming.file ? extname(naming.file) || '.txt' : '.txt';
+    if (naming.file) {
+        const stem = naming.file.slice(0, naming.file.length - extname(naming.file).length);
+        parts.push(sanitiseNamePart(stem, 50));
+    }
+    parts.push(stampOf(at));
+    return `${parts.join(' - ')}${extension}`;
+}
+/**
+ * The asked-for name, or the first free variation of it.
+ *
+ * Two saves inside the same second collide on the timestamp, and so does a folder restored
+ * from a backup. Windows' own ` (2)` suffix is used because the operator has seen it before
+ * and knows what it means.
+ */
+export function freeName(dir, fileName, taken = existsSync) {
+    if (!taken(join(dir, fileName)))
+        return fileName;
+    const extension = extname(fileName);
+    const stem = fileName.slice(0, fileName.length - extension.length);
+    for (let n = 2; n < 1000; n += 1) {
+        const candidate = `${stem} (${n})${extension}`;
+        if (!taken(join(dir, candidate)))
+            return candidate;
+    }
+    // A thousand collisions is not a folder anyone is still reading, so stop guessing politely.
+    return `${stem} (${Date.now()})${extension}`;
+}
+/**
+ * Explorer, opened on the folder with the file selected.
+ *
+ * `explorer.exe` exits with a non-zero code when it has done exactly what was asked, which is
+ * long-standing and documented behaviour rather than a bug to work around, so the exit code is
+ * ignored entirely. Only a failure to start the process at all means the reveal did not
+ * happen. The arguments go through verbatim because Explorer parses `/select,"<path>"` itself
+ * and Node's own quoting of an argument with spaces in it would leave it parsing something
+ * else.
+ *
+ * `windowsHide` is deliberately not set, unlike everywhere else in this codebase that starts a
+ * process: it asks Windows to start the child with its window hidden, and a hidden window is
+ * the exact opposite of the point here. Explorer is a windowed program with no console of its
+ * own, so nothing flashes for leaving it off.
+ */
+export const revealInExplorer = (path) => new Promise((settle, fail) => {
+    const child = spawn('explorer.exe', [`/select,"${path}"`], {
+        windowsVerbatimArguments: true,
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.on('error', fail);
+    // Explorer outlives the API process; nothing here waits for it to close.
+    child.on('spawn', () => {
+        child.unref();
+        settle();
+    });
+});
+/**
+ * Writes the text to the Desktop folder and opens Explorer on it.
+ *
+ * Failing to reveal is not failing to save. The file is on disk either way and the caller is
+ * told where, because a path the operator can paste into an address bar is still most of what
+ * they wanted.
+ */
+export async function saveAndReveal(text, naming, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const dir = logsDir(env);
+    await mkdir(dir, { recursive: true });
+    const fileName = freeName(dir, logFileName(naming, options.now ?? new Date()));
+    const path = join(dir, fileName);
+    await writeFile(path, text, 'utf8');
+    if (platform !== 'win32') {
+        return { path, dir, fileName, revealed: false, note: 'Opening the folder is Windows-only. The file was saved.' };
+    }
+    const reveal = options.reveal ?? revealInExplorer;
+    try {
+        await reveal(path);
+        return { path, dir, fileName, revealed: true };
+    }
+    catch (e) {
+        return { path, dir, fileName, revealed: false, note: `The file was saved, but Explorer did not open: ${e.message}` };
+    }
+}

package/dist/src/api/security.js

@@ -0,0 +1,225 @@
+/**
+ * Who is allowed to drive this API.
+ *
+ * The controller used to say it plainly: "There is no authentication because there is no network:
+ * this API runs on the operator's own machine and drives that machine's browser." Every clause of
+ * that is true and the conclusion does not follow, because "no network" is not the same as "no
+ * callers". Two of them were always reachable.
+ *
+ * A web page. Any site the operator visits in their ordinary browser can issue requests to
+ * `http://127.0.0.1:4000`. CORS stops that page *reading* the answer, which is not the point: a
+ * request that starts a session has done its damage before anybody reads anything. And an origin
+ * check alone is not enough either, because DNS rebinding exists — the attacker's own domain is
+ * made to resolve to 127.0.0.1, and from the browser's point of view the request is then
+ * same-origin. The answer to that is the `Host` header, which still carries the attacker's name.
+ *
+ * Another process on the machine. Anything running locally can POST to the port and queue a task
+ * that runs commands. A token in a file readable by the same user does not stop a process running
+ * *as* that user — nothing at this layer can — but it does stop everything that cannot read that
+ * file: another account, a container, a curious script, and any of the browser cases above.
+ *
+ * So three checks, cheapest first, and all of them before Nest's routing sees the request:
+ *
+ *   host      the request must be addressed to this loopback port by name. Defeats rebinding.
+ *   origin    a browser always sets it on a cross-origin request and a page cannot forge it, so
+ *             an origin that is not the configured UI is refused outright rather than merely
+ *             prevented from reading the reply.
+ *   token     a per-install secret, in `Authorization: Bearer`, `x-cop-token`, or — for the two
+ *             kinds of request that cannot carry a header at all, `EventSource` and a plain
+ *             `<a download>` — the `token` query parameter.
+ *
+ * `/api/health` is deliberately open: `scripts/dev.mjs` polls it to find out whether the API has
+ * finished starting, it says nothing but the time, and requiring a token to ask "are you up" would
+ * make the start-up race harder to debug for no gain.
+ *
+ * The web interface, when this process serves it (an install from npm, `cop start`): its pages are
+ * static files and answer without a token — the host check still applies, so a rebound domain gets
+ * nothing — and every page hands the browser the token as a cookie scoped to `/api`, HttpOnly (no
+ * script reads it) and SameSite=Strict (no other site's page sends it). The page's own requests
+ * then carry it by themselves, the stream and the downloads included, and no URL ever holds it.
+ *
+ * The honest limit, since this is the file somebody will quote: none of this contains a process
+ * already running as the operator. It raises the floor from "anything on this machine, and quite a
+ * few things off it" to "something that can read a file in the install". The boundary is still the
+ * account the runner runs in.
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The one path that answers without a token. */
+export const OPEN_PATHS = ['/api/health'];
+export const TOKEN_FILE = 'api-token';
+/**
+ * Whether the `Host` header names this loopback port.
+ *
+ * The header is the attacker's own domain under DNS rebinding, which is exactly why it is worth
+ * reading: the address resolves to 127.0.0.1 but it is still called `evil.example`, and a check
+ * that only looked at the socket would see nothing wrong at all.
+ */
+export function isLoopbackHost(host, port) {
+    if (!host)
+        return false;
+    let hostname = host;
+    let hostPort;
+    if (host.startsWith('[')) {
+        // `[::1]:4000`
+        const close = host.indexOf(']');
+        if (close < 0)
+            return false;
+        hostname = host.slice(1, close);
+        const rest = host.slice(close + 1);
+        if (rest.startsWith(':'))
+            hostPort = rest.slice(1);
+        else if (rest.length > 0)
+            return false;
+    }
+    else {
+        const colon = host.lastIndexOf(':');
+        if (colon >= 0) {
+            hostname = host.slice(0, colon);
+            hostPort = host.slice(colon + 1);
+        }
+    }
+    const loopback = hostname === '127.0.0.1' || hostname === '::1' || hostname.toLowerCase() === 'localhost';
+    if (!loopback)
+        return false;
+    return hostPort === undefined || hostPort === String(port);
+}
+/**
+ * Whether a request's `Origin` is one the UI is served from.
+ *
+ * An absent origin is allowed through to the token check: it means the caller is not a browser —
+ * `curl`, the CLI, a script — and for those the token is the whole of the answer. A *present*
+ * origin that does not match is refused, because only a browser sets it and only a page on another
+ * site would set it to anything else.
+ */
+export function originAllowed(origin, allowed) {
+    if (!origin)
+        return true;
+    const o = origin.trim().toLowerCase().replace(/\/$/, '');
+    return allowed.some((a) => a.trim().toLowerCase().replace(/\/$/, '') === o);
+}
+/** Constant-time comparison, so a wrong token cannot be found one character at a time. */
+export function tokenMatches(presented, expected) {
+    if (!presented || !expected)
+        return false;
+    const a = Buffer.from(presented, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/** The cookie the served interface is given the token in. */
+export const TOKEN_COOKIE = 'cop_token';
+/** Whether a path is the web interface rather than the API. */
+export function isInterfacePath(path) {
+    return path !== '/api' && !path.startsWith('/api/');
+}
+/** The `Set-Cookie` value that hands a served page the token. */
+export function tokenCookie(token) {
+    return `${TOKEN_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/api`;
+}
+/** The token a request presents, from any of the places one can be carried. */
+export function presentedToken(req) {
+    const cookie = req.headers.cookie;
+    if (typeof cookie === 'string') {
+        for (const part of cookie.split(';')) {
+            const [name, ...rest] = part.trim().split('=');
+            if (name === TOKEN_COOKIE && rest.join('=').trim())
+                return rest.join('=').trim();
+        }
+    }
+    const auth = req.headers.authorization;
+    if (typeof auth === 'string' && /^bearer\s+/i.test(auth))
+        return auth.replace(/^bearer\s+/i, '').trim();
+    const header = req.headers['x-cop-token'];
+    if (typeof header === 'string' && header.trim())
+        return header.trim();
+    const q = req.query?.token;
+    if (typeof q === 'string' && q.trim())
+        return q.trim();
+    return undefined;
+}
+/**
+ * The install's token, read from `<dataDir>/api-token` and created there if it is not there yet.
+ *
+ * Generated rather than configured, so a machine that nobody has thought about is not a machine
+ * with a default password. Written with owner-only permissions where the platform honours them;
+ * on Windows that is a best effort and the file's protection is really the profile's, which is the
+ * same protection the session store and the Edge profile already rely on.
+ */
+export async function ensureApiToken(dataDir) {
+    const path = join(dataDir, TOKEN_FILE);
+    try {
+        const existing = (await readFile(path, 'utf8')).trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // Not there yet, or unreadable: make one.
+    }
+    const token = randomBytes(32).toString('hex');
+    await mkdir(dataDir, { recursive: true });
+    await writeFile(path, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+    return token;
+}
+/**
+ * The decision, with no Express in it, so the rules can be exercised directly by a check rather
+ * than through a running server. `localApiGuard` is the thin wrapper that puts it on the wire.
+ */
+export function judgeRequest(req, opts) {
+    const host = typeof req.headers.host === 'string' ? req.headers.host : undefined;
+    if (!isLoopbackHost(host, opts.port)) {
+        return {
+            ok: false,
+            status: 421,
+            reason: 'host',
+            detail: `this API answers only to 127.0.0.1:${opts.port}; the request was addressed to "${host ?? '(none)'}"`,
+        };
+    }
+    const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined;
+    if (!originAllowed(origin, opts.allowedOrigins)) {
+        return { ok: false, status: 403, reason: 'origin', detail: `requests from ${origin} are not accepted by this API` };
+    }
+    if (OPEN_PATHS.includes(req.path))
+        return { ok: true };
+    // The interface's own files: answered to the right host with no token, since they are how the
+    // browser gets one. Only when this process serves them; see `localApiGuard`.
+    if (opts.servesInterface && isInterfacePath(req.path))
+        return { ok: true };
+    const presented = presentedToken({ headers: req.headers, query: (req.query ?? {}) });
+    if (!tokenMatches(presented, opts.token)) {
+        return {
+            ok: false,
+            status: 401,
+            reason: 'token',
+            detail: 'this API needs the token kept in data/api-token (.copilot-operator/data/api-token when installed from npm), ' +
+                'as an Authorization: Bearer header, ' +
+                'an x-cop-token header, or a token query parameter. Open the interface from `npx cop start` (or ' +
+                '`npm start` in a clone) and it is given the token.',
+        };
+    }
+    return { ok: true };
+}
+/** The guard as Express middleware, mounted before Nest's routing so it covers every route. */
+export function localApiGuard(opts) {
+    return (req, res, next) => {
+        /*
+         * A CORS preflight carries no credentials and is answered by the CORS layer; refusing it here
+         * would turn every cross-origin refusal into an opaque network error in the page rather than
+         * the 401 the UI can actually say something about.
+         */
+        if (req.method === 'OPTIONS') {
+            next();
+            return;
+        }
+        const verdict = judgeRequest({ path: req.path, headers: req.headers, query: req.query }, opts);
+        if (verdict.ok) {
+            if (opts.servesInterface && isInterfacePath(req.path))
+                res.setHeader('Set-Cookie', tokenCookie(opts.token));
+            next();
+            return;
+        }
+        res.status(verdict.status).json({ error: verdict.reason, message: verdict.detail });
+    };
+}

package/dist/src/api/settings.js

@@ -0,0 +1,57 @@
+/**
+ * Settings for the API: the same shape as `run.yaml`, kept as `data/settings.json`.
+ *
+ * The UI edits this file through the API. Anything not present falls back to the schema
+ * defaults, so an empty file is a valid, safe configuration.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { loadConfigObject } from '../config/schema.js';
+export class Settings {
+    projectRoot;
+    dataDir;
+    installDefaults;
+    path;
+    constructor(projectRoot, dataDir, 
+    /**
+     * Defaults that depend on how the program is installed, applied under whatever the file says.
+     * A package keeps its runs in the project's records folder and reads its contract from the
+     * package; a checkout's own defaults (`./runs`, `prompts/level1.md`) need nothing here.
+     */
+    installDefaults = {}) {
+        this.projectRoot = projectRoot;
+        this.dataDir = dataDir;
+        this.installDefaults = installDefaults;
+        this.path = join(dataDir, 'settings.json');
+    }
+    /** The raw object as saved, or `{}` when there is no file yet. */
+    async raw() {
+        if (!existsSync(this.path))
+            return {};
+        try {
+            return JSON.parse(await readFile(this.path, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Parsed, defaulted and resolved against the project root. */
+    async load() {
+        const raw = await this.raw();
+        return await loadConfigObject({ ...this.installDefaults, ...raw, dataDir: this.dataDir }, this.projectRoot, this.path);
+    }
+    /** Validates before saving, so a bad edit is rejected rather than stored. */
+    async save(value) {
+        const resolved = await loadConfigObject({ ...this.installDefaults, ...value, dataDir: this.dataDir }, this.projectRoot, this.path);
+        await mkdir(dirname(this.path), { recursive: true });
+        await writeFile(this.path, JSON.stringify(value, null, 2), 'utf8');
+        return resolved;
+    }
+    /** The schema defaults, for the UI to show what "not set" means. */
+    async defaults() {
+        const resolved = await loadConfigObject({}, this.projectRoot, 'defaults');
+        const { configPath: _c, baseDir: _b, resolved: _r, ...cfg } = resolved;
+        return cfg;
+    }
+}