@evermore.work/plugin-cloudflare-sandbox 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# `@evermore.work/plugin-cloudflare-sandbox`
+
+Published Cloudflare sandbox provider plugin for Evermore.
+
+This package lives in the Evermore monorepo, but it is intentionally excluded from the root `pnpm` workspace and shaped to publish and install like a standalone npm package. Operators can install it from the Plugins page by package name, and the host will fetch its dependencies at install time without adding lockfile churn to the Evermore repo.
+
+## Install
+
+From an Evermore instance, install:
+
+```text
+@evermore.work/plugin-cloudflare-sandbox
+```
+
+Configure Cloudflare from `Company Settings -> Environments`, not from the plugin's instance settings page.
+
+## Configuration
+
+The environment uses core `driver: "sandbox"` with `provider: "cloudflare"`.
+
+Required fields:
+
+- `bridgeBaseUrl`
+- `bridgeAuthToken`
+
+Important validation rules:
+
+- `reuseLease: true` requires `keepAlive: true`
+- non-local `bridgeBaseUrl` values must be `https://`
+- `sessionId` is required when `sessionStrategy` is `named`
+
+Pasted auth tokens are stored by Evermore as company secrets because the manifest marks `bridgeAuthToken` as a `secret-ref` field.
+
+## Bridge template
+
+The package includes an operator-facing Cloudflare Worker scaffold under [bridge-template](./bridge-template). That template uses `@cloudflare/sandbox`, a `Sandbox` Durable Object binding, and a small JSON HTTP surface under `/api/evermore-sandbox/v1`.
+
+## Local development
+
+```bash
+cd packages/plugins/sandbox-providers/cloudflare
+pnpm install --ignore-workspace --no-lockfile
+pnpm build
+pnpm test
+pnpm typecheck
+```
+
+These commands assume the repo root has already been installed once so the local `@evermore.work/plugin-sdk` workspace package is available to the compiler during development.

package/bridge-template/Dockerfile

@@ -0,0 +1,14 @@
+FROM docker.io/cloudflare/sandbox:0.7.0
+
+RUN apt-get update \
+  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    coreutils \
+    curl \
+    findutils \
+    git \
+    tar \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace

package/bridge-template/README.md

@@ -0,0 +1,50 @@
+# Cloudflare Sandbox Bridge Template
+
+This Worker is the operator-facing bridge used by `@evermore.work/plugin-cloudflare-sandbox`.
+
+It exposes a small authenticated JSON API under `/api/evermore-sandbox/v1` and translates Evermore lease and command requests into Cloudflare Sandbox SDK calls.
+
+## What it does
+
+- health and probe
+- acquire, resume, release, and destroy leases
+- execute commands in a sandbox session
+- clean up timed-out sessions so Evermore does not inherit wedged background processes
+
+## Prerequisites
+
+1. Cloudflare account with Sandbox / Containers access
+2. `wrangler` configured for that account
+3. Docker running locally for `wrangler deploy`
+4. A bridge auth token set as a Worker secret:
+
+```bash
+npx wrangler secret put BRIDGE_AUTH_TOKEN
+```
+
+## Local development
+
+```bash
+cd bridge-template
+pnpm install --ignore-workspace --no-lockfile
+pnpm test
+pnpm typecheck
+pnpm dev
+```
+
+## Deploy
+
+```bash
+pnpm deploy
+```
+
+After deploy, configure Evermore with:
+
+- `bridgeBaseUrl`: your Worker URL
+- `bridgeAuthToken`: the same bearer token value stored in `BRIDGE_AUTH_TOKEN`
+
+## Notes
+
+- `reuseLease: true` should only be used together with `keepAlive: true`
+- `.workers.dev` is fine for bridge HTTP traffic, but preview/wildcard host flows are intentionally out of scope here
+- keep the Docker image aligned with the installed `@cloudflare/sandbox` version

package/bridge-template/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "evermore-cloudflare-sandbox-bridge-template",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@cloudflare/sandbox": "^0.7.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260501.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4",
+    "wrangler": "^4.15.0"
+  }
+}

