@themoltnet/sandbox-gondolin 0.1.0 → 0.2.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>;
 
 /**
@@ -109,11 +156,23 @@ 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;
     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 +377,12 @@ 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[];
     /** Structured credential-boundary diagnostics for daemon loggers. */
     onDiagnostic?: (diagnostic: VmDiagnostic) => void;
     /** Abort resume/setup work, closing any live VM owned by resumeVm. */
@@ -355,10 +420,12 @@ 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';
     level: 'info' | 'warning';
     message: string;
     credentialMode: GuestCredentialMode;
+    /** Present only for the value-free broker summary event. */
+    brokeredSecretCount?: number;
 }
 
 export { }

package/dist/index.js

@@ -529,6 +529,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);
@@ -637,9 +805,47 @@ 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 brokeredSecrets = prepareBrokeredHttpSecrets({
+		bindings: config.brokeredSecrets,
+		allowedHosts: [...allowedHosts, ...runtimeAllowedInternalHosts],
+		occupiedGuestEnvNames: [
+			"PATH",
+			"HOME",
+			"NODE_NO_WARNINGS",
+			"NODE_EXTRA_CA_CERTS",
+			"MOLTNET_GUEST_WORKSPACE",
+			...config.forwardEnv ?? [],
+			...Object.keys(creds.agentEnv),
+			...Object.keys(config.sandboxConfig?.env ?? {})
+		]
+	});
+	const brokeredSecretOriginPolicy = createBrokeredHttpSecretOriginPolicy(config.brokeredSecrets ?? []);
+	const { httpHooks, env: secretEnv, secretManager: gondolinSecretManager } = createHttpHooks({
+		allowedHosts,
+		allowedInternalHosts: runtimeAllowedInternalHosts,
+		...Object.keys(brokeredSecrets).length > 0 && {
+			secrets: brokeredSecrets,
+			isRequestAllowed: brokeredSecretOriginPolicy.isRequestAllowed
+		}
+	});
+	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`
 	});
 	const vmAgentDir = `/home/agent/.moltnet/${config.agentName}`;
 	const vmAgentEnv = {};
@@ -678,7 +884,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 +891,8 @@ 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
 	};
 	const resources = config.sandboxConfig?.resources;
 	const workspaceMode = config.workspaceMode ?? "shared_mount";
@@ -788,6 +994,7 @@ async function resumeVm(config) {
 		return {
 			vm,
 			credentials: creds,
+			secretManager,
 			mountPath: config.mountPath,
 			guestWorkspace,
 			agentDir
@@ -864,4 +1071,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_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.2.0",
   "description": "Gondolin microVM sandbox lifecycle for MoltNet runtimes: checkpoint resume, egress policy, VFS shadowing, guest credential boundary, host-brokered secrets",
   "keywords": [
     "moltnet",