@themoltnet/sandbox-gondolin 0.1.0 → 0.3.0

package/README.md

@@ -20,7 +20,7 @@ implementation can be added beside it without going through Pi.
   (`assertGuestEnvironmentBoundary`).
 - `VmConfig.brokeredSecrets` — host-brokered secrets: the guest sees a
   placeholder, Gondolin's `SecretManager` substitutes the value only in
-  requests to the declared host patterns.
+  requests to the declared protocol, host patterns, and ports.
 - `ensureSnapshot` — build and cache the base checkpoint.
 - Small helpers: `findMainWorktree`, `isResolvedPathInsideRoot`,
   `abortableResource` / `throwIfAborted`.
@@ -36,11 +36,76 @@ implementation can be added beside it without going through Pi.
 
 ## Known boundary facts
 
-- Egress policy is hostname-granular: no scheme or port narrowing.
+- Network egress policy is hostname-granular. Brokered credentials add a
+  separately attested protocol and port boundary.
 - Guest `127.0.0.1` / `localhost` never leave the VM; names are resolved on
   the host side by the proxy.
 - Exec abort only drops the host session; a caller that needs the guest
   process gone must kill it in the guest.
 
+## Brokered HTTP secrets
+
+`brokeredSecrets` is trusted-host input to `resumeVm`; it is deliberately not
+part of `SandboxConfig`. A remotely stored runtime profile may constrain
+network access and refer to a logical credential requirement, but it must not
+contain a value or choose a host secret-provider coordinate.
+
+```ts
+const managed = await resumeVm({
+  checkpointPath,
+  agentName: 'worker',
+  guestCredentialMode: 'host-authenticated',
+  mountPath: workspace,
+  sandboxConfig: {
+    network: { allowedHosts: ['api.example.com'] },
+  },
+  brokeredSecrets: [
+    {
+      id: 'example-api',
+      guestEnv: 'EXAMPLE_API_TOKEN',
+      hosts: ['api.example.com'],
+      value: await trustedHostSecretProvider.get('example-api'),
+    },
+  ],
+});
+```
+
+Inside the VM, `$EXAMPLE_API_TOKEN` is a random Gondolin placeholder. A normal
+guest command can use it in an HTTP header:
+
+```bash
+curl -fsS \
+  -H "Authorization: Bearer $EXAMPLE_API_TOKEN" \
+  https://api.example.com/v1/items
+```
+
+The host proxy substitutes the real value only for the declared origin. HTTPS
+on port 443 is the default. Plain HTTP requires an explicit `protocol: 'http'`
+and should be limited to an exact port for a controlled local fixture.
+Preflight fails before VM resume when the binding is missing, an environment
+name collides with another guest source, or a credential host is outside the
+effective network policy. Values are not substituted in request bodies or URL
+queries. Gondolin also decodes, substitutes, and re-encodes HTTP Basic
+authorization, covering the password encoding used by HTTPS Git credential
+helpers; OAuth client secrets sent in form bodies remain host-only.
+
+Rotation and revocation do not require exposing or changing the guest
+placeholder:
+
+```ts
+managed.secretManager.rotateSecret('EXAMPLE_API_TOKEN', rotated);
+managed.secretManager.revokeSecret('EXAMPLE_API_TOKEN');
+```
+
+Keep signing keys, GitHub App private keys, SSH keys, and other non-HTTP
+credentials out of this channel. They require narrow host capabilities rather
+than bearer-secret substitution.
+
+The portable boundary is the sequence _requirement → trusted local binding →
+resolved delivery_. A Docker sandbox can implement the same sequence with its
+native secret broker; hostname rewriting, placeholder lifecycle, and other
+provider behavior remain adapter-specific, while the attested protocol, host,
+and port boundary must remain equivalent.
+
 Live tests (`vm-manager.integration.test.ts`) boot real VMs and run only with
 `MOLTNET_PI_VM_INTEGRATION=1`; CI runs them in the agent-daemon Core lane.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { MemoryProvider } from '@earendil-works/gondolin';
+import { SecretDefinition } from '@earendil-works/gondolin';
 import { VirtualFileHandle } from '@earendil-works/gondolin';
 import { VM } from '@earendil-works/gondolin';
 
