@kammcs/buildit-mcp 0.8.0 → 0.10.0

package/dist/files/paths.js

@@ -0,0 +1,69 @@
+/**
+ * Where a file a session shares may come from: inside the session's
+ * working folder or the OS temp folder (by its real path, symlinks
+ * resolved), and never from a well-known secret folder, whatever the roots.
+ */
+import { realpath } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { defaultTokenFile } from '../secrets/keychain.js';
+/** Whether paths on this platform compare without case (Windows and macOS). */
+const FOLD = process.platform === 'win32' || process.platform === 'darwin';
+const norm = (p) => (FOLD ? p.toLowerCase() : p);
+/** Whether `child` is `parent` or inside it (both resolved). */
+export function isInside(parent, child) {
+    const rel = relative(norm(parent), norm(child));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.startsWith(sep + sep));
+}
+/** The real path of a folder, or the folder itself when it can't be resolved. */
+async function real(folder) {
+    return realpath(folder).catch(() => resolve(folder));
+}
+/**
+ * The secret folders and files a session never shares from, under the home
+ * folder: SSH, cloud and cluster credentials, GnuPG, the Docker login,
+ * buildit-mcp's own token file, and the browsers' profiles (passwords and
+ * cookies).
+ */
+export function secretLocations(home = homedir()) {
+    const h = (...parts) => join(home, ...parts);
+    return [
+        h('.ssh'),
+        h('.aws'),
+        h('.azure'),
+        h('.gnupg'),
+        h('.config', 'gcloud'),
+        h('.kube'),
+        h('.docker', 'config.json'),
+        h('.git-credentials'),
+        dirname(defaultTokenFile()),
+        // Browser profiles.
+        h('AppData', 'Local', 'Google', 'Chrome', 'User Data'),
+        h('AppData', 'Local', 'Microsoft', 'Edge', 'User Data'),
+        h('AppData', 'Local', 'BraveSoftware'),
+        h('AppData', 'Roaming', 'Mozilla', 'Firefox'),
+        h('AppData', 'Roaming', 'Opera Software'),
+        h('Library', 'Application Support', 'Google', 'Chrome'),
+        h('Library', 'Application Support', 'Microsoft Edge'),
+        h('Library', 'Application Support', 'Firefox'),
+        h('Library', 'Application Support', 'BraveSoftware'),
+        h('Library', 'Safari'),
+        h('Library', 'Cookies'),
+        h('Library', 'Keychains'),
+        h('.mozilla'),
+        h('.config', 'google-chrome'),
+        h('.config', 'chromium'),
+        h('.config', 'BraveSoftware'),
+        h('.local', 'share', 'keyrings'),
+    ];
+}
+/** Why a resolved path may not be shared from where it is, or undefined. */
+export async function locationProblem(path, roots) {
+    const home = roots.home ?? homedir();
+    for (const secret of secretLocations(home)) {
+        if (isInside(await real(secret), path) || isInside(secret, path))
+            return 'secret_folder';
+    }
+    const allowed = [await real(roots.folder), await real(tmpdir())];
+    return allowed.some((root) => isInside(root, path)) ? undefined : 'outside_roots';
+}

package/dist/files/poster.js

