@questpie/sandbox 3.16.0 → 3.17.0

package/src/server-internals.ts

@@ -45,13 +45,187 @@ export interface RunOutcome {
 	timedOut?: boolean;
 }
 
+const MAX_RESULT_DEPTH = 32;
+const MAX_RESULT_NODES = 10_000;
+const MAX_RESULT_JSON_BYTES = 1_048_576;
+const MAX_RESULT_LOGS = 1_000;
+const MAX_RESULT_LOG_BYTES = 4_000;
+const MAX_TOTAL_LOG_BYTES = 1_048_576;
+
+function exactKeys(
+	value: Record<string, unknown>,
+	required: readonly string[],
+	optional: readonly string[],
+): boolean {
+	const keys = Object.keys(value);
+	return (
+		required.every((key) => keys.includes(key)) &&
+		keys.every((key) => required.includes(key) || optional.includes(key))
+	);
+}
+
+function isBoundedJson(
+	value: unknown,
+	budget = { nodes: 0, bytes: 0 },
+	depth = 0,
+	maximumBytes = MAX_RESULT_JSON_BYTES,
+): boolean {
+	if (depth > MAX_RESULT_DEPTH) return false;
+	budget.nodes += 1;
+	if (budget.nodes > MAX_RESULT_NODES) return false;
+	if (value === null || typeof value === "boolean") {
+		budget.bytes += 5;
+	} else if (typeof value === "number") {
+		if (!Number.isFinite(value)) return false;
+		budget.bytes += 24;
+	} else if (typeof value === "string") {
+		budget.bytes += new TextEncoder().encode(value).byteLength;
+	} else if (Array.isArray(value)) {
+		budget.bytes += 2;
+		for (const item of value) {
+			if (!isBoundedJson(item, budget, depth + 1, maximumBytes)) return false;
+		}
+	} else if (typeof value === "object" && value !== null) {
+		budget.bytes += 2;
+		for (const [key, item] of Object.entries(value)) {
+			budget.bytes += new TextEncoder().encode(key).byteLength;
+			if (!isBoundedJson(item, budget, depth + 1, maximumBytes)) return false;
+		}
+	} else {
+		return false;
+	}
+	return budget.bytes <= maximumBytes;
+}
+
+export function parseSandboxRunResult(
+	value: unknown,
+): (RunOutcome & { ms?: number }) | null {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const result = value as Record<string, unknown>;
+	if (
+		!exactKeys(result, ["ok", "logs"], ["output", "error", "timedOut", "ms"]) ||
+		typeof result.ok !== "boolean" ||
+		!Array.isArray(result.logs) ||
+		result.logs.length > MAX_RESULT_LOGS ||
+		(result.error !== undefined && typeof result.error !== "string") ||
+		(result.timedOut !== undefined && typeof result.timedOut !== "boolean") ||
+		(result.ms !== undefined &&
+			(typeof result.ms !== "number" ||
+				!Number.isFinite(result.ms) ||
+				result.ms < 0))
+	) {
+		return null;
+	}
+	if (
+		(result.ok === true &&
+			(Object.hasOwn(result, "error") || Object.hasOwn(result, "timedOut"))) ||
+		(result.ok === false &&
+			(typeof result.error !== "string" ||
+				Object.hasOwn(result, "output") ||
+				(Object.hasOwn(result, "timedOut") && result.timedOut !== true)))
+	) {
+		return null;
+	}
+	let logBytes = 0;
+	for (const log of result.logs) {
+		if (typeof log !== "string") return null;
+		const bytes = new TextEncoder().encode(log).byteLength;
+		logBytes += bytes;
+		if (bytes > MAX_RESULT_LOG_BYTES || logBytes > MAX_TOTAL_LOG_BYTES) {
+			return null;
+		}
+	}
+	if (result.output !== undefined && !isBoundedJson(result.output)) return null;
+	return {
+		ok: result.ok,
+		...(result.output !== undefined ? { output: result.output } : {}),
+		...(typeof result.error === "string" ? { error: result.error } : {}),
+		logs: result.logs as string[],
+		...(typeof result.timedOut === "boolean"
+			? { timedOut: result.timedOut }
+			: {}),
+		...(typeof result.ms === "number" ? { ms: result.ms } : {}),
+	};
+}
+
+export type BrokerRelayResult =
+	| { ok: true; value?: unknown }
+	| {
+			ok: false;
+			error: { code: string; message: string; correlationId?: string };
+	  };
+
+const BROKER_ERROR_MESSAGES: Readonly<Record<string, string>> = Object.freeze({
+	bad_method: "invalid sandbox binding method",
+	bad_args: "invalid sandbox binding arguments",
+	unauthorized: "sandbox binding authorization failed",
+	forbidden: "sandbox binding operation forbidden",
+	not_implemented: "sandbox binding operation unavailable",
+	execution_error: "sandbox binding operation failed",
+});
+
+export function parseBrokerResponse(
+	value: unknown,
+	maxValueBytes = MAX_RESULT_JSON_BYTES,
+): BrokerRelayResult | null {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const response = value as Record<string, unknown>;
+	if (response.ok === true) {
+		if (!exactKeys(response, ["ok", "value"], [])) return null;
+		if (!isBoundedJson(response.value, undefined, 0, maxValueBytes))
+			return null;
+		return { ok: true, value: response.value };
+	}
+	if (
+		response.ok !== false ||
+		!exactKeys(response, ["ok", "error"], []) ||
+		!response.error ||
+		typeof response.error !== "object" ||
+		Array.isArray(response.error)
+	) {
+		return null;
+	}
+	const error = response.error as Record<string, unknown>;
+	if (
+		!exactKeys(error, ["code", "message"], ["correlationId"]) ||
+		typeof error.code !== "string" ||
+		typeof error.message !== "string" ||
+		(error.correlationId !== undefined &&
+			(typeof error.correlationId !== "string" ||
+				!/^[\w-]{1,128}$/.test(error.correlationId)))
+	) {
+		return null;
+	}
+	const code = Object.hasOwn(BROKER_ERROR_MESSAGES, error.code)
+		? error.code
+		: "execution_error";
+	return {
+		ok: false,
+		error: {
+			code,
+			message: BROKER_ERROR_MESSAGES[code]!,
+			...(typeof error.correlationId === "string"
+				? { correlationId: error.correlationId }
+				: {}),
+		},
+	};
+}
+
 /** Normalize a broker URL for comparison (drop a trailing slash; ignore case of origin). */
 export function normalizeBrokerUrl(raw: string): string | null {
 	try {
 		const u = new URL(raw);
+		if (
+			(u.protocol !== "http:" && u.protocol !== "https:") ||
+			u.username.length > 0 ||
+			u.password.length > 0 ||
+			u.hash.length > 0
+		) {
+			return null;
+		}
 		// Compare origin (lowercased by URL) + pathname without a trailing slash.
 		const path = u.pathname.replace(/\/$/, "");
-		return `${u.origin}${path}`;
+		return `${u.origin}${path}${u.search}`;
 	} catch {
 		return null;
 	}
@@ -60,10 +234,16 @@ export function normalizeBrokerUrl(raw: string): string | null {
 /**
  * Reject a guest's bindings target URL unless it matches the supervisor's
  * configured expected broker URL. Returns an error string to surface, or
- * `null` when the URL is acceptable (or no expectation is configured).
+ * `null` only when the URL is acceptable. Bindings fail closed when the
+ * supervisor has no canonical broker target configured.
  */
-export function brokerUrlRejection(url: unknown, expected: string | undefined): string | null {
-	if (!expected) return null; // not configured → skip (back-compat)
+export function brokerUrlRejection(
+	url: unknown,
+	expected: string | undefined,
+): string | null {
+	if (!expected || normalizeBrokerUrl(expected) === null) {
+		return "sandbox broker URL is not configured";
+	}
 	if (typeof url !== "string" || url.length === 0) {
 		return "bindings.url is missing";
 	}
@@ -76,7 +256,12 @@ export function brokerUrlRejection(url: unknown, expected: string | undefined):
 	return null;
 }
 
-export function clampInt(v: unknown, def: number, min: number, max: number): number {
+export function clampInt(
+	v: unknown,
+	def: number,
+	min: number,
+	max: number,
+): number {
 	const n = Number(v);
 	if (!Number.isFinite(n)) return def;
 	return Math.min(Math.max(Math.round(n), min), max);
@@ -107,7 +292,10 @@ export function importFlags(hosts: string[]): string[] {
 }
 
 /** Pull the marked JSON result line out of the guest's stdout. */
-export function extractResult(stdout: string, marker: string): RunOutcome | null {
+export function extractResult(
+	stdout: string,
+	marker: string,
+): RunOutcome | null {
 	const idx = stdout.lastIndexOf(marker);
 	if (idx === -1) return null;
 	const after = stdout.slice(idx + marker.length);
@@ -115,12 +303,7 @@ export function extractResult(stdout: string, marker: string): RunOutcome | null
 	const json = newline === -1 ? after : after.slice(0, newline);
 	try {
 		const parsed = JSON.parse(json);
-		return {
-			ok: !!parsed.ok,
-			output: parsed.output,
-			error: parsed.error,
-			logs: Array.isArray(parsed.logs) ? parsed.logs : [],
-		};
+		return parseSandboxRunResult(parsed);
 	} catch {
 		return null;
 	}

package/src/types.ts

@@ -46,6 +46,8 @@ export interface SandboxBindings {
 
 /** POST /run request body. */
 export interface SandboxRunRequest {
+	/** Explicit transport admission. The supervisor rejects omitted/unknown modes. */
+	mode: "workload" | "host";
 	/** Guest TypeScript source. Must `export default` a `function(input)`. */
 	source: string;
 	/** Payload passed to the guest entry function. */
@@ -65,16 +67,35 @@ export interface SandboxRunRequest {
 }
 
 /** POST /run response body — also the `ExecutorAdapter.run` result shape. */
-export interface SandboxRunResult {
-	ok: boolean;
-	output?: unknown;
-	logs: string[];
-	error?: string;
-	/** True when the run was killed by the wall-clock timeout. */
-	timedOut?: boolean;
-	/** Wall-clock duration in ms (server-measured). */
-	ms?: number;
-}
+export type SandboxRunResult =
+	| {
+			ok: true;
+			output?: unknown;
+			logs: string[];
+			error?: never;
+			timedOut?: never;
+			/** Wall-clock duration in ms (server-measured). */
+			ms?: number;
+	  }
+	| {
+			ok: false;
+			error: string;
+			logs: string[];
+			output?: never;
+			timedOut?: never;
+			/** Wall-clock duration in ms (server-measured). */
+			ms?: number;
+	  }
+	| {
+			ok: false;
+			error: string;
+			logs: string[];
+			output?: never;
+			/** True when the run was killed by the wall-clock timeout. */
+			timedOut: true;
+			/** Wall-clock duration in ms (server-measured). */
+			ms?: number;
+	  };
 
 // ──────────────────────────────────────────────────────────────────────────
 // FRAMED stdio protocol (guest subprocess ⇄ supervisor) for the bindings path.
@@ -96,10 +117,17 @@ export const FRAME_MARKER = "__QP_SANDBOX_MSG__";
  */
 export const BINDINGS_TOKEN_HEADER = "x-questpie-sandbox-token";
 
+/** Host-issued admission binding an authorized workload to one exact request. */
+export const WORKLOAD_ADMISSION_HEADER = "x-questpie-workload-admission";
+
+/** Trusted service identity for the structurally separate direct-host path. */
+export const HOST_ADMISSION_HEADER = "x-questpie-sandbox-host-admission";
+
 /** Structured error returned by the broker (mirrors `questpie` `BindingError`). */
 export interface SandboxBindingError {
 	code: string;
 	message: string;
+	correlationId?: string;
 }
 
 /** Guest → supervisor: a binding RPC awaiting a brokered result. */

package/src/workload-admission.ts

@@ -0,0 +1,289 @@
+const ADMISSION_VERSION = "qpsw1";
+const MINIMUM_SECRET_BYTES = 32;
+const MAXIMUM_ADMISSION_TTL_MS = 5_000;
+
+export interface SandboxWorkloadAdmissionClaims {
+	readonly kind: "sandbox_workload_admission";
+	readonly version: 1;
+	readonly admissionId: string;
+	readonly supervisorInstanceId: string;
+	readonly expiresAt: string;
+	readonly requestSha256: string;
+}
+
+export interface SandboxWorkloadAdmissionKey {
+	readonly keyId: string;
+	readonly secret: Uint8Array;
+	/** Unique per supervisor process; rotate on every restart. */
+	readonly instanceId: string;
+}
+
+export type SandboxWorkloadAdmissionDenialReason =
+	| "invalid"
+	| "wrong_instance"
+	| "expired"
+	| "body_mismatch";
+
+export type SandboxWorkloadAdmissionVerification =
+	| {
+			readonly ok: true;
+			readonly claims: SandboxWorkloadAdmissionClaims;
+	  }
+	| {
+			readonly ok: false;
+			readonly reason: SandboxWorkloadAdmissionDenialReason;
+			readonly claims?: SandboxWorkloadAdmissionClaims;
+	  };
+
+interface ReplayExpiry {
+	readonly admissionId: string;
+	readonly expiresAt: number;
+}
+
+export class SandboxWorkloadReplayCache {
+	private readonly consumed = new Map<string, number>();
+	private readonly expiries: ReplayExpiry[] = [];
+
+	constructor(private readonly maximumEntries: number) {
+		if (!Number.isInteger(maximumEntries) || maximumEntries < 1) {
+			throw new Error("Invalid sandbox workload replay cache size.");
+		}
+	}
+
+	consume(
+		admission: SandboxWorkloadAdmissionClaims,
+		now = Date.now(),
+	): boolean {
+		this.deleteExpired(now);
+		if (this.consumed.has(admission.admissionId)) return false;
+		if (this.consumed.size >= this.maximumEntries) return false;
+		const expiresAt = Date.parse(admission.expiresAt);
+		if (!Number.isFinite(expiresAt) || expiresAt <= now) return false;
+		this.consumed.set(admission.admissionId, expiresAt);
+		this.push({ admissionId: admission.admissionId, expiresAt });
+		return true;
+	}
+
+	private deleteExpired(now: number): void {
+		while (this.expiries[0] && this.expiries[0].expiresAt <= now) {
+			const expired = this.pop()!;
+			if (this.consumed.get(expired.admissionId) === expired.expiresAt) {
+				this.consumed.delete(expired.admissionId);
+			}
+		}
+	}
+
+	private push(value: ReplayExpiry): void {
+		let index = this.expiries.push(value) - 1;
+		while (index > 0) {
+			const parent = Math.floor((index - 1) / 2);
+			if (this.expiries[parent]!.expiresAt <= value.expiresAt) break;
+			this.expiries[index] = this.expiries[parent]!;
+			index = parent;
+		}
+		this.expiries[index] = value;
+	}
+
+	private pop(): ReplayExpiry | undefined {
+		const root = this.expiries[0];
+		const last = this.expiries.pop();
+		if (!root || !last || this.expiries.length === 0) return root;
+		let index = 0;
+		while (true) {
+			const left = index * 2 + 1;
+			if (left >= this.expiries.length) break;
+			const right = left + 1;
+			const child =
+				right < this.expiries.length &&
+				this.expiries[right]!.expiresAt < this.expiries[left]!.expiresAt
+					? right
+					: left;
+			if (this.expiries[child]!.expiresAt >= last.expiresAt) break;
+			this.expiries[index] = this.expiries[child]!;
+			index = child;
+		}
+		this.expiries[index] = last;
+		return root;
+	}
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function encodeBase64Url(value: Uint8Array): string {
+	let binary = "";
+	for (const byte of value) binary += String.fromCharCode(byte);
+	return btoa(binary)
+		.replaceAll("+", "-")
+		.replaceAll("/", "_")
+		.replace(/=+$/, "");
+}
+
+function decodeBase64Url(value: string): Uint8Array | null {
+	try {
+		const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+		const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+		const binary = atob(padded);
+		return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+	} catch {
+		return null;
+	}
+}
+
+function isIdentity(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length <= 128 &&
+		/^[A-Za-z0-9_-]+$/.test(value)
+	);
+}
+
+export function assertSandboxWorkloadAdmissionKey(
+	key: SandboxWorkloadAdmissionKey,
+): void {
+	if (
+		!isIdentity(key.keyId) ||
+		!isIdentity(key.instanceId) ||
+		key.secret.byteLength < MINIMUM_SECRET_BYTES
+	) {
+		throw new Error("Invalid sandbox workload admission configuration.");
+	}
+}
+
+async function importHmacKey(
+	key: SandboxWorkloadAdmissionKey,
+	usage: "sign" | "verify",
+): Promise<CryptoKey> {
+	assertSandboxWorkloadAdmissionKey(key);
+	return crypto.subtle.importKey(
+		"raw",
+		Uint8Array.from(key.secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		[usage],
+	);
+}
+
+async function sha256(value: string): Promise<string> {
+	const digest = await crypto.subtle.digest("SHA-256", encoder.encode(value));
+	return [...new Uint8Array(digest)]
+		.map((byte) => byte.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+function exactKeys(value: object, keys: readonly string[]): boolean {
+	const actual = Object.keys(value).sort();
+	const expected = [...keys].sort();
+	return (
+		actual.length === expected.length &&
+		actual.every((key, index) => key === expected[index])
+	);
+}
+
+function parseClaims(value: unknown): SandboxWorkloadAdmissionClaims | null {
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		Array.isArray(value) ||
+		!exactKeys(value, [
+			"kind",
+			"version",
+			"admissionId",
+			"supervisorInstanceId",
+			"expiresAt",
+			"requestSha256",
+		])
+	) {
+		return null;
+	}
+	const claims = value as Record<string, unknown>;
+	if (
+		claims.kind !== "sandbox_workload_admission" ||
+		claims.version !== 1 ||
+		!isIdentity(claims.admissionId) ||
+		!isIdentity(claims.supervisorInstanceId) ||
+		typeof claims.expiresAt !== "string" ||
+		!Number.isFinite(Date.parse(claims.expiresAt)) ||
+		typeof claims.requestSha256 !== "string" ||
+		!/^[a-f0-9]{64}$/.test(claims.requestSha256)
+	) {
+		return null;
+	}
+	return claims as unknown as SandboxWorkloadAdmissionClaims;
+}
+
+export async function sealSandboxWorkloadAdmission(
+	key: SandboxWorkloadAdmissionKey,
+	claims: Omit<SandboxWorkloadAdmissionClaims, "requestSha256">,
+	requestBody: string,
+): Promise<string> {
+	const payload: SandboxWorkloadAdmissionClaims = {
+		...claims,
+		requestSha256: await sha256(requestBody),
+	};
+	const encodedKeyId = encodeBase64Url(encoder.encode(key.keyId));
+	const encodedPayload = encodeBase64Url(
+		encoder.encode(JSON.stringify(payload)),
+	);
+	const signed = `${ADMISSION_VERSION}.${encodedKeyId}.${encodedPayload}`;
+	const cryptoKey = await importHmacKey(key, "sign");
+	const signature = await crypto.subtle.sign(
+		"HMAC",
+		cryptoKey,
+		encoder.encode(signed),
+	);
+	return `${signed}.${encodeBase64Url(new Uint8Array(signature))}`;
+}
+
+export async function verifySandboxWorkloadAdmission(
+	key: SandboxWorkloadAdmissionKey,
+	envelope: string,
+	requestBody: string,
+	now = new Date(),
+): Promise<SandboxWorkloadAdmissionVerification> {
+	const parts = envelope.split(".");
+	if (parts.length !== 4 || parts[0] !== ADMISSION_VERSION) {
+		return { ok: false, reason: "invalid" };
+	}
+	const encodedKeyId = encodeBase64Url(encoder.encode(key.keyId));
+	if (parts[1] !== encodedKeyId) return { ok: false, reason: "invalid" };
+	const signature = decodeBase64Url(parts[3]!);
+	if (!signature) return { ok: false, reason: "invalid" };
+	const signed = `${parts[0]}.${parts[1]}.${parts[2]}`;
+	const cryptoKey = await importHmacKey(key, "verify");
+	if (
+		!(await crypto.subtle.verify(
+			"HMAC",
+			cryptoKey,
+			Uint8Array.from(signature),
+			encoder.encode(signed),
+		))
+	) {
+		return { ok: false, reason: "invalid" };
+	}
+	const encodedPayload = decodeBase64Url(parts[2]!);
+	if (!encodedPayload) return { ok: false, reason: "invalid" };
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(decoder.decode(encodedPayload));
+	} catch {
+		return { ok: false, reason: "invalid" };
+	}
+	const claims = parseClaims(decoded);
+	if (!claims) return { ok: false, reason: "invalid" };
+	const frozenClaims = Object.freeze(claims);
+	if (claims.supervisorInstanceId !== key.instanceId) {
+		return { ok: false, reason: "wrong_instance", claims: frozenClaims };
+	}
+	const expiresAt = Date.parse(claims.expiresAt);
+	if (
+		expiresAt <= now.getTime() ||
+		expiresAt > now.getTime() + MAXIMUM_ADMISSION_TTL_MS
+	) {
+		return { ok: false, reason: "expired", claims: frozenClaims };
+	}
+	if (claims.requestSha256 !== (await sha256(requestBody))) {
+		return { ok: false, reason: "body_mismatch", claims: frozenClaims };
+	}
+	return { ok: true, claims: frozenClaims };
+}