@themoltnet/sandbox-gondolin 0.4.0 → 0.5.0

package/README.md

@@ -87,6 +87,18 @@ 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.
 
+`vm.network.policy_bound` reports the complete hostname inputs passed to
+Gondolin; it is configuration evidence, not independent proof of Gondolin's
+resolved state. Brokered requests emit `vm.network.origin_checked` for
+canonical protocol/hostname/port decisions at request and IP phases. Denials
+remain available as `vm.network.origin_denied`. All diagnostics are
+value-free.
+
+Gondolin 0.12 pins the actual upstream connection to the policy-checked IP only
+when using its default fetch. This package therefore does not expose a custom
+fetch or fixture-routing seam: doing so would retain a preflight IP check while
+losing connect-time pinning and reopening a DNS-rebinding window.
+
 Rotation and revocation do not require exposing or changing the guest
 placeholder:
 

package/dist/index.d.ts

@@ -91,8 +91,9 @@ export declare function canonicalizeBrokeredHttpSecretDescriptor(descriptor: Bro
  * enforce the descriptor protocol and port before request or IP dispatch.
  */
 export declare function createBrokeredHttpNetworkOriginPolicy(bindings: readonly BrokeredHttpSecretDescriptor[], options?: {
-    onDenied?: (denial: RequestOrigin & {
+    onDecision?: (decision: RequestOrigin & {
         phase: 'request' | 'ip';
+        allowed: boolean;
     }) => void;
 }): {
     isRequestAllowed: (request: Request) => boolean;
@@ -461,7 +462,7 @@ export declare interface VmCredentials {
 }
 
 export declare interface VmDiagnostic {
-    event: 'vm.credentials.mode' | 'vm.http_secrets.bound' | 'vm.host_origins.bound' | 'vm.guest_projection.applied' | 'vm.guest_service.not_ready' | 'vm.network.origin_denied';
+    event: 'vm.credentials.mode' | 'vm.http_secrets.bound' | 'vm.host_origins.bound' | 'vm.guest_projection.applied' | 'vm.guest_service.not_ready' | 'vm.network.policy_bound' | 'vm.network.origin_checked' | 'vm.network.origin_denied';
     level: 'info' | 'warning';
     message: string;
     /** Present only for the value-free broker summary event. */
@@ -471,12 +472,18 @@ export declare interface VmDiagnostic {
     /** Present only for the guest-projection summary event. */
     projectedFileCount?: number;
     projectedServiceCount?: number;
-    /** Present only for an exact-origin denial event. */
+    /** Complete value-free hostname inputs passed to Gondolin. */
+    hostnamePolicy?: {
+        allowedHosts: readonly string[];
+        allowedInternalHosts: readonly string[];
+    };
+    /** Canonical, value-free decision for an origin check or denial. */
     origin?: {
         hostname: string;
         protocol: string;
         port: number;
         phase: 'request' | 'ip';
+        allowed: boolean;
     };
 }
 

package/dist/index.js

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
 import { MemoryProvider, RealFSProvider, ShadowProvider, VM, VmCheckpoint, createHttpHooks, createShadowPathPredicate, ensureImageSelector, isWriteFlag, loadGuestAssets } from "@earendil-works/gondolin";
 import { isIP } from "node:net";
+import { domainToASCII } from "node:url";
 //#region src/abort-utils.ts
 function throwIfAborted(signal, label) {
 	if (!signal?.aborted) return;
@@ -425,6 +426,76 @@ function pruneOldSnapshots(maxCached, currentDir) {
 	});
 }
 //#endregion
+//#region src/canonical-host.ts
+var DECIMAL_IPV4_COMPONENTS = /^\d+(?:\.\d+){0,3}$/;
+var NON_DECIMAL_IPV4 = /^(?:0x[\da-f]+|0[0-7]+)(?:\.(?:0x[\da-f]+|0[0-7]+|\d+)){0,3}$/i;
+function stripTrailingDots(value) {
+	let end = value.length;
+	while (end > 0 && value.charCodeAt(end - 1) === 46) end -= 1;
+	return value.slice(0, end);
+}
+function rejectAlternateNumericAddress(hostname) {
+	if (isIP(hostname) === 0 && (DECIMAL_IPV4_COMPONENTS.test(hostname) || NON_DECIMAL_IPV4.test(hostname) || /^\d+$/.test(hostname))) throw new Error("alternate numeric IP forms are not admitted");
+}
+/** Canonicalize one concrete DNS name or IP literal for policy comparison. */
+function canonicalizeHostname(input) {
+	const withoutTrailingDot = stripTrailingDots(input.trim().replace(/^\[|\]$/g, ""));
+	if (!withoutTrailingDot) throw new Error("hostname is required");
+	rejectAlternateNumericAddress(withoutTrailingDot);
+	const ipVersion = isIP(withoutTrailingDot);
+	if (ipVersion === 4) return withoutTrailingDot;
+	if (ipVersion === 6) return new URL(`http://[${withoutTrailingDot}]/`).hostname.slice(1, -1);
+	if (/[\s/:@?#[\]]/.test(withoutTrailingDot)) throw new Error("invalid hostname");
+	const ascii = domainToASCII(withoutTrailingDot.toLowerCase());
+	if (!ascii || ascii.length > 253) throw new Error("invalid hostname");
+	return ascii;
+}
+/**
+* Credential destinations deliberately support only exact hosts, a global
+* wildcard, or a leading one-label wildcard. Arbitrary globs are too
+* ambiguous for a secret-delivery boundary.
+*/
+function canonicalizeCredentialHostPattern(input) {
+	const pattern = input.trim();
+	if (pattern === "*") return pattern;
+	if (pattern.startsWith("*.") && pattern.indexOf("*", 1) === -1) return `*.${canonicalizeHostname(pattern.slice(2))}`;
+	if (pattern.includes("*")) throw new Error("credential host patterns allow only a leading *.");
+	return canonicalizeHostname(pattern);
+}
+function credentialHostMatches(hostnameInput, patternInput) {
+	const hostname = canonicalizeHostname(hostnameInput);
+	const pattern = canonicalizeCredentialHostPattern(patternInput);
+	if (pattern === "*") return true;
+	if (!pattern.startsWith("*.")) return hostname === pattern;
+	const suffix = pattern.slice(2);
+	if (!hostname.endsWith(`.${suffix}`)) return false;
+	const prefix = hostname.slice(0, -(suffix.length + 1));
+	return prefix.length > 0 && !prefix.includes(".");
+}
+/** Keep Gondolin's wider network glob syntax separate from secret patterns. */
+function normalizeNetworkHostPattern(input) {
+	const pattern = input.trim();
+	if (pattern === "*") return pattern;
+	if (!pattern.includes("*")) return canonicalizeHostname(pattern);
+	const normalized = stripTrailingDots(pattern.toLowerCase());
+	if (normalized === "" || normalized.includes("://") || normalized.includes("/") || normalized.includes(":") || /\s/.test(normalized)) throw new Error("invalid network host pattern");
+	return normalized;
+}
+function networkPatternMatchesHostname(networkPatternInput, hostnameInput) {
+	const networkPattern = normalizeNetworkHostPattern(networkPatternInput);
+	const hostname = canonicalizeHostname(hostnameInput);
+	const expression = networkPattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+	return new RegExp(`^${expression}$`, "i").test(hostname);
+}
+/** Prove that a network grant covers a narrower credential destination. */
+function networkPatternCoversCredentialPattern(networkPatternInput, credentialPatternInput) {
+	const networkPattern = normalizeNetworkHostPattern(networkPatternInput);
+	const credentialPattern = canonicalizeCredentialHostPattern(credentialPatternInput);
+	if (networkPattern === "*") return true;
+	if (credentialPattern.includes("*")) return networkPattern === credentialPattern;
+	return networkPatternMatchesHostname(networkPattern, credentialPattern);
+}
+//#endregion
 //#region src/host-origins.ts
 function hostOriginHostnames(origins) {
 	return Object.keys(origins).map((origin) => new URL(origin).hostname).sort();
@@ -660,16 +731,6 @@ var OBJECT_META_PROPERTY_NAMES = new Set([
 	"constructor",
 	"prototype"
 ]);
-function normalizeHostPattern(pattern) {
-	let normalized = pattern.trim().toLowerCase();
-	if (normalized.startsWith("[") && normalized.endsWith("]")) normalized = normalized.slice(1, -1);
-	if (normalized.endsWith(".")) normalized = normalized.slice(0, -1);
-	return normalized;
-}
-function isValidHostPattern(pattern) {
-	if (isIP(pattern) !== 0) return true;
-	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
@@ -679,15 +740,20 @@ 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 hosts = [];
 	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}"`);
+	for (const hostInput of descriptor.hosts) try {
+		hosts.push(canonicalizeCredentialHostPattern(hostInput));
+	} catch {
+		issues.push(`requirement "${id}" has invalid host pattern "${hostInput.trim()}"`);
+	}
+	const uniqueHosts = [...new Set(hosts)].sort();
+	if (descriptor.hosts.length === 0) issues.push(`requirement "${id}" has no destination hosts`);
 	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}"`);
@@ -695,16 +761,12 @@ function canonicalizeBrokeredHttpSecretDescriptor(descriptor) {
 	return Object.freeze({
 		id,
 		guestEnv,
-		hosts: Object.freeze(hosts),
+		hosts: Object.freeze(uniqueHosts),
 		protocol,
 		ports: Object.freeze(ports),
 		required: descriptor.required !== false
 	});
 }
-function hostMatchesPattern(hostname, pattern) {
-	const expression = normalizeHostPattern(pattern).split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
-	return new RegExp(`^${expression}$`, "i").test(normalizeHostPattern(hostname));
-}
 /**
 * Conservative subset check for Gondolin hostname globs. Exact secret hosts
 * may sit below a broader network wildcard. A wildcard secret destination must
@@ -712,9 +774,7 @@ function hostMatchesPattern(hostname, pattern) {
 * through an ambiguous glob comparison.
 */
 function networkPatternCoversSecretPattern(networkPattern, secretPattern) {
-	if (networkPattern === "*") return true;
-	if (secretPattern.includes("*")) return networkPattern === secretPattern;
-	return hostMatchesPattern(secretPattern, networkPattern);
+	return networkPatternCoversCredentialPattern(networkPattern, secretPattern);
 }
 /**
 * Validate value-free descriptors, host-local bindings, environment
@@ -725,7 +785,7 @@ function prepareBrokeredHttpSecrets(options) {
 	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 allowedHosts = [...new Set(options.allowedHosts.map(normalizeNetworkHostPattern))];
 	const secrets = Object.create(null);
 	for (const binding of options.bindings ?? []) {
 		let descriptor;
@@ -780,7 +840,7 @@ function parseRequestOrigin(url) {
 		const parsed = new URL(url);
 		const protocol = parsed.protocol.slice(0, -1);
 		return {
-			hostname: normalizeHostPattern(parsed.hostname),
+			hostname: canonicalizeHostname(parsed.hostname),
 			protocol,
 			port: parsed.port ? Number(parsed.port) : protocol === "https" ? 443 : 80
 		};
@@ -808,7 +868,7 @@ function createBrokeredHttpSecretOriginPolicy(bindings) {
 			if (!requestOrigin) return false;
 			for (const entry of entries.values()) {
 				if (entry.deleted || !headersContainSecretValue(request.headers, entry.value)) continue;
-				if (requestOrigin.protocol !== entry.protocol || !entry.ports.includes(requestOrigin.port) || !entry.hosts.some((host) => hostMatchesPattern(requestOrigin.hostname, host))) return false;
+				if (requestOrigin.protocol !== entry.protocol || !entry.ports.includes(requestOrigin.port) || !entry.hosts.some((host) => credentialHostMatches(requestOrigin.hostname, host))) return false;
 			}
 			return true;
 		},
@@ -833,15 +893,21 @@ function createBrokeredHttpSecretOriginPolicy(bindings) {
 function createBrokeredHttpNetworkOriginPolicy(bindings, options = {}) {
 	const origins = bindings.map(canonicalizeBrokeredHttpSecretDescriptor);
 	const isAllowed = (input) => {
-		const hostname = normalizeHostPattern(input.hostname);
-		const matching = origins.filter((origin) => origin.hosts.some((host) => hostMatchesPattern(hostname, host)));
+		let hostname;
+		try {
+			hostname = canonicalizeHostname(input.hostname);
+		} catch {
+			return false;
+		}
+		const matching = origins.filter((origin) => origin.hosts.some((host) => credentialHostMatches(hostname, host)));
 		if (matching.length === 0) return true;
 		const allowed = matching.some((origin) => origin.protocol === input.protocol && origin.ports.includes(input.port));
-		if (!allowed) options.onDenied?.({
+		options.onDecision?.({
 			hostname,
 			protocol: input.protocol,
 			port: input.port,
-			phase: input.phase
+			phase: input.phase,
+			allowed
 		});
 		return allowed;
 	};
@@ -970,6 +1036,16 @@ async function resumeVm(config) {
 	const hostOriginHosts = hostOriginHostnames(hostOrigins);
 	assertInternalHostsDoNotOverlapProtectedHosts(hostOriginHosts, protectedExternalHosts);
 	const allowedInternalHosts = [...new Set([...runtimeAllowedInternalHosts, ...hostOriginHosts])];
+	const requestedHostnamePolicy = Object.freeze({
+		allowedHosts: Object.freeze([...allowedHosts].sort()),
+		allowedInternalHosts: Object.freeze([...allowedInternalHosts].sort())
+	});
+	config.onDiagnostic?.({
+		event: "vm.network.policy_bound",
+		level: "info",
+		message: "Passed the complete requested hostname policy to Gondolin",
+		hostnamePolicy: requestedHostnamePolicy
+	});
 	const projectedEnv = config.guestProjection?.env ?? {};
 	const brokeredSecrets = prepareBrokeredHttpSecrets({
 		bindings: config.brokeredSecrets,
@@ -987,12 +1063,18 @@ async function resumeVm(config) {
 		]
 	});
 	const brokeredSecretOriginPolicy = createBrokeredHttpSecretOriginPolicy(config.brokeredSecrets ?? []);
-	const brokeredNetworkOriginPolicy = createBrokeredHttpNetworkOriginPolicy(config.brokeredSecrets ?? [], { onDenied(origin) {
+	const brokeredNetworkOriginPolicy = createBrokeredHttpNetworkOriginPolicy(config.brokeredSecrets ?? [], { onDecision(decision) {
 		config.onDiagnostic?.({
+			event: "vm.network.origin_checked",
+			level: "info",
+			message: "Checked a canonical brokered credential origin",
+			origin: decision
+		});
+		if (!decision.allowed) config.onDiagnostic?.({
 			event: "vm.network.origin_denied",
 			level: "warning",
-			message: "denied request outside a brokered credential origin",
-			origin
+			message: "Denied a request outside a brokered credential origin",
+			origin: decision
 		});
 	} });
 	const { httpHooks, env: secretEnv, secretManager: gondolinSecretManager } = createHttpHooks({

package/package.json

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