@@ -0,0 +1,281 @@
+/**
+ * A video's length and poster frame, for `reply`'s `files`, made with
+ * ffprobe and ffmpeg when both are on the PATH. Without them (or when
+ * either fails, is slow, or makes a poster over the contract's limits),
+ * there is no poster and no length, and the file is shared as before:
+ * nothing here ever refuses a file.
+ *
+ * The programs run safely:
+ * - **No shell.** Each is spawned by its absolute path, found in the PATH's
+ *   absolute folders only (never the current folder, never a `.cmd` or
+ *   `.bat`, which would need a shell), with an argument array.
+ * - **Paths as `file:` URLs** of absolute paths, so a name can't be read as
+ *   an option or another protocol.
+ * - **A timeout** for each run (and the tool call's own signal), after
+ *   which the program is killed.
+ * - **A temporary output**, in a folder the caller removes, written by
+ *   ffmpeg with no metadata (`-map_metadata -1`), so the poster carries
+ *   nothing but the frame.
+ *
+ * The poster is a JPEG of at most 320 px a side (never enlarged) and
+ * 64 KiB, as the contract's `thumbnail` asks; a frame that is still over
+ * 64 KiB at the lowest quality is dropped.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, readFile, rm, stat } from 'node:fs/promises';
+import { delimiter, isAbsolute, join } from 'node:path';
+/** The contract's limits for a video's poster. */
+export const POSTER_MAX_BYTES = 64 * 1024;
+export const POSTER_MAX_SIDE = 320;
+/** The contract's limits for duration_ms. */
+const DURATION_MAX_MS = 86_400_000;
+/** How long ffprobe and ffmpeg may each take. */
+export const PROBE_TIMEOUT_MS = 10_000;
+export const FRAME_TIMEOUT_MS = 20_000;
+/** The JPEG qualities tried in turn (ffmpeg's -q:v, 2 best to 31 worst). */
+const QUALITIES = [4, 8, 14, 22, 31];
+/** At most this much of a program's output is kept. */
+const MAX_STDOUT = 16 * 1024;
+/**
+ * The absolute path of `name` in the PATH's absolute folders, or undefined.
+ * On Windows only `.exe` and `.com` count (a `.cmd` or `.bat` needs a shell).
+ */
+export async function findProgram(name, env = process.env, platform = process.platform) {
+    const win = platform === 'win32';
+    const raw = (win ? (env.Path ?? env.PATH) : env.PATH) ?? '';
+    const dirs = raw
+        .split(win ? ';' : delimiter)
+        .map((d) => d.trim().replace(/^"(.*)"$/, '$1'))
+        .filter((d) => d !== '' && isAbsolute(d));
+    const names = win ? [`${name}.exe`, `${name}.com`] : [name];
+    for (const dir of dirs) {
+        for (const n of names) {
+            const candidate = join(dir, n);
+            try {
+                const info = await stat(candidate);
+                if (!info.isFile())
+                    continue;
+                if (!win)
+                    await access(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // Not here.
+            }
+        }
+    }
+    return undefined;
+}
+/** Runs a program (no shell) and resolves with its exit code and first output; rejects on a spawn error or timeout. */
+function run(spawn, program, args, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        const limit = AbortSignal.timeout(timeoutMs);
+        const both = signal === undefined ? limit : AbortSignal.any([signal, limit]);
+        let child;
+        try {
+            child = spawn(program, args, {
+                shell: false,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                signal: both,
+                killSignal: 'SIGKILL',
+            });
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error('spawn failed'));
+            return;
+        }
+        let out = '';
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            if (out.length < MAX_STDOUT)
+                out += chunk.slice(0, MAX_STDOUT - out.length);
+        });
+        // Drained and dropped: its text can name the file.
+        child.stderr?.resume();
+        let settled = false;
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (both.aborted)
+                reject(new Error('timed out'));
+            else
+                resolve({ code, stdout: out });
+        });
+    });
+}
+/** A file's path as ffmpeg's `file:` URL protocol takes it (no option or protocol tricks). */
+export function fileArg(path) {
+    return `file:${path}`;
+}
+/** The length in ms that ffprobe's `format=duration` gives, within the contract's range. */
+export function parseDuration(stdout) {
+    const seconds = Number.parseFloat(stdout.trim().split(/\s+/)[0] ?? '');
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    const ms = Math.round(seconds * 1000);
+    if (ms < 1 || ms > DURATION_MAX_MS)
+        return undefined;
+    return ms;
+}
+/** A JPEG's width and height, from its first start-of-frame marker. */
+export function jpegSize(b) {
+    if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8)
+        return undefined;
+    const at = (n) => b[n] ?? 0;
+    const u16 = (n) => (at(n) << 8) | at(n + 1);
+    let i = 2;
+    while (i + 4 <= b.length) {
+        if (b[i] !== 0xff)
+            return undefined;
+        const marker = at(i + 1);
+        if (marker === 0xff) {
+            i++;
+            continue;
+        }
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            i += 2;
+            continue;
+        }
+        const len = u16(i + 2);
+        if (len < 2)
+            return undefined;
+        const sof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (sof) {
+            if (i + 9 > b.length)
+                return undefined;
+            const height = u16(i + 5);
+            const width = u16(i + 7);
+            return width > 0 && height > 0 ? { width, height } : undefined;
+        }
+        if (marker === 0xda || marker === 0xd9)
+            return undefined;
+        i += 2 + len;
+    }
+    return undefined;
+}
+/** ffprobe's arguments for a file's length. */
+export function probeArgs(source) {
+    return [
+        '-v',
+        'error',
+        '-show_entries',
+        'format=duration',
+        '-of',
+        'default=noprint_wrappers=1:nokey=1',
+        fileArg(source),
+    ];
+}
+/** ffmpeg's arguments for one poster frame at `atSeconds`, at most 320 px a side, no metadata. */
+export function frameArgs(source, output, atSeconds, quality) {
+    const side = POSTER_MAX_SIDE;
+    return [
+        '-nostdin',
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-ss',
+        atSeconds.toFixed(3),
+        '-i',
+        fileArg(source),
+        '-map',
+        '0:v:0',
+        '-frames:v',
+        '1',
+        '-an',
+        '-sn',
+        '-dn',
+        '-map_metadata',
+        '-1',
+        '-vf',
+        `scale=w='min(${side},iw)':h='min(${side},ih)':force_original_aspect_ratio=decrease,format=yuvj420p`,
+        '-c:v',
+        'mjpeg',
+        '-q:v',
+        String(quality),
+        '-f',
+        'image2',
+        '-update',
+        '1',
+        '-y',
+        fileArg(output),
+    ];
+}
+/** Where in the video the poster is taken: 1 s in, or a third of a shorter one. */
+export function posterTime(durationMs) {
+    if (durationMs === undefined)
+        return 0;
+    return durationMs > 3000 ? 1 : durationMs / 3000;
+}
+/**
+ * The video's length and a poster, written as `poster-<index>.jpg` in the
+ * folder `dir` gives (a temporary folder the caller removes; asked for only
+ * when both programs are found). Each is undefined when it can't be made;
+ * this never throws.
+ */
+export async function videoFacts(source, dir, index, options = {}) {
+    const spawn = options.spawn ?? nodeSpawn;
+    const which = options.which ?? ((name) => findProgram(name));
+    const none = { durationMs: undefined, poster: undefined };
+    try {
+        const [ffprobe, ffmpeg] = await Promise.all([which('ffprobe'), which('ffmpeg')]);
+        if (ffprobe === undefined || ffmpeg === undefined)
+            return none;
+        let durationMs;
+        try {
+            const probe = await run(spawn, ffprobe, probeArgs(source), PROBE_TIMEOUT_MS, options.signal);
+            if (probe.code === 0)
+                durationMs = parseDuration(probe.stdout);
+        }
+        catch {
+            // No length; the poster may still be made.
+        }
+        if (options.signal?.aborted === true)
+            return none;
+        const output = join(await dir(), `poster-${index}.jpg`);
+        const at = posterTime(durationMs);
+        const poster = await makePoster(spawn, ffmpeg, source, output, at, options.signal).catch(() => undefined);
+        return { durationMs, poster };
+    }
+    catch {
+        return none;
+    }
+}
+async function makePoster(spawn, ffmpeg, source, output, at, signal) {
+    for (const quality of QUALITIES) {
+        await rm(output, { force: true });
+        let r = await run(spawn, ffmpeg, frameArgs(source, output, at, quality), FRAME_TIMEOUT_MS, signal);
+        let bytes = r.code === 0 ? await readFile(output).catch(() => undefined) : undefined;
+        if ((bytes === undefined || bytes.length === 0) && at > 0) {
+            // No frame there (a short or odd file): the first frame instead.
+            await rm(output, { force: true });
+            r = await run(spawn, ffmpeg, frameArgs(source, output, 0, quality), FRAME_TIMEOUT_MS, signal);
+            bytes = r.code === 0 ? await readFile(output).catch(() => undefined) : undefined;
+            at = 0;
+        }
+        if (bytes === undefined || bytes.length === 0)
+            break;
+        if (bytes.length > POSTER_MAX_BYTES)
+            continue;
+        const size = jpegSize(bytes);
+        if (size === undefined || size.width > POSTER_MAX_SIDE || size.height > POSTER_MAX_SIDE)
+            break;
+        return {
+            path: output,
+            contentType: 'image/jpeg',
+            size: bytes.length,
+            width: size.width,
+            height: size.height,
+        };
+    }
+    await rm(output, { force: true }).catch(() => undefined);
+    return undefined;
+}

