@superhq/shuru 0.1.1 → 0.2.0

package/README.md

@@ -19,7 +19,8 @@ const result = await sb.exec("echo hello");
 console.log(result.stdout); // "hello\n"
 
 await sb.writeFile("/tmp/app.ts", "console.log('hi')");
-const content = await sb.readFile("/tmp/app.ts");
+const data = await sb.readFile("/tmp/app.ts"); // Uint8Array
+const text = new TextDecoder().decode(data);
 
 await sb.checkpoint("my-env"); // saves disk state and stops the VM
 ```
@@ -41,6 +42,10 @@ const sb = await Sandbox.start({
   allowNet: true,
   ports: ["8080:80"],
   mounts: { "./src": "/workspace" },
+  secrets: {
+    API_KEY: { from: "OPENAI_API_KEY", hosts: ["api.openai.com"] },
+  },
+  network: { allow: ["api.openai.com", "registry.npmjs.org"] },
 });
 ```
 
@@ -53,6 +58,8 @@ const sb = await Sandbox.start({
 | `allowNet` | `boolean` | Enable network access |
 | `ports` | `string[]` | Port forwards (`"host:guest"`) |
 | `mounts` | `Record<string, string>` | Directory mounts (`{ hostPath: guestPath }`) |
+| `secrets` | `Record<string, SecretConfig>` | Secrets to inject via proxy (see below) |
+| `network` | `NetworkConfig` | Network access policy (see below) |
 | `shuruBin` | `string` | Path to shuru binary (default: `"shuru"`) |
 
 ## API
@@ -65,13 +72,13 @@ Boot a new microVM. Returns when the VM is ready.
 
 Run a shell command in the VM. Returns `{ stdout, stderr, exitCode }`.
 
-### `sandbox.readFile(path): Promise<string>`
+### `sandbox.readFile(path): Promise<Uint8Array>`
 
-Read a file from the VM.
+Read a file from the VM. Returns raw bytes. Use `new TextDecoder().decode(data)` for text files.
 
-### `sandbox.writeFile(path, content): Promise<void>`
+### `sandbox.writeFile(path, content: Uint8Array | string): Promise<void>`
 
-Write a file to the VM.
+Write a file to the VM. Accepts raw bytes or a string.
 
 ### `sandbox.checkpoint(name): Promise<void>`
 
@@ -81,6 +88,34 @@ Save the VM's disk state and stop the VM. To continue working, call `Sandbox.sta
 
 Stop the VM without saving. All changes are discarded.
 
+### Secrets
+
+Secrets keep API keys on the host. The guest receives a random placeholder token; the proxy substitutes the real value only on HTTPS requests to the specified hosts.
+
+```ts
+const sb = await Sandbox.start({
+  allowNet: true,
+  secrets: {
+    API_KEY: { from: "OPENAI_API_KEY", hosts: ["api.openai.com"] },
+  },
+});
+// Inside the VM, $API_KEY is a placeholder token.
+// Requests to api.openai.com get the real key injected by the proxy.
+```
+
+### Network policy
+
+Restrict which domains the guest can reach:
+
+```ts
+const sb = await Sandbox.start({
+  allowNet: true,
+  network: { allow: ["api.openai.com", "*.npmjs.org"] },
+});
+```
+
+Omit `network.allow` to allow all domains.
+
 ## Requirements
 
 - macOS 14+ on Apple Silicon

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@superhq/shuru",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "files": ["src"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/superhq-ai/shuru",
+    "directory": "packages/sdk"
+  },
   "scripts": {
     "test": "bun test test/unit/",
     "test:integration": "bun test test/integration/",

package/src/index.ts

@@ -1,2 +1,7 @@
 export { Sandbox } from "./sandbox";
-export type { ExecResult, StartOptions, StdioResponse } from "./types";
+export type {
+	ExecResult,
+	NetworkConfig,
+	SecretConfig,
+	StartOptions,
+} from "./types";

package/src/process.ts

@@ -1,15 +1,17 @@
 import type { Subprocess } from "bun";
-import type { StdioResponse } from "./types";
+import type { JsonRpcResponse, JsonRpcResult } from "./types";
 
 interface PendingRequest {
-	resolve: (value: StdioResponse) => void;
+	resolve: (value: JsonRpcResult) => void;
 	reject: (reason: Error) => void;
 }
 
 export class ShuruProcess {
 	private proc: Subprocess<"pipe", "pipe", "inherit"> | null = null;
-	private pending = new Map<string, PendingRequest>();
+	private pending = new Map<number, PendingRequest>();
 	private idCounter = 0;
+	private onReady: (() => void) | null = null;
+	private onReadyError: ((err: Error) => void) | null = null;
 
 	async start(args: string[]): Promise<void> {
 		this.proc = Bun.spawn(args, {
@@ -25,27 +27,28 @@ export class ShuruProcess {
 				reject(new Error("shuru: timed out waiting for ready signal (30s)"));
 			}, 30_000);
 
-			this.pending.set("__ready__", {
-				resolve: () => {
-					clearTimeout(timeout);
-					resolve();
-				},
-				reject: (err: Error) => {
-					clearTimeout(timeout);
-					reject(err);
-				},
-			});
+			this.onReady = () => {
+				clearTimeout(timeout);
+				resolve();
+			};
+			this.onReadyError = (err: Error) => {
+				clearTimeout(timeout);
+				reject(err);
+			};
 		});
 	}
 
-	async send(msg: Record<string, unknown>): Promise<StdioResponse> {
+	send(
+		method: string,
+		params: Record<string, unknown>,
+	): Promise<JsonRpcResult> {
 		if (!this.proc) throw new Error("shuru process not started");
 
-		const id = String(++this.idCounter);
-		const line = `${JSON.stringify({ id, ...msg })}\n`;
+		const id = ++this.idCounter;
+		const line = `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
 		const proc = this.proc;
 
-		return new Promise<StdioResponse>((resolve, reject) => {
+		return new Promise<JsonRpcResult>((resolve, reject) => {
 			this.pending.set(id, { resolve, reject });
 			proc.stdin.write(line);
 			proc.stdin.flush();
@@ -88,21 +91,26 @@ export class ShuruProcess {
 
 		const reader = this.proc.stdout.getReader();
 		const decoder = new TextDecoder();
-		let buffer = "";
+		let remainder = "";
 
 		try {
 			while (true) {
 				const { done, value } = await reader.read();
 				if (done) break;
 
-				buffer += decoder.decode(value, { stream: true });
-				const lines = buffer.split("\n");
-				buffer = lines.pop() ?? "";
+				remainder += decoder.decode(value, { stream: true });
+
+				while (true) {
+					const newlineIdx = remainder.indexOf("\n");
+					if (newlineIdx === -1) break;
+					const line = remainder.slice(0, newlineIdx);
+					remainder = remainder.slice(newlineIdx + 1);
 
-				for (const line of lines) {
 					if (!line) continue;
+
 					try {
-						this.dispatch(JSON.parse(line) as StdioResponse);
+						const msg = JSON.parse(line) as JsonRpcResponse;
+						this.dispatch(msg);
 					} catch {
 						// malformed line
 					}
@@ -112,33 +120,38 @@ export class ShuruProcess {
 			// stream closed
 		}
 
+		if (this.onReadyError) {
+			this.onReadyError(new Error("shuru process exited unexpectedly"));
+			this.onReady = null;
+			this.onReadyError = null;
+		}
 		for (const [, req] of this.pending) {
 			req.reject(new Error("shuru process exited unexpectedly"));
 		}
 		this.pending.clear();
 	}
 
-	private dispatch(msg: StdioResponse): void {
-		if (msg.type === "ready") {
-			const req = this.pending.get("__ready__");
-			if (req) {
-				this.pending.delete("__ready__");
-				req.resolve(msg);
+	private dispatch(msg: JsonRpcResponse): void {
+		if ("method" in msg && msg.method === "ready") {
+			if (this.onReady) {
+				this.onReady();
+				this.onReady = null;
+				this.onReadyError = null;
 			}
 			return;
 		}
 
-		const { id } = msg;
-		if (!id) return;
+		if (!("id" in msg) || msg.id == null) return;
+		const id = msg.id as number;
 
 		const req = this.pending.get(id);
 		if (!req) return;
 		this.pending.delete(id);
 
-		if (msg.type === "error") {
-			req.reject(new Error(msg.error));
+		if ("error" in msg) {
+			req.reject(new Error(msg.error.message));
 		} else {
-			req.resolve(msg);
+			req.resolve(msg as JsonRpcResult);
 		}
 	}
 }

package/src/sandbox.ts

@@ -1,6 +1,13 @@
 import { ShuruProcess } from "./process";
 import type { ExecResult, StartOptions } from "./types";
 
+const Method = {
+	EXEC: "exec",
+	READ_FILE: "read_file",
+	WRITE_FILE: "write_file",
+	CHECKPOINT: "checkpoint",
+} as const;
+
 export class Sandbox {
 	private proc: ShuruProcess;
 	private stopped = false;
@@ -20,57 +27,34 @@ export class Sandbox {
 	}
 
 	async exec(command: string): Promise<ExecResult> {
-		const resp = await this.proc.send({
-			type: "exec",
+		const resp = await this.proc.send(Method.EXEC, {
 			argv: ["sh", "-c", command],
 		});
-		if (resp.type !== "exec") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
+		const r = resp.result as {
+			stdout: string;
+			stderr: string;
+			exit_code: number;
+		};
 		return {
-			stdout: resp.stdout,
-			stderr: resp.stderr,
-			exitCode: resp.exit_code,
+			stdout: r.stdout,
+			stderr: r.stderr,
+			exitCode: r.exit_code,
 		};
 	}
 
-	async readFile(path: string): Promise<string> {
-		const resp = await this.proc.send({
-			type: "exec",
-			argv: ["cat", path],
-		});
-		if (resp.type !== "exec") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
-		if (resp.exit_code !== 0) {
-			throw new Error(
-				`readFile failed (exit ${resp.exit_code}): ${resp.stderr}`,
-			);
-		}
-		return resp.stdout;
+	async readFile(path: string): Promise<Uint8Array> {
+		const resp = await this.proc.send(Method.READ_FILE, { path });
+		const r = resp.result as { content: string };
+		return new Uint8Array(Buffer.from(r.content, "base64"));
 	}
 
-	async writeFile(path: string, content: string): Promise<void> {
-		const b64 = btoa(content);
-		const resp = await this.proc.send({
-			type: "exec",
-			argv: ["sh", "-c", `echo '${b64}' | base64 -d > "$1"`, "--", path],
-		});
-		if (resp.type !== "exec") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
-		if (resp.exit_code !== 0) {
-			throw new Error(
-				`writeFile failed (exit ${resp.exit_code}): ${resp.stderr}`,
-			);
-		}
+	async writeFile(path: string, content: Uint8Array | string): Promise<void> {
+		const b64 = Buffer.from(content).toString("base64");
+		await this.proc.send(Method.WRITE_FILE, { path, content: b64 });
 	}
 
 	async checkpoint(name: string): Promise<void> {
-		const resp = await this.proc.send({ type: "checkpoint", name });
-		if (resp.type !== "checkpoint") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
+		await this.proc.send(Method.CHECKPOINT, { name });
 		this.stopped = true;
 		await this.proc.stop();
 	}
@@ -92,6 +76,18 @@ export function buildArgs(bin: string, opts: StartOptions): string[] {
 	if (opts.diskSize) args.push("--disk-size", String(opts.diskSize));
 	if (opts.allowNet) args.push("--allow-net");
 
+	if (opts.secrets) {
+		for (const [name, secret] of Object.entries(opts.secrets)) {
+			args.push("--secret", `${name}=${secret.from}@${secret.hosts.join(",")}`);
+		}
+	}
+
+	if (opts.network?.allow) {
+		for (const host of opts.network.allow) {
+			args.push("--allow-host", host);
+		}
+	}
+
 	if (opts.ports) {
 		for (const p of opts.ports) {
 			args.push("-p", p);

package/src/types.ts

@@ -1,3 +1,15 @@
+export interface SecretConfig {
+	/** Host environment variable containing the real value. */
+	from: string;
+	/** Domains where this secret may be sent (e.g. "api.openai.com"). */
+	hosts: string[];
+}
+
+export interface NetworkConfig {
+	/** Allowed domain patterns. Omit to allow all. */
+	allow?: string[];
+}
+
 export interface StartOptions {
 	from?: string;
 	cpus?: number;
@@ -6,6 +18,8 @@ export interface StartOptions {
 	allowNet?: boolean;
 	ports?: string[];
 	mounts?: Record<string, string>;
+	secrets?: Record<string, SecretConfig>;
+	network?: NetworkConfig;
 	shuruBin?: string;
 }
 
@@ -15,14 +29,26 @@ export interface ExecResult {
 	exitCode: number;
 }
 
-export type StdioResponse =
-	| { type: "ready" }
-	| {
-			type: "exec";
-			id: string;
-			stdout: string;
-			stderr: string;
-			exit_code: number;
-	  }
-	| { type: "checkpoint"; id: string; ok: boolean }
-	| { type: "error"; id: string; error: string };
+// --- JSON-RPC 2.0 wire types (internal) ---
+
+export interface JsonRpcResult {
+	jsonrpc: "2.0";
+	id: number;
+	result: unknown;
+}
+
+export interface JsonRpcError {
+	jsonrpc: "2.0";
+	id: number;
+	error: { code: number; message: string };
+}
+
+export interface JsonRpcNotification {
+	jsonrpc: "2.0";
+	method: string;
+}
+
+export type JsonRpcResponse =
+	| JsonRpcResult
+	| JsonRpcError
+	| JsonRpcNotification;