@@ -38,6 +39,52 @@ export declare class AutoParentMemoryProvider extends MemoryProvider {
     openSync(pathname: string, flags: string, mode?: number): VirtualFileHandle;
 }
 
+/** Per-attempt host binding. The value must never be persisted or evidenced. */
+export declare interface BrokeredHttpSecretBinding extends BrokeredHttpSecretDescriptor {
+    /** Resolved only by trusted host code immediately before VM resume. */
+    value?: string;
+}
+
+export declare class BrokeredHttpSecretBoundaryError extends Error {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+
+/**
+ * Value-free declaration of one HTTP credential delivered by the Gondolin
+ * host proxy. This is an adapter contract, not a persisted runtime-profile
+ * schema: trusted host code resolves the matching value for each attempt.
+ */
+export declare interface BrokeredHttpSecretDescriptor {
+    /** Stable, evidence-safe logical requirement id. */
+    id: string;
+    /** Guest variable that receives an opaque Gondolin placeholder. */
+    guestEnv: string;
+    /** Hostname patterns to which the proxy may send the resolved value. */
+    hosts: readonly string[];
+    /** Attested upstream transport. Defaults to HTTPS. */
+    protocol?: 'https' | 'http';
+    /** Attested upstream ports. Defaults to 443 for HTTPS and 80 for HTTP. */
+    ports?: readonly number[];
+    /** Missing values fail preflight unless explicitly optional. */
+    required?: boolean;
+}
+
+/** Host-only capabilities that cannot widen a validated destination grant. */
+export declare interface BrokeredHttpSecretManager {
+    /** Rotate a configured secret value without changing its destination set. */
+    rotateSecret(guestEnv: string, value: string): void;
+    /** Revoke a configured secret for the remainder of this VM lifetime. */
+    revokeSecret(guestEnv: string): void;
+}
+
+/**
+ * Canonicalize and validate the value-free portion of a brokered binding.
+ * Runtime attestation and Gondolin enforcement both consume this function so
+ * the evidenced destination set cannot drift from the enforced one.
+ */
+export declare function canonicalizeBrokeredHttpSecretDescriptor(descriptor: BrokeredHttpSecretDescriptor): Required<BrokeredHttpSecretDescriptor>;
+
 export declare function delay(ms: number, signal: AbortSignal | undefined, label: string): Promise<void>;
 
 /**
@@ -62,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
@@ -94,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.
  *
@@ -109,11 +192,25 @@ export declare function loadCredentials(agentDir: string, mode?: GuestCredential
 export declare interface ManagedVm {
     vm: VM;
     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;
 }
 
+/**
+ * Validate value-free descriptors, host-local bindings, environment
+ * collisions, and destination coverage before Gondolin creates any VM.
+ */
+export declare function prepareBrokeredHttpSecrets(options: {
+    bindings?: readonly BrokeredHttpSecretBinding[];
+    allowedHosts: readonly string[];
+    occupiedGuestEnvNames?: readonly string[];
+}): Record<string, SecretDefinition>;
+
 export declare interface ProviderAuthSource {
     /** Read the auth blob from the host, or return null when absent. */
     load(): string | null;
@@ -318,6 +415,25 @@ export declare interface VmConfig {
      * into the guest without storing secret values in the profile.
      */
     forwardEnv?: string[];
+    /**
+     * Trusted-host, per-attempt HTTP secret bindings. These are deliberately
+     * outside SandboxConfig so remotely stored runtime profiles cannot carry
+     * 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. */
@@ -355,10 +471,17 @@ export declare interface VmCredentials {
 }
 
 export declare interface VmDiagnostic {
-    event: 'vm.credentials.mode' | 'vm.credentials.github_key_missing';
+    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) {
@@ -529,6 +565,174 @@ var GuestEnvironmentBoundaryError = class extends Error {
 		this.name = "GuestEnvironmentBoundaryError";
 	}
 };
+var BrokeredHttpSecretBoundaryError = class extends Error {
+	constructor(issues) {
+		super("Brokered HTTP secret boundary refused the resolved bindings: " + issues.join("; "));
+		this.issues = issues;
+		this.name = "BrokeredHttpSecretBoundaryError";
+	}
+};
+var BROKERED_SECRET_ID_REGEXP = /^[a-z][a-z0-9._-]{0,63}$/;
+var GUEST_ENV_NAME_REGEXP = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var OBJECT_META_PROPERTY_NAMES = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function normalizeHostPattern(pattern) {
+	return pattern.trim().toLowerCase();
+}
+function isValidHostPattern(pattern) {
+	return pattern !== "" && !pattern.includes("://") && !pattern.includes("/") && !pattern.includes(":") && !/\s/.test(pattern);
+}
+/**
+* Canonicalize and validate the value-free portion of a brokered binding.
+* Runtime attestation and Gondolin enforcement both consume this function so
+* the evidenced destination set cannot drift from the enforced one.
+*/
+function canonicalizeBrokeredHttpSecretDescriptor(descriptor) {
+	const issues = [];
+	const id = descriptor.id.trim();
+	const guestEnv = descriptor.guestEnv.trim();
+	const hosts = [...new Set(descriptor.hosts.map(normalizeHostPattern))].sort();
+	const protocolInput = descriptor.protocol ?? "https";
+	const protocol = protocolInput === "http" ? "http" : "https";
+	const ports = [...new Set(descriptor.ports ?? [protocol === "https" ? 443 : 80])].sort((left, right) => left - right);
+	if (!BROKERED_SECRET_ID_REGEXP.test(id)) issues.push(`invalid requirement id "${id || "<empty>"}"`);
+	if (!GUEST_ENV_NAME_REGEXP.test(guestEnv)) issues.push(`requirement "${id}" has invalid guest env "${guestEnv}"`);
+	else if (isReservedGuestEnvironmentName(guestEnv) || OBJECT_META_PROPERTY_NAMES.has(guestEnv)) issues.push(`requirement "${id}" uses reserved guest env "${guestEnv}"`);
+	if (hosts.length === 0) issues.push(`requirement "${id}" has no destination hosts`);
+	for (const host of hosts) if (!isValidHostPattern(host)) issues.push(`requirement "${id}" has invalid host pattern "${host}"`);
+	if (protocolInput !== "https" && protocolInput !== "http") issues.push(`requirement "${id}" has invalid protocol "${String(protocolInput)}"`);
+	if (ports.length === 0) issues.push(`requirement "${id}" has no destination ports`);
+	for (const port of ports) if (!Number.isInteger(port) || port < 1 || port > 65535) issues.push(`requirement "${id}" has invalid port "${port}"`);
+	if (issues.length > 0) throw new BrokeredHttpSecretBoundaryError(issues);
+	return Object.freeze({
+		id,
+		guestEnv,
+		hosts: Object.freeze(hosts),
+		protocol,
+		ports: Object.freeze(ports),
+		required: descriptor.required !== false
+	});
+}
+function hostMatchesPattern(hostname, pattern) {
+	const expression = pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+	return new RegExp(`^${expression}$`, "i").test(hostname);
+}
+/**
+* Conservative subset check for Gondolin hostname globs. Exact secret hosts
+* may sit below a broader network wildcard. A wildcard secret destination must
+* be repeated exactly (or covered by `*`) so a credential grant cannot widen
+* through an ambiguous glob comparison.
+*/
+function networkPatternCoversSecretPattern(networkPattern, secretPattern) {
+	if (networkPattern === "*") return true;
+	if (secretPattern.includes("*")) return networkPattern === secretPattern;
+	return hostMatchesPattern(secretPattern, networkPattern);
+}
+/**
+* Validate value-free descriptors, host-local bindings, environment
+* collisions, and destination coverage before Gondolin creates any VM.
+*/
+function prepareBrokeredHttpSecrets(options) {
+	const issues = [];
+	const ids = /* @__PURE__ */ new Set();
+	const guestEnvNames = /* @__PURE__ */ new Set();
+	const occupiedGuestEnvNames = new Set(options.occupiedGuestEnvNames ?? []);
+	const allowedHosts = [...new Set(options.allowedHosts.map(normalizeHostPattern))];
+	const secrets = Object.create(null);
+	for (const binding of options.bindings ?? []) {
+		let descriptor;
+		try {
+			descriptor = canonicalizeBrokeredHttpSecretDescriptor(binding);
+		} catch (error) {
+			if (error instanceof BrokeredHttpSecretBoundaryError) {
+				issues.push(...error.issues);
+				continue;
+			}
+			throw error;
+		}
+		const { id, guestEnv, hosts } = descriptor;
+		if (ids.has(id)) issues.push(`duplicate requirement id "${id}"`);
+		ids.add(id);
+		if (guestEnvNames.has(guestEnv)) issues.push(`duplicate guest env "${guestEnv}"`);
+		else if (occupiedGuestEnvNames.has(guestEnv)) issues.push(`guest env "${guestEnv}" is already supplied by another source`);
+		guestEnvNames.add(guestEnv);
+		for (const host of hosts) if (!allowedHosts.some((allowedHost) => networkPatternCoversSecretPattern(allowedHost, host))) issues.push(`requirement "${id}" host "${host}" is outside the effective network policy`);
+		const value = binding.value;
+		if (value === void 0 || value === "") {
+			if (descriptor.required) issues.push(`required binding "${id}" has no resolved value`);
+			continue;
+		}
+		secrets[guestEnv] = {
+			hosts: [...hosts],
+			value
+		};
+	}
+	if (issues.length > 0) throw new BrokeredHttpSecretBoundaryError(issues);
+	return secrets;
+}
+function decodeBasicAuthorization(value) {
+	const match = /^Basic\s+([^\s]+)$/i.exec(value);
+	if (!match) return void 0;
+	try {
+		return Buffer.from(match[1], "base64").toString("utf8");
+	} catch {
+		return;
+	}
+}
+function headersContainSecretValue(headers, value) {
+	if (value === "") return false;
+	for (const [name, headerValue] of headers.entries()) {
+		if (headerValue.includes(value)) return true;
+		if (/^(authorization|proxy-authorization)$/i.test(name) && decodeBasicAuthorization(headerValue)?.includes(value)) return true;
+	}
+	return false;
+}
+function createBrokeredHttpSecretOriginPolicy(bindings) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const binding of bindings) {
+		if (binding.value === void 0 || binding.value === "") continue;
+		const descriptor = canonicalizeBrokeredHttpSecretDescriptor(binding);
+		entries.set(descriptor.guestEnv, {
+			guestEnv: descriptor.guestEnv,
+			hosts: descriptor.hosts,
+			protocol: descriptor.protocol,
+			ports: descriptor.ports,
+			value: binding.value,
+			deleted: false
+		});
+	}
+	return {
+		isRequestAllowed(request) {
+			let url;
+			try {
+				url = new URL(request.url);
+			} catch {
+				return false;
+			}
+			const protocol = url.protocol.slice(0, -1);
+			const port = url.port ? Number(url.port) : protocol === "https" ? 443 : 80;
+			for (const entry of entries.values()) {
+				if (entry.deleted || !headersContainSecretValue(request.headers, entry.value)) continue;
+				if (protocol !== entry.protocol || !entry.ports.includes(port) || !entry.hosts.some((host) => hostMatchesPattern(url.hostname, host))) return false;
+			}
+			return true;
+		},
+		rotateSecret(guestEnv, value) {
+			const entry = entries.get(guestEnv);
+			if (!entry) throw new Error(`unknown brokered secret: ${guestEnv}`);
+			if (entry.deleted) throw new Error(`brokered secret revoked: ${guestEnv}`);
+			entry.value = value;
+		},
+		revokeSecret(guestEnv) {
+			const entry = entries.get(guestEnv);
+			if (!entry) throw new Error(`unknown brokered secret: ${guestEnv}`);
+			entry.deleted = true;
+		}
+	};
+}
 function assertGuestEnvironmentBoundary(options) {
 	const refusedForwardEnv = (options.forwardEnv ?? []).filter((name) => isReservedGuestEnvironmentName(name) || options.guestCredentialMode === "host-authenticated" && !HOST_AUTHENTICATED_GUEST_ENV_ALLOWLIST.has(name));
 	const refusedSandboxEnv = Object.keys(options.sandboxEnv ?? {}).filter(isReservedGuestEnvironmentName);
@@ -584,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}"`);
@@ -637,9 +845,61 @@ async function resumeVm(config) {
 		...config.extraAllowedHosts ?? []
 	])];
 	assertInternalHostsDoNotOverlapProtectedHosts(runtimeAllowedInternalHosts, protectedExternalHosts);
