@themoltnet/sandbox-gondolin 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -109,6 +109,9 @@ export declare function findMainWorktree(startPath?: string): string;
 /** Commands guaranteed by the base Gondolin snapshot. */
 export declare const GONDOLIN_BASE_EXECUTABLES: readonly string[];
 
+/** Guest directory holding one PID file per projected service. */
+export declare const GUEST_SERVICE_PID_DIR = "/run/moltnet/services";
+
 /**
  * Memory-backed VFS mount used by the daemon to inject task context
  * (#943 slice 1.5). This is a separate top-level mount because Gondolin
@@ -141,6 +144,39 @@ export declare class GuestEnvironmentBoundaryError extends Error {
     constructor(refusedNames: readonly string[]);
 }
 
+/** Declarative, trusted-host guest projection (env, files, services). */
+export declare interface GuestProjectionInput {
+    env?: Record<string, string>;
+    files?: {
+        path: string;
+        content: string | Uint8Array;
+        mode?: number;
+    }[];
+    services?: {
+        id: string;
+        command: readonly string[];
+        env?: Record<string, string>;
+        /** Guest path to wait for before the session starts. */
+        readiness?: {
+            path: string;
+            timeoutMs?: number;
+            required?: boolean;
+        };
+    }[];
+}
+
+/** Lifecycle handle for projected guest services. */
+export declare interface GuestServices {
+    stop(): Promise<void>;
+}
+
+/**
+ * Host origins: hostnames the guest can reach whose responses are produced by
+ * host code inside the proxy (`onRequest` short-circuit). Nothing is listened
+ * on, nothing is forwarded; the sandbox knows only the origin → handler map.
+ */
+declare type HostOriginHandler = (request: Request) => Promise<Response>;
+
 /**
  * Check containment for already-resolved lexical or real paths.
  *
@@ -158,6 +194,8 @@ export declare interface ManagedVm {
     credentials: VmCredentials;
     /** Host-only rotation and revocation handle. It cannot widen destinations. */
     secretManager: BrokeredHttpSecretManager;
+    /** Projected guest services; `stop()` before closing the VM. Always present. */
+    services: GuestServices;
     mountPath: string;
     guestWorkspace: string;
     agentDir: string;
@@ -383,6 +421,19 @@ export declare interface VmConfig {
      * raw values or select host secret-provider coordinates.
      */
     brokeredSecrets?: readonly BrokeredHttpSecretBinding[];
+    /**
+     * Trusted-host origins answered in-process by the proxy. Keys are full
+     * origins (`https://name.moltnet.internal`). Like brokered secrets these are
+     * outside SandboxConfig: a remotely stored profile cannot register one.
+     */
+    hostOrigins?: Record<string, HostOriginHandler>;
+    /**
+     * Trusted-host guest projection: env merged last (after broker
+     * placeholders), files written before the session starts, services run in
+     * the guest for the session's lifetime. Not subject to the profile env
+     * reserved-name guard — the runtime, not the profile, declares it.
+     */
+    guestProjection?: GuestProjectionInput;
     /** Structured credential-boundary diagnostics for daemon loggers. */
     onDiagnostic?: (diagnostic: VmDiagnostic) => void;
     /** Abort resume/setup work, closing any live VM owned by resumeVm. */
@@ -420,12 +471,17 @@ export declare interface VmCredentials {
 }
 
 export declare interface VmDiagnostic {
-    event: 'vm.credentials.mode' | 'vm.credentials.github_key_missing' | 'vm.http_secrets.bound';
+    event: 'vm.credentials.mode' | 'vm.credentials.github_key_missing' | 'vm.http_secrets.bound' | 'vm.host_origins.bound' | 'vm.guest_projection.applied' | 'vm.guest_service.not_ready';
     level: 'info' | 'warning';
     message: string;
     credentialMode: GuestCredentialMode;
     /** Present only for the value-free broker summary event. */
     brokeredSecretCount?: number;
+    /** Present only for the host-origins summary event. */
+    hostOriginCount?: number;
+    /** Present only for the guest-projection summary event. */
+    projectedFileCount?: number;
+    projectedServiceCount?: number;
 }
 
 export { }

package/dist/index.js

@@ -100,6 +100,7 @@ var BASE_ALPINE_PACKAGE_EXECUTABLES = {
 	file: "file",
 	git: "git",
 	jq: "jq",
+	"openssh-keygen": "ssh-keygen",
 	ripgrep: "rg",
 	tar: "tar",
 	xz: "xz"
@@ -292,6 +293,35 @@ function pruneOldSnapshots(maxCached, currentDir) {
 	});
 }
 //#endregion
