@clawscarf/cli 0.1.0-alpha.1

package/scripts/controller.js

@@ -0,0 +1,143 @@
+import { OperatorError } from "./errors.js";
+import { Command } from "commander";
+import { execFile } from "node:child_process";
+import { chmod, copyFile, mkdir, readFile, readdir, writeFile, } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+const execute = promisify(execFile);
+const settingsSchema = z.strictObject({
+    name: z.string().regex(/^[a-z][a-z0-9-]{0,40}$/),
+    port: z.number().int().min(1024).max(65535),
+    gateway: z.string().min(1),
+    cli: z.string().min(1),
+});
+const releaseInput = JSON.parse(await readFile(new URL("../release/components.json", import.meta.url), "utf8"));
+const release = z
+    .object({
+    openshell: z.object({
+        version: z.string().min(1),
+        gatewayImage: z.string().regex(/@sha256:[a-f0-9]{64}$/),
+        supervisorImage: z.string().regex(/@sha256:[a-f0-9]{64}$/),
+    }),
+})
+    .parse(releaseInput).openshell;
+function environment(directory) {
+    if (Object.keys(process.env).some((name) => name.startsWith("OPENSHELL_")))
+        throw new OperatorError("Unset OPENSHELL_* environment overrides; this controller uses its private configuration.");
+    return {
+        ...process.env,
+        XDG_CONFIG_HOME: join(directory, "config"),
+        XDG_STATE_HOME: join(directory, "state"),
+        XDG_DATA_HOME: join(directory, "data"),
+    };
+}
+async function protect(directory) {
+    await chmod(directory, 0o700);
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            await protect(path);
+        else if (entry.isFile())
+            await chmod(path, 0o600);
+        else
+            throw new OperatorError("Controller state must not contain symlinks or special files.");
+    }
+}
+async function verifyExecutable(path) {
+    const { stdout } = await execute(path, ["--version"], { timeout: 10000 });
+    if (!stdout.trim().split(/\s+/).includes(release.version))
+        throw new OperatorError(`Use the pinned OpenShell ${release.version} executable.`);
+}
+function toml(directory, settings) {
+    const path = (value) => JSON.stringify(join(directory, "tls", value));
+    return `[openshell]
+version = 1
+[openshell.gateway]
+name = ${JSON.stringify(settings.name)}
+bind_address = "0.0.0.0:${String(settings.port)}"
+compute_drivers = ["docker"]
+disable_tls = false
+[openshell.gateway.tls]
+cert_path = ${path("server/tls.crt")}
+key_path = ${path("server/tls.key")}
+client_ca_path = ${path("ca.crt")}
+require_client_auth = true
+[openshell.gateway.mtls_auth]
+enabled = true
+[openshell.gateway.auth]
+allow_unauthenticated_users = false
+[openshell.gateway.gateway_jwt]
+signing_key_path = ${path("jwt/signing.pem")}
+public_key_path = ${path("jwt/public.pem")}
+kid_path = ${path("jwt/kid")}
+gateway_id = ${JSON.stringify(settings.name)}
+ttl_secs = 0
+[openshell.drivers.docker]
+network_name = ${JSON.stringify(settings.name)}
+sandbox_namespace = ${JSON.stringify(settings.name)}
+supervisor_image = ${JSON.stringify(release.supervisorImage)}
+image_pull_policy = "IfNotPresent"
+enable_bind_mounts = false
+grpc_endpoint = "https://host.openshell.internal:${String(settings.port)}"
+guest_tls_ca = ${path("ca.crt")}
+guest_tls_cert = ${path("client/tls.crt")}
+guest_tls_key = ${path("client/tls.key")}
+`;
+}
+const command = new Command().name("clawscarf-controller");
+command
+    .command("init")
+    .requiredOption("--directory <path>", "New private controller directory")
+    .requiredOption("--gateway <path>", "Verified openshell-gateway executable")
+    .requiredOption("--cli <path>", "Verified openshell executable")
+    .option("--name <name>", "Isolated controller name", "clawscarf")
+    .option("--port <port>", "Loopback controller port", "17671")
+    .action(async (options) => {
+    const directory = resolve(options.directory);
+    const env = environment(directory);
+    const settings = settingsSchema.parse({
+        name: options.name,
+        port: Number(options.port),
+        gateway: resolve(options.gateway),
+        cli: resolve(options.cli),
+    });
+    await verifyExecutable(settings.gateway);
+    await verifyExecutable(settings.cli);
+    await mkdir(directory, { mode: 0o700 });
+    await execute(settings.gateway, [
+        "generate-certs",
+        "--output-dir",
+        join(directory, "tls"),
+        "--server-san",
+        "127.0.0.1",
+        "--server-san",
+        "localhost",
+        "--server-san",
+        "host.openshell.internal",
+    ], { timeout: 30000 });
+    const mtls = join(directory, "config/openshell/gateways", settings.name, "mtls");
+    await mkdir(mtls, { recursive: true, mode: 0o700 });
+    for (const [source, destination] of [
+        ["ca.crt", "ca.crt"],
+        ["client/tls.crt", "tls.crt"],
+        ["client/tls.key", "tls.key"],
+    ]) {
+        if (!source || !destination)
+            throw new OperatorError("Invalid certificate mapping.");
+        await copyFile(join(directory, "tls", source), join(mtls, destination));
+    }
+    await writeFile(join(directory, "gateway.toml"), toml(directory, settings), { flag: "wx", mode: 0o600 });
+    await writeFile(join(directory, "controller.json"), JSON.stringify(settings, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+    await execute(settings.cli, [
+        "gateway",
+        "add",
+        `https://127.0.0.1:${String(settings.port)}`,
+        "--name",
+        settings.name,
+        "--local",
+    ], { env, timeout: 15000 });
+    await protect(directory);
+    process.stdout.write("Controller initialized. Keep this directory private and persistent.\n");
+});
+await command.parseAsync();

package/scripts/deployment/browser-node-compose.js

@@ -0,0 +1,81 @@
+import { join } from "node:path";
+import { browserNodeName, } from "./browser-node.js";
+import { resourceNames } from "./state.js";
+export function browserNodeServices(state, directory, browserAddress, prepared) {
+    const input = state.input.browser;
+    if (!input || !state.input.relayImage)
+        throw Error("Browser images are required.");
+    const { addresses, fingerprint } = prepared;
+    const file = (name) => join(directory, "private", name);
+    const constrained = {
+        read_only: true,
+        cap_drop: ["ALL"],
+        security_opt: ["no-new-privileges:true"],
+        init: true,
+        labels: { "clawscarf.installation": state.ownerId },
+    };
+    return {
+        "browser-node": {
+            ...constrained,
+            image: input.nodeImage,
+            user: "1000:1000",
+            networks: { machine: { ipv4_address: addresses.node }, browser: {} },
+            extra_hosts: [`chromium:${browserAddress}`],
+            environment: {
+                CLAWSCARF_BROWSER_NODE_GATEWAY_URL: `wss://${addresses.ingress}:18803`,
+                CLAWSCARF_BROWSER_NODE_TLS_FINGERPRINT: fingerprint,
+                CLAWSCARF_BROWSER_NODE_NAME: browserNodeName(state),
+            },
+            volumes: [
+                "browser-node:/state",
+                "browser-node-config:/configuration:ro",
+                `${file("browser-node-resolv.conf")}:/etc/resolv.conf:ro`,
+            ],
+            tmpfs: ["/tmp:rw,noexec,nosuid,nodev,size=128m"],
+            mem_limit: "1g",
+            pids_limit: 128,
+            depends_on: ["browser", "browser-node-ingress", "browser-node-dns"],
+        },
+        "browser-node-ingress": {
+            ...constrained,
+            image: state.input.relayImage,
+            user: String(process.getuid?.() ?? 1000),
+            networks: { machine: { ipv4_address: addresses.ingress }, default: {} },
+            extra_hosts: ["host.docker.internal:host-gateway"],
+            environment: {
+                CLAWSCARF_NODE_INGRESS_ADDRESS: addresses.ingress,
+                CLAWSCARF_NODE_GATEWAY_PORT: String(state.input.ports.native),
+            },
+            volumes: [
+                `${file("browser-node.pem")}:/run/clawscarf/node-ingress.pem:ro`,
+                `${file("browser-node-ingress.cfg")}:/usr/local/etc/haproxy/haproxy.cfg:ro`,
+            ],
+            mem_limit: "64m",
+            pids_limit: 64,
+        },
+        "browser-node-dns": {
+            ...constrained,
+            image: input.dnsImage,
+            networks: { machine: { ipv4_address: addresses.dns }, default: {} },
+            sysctls: {
+                "net.ipv4.ip_unprivileged_port_start": "53",
+                "net.ipv4.ip_forward": "0",
+            },
+            volumes: [
+                `${file("browser-node-dns.conf")}:/etc/unbound/deployment.conf:ro`,
+            ],
+            mem_limit: "128m",
+            pids_limit: 32,
+        },
+    };
+}
+export function browserNodeVolumes(state) {
+    const names = resourceNames(state);
+    return {
+        "browser-node": { external: true, name: names.browserNodeVolume },
+        "browser-node-config": {
+            external: true,
+            name: names.browserNodeConfigVolume,
+        },
+    };
+}

package/scripts/deployment/browser-node-helper.js

@@ -0,0 +1,9 @@
+import { readFile } from "node:fs/promises";
+import { stripTypeScriptTypes } from "node:module";
+/** Execute the same checked helper from source or a built operator. */
+export async function browserOperatorSource() {
+    const source = import.meta.url.endsWith(".ts");
+    const text = await readFile(new URL(`../../deploy/execution/browser-node/operator.${source ? "ts" : "js"}`, import.meta.url), "utf8");
+    return ((source ? stripTypeScriptTypes(text) : text) +
+        "\nawait runBrowserOperator();\n");
+}

package/scripts/deployment/browser-node-pairing.js

@@ -0,0 +1,165 @@
+import { readFile, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { browserNodeName, pairedBrowserSchema } from "./browser-node.js";
+import { browserOperatorSource } from "./browser-node-helper.js";
+import { observedBrowserMachineAddresses } from "./networks.js";
+import { compose } from "./compose.js";
+import { ensurePrivateFile, resourceNames } from "./state.js";
+import { LocalSetupError, run } from "./process.js";
+import { verifyRuntimeBinding } from "./runtime-binding.js";
+export const nodeObservationSchema = z.array(z.strictObject({
+    nodeId: z.string(),
+    admitted: z.boolean(),
+    connectedAt: z.number().nullable(),
+    disconnectedAt: z.number().nullable(),
+}));
+export function browserNodeReady(value, startedAt) {
+    return (value.admitted &&
+        value.connectedAt !== null &&
+        value.connectedAt >= startedAt &&
+        (value.disconnectedAt === null || value.disconnectedAt < value.connectedAt));
+}
+async function receipt(directory, state) {
+    try {
+        const path = join(directory, "browser-node-paired.json");
+        const stat = await lstat(path);
+        if (!stat.isFile() ||
+            stat.nlink !== 1 ||
+            stat.uid !== process.getuid?.() ||
+            (stat.mode & 0o077) !== 0)
+            throw Error("Unsafe receipt");
+        const value = pairedBrowserSchema.parse(JSON.parse(await readFile(path, "utf8")));
+        if (value.ownerId !== state.ownerId)
+            throw Error("Owner differs");
+        return value;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw new LocalSetupError("configuration_changed", "Browser pairing receipt is unsafe or belongs to another installation.");
+    }
+}
+/** Local SDK issuance needs no user session. A recorded attempt is never silently repeated. */
+export async function startBrowserNode(directory, state, signal) {
+    const browser = state.input.browser;
+    if (!browser)
+        return;
+    const target = z
+        .object({
+        id: z.uuid(),
+        name: z.string(),
+        ownerId: z.literal(state.ownerId),
+    })
+        .parse(JSON.parse(await readFile(join(directory, "runtime.json"), "utf8")));
+    const binding = await verifyRuntimeBinding(state, target);
+    const source = await browserOperatorSource();
+    const native = async (input) => JSON.parse(await run("docker", [
+        "exec",
+        "-i",
+        "--user",
+        "1000",
+        "-e",
+        "HOME=/home/node",
+        "-e",
+        "SQLITE_TMPDIR=/tmp",
+        "--workdir",
+        "/app",
+        binding.containerId,
+        "node",
+        "--input-type=module",
+        "-e",
+        source,
+    ], { input: JSON.stringify(input) }));
+    const config = async (input) => run("docker", [
+        "run",
+        "--rm",
+        "-i",
+        "--network",
+        "none",
+        "--user",
+        "0",
+        "--workdir",
+        "/app",
+        "--mount",
+        `type=volume,src=${resourceNames(state).browserNodeConfigVolume},dst=/configuration`,
+        "--entrypoint",
+        "node",
+        browser.nodeImage,
+        "--input-type=module",
+        "-e",
+        source,
+    ], { input: JSON.stringify(input) });
+    const saved = await receipt(directory, state);
+    const observe = async () => nodeObservationSchema.parse(await native({
+        command: "observe",
+        name: browserNodeName(state),
+        ...(saved ? { nodeId: saved.nodeId } : {}),
+    }));
+    if (saved) {
+        const observed = await observe();
+        if (observed.length !== 1 || !observed[0]?.admitted)
+            throw new LocalSetupError("browser_unavailable", "The browser node's native admission was removed or changed. Startup will not re-enroll it.");
+    }
+    else {
+        const intent = join(directory, "browser-node-pairing-started.json");
+        try {
+            await lstat(intent);
+            throw new LocalSetupError("bootstrap_outcome_unknown", "Browser pairing was attempted without confirmed completion. Inspect native pairing and retained state; it will not be repeated.");
+        }
+        catch (error) {
+            if (!(error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT"))
+                throw error;
+        }
+        if ((await observe()).length)
+            throw new LocalSetupError("configuration_changed", "A browser node already has the prepared name. Inspect its native identity before proceeding.");
+        const addresses = await observedBrowserMachineAddresses(directory, state);
+        if (!addresses)
+            throw new LocalSetupError("network_unprepared", "Browser network is not prepared.");
+        signal.throwIfAborted();
+        await ensurePrivateFile(intent, JSON.stringify({ ownerId: state.ownerId }));
+        const setup = z.object({ setupCode: z.string().min(1) }).parse(await native({
+            command: "issue",
+            gatewayUrl: `wss://${addresses.ingress}:18803`,
+        }));
+        await config({
+            command: "write-code",
+            ownerId: state.ownerId,
+            setupCode: setup.setupCode,
+        });
+    }
+    if (saved)
+        await config({ command: "remove-code", ownerId: state.ownerId });
+    signal.throwIfAborted();
+    await compose(directory, ["up", "-d", "browser-node"]);
+    const id = (await compose(directory, ["ps", "-q", "browser-node"])).trim();
+    z.string()
+        .regex(/^[a-f0-9]{12,64}$/)
+        .parse(id);
+    const startedAt = z.coerce
+        .date()
+        .parse((await run("docker", ["inspect", "--format", "{{.State.StartedAt}}", id])).trim())
+        .getTime();
+    const deadline = Date.now() + 90000;
+    while (Date.now() < deadline) {
+        signal.throwIfAborted();
+        if ((await run("docker", ["inspect", "--format", "{{.State.Running}}", id])).trim() !== "true")
+            throw new LocalSetupError("browser_unavailable", "The browser node stopped during startup. Inspect its container logs; pairing was not repeated.");
+        const values = await observe();
+        if (values.length > 1)
+            throw new LocalSetupError("configuration_changed", "The browser node name is ambiguous.");
+        const value = values[0];
+        if (value && browserNodeReady(value, startedAt)) {
+            if (!saved) {
+                await ensurePrivateFile(join(directory, "browser-node-paired.json"), JSON.stringify({ ownerId: state.ownerId, nodeId: value.nodeId }));
+                await config({ command: "remove-code", ownerId: state.ownerId });
+            }
+            return;
+        }
+        await delay(1000, undefined, { signal });
+    }
+    throw new LocalSetupError("browser_unavailable", "The browser node did not establish its admitted native connection before the deadline. State was retained; enrollment will not be repeated.");
+}

package/scripts/deployment/browser-node.js

@@ -0,0 +1,154 @@
+import { browserOperatorSource } from "./browser-node-helper.js";
+import { createPrivateKey, X509Certificate } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { browserNodeConfiguration } from "../../deploy/execution/browser-node/configuration.js";
+import { observedBrowserMachineAddresses } from "./networks.js";
+import { ensureOwnedVolume } from "./volumes.js";
+import { ensurePrivateFile, resourceNames } from "./state.js";
+import { LocalSetupError, run } from "./process.js";
+export const browserNodeName = (state) => `${resourceNames(state).project}-browser`;
+async function certificate(directory, address, create) {
+    const path = join(directory, "private/browser-node.pem");
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() ||
+            info.nlink !== 1 ||
+            info.uid !== process.getuid?.() ||
+            (info.mode & 0o777) !== 0o600)
+            throw Error("unsafe");
+    }
+    catch (error) {
+        if (!(create &&
+            error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT"))
+            throw new LocalSetupError("invalid_certificate", "Browser node TLS material is missing or unsafe.");
+        const staging = join(directory, "private/browser-node-tls");
+        await mkdir(staging, { mode: 0o700 });
+        await run("openssl", [
+            "req",
+            "-x509",
+            "-newkey",
+            "rsa:3072",
+            "-nodes",
+            "-days",
+            "365",
+            "-subj",
+            "/CN=ClawScarf browser node",
+            "-addext",
+            `subjectAltName=IP:${address}`,
+            "-keyout",
+            join(staging, "key.pem"),
+            "-out",
+            join(staging, "cert.pem"),
+        ]);
+        await ensurePrivateFile(path, Buffer.concat([
+            await readFile(join(staging, "key.pem")),
+            await readFile(join(staging, "cert.pem")),
+        ]));
+        await rm(staging, { recursive: true });
+    }
+    try {
+        const pem = await readFile(path);
+        const cert = new X509Certificate(pem);
+        if (!cert.checkPrivateKey(createPrivateKey(pem)) ||
+            !cert.checkIP(address) ||
+            Date.parse(cert.validFrom) > Date.now() ||
+            Date.parse(cert.validTo) <= Date.now())
+            throw Error("invalid");
+        return cert.fingerprint256;
+    }
+    catch {
+        throw new LocalSetupError("invalid_certificate", "The private browser node certificate is invalid or expired; it was not replaced.");
+    }
+}
+export function browserNodeFiles(addresses) {
+    return {
+        "browser-node-resolv.conf": `nameserver ${addresses.dns}\noptions timeout:2 attempts:1\n`,
+        "browser-node-dns.conf": `server:\n    interface: ${addresses.dns}@53\n    access-control: ${addresses.node}/32 allow\nforward-zone:\n    name: "."\n    forward-first: no\n    forward-addr: 1.1.1.1@53\n    forward-addr: 1.0.0.1@53\n`,
+    };
+}
+async function materialize(directory, addresses, create) {
+    const files = {
+        ...browserNodeFiles(addresses),
+        "browser-node-ingress.cfg": await readFile(new URL("../../deploy/execution/network/node-ingress.cfg", import.meta.url), "utf8"),
+    };
+    for (const [name, content] of Object.entries(files)) {
+        const path = join(directory, "private", name);
+        try {
+            const info = await lstat(path);
+            if (!info.isFile() ||
+                info.nlink !== 1 ||
+                info.uid !== process.getuid?.() ||
+                (info.mode & 0o777) !== 0o444 ||
+                (await readFile(path, "utf8")) !== content)
+                throw Error("changed");
+        }
+        catch (error) {
+            if (!(create &&
+                error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT"))
+                throw new LocalSetupError("configuration_changed", "Private browser node network configuration differs from its prepared inputs.");
+            await writeFile(path, content, { flag: "wx", mode: 0o444 });
+            await chmod(path, 0o444);
+        }
+    }
+}
+export async function prepareBrowserNode(directory, state, token) {
+    const browser = state.input.browser;
+    if (!browser)
+        return undefined;
+    const addresses = await observedBrowserMachineAddresses(directory, state);
+    if (!addresses)
+        throw new LocalSetupError("network_unprepared", "The private browser node network is not prepared.");
+    const fingerprint = await certificate(directory, addresses.ingress, true);
+    await materialize(directory, addresses, true);
+    const names = resourceNames(state);
+    for (const name of [names.browserNodeVolume, names.browserNodeConfigVolume])
+        await ensureOwnedVolume(name, state.ownerId);
+    const configuration = browserNodeConfiguration(`http://openclaw:${token}@chromium:9223`);
+    await run("docker", [
+        "run",
+        "--rm",
+        "-i",
+        "--network",
+        "none",
+        "--user",
+        "0",
+        "--workdir",
+        "/app",
+        "--mount",
+        `type=volume,src=${names.browserNodeVolume},dst=/state,volume-nocopy`,
+        "--mount",
+        `type=volume,src=${names.browserNodeConfigVolume},dst=/configuration,volume-nocopy`,
+        "--entrypoint",
+        "node",
+        browser.nodeImage,
+        "--input-type=module",
+        "-e",
+        await browserOperatorSource(),
+    ], {
+        input: JSON.stringify({
+            command: "initialize",
+            ownerId: state.ownerId,
+            configuration,
+        }),
+    });
+    return { addresses, fingerprint };
+}
+export async function verifyBrowserNode(directory, state) {
+    if (!state.input.browser)
+        return;
+    const addresses = await observedBrowserMachineAddresses(directory, state);
+    if (!addresses)
+        throw new LocalSetupError("network_unprepared", "The private browser node network is not prepared.");
+    await certificate(directory, addresses.ingress, false);
+    await materialize(directory, addresses, false);
+}
+export const pairedBrowserSchema = z.strictObject({
+    ownerId: z.uuid(),
+    nodeId: z.string().min(1),
+});