@clawscarf/cli 0.1.0-alpha.1

package/scripts/deployment/state.js

@@ -0,0 +1,154 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { lstat, link, mkdir, mkdtemp, open, readFile, rename, rm, } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import lockfile from "proper-lockfile";
+import { z } from "zod";
+import { parseLocalInput } from "./configuration.js";
+import { LocalSetupError } from "./process.js";
+const identitySchema = z.object({
+    schemaVersion: z.literal(1),
+    ownerId: z.uuid(),
+});
+const stateSchema = identitySchema
+    .extend({ input: z.unknown().transform(parseLocalInput) })
+    .strict();
+export async function writePrivate(path, value) {
+    const temporary = path + "." + randomUUID();
+    try {
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(value);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Publish complete initial state, or retain an identical existing file. Never replace edits. */
+export async function ensurePrivateFile(path, value) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() ||
+            (metadata.mode & 0o077) !== 0 ||
+            !Buffer.from(value).equals(await readFile(path)))
+            throw new LocalSetupError("configuration_changed", "An existing private configuration file differs from setup inputs. Setup will not overwrite it.");
+        return;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    const temporary = path + "." + randomUUID();
+    try {
+        await writePrivate(temporary, value);
+        await link(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function readStateRecord(directory) {
+    const metadata = await lstat(directory);
+    if (!metadata.isDirectory() ||
+        (metadata.mode & 0o077) !== 0 ||
+        metadata.uid !== process.getuid?.())
+        throw new LocalSetupError("private_directory_required", "Use a private installation directory owned by the current user.");
+    return JSON.parse(await readFile(join(directory, "installation.json"), "utf8"));
+}
+/** Cleanup needs ownership, even when the execution configuration is incomplete. */
+export async function readInstallationIdentity(directory) {
+    return identitySchema.parse(await readStateRecord(directory));
+}
+export async function readState(directory) {
+    return stateSchema.parse(await readStateRecord(directory));
+}
+export async function initializeState(path, input) {
+    const directory = resolve(path);
+    try {
+        const existing = await readState(directory);
+        if (!isDeepStrictEqual(existing.input, input))
+            throw new LocalSetupError("configuration_changed", "The supplied configuration differs from this installation. Setup never overwrites an existing installation.");
+        return existing;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+        try {
+            await lstat(directory);
+        }
+        catch (missing) {
+            if (!(missing instanceof Error &&
+                "code" in missing &&
+                missing.code === "ENOENT"))
+                throw missing;
+            await mkdir(dirname(directory), { recursive: true, mode: 0o700 });
+            const staging = await mkdtemp(join(dirname(directory), ".clawscarf-init-"));
+            try {
+                const state = {
+                    schemaVersion: 1,
+                    ownerId: randomUUID(),
+                    input,
+                };
+                await writePrivate(join(staging, "installation.json"), JSON.stringify(state, null, 2) + "\n");
+                await mkdir(join(staging, "private"), { mode: 0o700 });
+                for (const name of [
+                    "database-admin-password",
+                    "database-runtime-password",
+                ])
+                    await writePrivate(join(staging, "private", name), randomBytes(32).toString("base64url"));
+                await writePrivate(join(staging, "private", "encryption.key"), randomBytes(32));
+                // mkdir reserves the destination; rename alone can replace an empty foreign directory.
+                await mkdir(directory, { mode: 0o700 });
+                await rename(staging, directory);
+                return state;
+            }
+            finally {
+                await rm(staging, { recursive: true, force: true });
+            }
+        }
+        throw new LocalSetupError("unowned_directory", "The destination exists without a ClawScarf installation identity; choose a new directory.");
+    }
+}
+export async function withInstallationLock(directory, work) {
+    directory = resolve(directory);
+    await mkdir(dirname(directory), { recursive: true, mode: 0o700 });
+    let release;
+    try {
+        release = await lockfile.lock(directory, {
+            realpath: false,
+            retries: 0,
+            lockfilePath: directory + ".operator-lock",
+        });
+    }
+    catch (error) {
+        if (!(error instanceof Error &&
+            "code" in error &&
+            error.code === "ELOCKED"))
+            throw error;
+        throw new LocalSetupError("operation_busy", "Another installation operation is active. Wait for it to finish.");
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await release();
+    }
+}
+export function resourceNames(state) {
+    const suffix = state.ownerId.replaceAll("-", "").slice(0, 12);
+    return {
+        project: `clawscarf-${suffix}`,
+        sandbox: `cs-${suffix}`,
+        volume: `clawscarf-${suffix}-home`,
+        databaseVolume: `clawscarf-${suffix}-postgres`,
+        browserVolume: `clawscarf-${suffix}-browser`,
+        browserNodeVolume: `clawscarf-${suffix}-browser-node`,
+        browserNodeConfigVolume: `clawscarf-${suffix}-browser-node-config`,
+    };
+}

package/scripts/deployment/team.js

@@ -0,0 +1,76 @@
+import { OperatorError } from "../errors.js";
+import { createPrivateKey, X509Certificate } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { isIP } from "node:net";
+import { get } from "node:https";
+import { join } from "node:path";
+import { ensurePrivateFile } from "./state.js";
+import { LocalSetupError } from "./process.js";
+export async function readTeamMaterials(team) {
+    try {
+        for (const path of [
+            ...(team.keyFile ? [team.keyFile] : []),
+            team.clientSecretFile,
+        ]) {
+            const info = await lstat(path);
+            if (!info.isFile() ||
+                info.uid !== process.getuid?.() ||
+                (info.mode & 0o077) !== 0)
+                throw new OperatorError("Private operator file required.");
+        }
+        const secret = (await readFile(team.clientSecretFile, "utf8")).trim();
+        if (!secret)
+            throw new OperatorError("OIDC secret is empty.");
+        if (!team.certificateFile || !team.keyFile)
+            return { secret };
+        const certificate = await readFile(team.certificateFile);
+        const key = await readFile(team.keyFile);
+        const cert = new X509Certificate(certificate);
+        if (!secret ||
+            !cert.checkPrivateKey(createPrivateKey(key)) ||
+            Date.parse(cert.validFrom) > Date.now() ||
+            Date.parse(cert.validTo) <= Date.now())
+            throw new OperatorError("Invalid TLS or OIDC material.");
+        for (const origin of [team.origin, team.widgetOrigin]) {
+            const host = new URL(origin).hostname.replace(/^\[|\]$/g, "");
+            if (!(isIP(host) ? cert.checkIP(host) : cert.checkHost(host)))
+                throw new OperatorError("Certificate name mismatch.");
+        }
+        return { certificate, key, secret };
+    }
+    catch {
+        throw new LocalSetupError("invalid_team_configuration", "Team setup requires valid TLS for both public names and private, operator-owned key and OIDC secret files.");
+    }
+}
+export async function prepareTeamFiles(directory, materials) {
+    if (materials.certificate) {
+        await ensurePrivateFile(join(directory, "application-cert.pem"), materials.certificate);
+        await ensurePrivateFile(join(directory, "application-key.pem"), materials.key);
+    }
+    await ensurePrivateFile(join(directory, "oidc-client-secret"), materials.secret);
+}
+/** Availability only: company login and native authority require the actual OIDC user. */
+export async function probeTeamAccess(directory, input, signal) {
+    const origin = input.team.origin;
+    const ca = await readFile(join(directory, "private/management-ca.pem"));
+    await new Promise((resolve, reject) => {
+        get({
+            hostname: "127.0.0.1",
+            servername: "localhost",
+            port: input.ports.management,
+            path: "/_clawscarf/health",
+            headers: { host: new URL(origin).host },
+            ca,
+            signal,
+        }, (response) => {
+            response.resume();
+            response.on("error", reject);
+            response.on("end", () => {
+                if (response.statusCode === 200)
+                    resolve();
+                else
+                    reject(new LocalSetupError("native_unavailable", "Team access has not become healthy."));
+            });
+        }).on("error", reject);
+    });
+}

package/scripts/deployment/upgrade-rpc.py

@@ -0,0 +1,148 @@
+"""Pinned public OpenShell protobuf RPCs absent from its high-level SandboxClient.
+
+Operator-only: private mTLS material and snapshots never enter the runtime image.
+The published SDK supplies generated messages; no private client attributes are used.
+"""
+import base64
+import json
+import pathlib
+import sys
+
+import grpc
+from openshell._proto import openshell_pb2 as api, openshell_pb2_grpc, sandbox_pb2 as policy
+
+
+class Refused(Exception):
+    pass
+
+
+def encode(message):
+    return base64.b64encode(message.SerializeToString(deterministic=True)).decode("ascii")
+
+
+def decode(value, kind):
+    result = kind()
+    result.ParseFromString(base64.b64decode(value, validate=True))
+    return result
+
+
+def current(stub, request):
+    result = stub.GetSandbox(api.GetSandboxRequest(name=request["name"], workspace="default"), timeout=15).sandbox
+    if result.metadata.id != request["id"] or result.metadata.labels.get("clawscarf.installation") != request["ownerId"]:
+        raise Refused("identity_changed")
+    return result
+
+
+def config(stub, sandbox):
+    return stub.GetSandboxConfig(policy.GetSandboxConfigRequest(sandbox_id=sandbox.metadata.id), timeout=15)
+
+
+def no_globals(stub, effective):
+    global_settings = stub.GetGatewayConfig(policy.GetGatewayConfigRequest(), timeout=15)
+    if any(value.WhichOneof("value") is not None for value in global_settings.settings.values()) or effective.policy_source != policy.POLICY_SOURCE_SANDBOX:
+        raise Refused("global_overrides_unsupported")
+
+
+def snapshot(stub, request):
+    sandbox = current(stub, request)
+    if sandbox.status.phase != api.SANDBOX_PHASE_STOPPED:
+        raise Refused("runtime_not_stopped")
+    effective = config(stub, sandbox)
+    no_globals(stub, effective)
+    revision = stub.GetSandboxPolicyStatus(api.GetSandboxPolicyStatusRequest(name=request["name"], workspace="default"), timeout=15)
+    if revision.revision.status != api.POLICY_STATUS_LOADED or revision.active_version != revision.revision.version:
+        raise Refused("policy_not_loaded")
+    spec = api.SandboxSpec()
+    spec.CopyFrom(sandbox.spec)
+    spec.policy.CopyFrom(revision.revision.policy)
+    if list(spec.command) != ["/app/clawscarf/bin/openclaw", "gateway"]:
+        raise Refused("runtime_command_unsupported")
+    create = api.CreateSandboxRequest(spec=spec, name=request["name"], workspace="default",
+                                     labels=sandbox.metadata.labels, annotations=sandbox.metadata.annotations)
+    result = {"create": encode(create), "effective": encode(effective),
+              "resourceVersion": str(sandbox.metadata.resource_version)}
+    # Reads are not a transaction: reject a revision changing during the snapshot.
+    if current(stub, request).metadata.resource_version != sandbox.metadata.resource_version or encode(config(stub, sandbox)) != result["effective"]:
+        raise Refused("configuration_changed")
+    return result
+
+
+def restored(stub, request, expected):
+    sandbox = current(stub, request)
+    actual = config(stub, sandbox)
+    no_globals(stub, actual)
+    if actual.policy != expected.policy or actual.settings != expected.settings:
+        raise Refused("restoration_unverified")
+    original = decode(request["snapshot"]["create"], api.CreateSandboxRequest)
+    if list(sandbox.spec.providers) != list(original.spec.providers):
+        raise Refused("configuration_changed")
+    return {"verified": True}
+
+
+def perform(stub, request):
+    action = request["action"]
+    if action == "snapshot":
+        return snapshot(stub, request)
+    original = decode(request["snapshot"]["create"], api.CreateSandboxRequest)
+    expected = decode(request["snapshot"]["effective"], policy.GetSandboxConfigResponse)
+    if original.name != request["name"] or original.labels.get("clawscarf.installation") != request["ownerId"]:
+        raise Refused("identity_changed")
+    if action == "create":
+        no_globals(stub, expected)
+        original.spec.template.image = request["image"]
+        original.spec.environment["CLAWSCARF_START_GATE"] = request["generation"]
+        original.labels["clawscarf.upgrade"] = request["generation"]
+        result = stub.CreateSandbox(original, timeout=120).sandbox
+        return {"id": result.metadata.id}
+    if action == "verify":
+        return restored(stub, request, expected)
+    if action == "restore":
+        sandbox = current(stub, request)
+        no_globals(stub, config(stub, sandbox))
+        for key, setting in expected.settings.items():
+            if setting.scope != policy.SETTING_SCOPE_SANDBOX or setting.value.WhichOneof("value") is None:
+                continue
+            sandbox = current(stub, request)
+            observed = config(stub, sandbox).settings.get(key)
+            if observed is not None and observed == setting:
+                continue
+            if observed is not None and observed.value.WhichOneof("value") is not None:
+                raise Refused("configuration_changed")
+            # The pinned setting-update API has no atomic revision precondition.
+            # Explicit resume skips observed matches and reapplies only unset values;
+            # exclusive operator control prevents concurrent edits.
+            stub.UpdateConfig(api.UpdateConfigRequest(name=request["name"], workspace="default", setting_key=key,
+                setting_value=setting.value), timeout=15)
+        return restored(stub, request, expected)
+    raise Refused("invalid_request")
+
+
+def main():
+    try:
+        raw = sys.stdin.buffer.read(4 * 1024 * 1024 + 1)
+        if len(raw) > 4 * 1024 * 1024:
+            raise Refused("invalid_request")
+        request = json.loads(raw)
+        directory = pathlib.Path(request["controller"])
+        settings = json.loads((directory / "controller.json").read_text())
+        if settings["name"] != request["name"]:
+            raise Refused("identity_changed")
+        tls = directory / "tls"
+        credentials = grpc.ssl_channel_credentials((tls / "ca.crt").read_bytes(),
+            (tls / "client/tls.key").read_bytes(), (tls / "client/tls.crt").read_bytes())
+        with grpc.secure_channel(f"127.0.0.1:{settings['port']}", credentials) as channel:
+            result = perform(openshell_pb2_grpc.OpenShellStub(channel), request)
+        output = json.dumps({"ok": True, "value": result})
+        if len(output.encode()) > 4 * 1024 * 1024:
+            raise Refused("response_too_large")
+        print(output)
+    except Refused as error:
+        print(json.dumps({"ok": False, "code": str(error)}))
+    except grpc.RpcError as error:
+        print(json.dumps({"ok": False, "code": error.code().name}))
+    except Exception:
+        print(json.dumps({"ok": False, "code": "unavailable"}))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/deployment/upgrade-state.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { LocalSetupError } from "./process.js";
+export const snapshotSchema = z.strictObject({
+    create: z.string().min(1),
+    effective: z.string().min(1),
+    resourceVersion: z.string().regex(/^[0-9]+$/),
+});
+export const upgradeSchema = z.strictObject({
+    ownerId: z.uuid(),
+    generation: z.uuid(),
+    fromImage: z.string(),
+    toImage: z.string(),
+    oldId: z.uuid(),
+    oldContainerId: z.string().regex(/^[a-f0-9]{64}$/),
+    newId: z.uuid().optional(),
+    snapshot: snapshotSchema,
+    stage: z.enum([
+        "prepared",
+        "delete_sent",
+        "deleted",
+        "create_sent",
+        "created",
+        "restore_sent",
+        "restored",
+        "stopped",
+        "released",
+        "committing",
+        "complete",
+    ]),
+});
+export async function readUpgrade(directory) {
+    try {
+        return upgradeSchema.parse(JSON.parse(await readFile(join(directory, "upgrade.json"), "utf8")));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function requireNoUpgrade(directory) {
+    const upgrade = await readUpgrade(directory);
+    if (upgrade && upgrade.stage !== "complete")
+        throw new LocalSetupError("upgrade_pending", "An upgrade is unfinished. Resume that upgrade before preparing or starting this installation.");
+}