copilot-operator 0.1.0

package/dist/src/api/dataAcl.js

@@ -0,0 +1,109 @@
+/**
+ * Who, besides the operator, can read or change a folder the bot keeps its records in.
+ *
+ * `data/` holds the API token, the settings (the deny list, the allowlist, the isolation claim),
+ * every session and the level-1 contract that is sent to Copilot; `runs/` holds every step's raw
+ * output. Checked on 2026-09-27: under `C:\Projects` a folder inherits `Authenticated Users:
+ * Modify` — every account on the machine could read the token and rewrite what the bot will run.
+ * A token that any local account can read guards nothing, which `security.ts` had already said in
+ * as many words.
+ *
+ * So at start each folder is narrowed to the account the API runs as, plus SYSTEM (which backup
+ * and the machine's own protection need), with inheritance from the parent cut; and then it is
+ * read back, by SID so that a translated Windows gives the same answer, and the API refuses to
+ * start if anybody else is still on it. Administrators are deliberately not added: they can take
+ * ownership of anything, and granting them access by default is granting it to every elevated
+ * process.
+ *
+ * Written to work under PowerShell's Constrained Language Mode, which corporate machines commonly
+ * enforce (verified 2026-09-27): the ACL is read as SDDL through `Get-Acl`, a cmdlet, and the
+ * account's SID through `Get-CimInstance`, another — neither the .NET `DirectoryInfo` call the
+ * first version used nor `WindowsIdentity` is allowed there. `icacls` is a system executable.
+ *
+ * Windows only. Elsewhere the folder's mode is the owner's business and this does nothing.
+ */
+import { spawnSync } from 'node:child_process';
+import { winPsEnv } from '../exec/winps.js';
+const SYSTEM_SID = 'S-1-5-18';
+/** SDDL's two-letter names for well-known principals, as `Get-Acl` prints them. */
+const SDDL_ALIASES = {
+    SY: 'S-1-5-18', // SYSTEM
+    BA: 'S-1-5-32-544', // Administrators
+    BU: 'S-1-5-32-545', // Users
+    AU: 'S-1-5-11', // Authenticated Users
+    WD: 'S-1-1-0', // Everyone
+    CO: 'S-1-3-0', // Creator Owner
+    CG: 'S-1-3-1', // Creator Group
+    OW: 'S-1-3-4', // Owner Rights
+    IU: 'S-1-5-4', // Interactive
+    RC: 'S-1-5-12', // Restricted Code
+    AN: 'S-1-5-7', // Anonymous
+    LS: 'S-1-5-19', // Local Service
+    NS: 'S-1-5-20', // Network Service
+    SO: 'S-1-5-32-549', // Server Operators
+    PU: 'S-1-5-32-547', // Power Users
+    RD: 'S-1-5-32-555', // Remote Desktop Users
+};
+/**
+ * The SIDs an SDDL string's DACL grants anything to, aliases expanded. Only access-allowed
+ * entries count: a deny entry for somebody is not access. Exported for the check.
+ */
+export function principalsInSddl(sddl) {
+    const dacl = /D:([^:]*)/.exec(sddl)?.[1] ?? '';
+    const out = new Set();
+    for (const ace of dacl.matchAll(/\(([^)]*)\)/g)) {
+        const parts = ace[1].split(';');
+        const type = (parts[0] ?? '').trim().toUpperCase();
+        const sid = (parts[5] ?? '').trim();
+        if (!sid || (type !== 'A' && type !== 'OA'))
+            continue;
+        out.add(SDDL_ALIASES[sid.toUpperCase()] ?? sid);
+    }
+    return [...out];
+}
+/** Narrows `dir` to this account and SYSTEM, then checks nobody else is on it. */
+export function secureDataDir(dir, env = process.env) {
+    if (process.platform !== 'win32')
+        return { ok: true };
+    const who = `${env.USERDOMAIN ?? ''}\\${env.USERNAME ?? ''}`;
+    spawnSync('icacls', [dir, '/inheritance:r', '/grant:r', `${who}:(OI)(CI)F`, '/grant:r', `*${SYSTEM_SID}:(OI)(CI)F`], {
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    const quoted = dir.replace(/'/g, "''");
+    const user = (env.USERNAME ?? '').replace(/'/g, "''");
+    const domain = (env.USERDOMAIN ?? '').replace(/'/g, "''");
+    const read = spawnSync('powershell', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        // The account's SID from WMI first (allowed in Constrained Language Mode), .NET second.
+        `$sid = (Get-CimInstance Win32_UserAccount -Filter "Name='${user}' AND Domain='${domain}'" -ErrorAction SilentlyContinue | Select-Object -First 1).SID; ` +
+            `if (-not $sid) { try { $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value } catch { $sid = '' } }; ` +
+            `$sddl = (Get-Acl -LiteralPath '${quoted}').Sddl; ` +
+            `@{ me = [string]$sid; sddl = [string]$sddl } | ConvertTo-Json -Compress`,
+    ], { encoding: 'utf8', windowsHide: true, timeout: 30_000, env: winPsEnv(env) });
+    const unreadable = { ok: false, reason: `could not read the permissions of ${dir}` };
+    if (read.status !== 0)
+        return unreadable;
+    try {
+        const { me, sddl } = JSON.parse(read.stdout);
+        const principals = principalsInSddl(sddl);
+        // A rule that could not be read is not evidence of nobody; fail closed.
+        if (!me || principals.length === 0)
+            return unreadable;
+        const others = principals.filter((s) => s !== me && s !== SYSTEM_SID);
+        if (others.length > 0) {
+            return {
+                ok: false,
+                reason: `${dir} can also be opened by ${others.join(', ')}. It holds the bot's records, so it must be readable by this ` +
+                    `account (and SYSTEM) only. Remove the others with icacls, or move the folder (COP_DATA_DIR, runsDir) somewhere ` +
+                    `private such as %LOCALAPPDATA%.`,
+            };
+        }
+        return { ok: true };
+    }
+    catch {
+        return unreadable;
+    }
+}

package/dist/src/api/folderPicker.js

@@ -0,0 +1,110 @@
+/**
+ * The native "pick a folder" dialog, for the Browse button in the web UI.
+ *
+ * A browser cannot hand a page a real directory path: the file input gives file names and the
+ * File System Access API gives a handle, never `C:\Projects\my-app`. But the API is a local
+ * process on the same machine as the browser, so it can open Windows' own folder dialog and
+ * report back what was picked. That is the only way the UI can offer a picker and still end up
+ * with the absolute path the mirror needs.
+ *
+ * The dialog is Windows-only by nature. Anywhere else this reports that plainly and the user
+ * types the path, which has always worked.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+/** Nothing is interpolated into the script; the start folder goes in as an environment variable. */
+const SCRIPT = `
+Add-Type -AssemblyName System.Windows.Forms | Out-Null
+$dialog = New-Object System.Windows.Forms.FolderBrowserDialog
+$dialog.Description = 'Select the project folder'
+$dialog.ShowNewFolderButton = $false
+if ($env:COP_PICKER_START -and (Test-Path -LiteralPath $env:COP_PICKER_START)) {
+  $dialog.SelectedPath = $env:COP_PICKER_START
+}
+# An owner window that is always on top, so the dialog lands in front of the browser
+# instead of behind it.
+$owner = New-Object System.Windows.Forms.Form
+$owner.TopMost = $true
+$owner.ShowInTaskbar = $false
+$owner.Opacity = 0
+$owner.Show()
+$result = $dialog.ShowDialog($owner)
+$owner.Close()
+if ($result -eq [System.Windows.Forms.DialogResult]::OK) {
+  [Console]::Out.Write('PICKED:' + $dialog.SelectedPath)
+} else {
+  [Console]::Out.Write('CANCELLED')
+}
+`;
+/** Windows PowerShell first: it is always present and its dialog is the familiar one. */
+function shellCandidates() {
+    return [
+        // No `-WindowStyle Hidden`: a hidden PowerShell is the first thing endpoint tooling hunts for, and
+        // the process is already started without a window (`windowsHide`), so the flag added nothing.
+        { exe: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-STA', '-Command', SCRIPT] },
+        { exe: 'pwsh.exe', args: ['-NoProfile', '-NonInteractive', '-STA', '-Command', SCRIPT] },
+    ];
+}
+/** Only one dialog at a time: a second one would sit behind the first with no way to reach it. */
+let open = false;
+export async function pickFolder(startDir, timeoutMs = 5 * 60_000) {
+    if (process.platform !== 'win32') {
+        return { ok: false, cancelled: false, reason: 'The folder dialog is Windows-only. Type the path instead.' };
+    }
+    if (open) {
+        return { ok: false, cancelled: false, reason: 'A folder dialog is already open. Finish it first.' };
+    }
+    open = true;
+    try {
+        for (const { exe, args } of shellCandidates()) {
+            const result = await run(exe, args, startDir, timeoutMs);
+            if (result.kind === 'unavailable')
+                continue;
+            return result.pick;
+        }
+        return { ok: false, cancelled: false, reason: 'PowerShell was not found, so the dialog could not be opened.' };
+    }
+    finally {
+        open = false;
+    }
+}
+function run(exe, args, startDir, timeoutMs) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(exe, args, {
+            windowsHide: true,
+            env: { ...process.env, COP_PICKER_START: startDir && existsSync(startDir) ? startDir : '' },
+        });
+        let out = '';
+        let err = '';
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(value);
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            settle({ kind: 'done', pick: { ok: false, cancelled: false, reason: 'The folder dialog timed out.' } });
+        }, timeoutMs);
+        child.stdout.on('data', (d) => (out += d.toString()));
+        child.stderr.on('data', (d) => (err += d.toString()));
+        child.on('error', () => {
+            clearTimeout(timer);
+            settle({ kind: 'unavailable' });
+        });
+        child.on('close', () => {
+            clearTimeout(timer);
+            const text = out.trim();
+            if (text.startsWith('PICKED:')) {
+                settle({ kind: 'done', pick: { ok: true, path: text.slice('PICKED:'.length).trim() } });
+            }
+            else if (text === 'CANCELLED') {
+                settle({ kind: 'done', pick: { ok: false, cancelled: true } });
+            }
+            else {
+                settle({ kind: 'done', pick: { ok: false, cancelled: false, reason: err.trim() || 'The folder dialog returned nothing.' } });
+            }
+        });
+    });
+}

