mlclaw 0.2.3 → 0.3.1

package/src/hf-state-sync/paths.ts

@@ -10,6 +10,8 @@ export type SyncConfig = {
   liveDir: string;
   /** Bucket repo id (`owner/name`), or null when no bucket is configured. */
   bucket: string | null;
+  /** Mounted bucket directory for Space runtimes, or null to use the Hub API. */
+  stateMountDir: string | null;
   /** Path prefix inside the bucket for all sync objects. */
   bucketPrefix: string;
   intervalSeconds: number;
@@ -22,9 +24,14 @@ export type SyncConfig = {
   agentName: string;
   gatewayLocation: "local" | "space" | "unknown";
   runtimeImage: string;
+  /** UID/GID used by the secret-free snapshot traversal worker. */
+  snapshotUid?: number;
+  snapshotGid?: number;
+  /** Root-owned runtime state overlaid by the trusted snapshot supervisor. */
+  protectedStateDir?: string;
 };
 
-const DEFAULT_LIVE_DIR = "/tmp/openclaw-live";
+const DEFAULT_LIVE_DIR = "/home/node/.local/share/mlclaw/live";
 export const DEFAULT_BUCKET_PREFIX = "openclaw-state";
 const DEFAULT_INTERVAL_SECONDS = 60;
 const DEFAULT_HANDOFF_POLL_SECONDS = 5;
@@ -37,9 +44,12 @@ function positiveIntFromEnv(value: string | undefined, fallback: number): number
 
 export function resolveSyncConfig(env: NodeJS.ProcessEnv = process.env): SyncConfig {
   const runId = env.MLCLAW_RUN_ID?.trim() || randomUUID();
+  const snapshotUid = nonNegativeIntFromEnv(env.MLCLAW_OPENCLAW_UID);
+  const snapshotGid = nonNegativeIntFromEnv(env.MLCLAW_OPENCLAW_GID);
   return {
     liveDir: env.OPENCLAW_LIVE_DIR?.trim() || DEFAULT_LIVE_DIR,
     bucket: env.OPENCLAW_HF_STATE_BUCKET?.trim() || null,
+    stateMountDir: env.MLCLAW_STATE_MOUNT_DIR?.trim() || null,
     bucketPrefix: normalizeBucketPrefix(env.OPENCLAW_HF_STATE_PREFIX),
     intervalSeconds: positiveIntFromEnv(env.HF_STATE_SYNC_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS),
     handoffPollSeconds: positiveIntFromEnv(env.HF_STATE_SYNC_HANDOFF_POLL_SECONDS, DEFAULT_HANDOFF_POLL_SECONDS),
@@ -47,13 +57,22 @@ export function resolveSyncConfig(env: NodeJS.ProcessEnv = process.env): SyncCon
     runId,
     runtimeId: env.MLCLAW_RUNTIME_ID?.trim() || runId,
     agentName: env.OPENCLAW_AGENT_NAME?.trim() || "openclaw",
-    gatewayLocation: env.MLCLAW_GATEWAY_LOCATION === "local" || env.MLCLAW_GATEWAY_LOCATION === "space"
-      ? env.MLCLAW_GATEWAY_LOCATION
-      : "unknown",
+    gatewayLocation:
+      env.MLCLAW_GATEWAY_LOCATION === "local" || env.MLCLAW_GATEWAY_LOCATION === "space"
+        ? env.MLCLAW_GATEWAY_LOCATION
+        : "unknown",
     runtimeImage: env.MLCLAW_RUNTIME_IMAGE?.trim() || "unknown",
+    ...(snapshotUid !== undefined ? { snapshotUid } : {}),
+    ...(snapshotGid !== undefined ? { snapshotGid } : {}),
+    ...(env.MLCLAW_PROTECTED_STATE_DIR?.trim() ? { protectedStateDir: env.MLCLAW_PROTECTED_STATE_DIR.trim() } : {}),
   };
 }
 
+function nonNegativeIntFromEnv(value: string | undefined): number | undefined {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
 /** Remote object path under the configured bucket prefix. */
 export function remotePath(config: Pick<SyncConfig, "bucketPrefix">, name: string): string {
   return `${normalizeBucketPrefix(config.bucketPrefix)}/${name.replace(/^\/+/, "")}`;

package/src/hf-state-sync/prepare.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { SyncConfig } from "./paths.js";
+
+export async function prepareRestore(config: SyncConfig): Promise<void> {
+  if (config.snapshotUid === undefined || config.snapshotGid === undefined) {
+    throw new Error("restore preparation requires MLCLAW_OPENCLAW_UID and MLCLAW_OPENCLAW_GID");
+  }
+  const liveParent = path.dirname(config.liveDir);
+  await fs.mkdir(liveParent, { recursive: true });
+  await fs.chown(liveParent, config.snapshotUid, config.snapshotGid);
+
+  if (!config.stateMountDir) {
+    return;
+  }
+  await makeTraversableDirectory(config.stateMountDir);
+  const prefixRoot = confinedPath(config.stateMountDir, config.bucketPrefix);
+  let prefixPart = config.stateMountDir;
+  for (const part of config.bucketPrefix.split("/").filter(Boolean)) {
+    prefixPart = path.join(prefixPart, part);
+    await makeTraversableDirectory(prefixPart);
+  }
+  await makeReadableIfFile(path.join(prefixRoot, "manifest.json"));
+  const snapshotsDir = path.join(prefixRoot, "snapshots");
+  await makeTraversableDirectory(snapshotsDir);
+  let entries;
+  try {
+    entries = await fs.readdir(snapshotsDir, { withFileTypes: true });
+  } catch (err) {
+    if (isNotFound(err)) {
+      return;
+    }
+    throw err;
+  }
+  for (const entry of entries) {
+    if (entry.isFile()) {
+      await fs.chmod(path.join(snapshotsDir, entry.name), 0o644);
+    }
+  }
+}
+
+async function makeTraversableDirectory(directory: string): Promise<void> {
+  try {
+    const stat = await fs.lstat(directory);
+    if (stat.isDirectory()) {
+      await fs.chmod(directory, 0o711);
+    }
+  } catch (err) {
+    if (!isNotFound(err)) {
+      throw err;
+    }
+  }
+}
+
+function confinedPath(root: string, relative: string): string {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relative);
+  if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`invalid state prefix outside mounted bucket: ${relative}`);
+  }
+  return resolved;
+}
+
+async function makeReadableIfFile(file: string): Promise<void> {
+  try {
+    const stat = await fs.lstat(file);
+    if (stat.isFile()) {
+      await fs.chmod(file, 0o644);
+    }
+  } catch (err) {
+    if (!isNotFound(err)) {
+      throw err;
+    }
+  }
+}
+
+function isNotFound(err: unknown): boolean {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}