-	const { httpHooks, env: secretEnv } = createHttpHooks({
-		allowedHosts: [...new Set([...protectedExternalHosts, ...runtimeAllowedHosts])],
-		allowedInternalHosts: runtimeAllowedInternalHosts
+	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, ...allowedInternalHosts],
+		occupiedGuestEnvNames: [
+			"PATH",
+			"HOME",
+			"NODE_NO_WARNINGS",
+			"NODE_EXTRA_CA_CERTS",
+			"MOLTNET_GUEST_WORKSPACE",
+			...config.forwardEnv ?? [],
+			...Object.keys(creds.agentEnv),
+			...Object.keys(config.sandboxConfig?.env ?? {}),
+			...Object.keys(projectedEnv)
+		]
+	});
+	const brokeredSecretOriginPolicy = createBrokeredHttpSecretOriginPolicy(config.brokeredSecrets ?? []);
+	const { httpHooks, env: secretEnv, secretManager: gondolinSecretManager } = createHttpHooks({
+		allowedHosts,
+		allowedInternalHosts,
+		...Object.keys(brokeredSecrets).length > 0 && {
+			secrets: brokeredSecrets,
+			isRequestAllowed: brokeredSecretOriginPolicy.isRequestAllowed
+		},
+		...hostOriginHosts.length > 0 && { onRequest: createHostOriginsOnRequest(hostOrigins) }
+	});
+	const secretManager = Object.freeze({
+		rotateSecret(guestEnv, value) {
+			gondolinSecretManager.updateSecret(guestEnv, { value });
+			brokeredSecretOriginPolicy.rotateSecret(guestEnv, value);
+		},
+		revokeSecret(guestEnv) {
+			gondolinSecretManager.deleteSecret(guestEnv);
+			brokeredSecretOriginPolicy.revokeSecret(guestEnv);
+		}
+	});
+	const brokeredSecretCount = Object.keys(brokeredSecrets).length;
+	if (brokeredSecretCount > 0) config.onDiagnostic?.({
+		event: "vm.http_secrets.bound",
+		level: "info",
+		credentialMode: guestCredentialMode,
+		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 = {};
@@ -678,7 +938,6 @@ async function resumeVm(config) {
 	}
 	const envOverrides = config.sandboxConfig?.env ?? {};
 	const vmEnv = {
-		...secretEnv,
 		...vmAgentEnv,
 		...forwardedEnv,
 		PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/lib/go/bin",
@@ -686,7 +945,9 @@ async function resumeVm(config) {
 		NODE_NO_WARNINGS: "1",
 		NODE_EXTRA_CA_CERTS: "/etc/ssl/certs/ca-certificates.crt",
 		...envOverrides,
-		MOLTNET_GUEST_WORKSPACE: guestWorkspace
+		MOLTNET_GUEST_WORKSPACE: guestWorkspace,
+		...secretEnv,
+		...projectedEnv
 	};
 	const resources = config.sandboxConfig?.resources;
 	const workspaceMode = config.workspaceMode ?? "shared_mount";
@@ -709,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
@@ -744,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
@@ -784,15 +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) {
@@ -864,4 +1231,4 @@ function rewriteMoltnetJsonPaths(moltnetJson, vmAgentDir, vmSshDir, githubAppPem
 	return JSON.stringify(config);
 }
 //#endregion
-export { AutoParentMemoryProvider, GONDOLIN_BASE_EXECUTABLES, GUEST_TASK_CONTEXT_MOUNT, GUEST_TASK_SKILLS_MOUNT, GuestEnvironmentBoundaryError, abortableResource, activateAgentEnv, assertGuestEnvironmentBoundary, assertHostAuthenticatedGuestEnvironment, delay, ensureSnapshot, findMainWorktree, isResolvedPathInsideRoot, loadCredentials, 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.1.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",