@overcrow/mcp 0.0.0 → 0.1.1

package/dist/bootstrap/download.js

@@ -0,0 +1,229 @@
+// Downloads one pinned file over HTTPS. Only the expected hosts are
+// contacted; redirects are followed by hand and bounded; the size must be
+// exactly the pinned size; the SHA-256 is computed while reading, and the
+// caller compares it with the pin before anything reads the file.
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { connect as tlsConnect } from "node:tls";
+export class DownloadError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = "DownloadError";
+    }
+}
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+/** Checks that `target` is an HTTPS URL of an allowed host, without credentials. */
+export function checkUrl(target, allowedHosts, testPort) {
+    if (target.protocol !== "https:")
+        throw new DownloadError(`refused a non-HTTPS address (${target.protocol})`);
+    if (target.username || target.password)
+        throw new DownloadError("refused an address with credentials");
+    if (!allowedHosts.includes(target.hostname.toLowerCase())) {
+        throw new DownloadError(`refused a redirect to another host (${target.hostname})`);
+    }
+    const port = target.port === "" ? 443 : Number(target.port);
+    if (port !== 443 && port !== testPort)
+        throw new DownloadError(`refused port ${port}`);
+}
+/**
+ * Downloads `url` into `destination` (created, never overwritten) and
+ * returns its size and SHA-256. On any failure the partial file is removed.
+ */
+export async function downloadPinned(url, destination, options) {
+    const maxRedirects = options.maxRedirects ?? 3;
+    const deadline = Date.now() + (options.totalTimeoutMs ?? 10 * 60_000);
+    let target = new URL(url);
+    checkUrl(target, options.allowedHosts, options.port);
+    try {
+        for (let hop = 0;; hop += 1) {
+            const response = await get(target, options, deadline);
+            const status = response.statusCode ?? 0;
+            if (REDIRECTS.has(status)) {
+                response.resume();
+                const location = response.headers.location;
+                if (!location)
+                    throw new DownloadError(`redirect ${status} without a location`);
+                if (hop >= maxRedirects)
+                    throw new DownloadError("too many redirects");
+                target = new URL(location, target);
+                checkUrl(target, options.allowedHosts, options.port);
+                continue;
+            }
+            if (status !== 200) {
+                response.resume();
+                throw new DownloadError(status === 404 ? "the file is not published (404)" : `the server answered ${status}`);
+            }
+            return await save(response, destination, options, deadline);
+        }
+    }
+    catch (error) {
+        await unlink(destination).catch(() => undefined);
+        if (error instanceof DownloadError)
+            throw error;
+        throw new DownloadError(networkReason(error));
+    }
+}
+function networkReason(error) {
+    const code = error.code;
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN")
+        return "the address could not be resolved (offline?)";
+    if (code === "ECONNREFUSED")
+        return "the connection was refused";
+    if (code === "ECONNRESET" || code === "EPIPE")
+        return "the connection was cut";
+    if (code?.startsWith("ERR_TLS") || code?.includes("CERT"))
+        return `the TLS certificate was refused (${code})`;
+    if (code === "ABORT_ERR")
+        return "cancelled";
+    return code ? `network error (${code})` : "network error";
+}
+/** One GET request, directly or through the proxy's CONNECT tunnel. */
+async function get(target, options, deadline) {
+    const host = target.hostname;
+    const port = target.port === "" ? 443 : Number(target.port);
+    const tunnel = options.proxy
+        ? await connectThroughProxy(options.proxy, host, port, options, deadline)
+        : undefined;
+    const requestOptions = {
+        method: "GET",
+        host,
+        port,
+        path: `${target.pathname}${target.search}`,
+        servername: host,
+        headers: {
+            "user-agent": "overcrow-mcp",
+            accept: "application/octet-stream",
+            // The size check needs the bytes as stored.
+            "accept-encoding": "identity",
+        },
+        rejectUnauthorized: true,
+        agent: false,
+        ...(options.ca !== undefined ? { ca: options.ca } : {}),
+        ...(tunnel ? { createConnection: () => tunnel } : {}),
+    };
+    return new Promise((resolve, reject) => {
+        const request = httpsRequest(requestOptions, resolve);
+        guard(request, options, deadline, reject);
+        request.end();
+    });
+}
+/** Applies the connection, idle and total timeouts and the abort signal to `request`. */
+function guard(request, options, deadline, reject) {
+    const connectTimer = setTimeout(() => request.destroy(new DownloadError("the connection timed out")), Math.min(options.connectTimeoutMs ?? 30_000, Math.max(0, deadline - Date.now())));
+    request.once("response", () => clearTimeout(connectTimer));
+    request.once("close", () => clearTimeout(connectTimer));
+    request.setTimeout(options.idleTimeoutMs ?? 60_000, () => request.destroy(new DownloadError("the server stopped sending")));
+    const onAbort = () => request.destroy(new DownloadError("cancelled"));
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    request.once("close", () => options.signal?.removeEventListener("abort", onAbort));
+    request.once("error", reject);
+}
+/** Opens a CONNECT tunnel through an `http://` proxy and returns its TLS socket. */
+async function connectThroughProxy(proxy, host, port, options, deadline) {
+    let proxyUrl;
+    try {
+        proxyUrl = new URL(proxy.includes("://") ? proxy : `http://${proxy}`);
+    }
+    catch {
+        throw new DownloadError("the proxy setting (HTTPS_PROXY) is not a valid address");
+    }
+    if (proxyUrl.protocol !== "http:") {
+        throw new DownloadError("only an http:// proxy is supported (HTTPS_PROXY)");
+    }
+    const headers = { host: `${host}:${port}` };
+    if (proxyUrl.username) {
+        const credentials = `${decodeURIComponent(proxyUrl.username)}:${decodeURIComponent(proxyUrl.password)}`;
+        headers["proxy-authorization"] = `Basic ${Buffer.from(credentials).toString("base64")}`;
+    }
+    const socket = await new Promise((resolve, reject) => {
+        const request = httpRequest({
+            method: "CONNECT",
+            host: proxyUrl.hostname,
+            port: proxyUrl.port === "" ? 80 : Number(proxyUrl.port),
+            path: `${host}:${port}`,
+            headers,
+            agent: false,
+        });
+        guard(request, options, deadline, reject);
+        request.once("connect", (response, tunnelSocket) => {
+            if (response.statusCode !== 200) {
+                tunnelSocket.destroy();
+                reject(new DownloadError(`the proxy refused the connection (${response.statusCode})`));
+                return;
+            }
+            resolve(tunnelSocket);
+        });
+        request.end();
+    });
+    return tlsConnect({
+        socket,
+        servername: host,
+        rejectUnauthorized: true,
+        ...(options.ca !== undefined ? { ca: options.ca } : {}),
+    });
+}
+/** Streams the body to `destination`, bounded by the expected size. */
+async function save(response, destination, options, deadline) {
+    const declared = response.headers["content-length"];
+    if (declared !== undefined && Number(declared) !== options.expectedSize) {
+        response.resume();
+        throw new DownloadError(`the file has another size than the pinned one (${declared} bytes)`);
+    }
+    const encoding = response.headers["content-encoding"];
+    if (encoding !== undefined && encoding !== "identity") {
+        response.resume();
+        throw new DownloadError(`unexpected content encoding (${encoding})`);
+    }
+    const hash = createHash("sha256");
+    const output = createWriteStream(destination, { flags: "wx", mode: 0o600 });
+    let received = 0;
+    let lastReport = 0;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const fail = (error) => {
+            // Destroying the response emits its own events: the first reason wins.
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+            response.destroy();
+            output.destroy();
+        };
+        const totalTimer = setTimeout(() => fail(new DownloadError("the download took too long")), Math.max(0, deadline - Date.now()));
+        output.once("error", (error) => fail(error));
+        response.once("error", (error) => fail(error));
+        response.once("aborted", () => fail(new DownloadError("the connection was cut")));
+        response.on("data", (chunk) => {
+            received += chunk.length;
+            if (received > options.expectedSize) {
+                fail(new DownloadError("the file is larger than the pinned size"));
+                return;
+            }
+            hash.update(chunk);
+            if (!output.write(chunk)) {
+                response.pause();
+                output.once("drain", () => response.resume());
+            }
+            if (options.onProgress && received - lastReport >= 1 << 20) {
+                lastReport = received;
+                options.onProgress(received, options.expectedSize);
+            }
+        });
+        response.once("end", () => {
+            clearTimeout(totalTimer);
+            if (received !== options.expectedSize) {
+                fail(new DownloadError("the download ended early"));
+                return;
+            }
+            settled = true;
+            output.end(() => resolve());
+        });
+        output.once("close", () => clearTimeout(totalTimer));
+    });
+    return { sha256: hash.digest("hex"), size: received };
+}