package/bridge-template/src/auth.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { isAuthorizedRequest, readBearerToken } from "./auth.js";
+
+describe("bridge auth", () => {
+  it("extracts bearer tokens from Authorization headers", () => {
+    const request = new Request("https://bridge.example.test", {
+      headers: { Authorization: "Bearer secret-token" },
+    });
+    expect(readBearerToken(request)).toBe("secret-token");
+  });
+
+  it("rejects mismatched tokens", async () => {
+    const request = new Request("https://bridge.example.test", {
+      headers: { Authorization: "Bearer wrong-token" },
+    });
+    await expect(isAuthorizedRequest(request, "expected-token")).resolves.toBe(false);
+  });
+
+  it("accepts matching tokens", async () => {
+    const request = new Request("https://bridge.example.test", {
+      headers: { Authorization: "Bearer expected-token" },
+    });
+    await expect(isAuthorizedRequest(request, "expected-token")).resolves.toBe(true);
+  });
+
+  it("rejects requests without an Authorization header", async () => {
+    const request = new Request("https://bridge.example.test");
+    await expect(isAuthorizedRequest(request, "expected-token")).resolves.toBe(false);
+  });
+});

package/bridge-template/src/auth.ts

@@ -0,0 +1,40 @@
+export function readBearerToken(request: Request): string | null {
+  const header = request.headers.get("Authorization");
+  if (!header) return null;
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1]?.trim() || null;
+}
+
+// Compare two strings in constant time so an attacker can't infer the expected
+// token character-by-character via response-latency timing. We hash both sides
+// to SHA-256 first so the byte-by-byte comparison length is fixed (and doesn't
+// leak the token's length), then walk the buffers with a constant-time XOR
+// reduction. This avoids `crypto.subtle.timingSafeEqual` because that helper
+// is not portable: it exists on Cloudflare Workers but is missing from Node's
+// `crypto.subtle` (which would break unit tests). The manual XOR reduction on
+// a fixed-length hash output is the same algorithm the helper uses internally.
+async function timingSafeStringEqual(a: string, b: string): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const [aHashBuf, bHashBuf] = await Promise.all([
+    crypto.subtle.digest("SHA-256", encoder.encode(a)),
+    crypto.subtle.digest("SHA-256", encoder.encode(b)),
+  ]);
+  const aBytes = new Uint8Array(aHashBuf);
+  const bBytes = new Uint8Array(bHashBuf);
+  if (aBytes.length !== bBytes.length) return false;
+  let diff = 0;
+  for (let i = 0; i < aBytes.length; i++) {
+    diff |= aBytes[i] ^ bBytes[i];
+  }
+  return diff === 0;
+}
+
+export async function isAuthorizedRequest(
+  request: Request,
+  expectedToken: string | undefined,
+): Promise<boolean> {
+  if (!expectedToken || expectedToken.trim().length === 0) return false;
+  const presented = readBearerToken(request);
+  if (!presented) return false;
+  return timingSafeStringEqual(presented, expectedToken);
+}