package/dist/src/api/main.js

@@ -0,0 +1,132 @@
+/**
+ * Starts the API on localhost.
+ *
+ *   node dist/src/api/main.js
+ *
+ * Only 127.0.0.1 is bound, because this process drives the operator's own browser and runs
+ * commands on this machine. Exposing it on a network interface would hand that to anyone who
+ * could reach the port.
+ */
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import { join } from 'node:path';
+import { AppModule } from './app.module.js';
+import { OperatorService } from './operator.service.js';
+import { ensureApiToken, localApiGuard } from './security.js';
+import { secureDataDir } from './dataAcl.js';
+import { pruneRuns } from '../session/retention.js';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { installLayout } from '../config/layout.js';
+const PORT = Number(process.env.COP_API_PORT ?? 4000);
+const WEB_ORIGIN = process.env.COP_WEB_ORIGIN ?? 'http://localhost:3210';
+async function main() {
+    const app = await NestFactory.create(AppModule, { logger: ['error', 'warn', 'log'] });
+    // A plan pasted from a chat carries every task's text at once, which the 100 KB default
+    // refuses with a message about entity size that says nothing about plans.
+    app.useBodyParser('json', { limit: '5mb' });
+    app.enableCors({
+        origin: [WEB_ORIGIN, WEB_ORIGIN.replace('localhost', '127.0.0.1')],
+        /*
+         * The one header the page has to be able to read.
+         *
+         * A browser hands script only a handful of response headers across origins, and
+         * `content-disposition` is not among them unless it is named here. The UI is on
+         * `localhost:3210` and this is on `127.0.0.1:4000`, so every fetch is cross-origin: without
+         * this, a download built from a blob cannot find out what the file is called, and the
+         * carefully composed `copilot-operator-bundle-2-tasks-2-sessions-<stamp>.json` arrives as
+         * whatever the client guessed. The plain `<a download>` exports never noticed, because the
+         * browser reads the header itself for those and never shows it to the page.
+         */
+        exposedHeaders: ['content-disposition'],
+    });
+    app.setGlobalPrefix('api');
+    /*
+     * Who may drive this. Mounted before routing so it covers every route including the SSE stream,
+     * and so that no controller has to remember. See `security.ts` for why "it is only on localhost"
+     * was never the whole answer — a page in the operator's ordinary browser and any other process
+     * on the machine were both callers all along.
+     */
+    const layout = installLayout();
+    const dataDir = layout.dataDir;
+    await mkdir(dataDir, { recursive: true });
+    if (layout.mode === 'package') {
+        /*
+         * The records folder sits inside the project, so it must be invisible to the project's git:
+         * version control refuses to branch on a tree with untracked files, and the records are not
+         * the project's work. A `.gitignore` of `*` inside the folder says so without touching the
+         * project's own .gitignore.
+         */
+        const ignore = join(layout.homeDir, '.gitignore');
+        if (!existsSync(ignore))
+            await writeFile(ignore, '*\n', 'utf8');
+    }
+    // Before the token is read: a token any local account can read guards nothing. See `dataAcl.ts`.
+    const acl = secureDataDir(dataDir);
+    if (!acl.ok) {
+        console.error(`copilot-operator api will not start: ${acl.reason}`);
+        process.exit(1);
+    }
+    const token = await ensureApiToken(dataDir);
+    // The dev UI's origin, and this process's own for the interface it serves itself.
+    const allowedOrigins = [WEB_ORIGIN, WEB_ORIGIN.replace('localhost', '127.0.0.1'), `http://127.0.0.1:${PORT}`, `http://localhost:${PORT}`];
+    app.use(localApiGuard({ token, port: PORT, allowedOrigins, servesInterface: layout.webDir !== null }));
+    if (layout.webDir) {
+        // The prebuilt interface, from the package: one process, one port, no dev server.
+        app.useStaticAssets(layout.webDir, { extensions: ['html'], index: 'index.html' });
+    }
+    await app.listen(PORT, '127.0.0.1');
+    // Close whatever the previous process left open before anyone can look at it, rather than
+    // waiting for the first request to trigger it.
+    const ops = app.get(OperatorService);
+    await ops.bootstrap();
+    /*
+     * runs/ holds every step's raw output and, on a failure, a screenshot of the signed-in page —
+     * as much the bot's records as data/ is, and until 2026-09-27 left with whatever permissions its
+     * parent folder had. Narrowed the same way, and pruned to the configured retention.
+     */
+    const cfg = await ops.settings.load();
+    await mkdir(cfg.resolved.runsDir, { recursive: true });
+    const runsAcl = secureDataDir(cfg.resolved.runsDir);
+    if (!runsAcl.ok) {
+        console.error(`copilot-operator api will not start: ${runsAcl.reason}`);
+        process.exit(1);
+    }
+    for (const [name, dir] of [['data', dataDir], ['runs', cfg.resolved.runsDir]]) {
+        if (/onedrive/i.test(dir) || /^\\\\/.test(dir)) {
+            console.warn(`  warning: the ${name} folder (${dir}) is under OneDrive or on a network share; keep the bot's records on a local disk (COP_DATA_DIR, runsDir)`);
+        }
+    }
+    const pruned = await pruneRuns(cfg.resolved.runsDir, cfg.runsRetentionDays);
+    if (pruned.length > 0)
+        console.log(`  removed ${pruned.length} run folder(s) older than ${cfg.runsRetentionDays} days (runsRetentionDays)`);
+    if (layout.webDir) {
+        console.log(`copilot-operator is running for ${layout.projectRoot}`);
+        console.log(`  open http://127.0.0.1:${PORT}/ in your browser`);
+        console.log(`  records are kept in ${layout.homeDir}`);
+    }
+    else {
+        console.log(`copilot-operator api listening on http://127.0.0.1:${PORT}/api  (web origin ${WEB_ORIGIN})`);
+        console.log(`  requests need the token in ${join(dataDir, 'api-token')}; npm start hands it to the UI`);
+    }
+}
+/*
+ * A stray rejection must not end a run.
+ *
+ * Node's default for an unhandled rejection is to crash, which for this process means killing
+ * the browser, the queue and every session still waiting behind it — for a promise nobody was
+ * even reading any more. That happened: a losing `Promise.race` branch inside a download
+ * rejected when the window closed and took a batch of three sessions with it. The cause is
+ * fixed where it was, but the class of fault is not worth dying for, so it is logged loudly and
+ * the process carries on. A task that genuinely failed still fails, through its own error path.
+ */
+process.on('unhandledRejection', (reason) => {
+    console.error('[api] unhandled rejection (the run continues):', reason instanceof Error ? reason.stack : reason);
+});
+process.on('uncaughtException', (error) => {
+    console.error('[api] uncaught exception (the run continues):', error.stack ?? error.message);
+});
+main().catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+});