package/dist/bootstrap/install.js

@@ -0,0 +1,280 @@
+// Installs the creator tools of one platform from a ZIP whose SHA-256 is the
+// pinned one: every file is extracted by the strict reader and checked
+// against the pin, the ZIP's own SHA256SUMS, cli.json and runtimes.json must
+// agree, and the CLI must pin exactly the runtime beside it. The files land
+// in a private temporary directory that is renamed into place at the end;
+// on any failure nothing is kept. Nothing goes on the PATH.
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { extractEntry, readEntries } from "./zip.js";
+export class InstallError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InstallError";
+    }
+}
+const ZIP_LIMITS = { maxEntries: 64, maxEntryBytes: 256 << 20, maxTotalBytes: 512 << 20 };
+const MAX_METADATA_BYTES = 64 * 1024;
+export function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function executableSuffix(platform) {
+    return platform === "windows-x86_64" ? ".exe" : "";
+}
+/** The file names of a creator tools ZIP, derived from the pin's file list. */
+export function toolNames(release, platform, names) {
+    const licenses = names
+        .map((name) => /^overcrow-widget-(\d+\.\d+\.\d+(?:-[a-z]+\.\d+)?)-LICENSE\.txt$/.exec(name)?.[1])
+        .filter((version) => version !== undefined);
+    if (licenses.length !== 1)
+        throw new InstallError("the creator tools do not hold exactly one CLI");
+    const cliVersion = licenses[0];
+    const suffix = executableSuffix(platform);
+    const expected = {
+        cli: `overcrow-widget-${cliVersion}-${platform}${suffix}`,
+        cliLicense: `overcrow-widget-${cliVersion}-LICENSE.txt`,
+        cliNotices: `overcrow-widget-${cliVersion}-THIRD-PARTY-NOTICES.md`,
+        runtime: `overcrow-widget-headless-${release}-${platform}${suffix}`,
+        runtimeLicense: `overcrow-widget-headless-${release}-LICENSE.md`,
+    };
+    const all = new Set([
+        ...Object.values(expected),
+        "cli.json",
+        "runtimes.json",
+        "README.txt",
+        "SHA256SUMS",
+    ]);
+    if (all.size !== names.length || !names.every((name) => all.has(name))) {
+        throw new InstallError("the creator tools have missing or unexpected files");
+    }
+    return { cliVersion, ...expected };
+}
+/**
+ * Checks `archive` against `pinned` and returns its files by name. The
+ * SHA-256 of the whole archive is checked before any byte is parsed.
+ */
+export function verifyArchive(archive, pinned) {
+    if (archive.length !== pinned.size || sha256(archive) !== pinned.sha256) {
+        throw new InstallError("the creator tools ZIP is not the pinned one (size or SHA-256 differs)");
+    }
+    const root = pinned.name.replace(/\.zip$/, "");
+    const entries = readEntries(archive, ZIP_LIMITS);
+    const expected = new Map(pinned.files.map((file) => [file.path, file]));
+    if (entries.length !== expected.size)
+        throw new InstallError("the creator tools ZIP has another file list than the pin");
+    const files = new Map();
+    for (const entry of entries) {
+        const pin = expected.get(entry.name);
+        if (!pin || entry.size !== pin.size)
+            throw new InstallError(`unexpected file in the creator tools ZIP: ${entry.name}`);
+        const data = extractEntry(archive, entry);
+        if (sha256(data) !== pin.sha256)
+            throw new InstallError(`a file of the creator tools ZIP differs from the pin: ${entry.name}`);
+        files.set(entry.name.slice(root.length + 1), data);
+    }
+    return files;
+}
+function parseJson(data, name) {
+    if (!data || data.length > MAX_METADATA_BYTES)
+        throw new InstallError(`${name} is missing or too large`);
+    try {
+        const value = JSON.parse(data.toString("utf8"));
+        if (typeof value === "object" && value !== null && !Array.isArray(value))
+            return value;
+    }
+    catch {
+        // Reported below.
+    }
+    throw new InstallError(`${name} is not a JSON object`);
+}
+/**
+ * The checks between the files of the ZIP: SHA256SUMS lists every other
+ * file with its digest, runtimes.json describes the runtime, and cli.json
+ * describes the CLI and pins that same runtime.
+ */
+export function crossCheck(files, release, platform) {
+    const names = toolNames(release, platform, [...files.keys()]);
+    const sums = files.get("SHA256SUMS")?.toString("utf8") ?? "";
+    const listed = new Map();
+    for (const line of sums.split("\n")) {
+        if (line === "")
+            continue;
+        const match = /^([0-9a-f]{64}) [ *]([A-Za-z0-9][A-Za-z0-9._+-]*)$/.exec(line);
+        if (!match || listed.has(match[2]))
+            throw new InstallError("SHA256SUMS is malformed");
+        listed.set(match[2], match[1]);
+    }
+    for (const [name, data] of files) {
+        if (name === "SHA256SUMS")
+            continue;
+        if (listed.get(name) !== sha256(data))
+            throw new InstallError(`SHA256SUMS does not match ${name}`);
+    }
+    if (listed.size !== files.size - 1)
+        throw new InstallError("SHA256SUMS lists files that are not in the ZIP");
+    const cliData = files.get(names.cli);
+    const runtimeData = files.get(names.runtime);
+    const runtimeSha = sha256(runtimeData);
+    const runtimes = parseJson(files.get("runtimes.json"), "runtimes.json");
+    const runtimeEntry = runtimes.runtimes?.[`headless-${platform}`];
+    if (runtimes.version !== release ||
+        runtimeEntry?.name !== names.runtime ||
+        runtimeEntry?.sha256 !== runtimeSha ||
+        runtimeEntry?.size !== runtimeData.length) {
+        throw new InstallError("runtimes.json does not describe the runtime of the ZIP");
+    }
+    const cli = parseJson(files.get("cli.json"), "cli.json");
+    const runtimePin = cli.runtime;
+    const cliFiles = Array.isArray(cli.files) ? cli.files : [];
+    const cliEntry = cliFiles.find((file) => file.name === names.cli);
+    if (cli.version !== names.cliVersion ||
+        runtimePin?.version !== release ||
+        runtimePin.sha256?.[platform] !== runtimeSha ||
+        cliEntry?.sha256 !== sha256(cliData) ||
+        cliEntry?.size !== cliData.length) {
+        throw new InstallError("cli.json does not describe this CLI, or pins another runtime");
+    }
+    return { ...names, runtimeSha256: runtimeSha };
+}
+/** Creates the cache root (0700) and refuses a link in its place. */
+export async function prepareCacheRoot(cacheRoot) {
+    await mkdir(cacheRoot, { recursive: true, mode: 0o700 });
+    const info = await lstat(cacheRoot);
+    if (!info.isDirectory())
+        throw new InstallError("the tools cache is not a plain directory");
+    if (process.platform !== "win32" &&
+        typeof process.getuid === "function" &&
+        info.uid !== process.getuid()) {
+        throw new InstallError("the tools cache belongs to another user");
+    }
+}
+async function writeDurably(path, data, mode) {
+    const handle = await open(path, "wx", mode);
+    try {
+        await handle.writeFile(data);
+        await handle.chmod(mode);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function syncDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function installDirectory(cacheRoot, release, platform) {
+    return join(cacheRoot, `${release}-${platform}`);
+}
+/**
+ * Installs `archive` (already read in memory) into the cache. Returns the
+ * installed tools; if another server installed the same release meanwhile,
+ * its copy is checked and used.
+ */
+export async function install(archive, pinned, release, platform, cacheRoot, probe) {
+    const files = verifyArchive(archive, pinned);
+    const names = crossCheck(files, release, platform);
+    await prepareCacheRoot(cacheRoot);
+    const working = await mkdtemp(join(cacheRoot, ".install-"));
+    try {
+        for (const [name, data] of files) {
+            const executable = name === names.cli || name === names.runtime;
+            await writeDurably(join(working, name), data, executable ? 0o755 : 0o644);
+        }
+        await syncDirectory(working);
+        await checkVersion(join(working, names.cli), working, release, platform, names, probe);
+        const final = installDirectory(cacheRoot, release, platform);
+        try {
+            await rename(working, final);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOTEMPTY" && code !== "EEXIST" && code !== "EPERM")
+                throw error;
+            // Another server finished first: use its copy once checked.
+            const existing = await loadInstalled(pinned, release, platform, cacheRoot);
+            if (existing)
+                return existing;
+            // A damaged copy of our own cache: set it aside, then take its place.
+            const damaged = `${final}.damaged-${randomBytes(4).toString("hex")}`;
+            await rename(final, damaged);
+            await rm(damaged, { recursive: true, force: true });
+            await rename(working, final);
+        }
+        await syncDirectory(cacheRoot);
+        return {
+            release,
+            platform,
+            directory: final,
+            cli: join(final, names.cli),
+            runtime: join(final, names.runtime),
+            cliVersion: names.cliVersion,
+            runtimeSha256: names.runtimeSha256,
+        };
+    }
+    finally {
+        await rm(working, { recursive: true, force: true });
+    }
+}
+async function checkVersion(cli, cwd, release, platform, names, probe) {
+    const report = (await probe(cli, cwd));
+    if (report?.version !== names.cliVersion ||
+        report.apiVersion !== 1 ||
+        report.runtime?.version !== release ||
+        report.runtime.sha256?.[platform] !== names.runtimeSha256) {
+        throw new InstallError("the CLI does not report the version and runtime of its ZIP");
+    }
+}
+/**
+ * The installed tools of the pinned release, after checking every file
+ * against the pin again; undefined when they are absent or damaged.
+ */
+export async function loadInstalled(pinned, release, platform, cacheRoot) {
+    const directory = installDirectory(cacheRoot, release, platform);
+    try {
+        const info = await lstat(directory);
+        if (!info.isDirectory())
+            return undefined;
+        const root = pinned.name.replace(/\.zip$/, "");
+        const expected = new Map(pinned.files.map((file) => [file.path.slice(root.length + 1), file]));
+        const present = await readdir(directory);
+        if (present.length !== expected.size)
+            return undefined;
+        for (const name of present) {
+            const pin = expected.get(name);
+            if (!pin)
+                return undefined;
+            const path = join(directory, name);
+            const fileInfo = await lstat(path);
+            if (!fileInfo.isFile() || fileInfo.size !== pin.size)
+                return undefined;
+            if (sha256(await readFile(path)) !== pin.sha256)
+                return undefined;
+        }
+        const names = toolNames(release, platform, present);
+        return {
+            release,
+            platform,
+            directory,
+            cli: join(directory, names.cli),
+            runtime: join(directory, names.runtime),
+            cliVersion: names.cliVersion,
+            runtimeSha256: expected.get(names.runtime).sha256,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A fresh, private path for a download in the cache root. */
+export function downloadPath(cacheRoot) {
+    return join(cacheRoot, `.download-${randomBytes(8).toString("hex")}.zip`);
+}

package/dist/bootstrap/pin.js

@@ -0,0 +1,85 @@
+// The creator tools release this version of the package uses: its version
+// and, for each platform, the ZIP's name, size and SHA-256 and every file
+// in it (the `creatorTools` entry of the release's public release.json,
+// copied by `scripts/pin-release.mjs`). Nothing else is ever downloaded.
+import { readFileSync } from "node:fs";
+export const RELEASES_REPOSITORY = "Valhallab/playervox-overcrow-releases";
+export const DOWNLOAD_HOSTS = [
+    "github.com",
+    "release-assets.githubusercontent.com",
+    "objects.githubusercontent.com",
+];
+const HEX64 = /^[0-9a-f]{64}$/;
+const INTEGRITY = /^sha512-[A-Za-z0-9+/]{86}==$/;
+const VERSION = /^\d+\.\d+\.\d+(?:-[a-z]+\.\d+)?$/;
+const FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+/** The address of a pinned ZIP. */
+export function toolsUrl(release, name, base = "https://github.com") {
+    return `${base}/${RELEASES_REPOSITORY}/releases/download/v${release}/${name}`;
+}
+/** Checks the shape of a pin; throws on anything unexpected. */
+export function validatePin(value) {
+    const fail = (why) => {
+        throw new Error(`invalid pin: ${why}`);
+    };
+    if (typeof value !== "object" || value === null)
+        fail("not an object");
+    const { release, tools, npm } = value;
+    const packages = (npm ?? {});
+    const pinnedPackage = (name) => {
+        const { version, integrity } = (packages[name] ?? {});
+        if (typeof version !== "string" || !VERSION.test(version))
+            fail(`${name} version`);
+        if (typeof integrity !== "string" || !INTEGRITY.test(integrity))
+            fail(`${name} integrity`);
+        return { version: version, integrity: integrity };
+    };
+    const npmPins = { sdk: pinnedPackage("@overcrow/sdk"), typescript: pinnedPackage("typescript") };
+    if (release === null)
+        return { release: null, tools: {}, npm: npmPins };
+    if (typeof release !== "string" || !VERSION.test(release))
+        fail("release version");
+    if (typeof tools !== "object" || tools === null)
+        fail("tools");
+    const result = { release: release, tools: {}, npm: npmPins };
+    for (const platform of ["linux-x86_64", "windows-x86_64"]) {
+        const entry = tools[platform];
+        if (typeof entry !== "object" || entry === null)
+            fail(`missing ${platform}`);
+        const { name, size, sha256, files } = entry;
+        const root = `overcrow-creator-tools-${release}-${platform}`;
+        if (name !== `${root}.zip`)
+            fail(`${platform} name`);
+        if (!Number.isSafeInteger(size) || size <= 0)
+            fail(`${platform} size`);
+        if (typeof sha256 !== "string" || !HEX64.test(sha256))
+            fail(`${platform} digest`);
+        if (!Array.isArray(files) || files.length === 0 || files.length > 64)
+            fail(`${platform} files`);
+        const checked = [];
+        for (const file of files) {
+            const { path, size: fileSize, sha256: fileSha } = (file ?? {});
+            if (typeof path !== "string" ||
+                !path.startsWith(`${root}/`) ||
+                !FILE_NAME.test(path.slice(root.length + 1))) {
+                fail(`${platform} file path`);
+            }
+            if (!Number.isSafeInteger(fileSize) || fileSize <= 0)
+                fail(`${platform} file size`);
+            if (typeof fileSha !== "string" || !HEX64.test(fileSha))
+                fail(`${platform} file digest`);
+            checked.push({ path: path, size: fileSize, sha256: fileSha });
+        }
+        result.tools[platform] = {
+            name: name,
+            size: size,
+            sha256: sha256,
+            files: checked,
+        };
+    }
+    return result;
+}
+/** The pin shipped with the package (`dist/pin.json`). */
+export function shippedPin() {
+    return validatePin(JSON.parse(readFileSync(new URL("./pin.json", import.meta.url), "utf8")));
+}