package/dist/files/scan.js

@@ -0,0 +1,108 @@
+/**
+ * The credential scan of a text file a session is about to share: the whole
+ * file, streamed in pieces of whole lines, through the tool approvals'
+ * credential rules (mask.ts, R1 to R8), before anything is uploaded. The
+ * agent API checks the first MiB again with the same rules.
+ *
+ * It names the lines and the rules' kinds, never a value.
+ */
+import { createReadStream } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+import { findCredentials } from '../channel/mask.js';
+/** The most lines a finding names. */
+export const FINDING_MAX_LINES = 20;
+/** How much text is scanned at once (whole lines; one longer line is scanned on its own). */
+const PIECE_CHARS = 1024 * 1024;
+/** A line longer than this is scanned in pieces (a minified file). */
+const LINE_MAX_CHARS = 8 * 1024 * 1024;
+/** What a piece of text adds to the finding, and how many lines it held. */
+function scanPiece(text, firstLine, into) {
+    const found = findCredentials(text, firstLine);
+    if (found !== undefined) {
+        for (const line of found.lines)
+            into.lines.add(line);
+        for (const kind of found.kinds)
+            into.kinds.add(kind);
+    }
+    // Lines as the rules count them: CR LF, CR and the Unicode separators end a line.
+    return lineBreaks(text);
+}
+/** How many line breaks a text holds: LF, CR LF and CR, and U+2028 and U+2029. */
+export function lineBreaks(text) {
+    let n = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (c === 10 || c === 0x2028 || c === 0x2029)
+            n++;
+        else if (c === 13 && text.charCodeAt(i + 1) !== 10)
+            n++;
+    }
+    return n;
+}
+/** Scans the file at `path` whole; undefined when nothing looks like a credential. */
+export async function scanFileForCredentials(path, signal) {
+    const decoder = new StringDecoder('utf8');
+    const found = { lines: new Set(), kinds: new Set() };
+    let pending = '';
+    let line = 1;
+    /** Scans the whole lines waiting (all of it at the end), keeping a partial last line. */
+    const flush = (end) => {
+        let cut = end ? pending.length : pending.lastIndexOf('\n') + 1;
+        if (!end && cut === 0) {
+            // One very long line: scanned in pieces, never cutting a CR LF in two.
+            if (pending.length <= LINE_MAX_CHARS)
+                return;
+            cut = pending.charCodeAt(LINE_MAX_CHARS - 1) === 13 ? LINE_MAX_CHARS - 1 : LINE_MAX_CHARS;
+        }
+        if (cut === 0)
+            return;
+        line += scanPiece(pending.slice(0, cut), line, found);
+        pending = pending.slice(cut);
+    };
+    const stream = createReadStream(path, {
+        highWaterMark: 256 * 1024,
+        ...(signal ? { signal } : {}),
+    });
+    for await (const chunk of stream) {
+        pending += decoder.write(chunk);
+        if (pending.length >= PIECE_CHARS)
+            flush(false);
+    }
+    pending += decoder.end();
+    flush(true);
+    if (found.kinds.size === 0)
+        return undefined;
+    const order = [
+        'private_key',
+        'authorization_header',
+        'bearer_token',
+        'url_password',
+        'credential_option',
+        'credential_assignment',
+        'api_key',
+        'jwt',
+    ];
+    return {
+        lines: [...found.lines].sort((a, b) => a - b).slice(0, FINDING_MAX_LINES),
+        kinds: order.filter((k) => found.kinds.has(k)),
+    };
+}
+/** A finding in plain words: "line 12 looks like an API key". */
+export function describeFinding(f) {
+    const what = f.kinds.map((k) => KIND_WORDS[k] ?? k.replace(/_/g, ' ')).join(', ');
+    if (f.lines.length === 0)
+        return `it looks like it holds ${what}`;
+    if (f.lines.length === 1)
+        return `line ${f.lines[0]} looks like ${what}`;
+    return `lines ${f.lines.join(', ')} look like ${what}`;
+}
+const KIND_WORDS = {
+    private_key: 'a private key',
+    authorization_header: 'an Authorization header',
+    bearer_token: 'a bearer token',
+    url_password: 'a password in a URL',
+    credential_option: 'a password or token option',
+    credential_assignment: 'a password, secret or token assignment',
+    api_key: 'an API key',
+    jwt: 'a JSON Web Token',
+};