package/src/hf-state-sync/snapshot.ts

@@ -18,6 +18,15 @@ export type SnapshotOutcome =
   | { kind: "skipped"; reason: "no-bucket" | "empty-state" }
   | { kind: "failed"; detail: string };
 
+export type StagedArchiveOutcome =
+  | { kind: "staged"; databaseCount: number }
+  | { kind: "corrupt-database"; database: string; detail: string };
+
+export type StageArchive = (params: {
+  liveDir: string;
+  archivePath: string;
+}) => Promise<StagedArchiveOutcome>;
+
 // Object names must be unique across overlapping containers (run-id suffix)
 // AND within one run (counter): a final snapshot can land in the same second
 // as the last interval snapshot, and an overwritten tarball behind a distinct
@@ -61,6 +70,7 @@ export async function runSnapshot(params: {
   hub: BucketHub;
   bootTime: string;
   now?: () => Date;
+  stageArchive?: StageArchive;
 }): Promise<SnapshotOutcome> {
   const { config, hub } = params;
   if (!config.bucket) {
@@ -74,8 +84,13 @@ export async function runSnapshot(params: {
 
   const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "hf-state-snapshot-"));
   try {
-    const stagingDir = path.join(workDir, "stage");
-    const staged = await stageLiveDir(config.liveDir, stagingDir);
+    const now = (params.now ?? (() => new Date()))();
+    const id = snapshotId(now, config.runId);
+    const archiveName = `state-${id}.tar.zst`;
+    const archivePath = path.join(workDir, archiveName);
+    const staged = params.stageArchive
+      ? await params.stageArchive({ liveDir: config.liveDir, archivePath })
+      : await stageArchiveInProcess(config.liveDir, path.join(workDir, "stage"), archivePath);
     if (staged.kind === "corrupt-database") {
       return {
         kind: "failed",
@@ -83,12 +98,6 @@ export async function runSnapshot(params: {
       };
     }
 
-    const now = (params.now ?? (() => new Date()))();
-    const id = snapshotId(now, config.runId);
-    const archiveName = `state-${id}.tar.zst`;
-    const archivePath = path.join(workDir, archiveName);
-    await createTarZst(stagingDir, archivePath);
-
     const entry: SnapshotEntry = {
       id,
       path: remotePath(config, `snapshots/${archiveName}`),
@@ -123,7 +132,7 @@ export async function runSnapshot(params: {
     if (expired.length > 0) {
       await hub.delete(expired.map((e) => e.path));
     }
-    log(`snapshot ${entry.id} uploaded (${entry.sizeBytes} bytes, ${staged.databases.length} dbs)`);
+    log(`snapshot ${entry.id} uploaded (${entry.sizeBytes} bytes, ${staged.databaseCount} dbs)`);
     return { kind: "uploaded", entry };
   } catch (err) {
     return { kind: "failed", detail: err instanceof Error ? err.message : String(err) };
@@ -131,3 +140,16 @@ export async function runSnapshot(params: {
     await fs.rm(workDir, { recursive: true, force: true });
   }
 }
+
+async function stageArchiveInProcess(
+  liveDir: string,
+  stagingDir: string,
+  archivePath: string,
+): Promise<StagedArchiveOutcome> {
+  const staged = await stageLiveDir(liveDir, stagingDir);
+  if (staged.kind === "corrupt-database") {
+    return staged;
+  }
+  await createTarZst(stagingDir, archivePath);
+  return { kind: "staged", databaseCount: staged.databases.length };
+}

package/src/hf-state-sync/stage-worker.ts

@@ -0,0 +1,165 @@
+import { spawn } from "node:child_process";
+import { createReadStream, createWriteStream, writeFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { PROTECTED_STATE_DIR_NAME, createTarZst, extractTarZst, stageLiveDir } from "./archive.js";
+import type { SyncConfig } from "./paths.js";
+import type { StageArchive, StagedArchiveOutcome } from "./snapshot.js";
+
+type WorkerMessage = StagedArchiveOutcome | { kind: "failed"; detail: string };
+
+export function unprivilegedStageArchive(params: { uid: number; gid: number; scriptPath: string }): StageArchive {
+  return async ({ liveDir, archivePath }) => {
+    const child = spawn(process.execPath, [params.scriptPath, "stage-worker", liveDir], {
+      uid: params.uid,
+      gid: params.gid,
+      env: snapshotWorkerEnvironment(process.env),
+      stdio: ["ignore", "pipe", "inherit", "pipe"],
+    });
+    if (!child.stdout || !child.stdio[3]) {
+      child.kill("SIGKILL");
+      throw new Error("snapshot staging worker pipes are unavailable");
+    }
+    const archiveOutput = createWriteStream(archivePath, { flags: "wx", mode: 0o600 });
+    const metadata = collect(child.stdio[3] as NodeJS.ReadableStream);
+    const archive = pipeline(child.stdout, archiveOutput);
+    const exitCode = await new Promise<number>((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+    await archive;
+    const message = parseWorkerMessage(await metadata);
+    if (exitCode !== 0 || message.kind === "failed") {
+      throw new Error(
+        message.kind === "failed" ? message.detail : `snapshot staging worker exited with code ${exitCode}`,
+      );
+    }
+    return message;
+  };
+}
+
+export function protectedStageArchive(params: {
+  base: StageArchive;
+  sourceDir: string;
+  archiveName: string;
+}): StageArchive {
+  return async (request) => {
+    const outcome = await params.base(request);
+    if (outcome.kind !== "staged") {
+      return outcome;
+    }
+    const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "hf-state-protected-stage-"));
+    try {
+      const stagingDir = path.join(workDir, "stage");
+      await extractTarZst(request.archivePath, stagingDir);
+      const destination = path.join(stagingDir, params.archiveName);
+      await fs.cp(params.sourceDir, destination, {
+        recursive: true,
+        force: false,
+        preserveTimestamps: true,
+        filter: (source) => includeProtectedSnapshotPath(params.sourceDir, source),
+      });
+      await fs.chmod(destination, 0o700);
+      await fs.rm(request.archivePath, { force: true });
+      await createTarZst(stagingDir, request.archivePath);
+      await fs.chmod(request.archivePath, 0o600);
+      return outcome;
+    } finally {
+      await fs.rm(workDir, { recursive: true, force: true });
+    }
+  };
+}
+
+export function includeProtectedSnapshotPath(sourceDir: string, source: string): boolean {
+  const relative = path.relative(sourceDir, source);
+  return relative !== "hf-broker/mirrors" && !relative.startsWith(`hf-broker/mirrors${path.sep}`);
+}
+
+export function trustedStageArchive(config: SyncConfig, scriptPath: string | undefined): StageArchive | undefined {
+  const canStageAsOpenClaw =
+    process.getuid?.() === 0 &&
+    Boolean(scriptPath) &&
+    config.snapshotUid !== undefined &&
+    config.snapshotGid !== undefined;
+  if (!canStageAsOpenClaw) {
+    if (config.protectedStateDir) {
+      throw new Error("protected runtime state requires root snapshot staging with an OpenClaw UID and GID");
+    }
+    return undefined;
+  }
+
+  let stageArchive = unprivilegedStageArchive({
+    uid: config.snapshotUid as number,
+    gid: config.snapshotGid as number,
+    scriptPath: scriptPath as string,
+  });
+  if (config.protectedStateDir) {
+    stageArchive = protectedStageArchive({
+      base: stageArchive,
+      sourceDir: config.protectedStateDir,
+      archiveName: PROTECTED_STATE_DIR_NAME,
+    });
+  }
+  return stageArchive;
+}
+
+export async function runStageWorker(liveDir: string): Promise<number> {
+  const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "hf-state-stage-worker-"));
+  try {
+    const stagingDir = path.join(workDir, "stage");
+    const archivePath = path.join(workDir, "snapshot.tar.zst");
+    const staged = await stageLiveDir(liveDir, stagingDir, { excludeProtectedState: true });
+    if (staged.kind === "corrupt-database") {
+      writeWorkerMessage(staged);
+      return 0;
+    }
+    await createTarZst(stagingDir, archivePath);
+    writeWorkerMessage({ kind: "staged", databaseCount: staged.databases.length });
+    await pipeline(createReadStream(archivePath), process.stdout);
+    return 0;
+  } catch (err) {
+    writeWorkerMessage({ kind: "failed", detail: err instanceof Error ? err.message : String(err) });
+    return 1;
+  } finally {
+    await fs.rm(workDir, { recursive: true, force: true });
+  }
+}
+
+export function snapshotWorkerEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return {
+    HOME: "/home/node",
+    PATH: env.PATH,
+    TMPDIR: env.TMPDIR,
+  };
+}
+
+function writeWorkerMessage(message: WorkerMessage): void {
+  writeFileSync(3, `${JSON.stringify(message)}\n`);
+}
+
+async function collect(stream: NodeJS.ReadableStream | null): Promise<string> {
+  if (!stream) {
+    throw new Error("snapshot staging worker metadata pipe is unavailable");
+  }
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function parseWorkerMessage(raw: string): WorkerMessage {
+  const parsed = JSON.parse(raw) as WorkerMessage;
+  if (parsed.kind === "staged" && Number.isInteger(parsed.databaseCount) && parsed.databaseCount >= 0) {
+    return parsed;
+  }
+  if (parsed.kind === "corrupt-database" && parsed.database && parsed.detail) {
+    return parsed;
+  }
+  if (parsed.kind === "failed" && parsed.detail) {
+    return parsed;
+  }
+  throw new Error("snapshot staging worker returned invalid metadata");
+}

package/src/hf-state-sync/supervise.ts

@@ -6,6 +6,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import type { BucketHub } from "./hub.js";
 import { type SyncConfig, log, logError, remotePath } from "./paths.js";
 import { runSnapshot, type SnapshotOutcome } from "./snapshot.js";
+import { trustedStageArchive } from "./stage-worker.js";
 
 const LEASE_HEARTBEAT_MS = 60_000;
 const HANDOFF_REQUEST_TTL_MS = 10 * 60 * 1000;
@@ -17,17 +18,15 @@ const HANDOFF_REQUEST_TTL_MS = 10 * 60 * 1000;
  * is lost. If the platform hard-kills us first, the interval loop has already
  * bounded the loss the same way.
  */
-export async function supervise(params: {
-  config: SyncConfig;
-  hub: BucketHub;
-  command: string[];
-}): Promise<number> {
+export async function supervise(params: { config: SyncConfig; hub: BucketHub; command: string[] }): Promise<number> {
   const { config, hub, command } = params;
   const [binary, ...args] = command;
   if (!binary) {
     throw new Error("supervise: missing child command");
   }
   const bootTime = new Date().toISOString();
+  const scriptPath = process.argv[1];
+  const stageArchive = trustedStageArchive(config, scriptPath);
   let lastSnapshotId: string | undefined;
   const handoffState: { request: RuntimeHandoffRequest | null } = { request: null };
 
@@ -104,7 +103,10 @@ export async function supervise(params: {
     }
   };
 
-  const child: ChildProcess = spawn(binary, args, { stdio: "inherit" });
+  const child: ChildProcess = spawn(binary, args, {
+    stdio: "inherit",
+    env: supervisedChildEnvironment(process.env),
+  });
   const childExit = new Promise<number>((resolve) => {
     child.on("exit", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
     child.on("error", (err) => {
@@ -117,7 +119,12 @@ export async function supervise(params: {
   let inFlight: Promise<SnapshotOutcome> | null = null;
   const runOnce = async (label: string): Promise<SnapshotOutcome> => {
     try {
-      const outcome = await runSnapshot({ config, hub, bootTime });
+      const outcome = await runSnapshot({
+        config,
+        hub,
+        bootTime,
+        ...(stageArchive ? { stageArchive } : {}),
+      });
       if (outcome.kind === "failed") {
         logError(`${label}: snapshot failed: ${outcome.detail}`);
       } else if (outcome.kind === "uploaded") {
@@ -162,7 +169,9 @@ export async function supervise(params: {
   void snapshotLoop;
 
   const heartbeatLoop = (async () => {
-    await writeLease().catch((err) => logError(`initial lease failed: ${err instanceof Error ? err.message : String(err)}`));
+    await writeLease().catch((err) =>
+      logError(`initial lease failed: ${err instanceof Error ? err.message : String(err)}`),
+    );
     while (!stopping) {
       await delay(LEASE_HEARTBEAT_MS);
       if (stopping) {
@@ -224,10 +233,14 @@ export async function supervise(params: {
   if (handoffState.request) {
     const request = handoffState.request;
     if (finalOutcome.kind !== "uploaded") {
-      throw new Error(`handoff ${request.requestId} final snapshot did not upload: ${snapshotFailureDetail(finalOutcome)}`);
+      throw new Error(
+        `handoff ${request.requestId} final snapshot did not upload: ${snapshotFailureDetail(finalOutcome)}`,
+      );
     }
     await writeHandoffAck(request).catch((err) => {
-      throw new Error(`handoff ${request.requestId} snapshot completed but ack failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(
+        `handoff ${request.requestId} snapshot completed but ack failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
     });
     log(`handoff ${request.requestId} acknowledged`);
     return 0;
@@ -235,6 +248,12 @@ export async function supervise(params: {
   return exitCode;
 }
 
+export function supervisedChildEnvironment(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env = { ...source };
+  delete env.MLCLAW_STATE_HF_TOKEN;
+  return env;
+}
+
 function snapshotFailureDetail(outcome: SnapshotOutcome): string {
   switch (outcome.kind) {
     case "uploaded":

package/src/vendor/hfjs-xet/utils/ChunkCache.ts

@@ -35,7 +35,7 @@ export class ChunkCache {
 			return;
 		}
 		if (this.map.values().next().value === this.index) {
-			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- The equality check proves the oldest key exists.
 			this.map.delete(this.map.keys().next().value!);
 		}
 		this.map.set(hash, this.index);

package/src/vendor/hfjs-xet/utils/XetBlob.ts

@@ -137,7 +137,7 @@ export class XetBlob extends Blob {
 			fetch: this.fetch,
 			hash: this.hash,
 			refreshUrl: this.refreshUrl,
-			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Clone is called only after reconstruction URL initialization.
 			reconstructionUrl: this.reconstructionUrl!,
 			size: this.size,
 		});
@@ -258,7 +258,7 @@ export class XetBlob extends Blob {
 					if (termRanges.every((range) => range.data)) {
 						log("all data available for term", term.hash, readBytesToSkip);
 						rangeLoop: for (const range of termRanges) {
-							// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+								// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- The preceding every check proves range data is present.
 							for (let chunk of range.data!) {
 								if (readBytesToSkip) {
 									const skipped = Math.min(readBytesToSkip, chunk.byteLength);

package/src/vendor/hfjs-xet/utils/createXorbs.ts

@@ -32,7 +32,7 @@ const INTERVAL_BETWEEN_REMOTE_DEDUP = 4_000_000; // 4MB
  * 0.5 = show progress when uploading the xorb and when processing the file
  */
 const PROCESSING_PROGRESS_RATIO = 0.1;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Kept in sync with the vendored upstream progress constants.
 const UPLOADING_PROGRESS_RATIO = 1 - PROCESSING_PROGRESS_RATIO;
 
 function computeXorbHashHex(chunks: { hash: string; length: number }[]): string {
@@ -703,7 +703,7 @@ async function loadDedupInfoToCache(
 	const chunker = createChunker(TARGET_CHUNK_SIZE);
 	const cache = chunkCache;
 
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Preserved for parity with upstream deduplication accounting.
 	let dedupedBytes = 0;
 	let chunksProcessed = 0;
 	let totalBytes = 0;