package/bridge-template/src/exec.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@cloudflare/sandbox", () => ({
+  getSandbox: vi.fn(),
+}));
+
+import { buildLoginShellScript, executeInSandbox } from "./exec.js";
+
+describe("bridge exec", () => {
+  it("invokes target.exec with a single shell command string and no args option", async () => {
+    const exec = vi.fn().mockResolvedValue({
+      exitCode: 0,
+      stdout: "claude 1.0.0\n",
+      stderr: "",
+    });
+    const sandbox = {
+      getSession: vi.fn().mockResolvedValue({ exec }),
+      writeFile: vi.fn(),
+      deleteFile: vi.fn(),
+    } as const;
+
+    await executeInSandbox({
+      sandbox: sandbox as never,
+      command: "claude",
+      args: ["--version"],
+      cwd: "/workspace/evermore",
+      env: { EVERMORE_TEST_FLAG: "1" },
+      sessionStrategy: "named",
+      sessionId: "evermore",
+      timeoutMs: 12_345,
+    });
+
+    expect(exec).toHaveBeenCalledTimes(1);
+    const [commandArg, optionsArg] = exec.mock.calls[0] ?? [];
+    expect(typeof commandArg).toBe("string");
+    expect(commandArg).toMatch(/^sh -lc /);
+    expect(optionsArg).toEqual({ cwd: "/", timeout: 12_345 });
+    expect(optionsArg).not.toHaveProperty("args");
+    expect(optionsArg).not.toHaveProperty("stdin");
+    expect(commandArg).toContain('. /etc/profile');
+    expect(commandArg).toContain("cd ");
+    expect(commandArg).toContain("/workspace/evermore");
+    expect(commandArg).toContain("EVERMORE_TEST_FLAG");
+    expect(commandArg).toContain("claude");
+    expect(commandArg).toContain("--version");
+  });
+
+  it("requests streaming callbacks when bridge output forwarding is enabled", async () => {
+    const exec = vi.fn().mockImplementation(async (_command, options) => {
+      await options?.onOutput?.("stdout", "hello\n");
+      return {
+        exitCode: 0,
+        stdout: "hello\n",
+        stderr: "",
+      };
+    });
+    const sandbox = {
+      getSession: vi.fn().mockResolvedValue({ exec }),
+      writeFile: vi.fn(),
+      deleteFile: vi.fn(),
+    } as const;
+    const onOutput = vi.fn();
+
+    await executeInSandbox({
+      sandbox: sandbox as never,
+      command: "echo",
+      args: ["hello"],
+      sessionStrategy: "named",
+      sessionId: "evermore",
+      timeoutMs: 5_000,
+      onOutput,
+    });
+
+    expect(exec).toHaveBeenCalledTimes(1);
+    expect(exec.mock.calls[0]?.[1]).toMatchObject({
+      cwd: "/",
+      timeout: 5_000,
+      stream: true,
+      onOutput: expect.any(Function),
+    });
+    expect(onOutput).toHaveBeenCalledWith("stdout", "hello\n");
+  });
+
+  it("stages stdin through a sandbox temp file and redirects from it", async () => {
+    const exec = vi.fn().mockResolvedValue({ exitCode: 0, stdout: "", stderr: "" });
+    const writeFile = vi.fn().mockResolvedValue(undefined);
+    const deleteFile = vi.fn().mockResolvedValue(undefined);
+    // sessionStrategy: "default" routes through the sandbox itself (no
+    // getSession wrapper), so exec must live directly on the sandbox.
+    const sandbox = {
+      exec,
+      getSession: vi.fn(),
+      writeFile,
+      deleteFile,
+    } as const;
+
+    await executeInSandbox({
+      sandbox: sandbox as never,
+      command: "cat",
+      args: [],
+      sessionStrategy: "default",
+      timeoutMs: 5_000,
+      stdin: "payload-bytes",
+    });
+
+    expect(writeFile).toHaveBeenCalledTimes(1);
+    const [stdinPath, stdinPayload] = writeFile.mock.calls[0] ?? [];
+    expect(typeof stdinPath).toBe("string");
+    expect(stdinPath).toMatch(/^\/tmp\/\.evermore-bridge-stdin-/);
+    expect(stdinPayload).toBe("payload-bytes");
+
+    const commandArg = exec.mock.calls[0]?.[0];
+    expect(commandArg).toContain(stdinPath);
+    expect(commandArg).toMatch(/<\s*['"]/);
+
+    expect(deleteFile).toHaveBeenCalledWith(stdinPath);
+  });
+
+  it("does not write a stdin file or redirect when stdin is empty", async () => {
+    const exec = vi.fn().mockResolvedValue({ exitCode: 0, stdout: "", stderr: "" });
+    const writeFile = vi.fn();
+    const deleteFile = vi.fn();
+    const sandbox = {
+      getSession: vi.fn().mockResolvedValue({ exec }),
+      writeFile,
+      deleteFile,
+    } as const;
+
+    await executeInSandbox({
+      sandbox: sandbox as never,
+      command: "pwd",
+      sessionStrategy: "named",
+      sessionId: "evermore",
+      timeoutMs: 5_000,
+      stdin: null,
+    });
+
+    expect(writeFile).not.toHaveBeenCalled();
+    expect(deleteFile).not.toHaveBeenCalled();
+    const commandArg = exec.mock.calls[0]?.[0];
+    expect(commandArg).not.toContain("<");
+  });
+
+  it("rejects invalid environment variable keys in the login-shell wrapper", () => {
+    expect(() => buildLoginShellScript({
+      command: "pwd",
+      args: [],
+      env: { "bad-key": "1" },
+    })).toThrow("Invalid sandbox environment variable key: bad-key");
+  });
+});

package/bridge-template/src/exec.ts

@@ -0,0 +1,147 @@
+import type { Sandbox as CloudflareSandbox } from "@cloudflare/sandbox";
+import { shellQuote } from "./helpers.js";
+import { isTimeoutError } from "./sandboxes.js";
+import { cleanupTimedOutExecution, resolveExecutionTarget, type SessionStrategy } from "./sessions.js";
+
+export interface BridgeExecuteParams {
+  sandbox: CloudflareSandbox;
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  stdin?: string | null;
+  timeoutMs?: number;
+  sessionStrategy: SessionStrategy;
+  sessionId?: string;
+  onOutput?: (stream: "stdout" | "stderr", data: string) => void | Promise<void>;
+}
+
+function isValidShellEnvKey(value: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+
+function randomToken(): string {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (typeof uuid === "string" && uuid.length > 0) return uuid.replace(/[^a-zA-Z0-9-]/g, "");
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+export function buildLoginShellScript(input: {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  stdinFile?: string | null;
+}): string {
+  const env = input.env ?? {};
+  for (const key of Object.keys(env)) {
+    if (!isValidShellEnvKey(key)) {
+      throw new Error(`Invalid sandbox environment variable key: ${key}`);
+    }
+  }
+
+  const envArgs = Object.entries(env)
+    .filter((entry): entry is [string, string] => typeof entry[1] === "string")
+    .map(([key, value]) => `${key}=${shellQuote(value)}`);
+  const commandParts = [shellQuote(input.command), ...input.args.map(shellQuote)].join(" ");
+  const stdinRedirect = input.stdinFile ? ` < ${shellQuote(input.stdinFile)}` : "";
+  const lines = [
+    'if [ -f /etc/profile ]; then . /etc/profile >/dev/null 2>&1 || true; fi',
+    'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',
+    'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; elif [ -f "$HOME/.bashrc" ]; then . "$HOME/.bashrc" >/dev/null 2>&1 || true; fi',
+    'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',
+    'export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"',
+    '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" >/dev/null 2>&1 || true',
+  ];
+  if (input.cwd) {
+    lines.push(`cd ${shellQuote(input.cwd)}`);
+  }
+  const execLine = envArgs.length > 0
+    ? `exec env ${envArgs.join(" ")} ${commandParts}${stdinRedirect}`
+    : `exec ${commandParts}${stdinRedirect}`;
+  lines.push(execLine);
+  return lines.join(" && ");
+}
+
+function coerceExecuteResult(result: {
+  success?: boolean;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+}) {
+  return {
+    exitCode:
+      typeof result.exitCode === "number" || result.exitCode === null
+        ? result.exitCode
+        : result.success === false
+          ? 1
+          : 0,
+    signal: null,
+    timedOut: false,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+export async function executeInSandbox(params: BridgeExecuteParams) {
+  // The @cloudflare/sandbox SDK's exec() takes a single command string and a
+  // narrow option set ({ cwd, env, timeout, ... }) — it does not accept `args`
+  // or `stdin`. We compose the full shell command ourselves and stage stdin
+  // through a temp file in the sandbox when the caller provides one.
+  const stdinPayload = typeof params.stdin === "string" && params.stdin.length > 0
+    ? params.stdin
+    : null;
+  const stdinFile = stdinPayload ? `/tmp/.evermore-bridge-stdin-${randomToken()}` : null;
+
+  if (stdinFile && stdinPayload) {
+    await params.sandbox.writeFile(stdinFile, stdinPayload, { encoding: "utf8" });
+  }
+
+  try {
+    const target = await resolveExecutionTarget(params.sandbox, {
+      sessionStrategy: params.sessionStrategy,
+      sessionId: params.sessionId,
+      cwd: params.cwd,
+      env: params.env,
+      timeoutMs: params.timeoutMs,
+    });
+    const script = buildLoginShellScript({
+      command: params.command,
+      args: params.args ?? [],
+      cwd: params.cwd,
+      env: params.env,
+      stdinFile,
+    });
+    const fullCommand = `sh -lc ${shellQuote(script)}`;
+    const result = await target.exec(fullCommand, {
+      cwd: "/",
+      timeout: params.timeoutMs,
+      ...(typeof params.onOutput === "function"
+        ? {
+            stream: true,
+            onOutput: params.onOutput,
+          }
+        : {}),
+    });
+    return coerceExecuteResult(result);
+  } catch (error) {
+    if (isTimeoutError(error)) {
+      await cleanupTimedOutExecution(params.sandbox, {
+        sessionStrategy: params.sessionStrategy,
+        sessionId: params.sessionId,
+      });
+      return {
+        exitCode: null,
+        signal: null,
+        timedOut: true,
+        stdout: typeof (error as { stdout?: unknown }).stdout === "string" ? (error as { stdout: string }).stdout : "",
+        stderr: `${error instanceof Error ? error.message : String(error)}\n`,
+      };
+    }
+    throw error;
+  } finally {
+    if (stdinFile) {
+      await params.sandbox.deleteFile?.(stdinFile).catch(() => undefined);
+    }
+  }
+}

package/bridge-template/src/helpers.ts

@@ -0,0 +1,39 @@
+export function normalizeLeaseIdPart(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+}
+
+export function buildLeaseSandboxId(input: {
+  environmentId: string;
+  runId: string;
+  reuseLease: boolean;
+  normalizeId: boolean;
+  randomId?: string;
+}): string {
+  const base = input.reuseLease
+    ? `pc-env-${input.environmentId}`
+    : `pc-${input.runId}-${input.randomId ?? crypto.randomUUID().slice(0, 8)}`;
+  return input.normalizeId ? normalizeLeaseIdPart(base) : base;
+}
+
+export function buildSentinelPath(remoteCwd: string): string {
+  return `${remoteCwd.replace(/\/+$/, "")}/.evermore-lease.json`;
+}
+
+export function isTimeoutError(error: unknown): boolean {
+  const name = (error as { name?: string } | null)?.name ?? "";
+  const message = error instanceof Error ? error.message : String(error);
+  return /timeout/i.test(name) || /timed out|timeout/i.test(message);
+}
+
+// Single-quote `value` for safe inclusion in a `sh -c` script. Single
+// quotes inside the value are escaped via the standard `'"'"'` dance.
+// Used by both `routes.ts` and `exec.ts` — keep one copy here so updates
+// (e.g. handling additional shell special characters) stay in sync.
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}

package/bridge-template/src/index.ts

@@ -0,0 +1,25 @@
+import { Sandbox } from "@cloudflare/sandbox";
+import { handleBridgeRequest, } from "./routes.js";
+import type { BridgeEnv } from "./sandboxes.js";
+
+export { Sandbox };
+
+export default {
+  async fetch(request: Request, env: BridgeEnv): Promise<Response> {
+    try {
+      return await handleBridgeRequest(request, env);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return new Response(
+        JSON.stringify({
+          error: "internal_error",
+          message,
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    }
+  },
+};