package/dist/files/transfer.js

@@ -0,0 +1,163 @@
+/**
+ * The two requests that don't go to the agent API: the GET of a presigned
+ * download URL and the PUT of a presigned upload URL. They go straight to
+ * storage, so they never carry the token (no Authorization header), and
+ * the PUT sends exactly the signed headers with the file streamed from disk.
+ *
+ * A presigned URL is a bearer URL for its few minutes: it is never logged,
+ * written to disk or shown to Claude, and an error never repeats it.
+ */
+import { createReadStream, createWriteStream } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+/** A failed transfer: an HTTP status from storage, or a local reason. Never the URL. */
+export class TransferError extends Error {
+    reason;
+    status;
+    constructor(reason, status) {
+        super(reason === 'status'
+            ? `storage answered HTTP ${status ?? 0}`
+            : reason === 'too_large'
+                ? 'the download is larger than the file'
+                : reason === 'short'
+                    ? 'the download ended early'
+                    : reason === 'timeout'
+                        ? 'the transfer timed out'
+                        : reason === 'url'
+                            ? 'the storage URL is not one this server uses'
+                            : 'the network failed');
+        this.reason = reason;
+        this.status = status;
+        this.name = 'TransferError';
+    }
+}
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+/** The URL, if storage may be reached there: https, or http on this computer (a local stack). */
+function storageUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new TransferError('url');
+    }
+    if (url.protocol === 'https:')
+        return url;
+    if (url.protocol === 'http:' && LOOPBACK.has(url.hostname))
+        return url;
+    throw new TransferError('url');
+}
+function send(url, method, headers, signal) {
+    const request = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    const req = request(url, { method, headers, ...(signal ? { signal } : {}) });
+    const response = new Promise((resolve, reject) => {
+        req.on('response', resolve);
+        req.on('error', (err) => {
+            reject(signal?.aborted === true || err.name === 'AbortError'
+                ? new TransferError('timeout')
+                : new TransferError('network'));
+        });
+    });
+    return { req, response };
+}
+/** Reads and drops a response's body (at most 64 KiB kept, as text). */
+async function readSmall(res) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of res) {
+        const b = chunk;
+        if (size < 65_536)
+            chunks.push(b);
+        size += b.length;
+    }
+    return Buffer.concat(chunks).toString('utf8').slice(0, 65_536);
+}
+/**
+ * GETs `url` into a new file at `dest` (created 0600, never over an
+ * existing file), stopping when more than `maxBytes` arrive. Returns the
+ * bytes written. With `exactBytes`, a shorter or longer body fails. The
+ * partial file is removed on any failure.
+ */
+export async function downloadToFile(rawUrl, dest, options) {
+    const url = storageUrl(rawUrl);
+    const { req, response } = send(url, 'GET', { Accept: '*/*' }, options.signal);
+    req.end();
+    let written = 0;
+    try {
+        const res = await response;
+        if ((res.statusCode ?? 0) < 200 || (res.statusCode ?? 0) >= 300) {
+            await readSmall(res).catch(() => '');
+            throw new TransferError('status', res.statusCode);
+        }
+        const counter = new Transform({
+            transform(chunk, _enc, done) {
+                written += chunk.length;
+                if (written > options.maxBytes)
+                    done(new TransferError('too_large'));
+                else
+                    done(null, chunk);
+            },
+        });
+        await pipeline(res, counter, createWriteStream(dest, { flags: 'wx', mode: 0o600 }), {
+            ...(options.signal ? { signal: options.signal } : {}),
+        }).catch((err) => {
+            if (err instanceof TransferError)
+                throw err;
+            throw new TransferError(options.signal?.aborted === true ? 'timeout' : 'network');
+        });
+        if (options.exactBytes !== undefined && written !== options.exactBytes) {
+            throw new TransferError(written < options.exactBytes ? 'short' : 'too_large');
+        }
+        return written;
+    }
+    catch (err) {
+        req.destroy();
+        await rm(dest, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+/**
+ * PUTs the file at `source` (`size` bytes) to `url` with exactly `headers`
+ * (the signed Content-Type and Content-Length), streamed, and no
+ * Authorization header. `onBytes` hears the bytes sent so far.
+ */
+export async function uploadFile(rawUrl, headers, source, size, options = {}) {
+    const url = storageUrl(rawUrl);
+    const sent = {};
+    for (const [name, value] of Object.entries(headers)) {
+        // Never a credential of ours: storage's signature is the only one.
+        if (name.toLowerCase() === 'authorization')
+            continue;
+        sent[name] = value;
+    }
+    if (!Object.keys(sent).some((k) => k.toLowerCase() === 'content-length')) {
+        sent['Content-Length'] = String(size);
+    }
+    const { req, response } = send(url, 'PUT', sent, options.signal);
+    let count = 0;
+    const counter = new Transform({
+        transform(chunk, _enc, done) {
+            count += chunk.length;
+            options.onBytes?.(count);
+            done(null, chunk);
+        },
+    });
+    const body = pipeline(createReadStream(source), counter, req).catch(() => {
+        // The response (or its error) says what happened.
+    });
+    try {
+        const res = await response;
+        await readSmall(res).catch(() => '');
+        await body;
+        if ((res.statusCode ?? 0) < 200 || (res.statusCode ?? 0) >= 300) {
+            throw new TransferError('status', res.statusCode);
+        }
+    }
+    catch (err) {
+        req.destroy();
+        throw err;
+    }
+}