+//#region src/host-origins.ts
+function hostOriginHostnames(origins) {
+	return Object.keys(origins).map((origin) => new URL(origin).hostname).sort();
+}
+function blocked() {
+	return new Response(JSON.stringify({
+		code: "host_origin_blocked",
+		message: "origin not served"
+	}), {
+		status: 421,
+		headers: { "content-type": "application/json" }
+	});
+}
+/**
+* Serve a registered origin in-process. Fails closed for any request whose
+* hostname belongs to a virtual origin but whose exact origin (scheme, host,
+* port) is not registered: such a request must never fall through to normal
+* outbound proxy forwarding (an SSRF route to a host-controlled name).
+*/
+function createHostOriginsOnRequest(origins) {
+	const virtualHostnames = new Set(hostOriginHostnames(origins));
+	return async (request) => {
+		const url = new URL(request.url);
+		const handler = origins[url.origin];
+		if (handler) return handler(request);
+		if (virtualHostnames.has(url.hostname)) return blocked();
+	};
+}
+//#endregion
 //#region src/vm-manager.ts
 /**
 * Memory-backed VFS mount used by the daemon to inject task context
@@ -314,6 +344,12 @@ function pruneOldSnapshots(maxCached, currentDir) {
 *     investigation and the alternatives we rejected.
 */
 var GUEST_TASK_CONTEXT_MOUNT = "/moltnet-task-context";
+/** Guest directory holding one PID file per projected service. */
+var GUEST_SERVICE_PID_DIR = "/run/moltnet/services";
+var GUEST_SERVICE_ID_RE = /^[a-z][a-z0-9-]{0,62}$/;
+function assertGuestServiceId(id) {
+	if (!GUEST_SERVICE_ID_RE.test(id)) throw new Error(`Invalid guest service id "${id}": expected ${GUEST_SERVICE_ID_RE}`);
+}
 /** @deprecated Use GUEST_TASK_CONTEXT_MOUNT. */
 var GUEST_TASK_SKILLS_MOUNT = GUEST_TASK_CONTEXT_MOUNT;
 function resolveVfsShadowConfig(config) {
@@ -752,6 +788,10 @@ function assertInternalHostsDoNotOverlapProtectedHosts(internalHosts, protectedH
 * surface immediately rather than fall through to cryptic agent
 * errors later.
 */
+/** Single-quote a POSIX shell argument (paths/ids are pre-validated). */
+function shellQuote(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
 async function vmRun(vm, label, command, signal) {
 	const wrapped = `set -eu\nset -o pipefail\n${command}`;
 	throwIfAborted(signal, `resume step "${label}"`);
@@ -806,9 +846,14 @@ async function resumeVm(config) {
 	])];
 	assertInternalHostsDoNotOverlapProtectedHosts(runtimeAllowedInternalHosts, protectedExternalHosts);
 	const allowedHosts = [...new Set([...protectedExternalHosts, ...runtimeAllowedHosts])];
+	const hostOrigins = config.hostOrigins ?? {};
+	const hostOriginHosts = hostOriginHostnames(hostOrigins);
+	assertInternalHostsDoNotOverlapProtectedHosts(hostOriginHosts, protectedExternalHosts);
+	const allowedInternalHosts = [...new Set([...runtimeAllowedInternalHosts, ...hostOriginHosts])];
+	const projectedEnv = config.guestProjection?.env ?? {};
 	const brokeredSecrets = prepareBrokeredHttpSecrets({
 		bindings: config.brokeredSecrets,
-		allowedHosts: [...allowedHosts, ...runtimeAllowedInternalHosts],
+		allowedHosts: [...allowedHosts, ...allowedInternalHosts],
 		occupiedGuestEnvNames: [
 			"PATH",
 			"HOME",
@@ -817,17 +862,19 @@ async function resumeVm(config) {
 			"MOLTNET_GUEST_WORKSPACE",
 			...config.forwardEnv ?? [],
 			...Object.keys(creds.agentEnv),
-			...Object.keys(config.sandboxConfig?.env ?? {})
+			...Object.keys(config.sandboxConfig?.env ?? {}),
+			...Object.keys(projectedEnv)
 		]
 	});
 	const brokeredSecretOriginPolicy = createBrokeredHttpSecretOriginPolicy(config.brokeredSecrets ?? []);
 	const { httpHooks, env: secretEnv, secretManager: gondolinSecretManager } = createHttpHooks({
 		allowedHosts,
-		allowedInternalHosts: runtimeAllowedInternalHosts,
+		allowedInternalHosts,
 		...Object.keys(brokeredSecrets).length > 0 && {
 			secrets: brokeredSecrets,
 			isRequestAllowed: brokeredSecretOriginPolicy.isRequestAllowed
-		}
+		},
+		...hostOriginHosts.length > 0 && { onRequest: createHostOriginsOnRequest(hostOrigins) }
 	});
 	const secretManager = Object.freeze({
 		rotateSecret(guestEnv, value) {
@@ -847,6 +894,13 @@ async function resumeVm(config) {
 		brokeredSecretCount,
 		message: `Bound ${brokeredSecretCount} HTTP secret placeholder${brokeredSecretCount === 1 ? "" : "s"} to the host proxy`
 	});
+	if (hostOriginHosts.length > 0) config.onDiagnostic?.({
+		event: "vm.host_origins.bound",
+		level: "info",
+		credentialMode: guestCredentialMode,
+		hostOriginCount: hostOriginHosts.length,
+		message: `Bound ${hostOriginHosts.length} host origin${hostOriginHosts.length === 1 ? "" : "s"} to the host proxy`
+	});
 	const vmAgentDir = `/home/agent/.moltnet/${config.agentName}`;
 	const vmAgentEnv = {};
 	for (const [k, v] of Object.entries(creds.agentEnv)) {
@@ -892,7 +946,8 @@ async function resumeVm(config) {
 		NODE_EXTRA_CA_CERTS: "/etc/ssl/certs/ca-certificates.crt",
 		...envOverrides,
 		MOLTNET_GUEST_WORKSPACE: guestWorkspace,
-		...secretEnv
+		...secretEnv,
+		...projectedEnv
 	};
 	const resources = config.sandboxConfig?.resources;
 	const workspaceMode = config.workspaceMode ?? "shared_mount";
@@ -915,6 +970,27 @@ async function resumeVm(config) {
 			process.stderr.write(`[vm] aborted resume late vm.close() failed: ${message}\n`);
 		}
 	});
+	const servicesAbort = new AbortController();
+	const serviceHandles = [];
+	const serviceIds = [];
+	const services = { async stop() {
+		if (serviceIds.length > 0) {
+			const pidFiles = serviceIds.map((id) => `${GUEST_SERVICE_PID_DIR}/${id}.pid`).join(" ");
+			try {
+				await vm.exec([
+					"sh",
+					"-c",
+					`for f in ${pidFiles}; do [ -f "$f" ] || continue; pid=$(cat "$f"); kill -TERM -- "-\$pid" 2>/dev/null || kill -TERM "\$pid" 2>/dev/null || true; done; sleep 0.2; for f in ${pidFiles}; do [ -f "$f" ] || continue; pid=$(cat "$f"); kill -KILL -- "-\$pid" 2>/dev/null || kill -KILL "\$pid" 2>/dev/null || true; rm -f "\$f"; done`
+				], {
+					stdout: "ignore",
+					stderr: "ignore"
+				});
+			} catch {}
+			serviceIds.length = 0;
+		}
+		servicesAbort.abort();
+		await Promise.allSettled(serviceHandles);
+	} };
 	try {
 		await vmRun(vm, "TLS certificates", `
     cp /etc/gondolin/mitm/ca.crt /usr/local/share/ca-certificates/gondolin-mitm.crt
@@ -950,8 +1026,14 @@ async function resumeVm(config) {
 		const vmSshDir = `${vmAgentDir}/ssh`;
 		const hasAgentFiles = guestCredentialMode === "guest-config";
 		const providerAuthDir = config.providerAuth ? path.posix.dirname(config.providerAuth.guestPath) : null;
-		const guestDirs = [...hasAgentFiles ? [`${vmAgentDir}/ssh`] : [], ...providerAuthDir ? [providerAuthDir] : []];
-		if (guestDirs.length > 0) await vm.exec(`mkdir -p ${guestDirs.join(" ")}`, { signal: config.signal });
+		const projectedFiles = config.guestProjection?.files ?? [];
+		const projectedDirs = [...new Set(projectedFiles.map((file) => path.posix.dirname(file.path)))];
+		const guestDirs = [
+			...hasAgentFiles ? [`${vmAgentDir}/ssh`] : [],
+			...providerAuthDir ? [providerAuthDir] : [],
+			...projectedDirs
+		];
+		if (guestDirs.length > 0) await vmRun(vm, "create guest directories", `mkdir -p ${guestDirs.map(shellQuote).join(" ")}`, config.signal);
 		if (creds.providerAuthJson !== null && config.providerAuth) await vm.fs.writeFile(config.providerAuth.guestPath, creds.providerAuthJson, {
 			mode: 384,
 			signal: config.signal
@@ -990,16 +1072,94 @@ async function resumeVm(config) {
 				signal: config.signal
 			});
 		}
-		await vm.exec(hasAgentFiles ? "chown -R agent:agent /home/agent/.pi /home/agent/.moltnet" : "chown -R agent:agent /home/agent/.pi", { signal: config.signal });
+		for (const file of projectedFiles) {
+			await vm.fs.writeFile(file.path, file.content, {
+				mode: file.mode ?? 420,
+				signal: config.signal
+			});
+			if (file.mode !== void 0) await vmRun(vm, `chmod projected file ${file.path}`, `chmod ${file.mode.toString(8)} ${shellQuote(file.path)}`, config.signal);
+		}
+		await vmRun(vm, "chown guest directories", `set -e; for d in ${[
+			"/home/agent/.pi",
+			...hasAgentFiles ? ["/home/agent/.moltnet"] : [],
+			...projectedDirs.filter((dir) => dir.startsWith("/home/agent/"))
+		].map(shellQuote).join(" ")}; do if [ -e "$d" ]; then chown -R agent:agent "$d"; fi; done`, config.signal);
+		const projectedServices = config.guestProjection?.services ?? [];
+		if (projectedServices.length > 0) await vmRun(vm, "create service pid directory", `mkdir -p ${GUEST_SERVICE_PID_DIR}`, config.signal);
+		for (const service of projectedServices) {
+			assertGuestServiceId(service.id);
+			const handle = vm.exec([
+				"setsid",
+				"sh",
+				"-c",
+				`echo $$ > ${GUEST_SERVICE_PID_DIR}/${service.id}.pid && exec "$@"`,
+				"moltnet-service",
+				...service.command
+			], {
+				stdout: "ignore",
+				stderr: "ignore",
+				...service.env && { env: service.env },
+				signal: servicesAbort.signal
+			});
+			serviceHandles.push(Promise.resolve(handle).catch(() => void 0));
+			serviceIds.push(service.id);
+		}
+		async function awaitServiceReady(service) {
+			if (!service.readiness) return;
+			const deadline = Date.now() + (service.readiness.timeoutMs ?? 1e4);
+			const pidFile = `${GUEST_SERVICE_PID_DIR}/${service.id}.pid`;
+			let ready = false;
+			while (Date.now() < deadline) {
+				throwIfAborted(config.signal, `service "${service.id}" readiness`);
+				if ((await vm.exec([
+					"sh",
+					"-c",
+					"[ -e \"$1\" ] && [ -r \"$2\" ] && kill -0 \"$(cat \"$2\" 2>/dev/null)\" 2>/dev/null",
+					"moltnet-readiness",
+					service.readiness.path,
+					pidFile
+				], {
+					stdout: "ignore",
+					stderr: "ignore",
+					signal: config.signal
+				})).exitCode === 0) {
+					ready = true;
+					break;
+				}
+				await new Promise((resolve) => {
+					setTimeout(resolve, 200);
+				});
+			}
+			if (!ready) {
+				if (service.readiness.required) throw new Error(`Projected guest service "${service.id}" did not become ready: ${service.readiness.path} absent or its process exited`);
+				config.onDiagnostic?.({
+					event: "vm.guest_service.not_ready",
+					level: "warning",
+					credentialMode: guestCredentialMode,
+					message: `Projected guest service "${service.id}" did not become ready (${service.readiness.path} absent or its process exited); continuing without it`
+				});
+			}
+		}
+		await Promise.all(projectedServices.map((service) => awaitServiceReady(service)));
+		if (projectedFiles.length > 0 || projectedServices.length > 0) config.onDiagnostic?.({
+			event: "vm.guest_projection.applied",
+			level: "info",
+			credentialMode: guestCredentialMode,
+			projectedFileCount: projectedFiles.length,
+			projectedServiceCount: projectedServices.length,
+			message: `Applied guest projection: ${projectedFiles.length} file(s), ${projectedServices.length} service(s)`
+		});
 		return {
 			vm,
 			credentials: creds,
 			secretManager,
+			services,
 			mountPath: config.mountPath,
 			guestWorkspace,
 			agentDir
 		};
 	} catch (err) {
+		servicesAbort.abort();
 		try {
 			await vm.close();
 		} catch (closeErr) {
@@ -1071,4 +1231,4 @@ function rewriteMoltnetJsonPaths(moltnetJson, vmAgentDir, vmSshDir, githubAppPem
 	return JSON.stringify(config);
 }
 //#endregion
-export { AutoParentMemoryProvider, BrokeredHttpSecretBoundaryError, GONDOLIN_BASE_EXECUTABLES, GUEST_TASK_CONTEXT_MOUNT, GUEST_TASK_SKILLS_MOUNT, GuestEnvironmentBoundaryError, abortableResource, activateAgentEnv, assertGuestEnvironmentBoundary, assertHostAuthenticatedGuestEnvironment, canonicalizeBrokeredHttpSecretDescriptor, delay, ensureSnapshot, findMainWorktree, isResolvedPathInsideRoot, loadCredentials, prepareBrokeredHttpSecrets, resolveVfsShadowConfig, resolveVmAgentDir, resumeVm, rewriteGitconfigPaths, rewriteMoltnetJsonPaths, shouldRunResumeCommand, shouldShadowNodeModulesPath, throwIfAborted };
+export { AutoParentMemoryProvider, BrokeredHttpSecretBoundaryError, GONDOLIN_BASE_EXECUTABLES, GUEST_SERVICE_PID_DIR, GUEST_TASK_CONTEXT_MOUNT, GUEST_TASK_SKILLS_MOUNT, GuestEnvironmentBoundaryError, abortableResource, activateAgentEnv, assertGuestEnvironmentBoundary, assertHostAuthenticatedGuestEnvironment, canonicalizeBrokeredHttpSecretDescriptor, delay, ensureSnapshot, findMainWorktree, isResolvedPathInsideRoot, loadCredentials, prepareBrokeredHttpSecrets, resolveVfsShadowConfig, resolveVmAgentDir, resumeVm, rewriteGitconfigPaths, rewriteMoltnetJsonPaths, shouldRunResumeCommand, shouldShadowNodeModulesPath, throwIfAborted };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/sandbox-gondolin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Gondolin microVM sandbox lifecycle for MoltNet runtimes: checkpoint resume, egress policy, VFS shadowing, guest credential boundary, host-brokered secrets",
   "keywords": [
     "moltnet",