@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/runtime/egress-lease.ts

@@ -0,0 +1,341 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+
+import type { ProxyVendorName } from "../config/loader.js";
+import { SDKError } from "../errors.js";
+
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export const ENGINE_CEREMONY_EGRESS_LEASE = Symbol.for(
+	"@apifuse/provider-sdk/engine-ceremony-egress-lease",
+);
+
+const HANDLE_VERSION = 1;
+const HANDLE_MAX_BYTES = 16_384;
+const AEAD_NONCE_BYTES = 12;
+const AEAD_TAG_BYTES = 16;
+const AEAD_ALGORITHM = "aes-256-gcm";
+const AEAD_KEY_DOMAIN = "apifuse:ceremony-egress-lease:v1\0";
+const LEASE_KEY_MIN_BYTES = 32;
+
+export type CeremonyEgressBinding = {
+	readonly vendor: ProxyVendorName;
+	readonly proxyUrl: string;
+	readonly poolIndex: number;
+	readonly affinityKey: string;
+	readonly refreshEpoch: number;
+	/**
+	 * Vendor session lifetime the endpoint was allocated for (`proxy.session.lifetimeMinutes`,
+	 * Smartproxy `life`, NodeMaven SID window). It is the upper bound of the lease, counted
+	 * from the mint (the first successful attempt), so a Smartproxy lease can outlive the
+	 * vendor session by the extraction-cache reuse window; expiry then drops and rebinds.
+	 * The bound is not a vendor guarantee (ADR-0010: a raw Smartproxy endpoint is not a hard
+	 * lease): the stealth runtime releases the binding as soon as the endpoint fails at the
+	 * transport, so a dead endpoint is left before the lifetime elapses.
+	 */
+	readonly lifetimeMinutes: number;
+};
+
+type CeremonyEgressLeasePayloadV1 = CeremonyEgressBinding & {
+	readonly version: typeof HANDLE_VERSION;
+	readonly tenantId: string;
+	readonly providerId: string;
+	readonly flowId: string;
+	readonly mintedAtMs: number;
+	readonly expiresAtMs: number;
+};
+
+type CeremonyEgressLeaseScopeV1 = Pick<
+	CeremonyEgressLeasePayloadV1,
+	"tenantId" | "providerId" | "flowId" | "affinityKey"
+>;
+
+export type CeremonyEgressLeaseRuntime = {
+	/** Exact egress bound to this ceremony; undefined until the first successful attempt binds one. */
+	readonly binding: CeremonyEgressBinding | undefined;
+	/**
+	 * Drops the binding once its vendor session lifetime has elapsed so the next attempt
+	 * selects and binds a fresh endpoint. Returns true when a binding was dropped: the
+	 * caller must also discard challenge state that was only valid for that endpoint.
+	 */
+	dropExpiredBinding(): boolean;
+	/**
+	 * Drops the binding unconditionally; the stealth runtime calls this when the bound
+	 * endpoint fails at the transport. Same return and caller obligation as
+	 * `dropExpiredBinding`.
+	 */
+	dropBinding(): boolean;
+	/**
+	 * Number of bindings dropped so far (expiry or release). Every stealth session created
+	 * from one client shares the lease; a session compares this to what it last observed to
+	 * retire endpoint-bound challenge state and replay records after another session moved
+	 * the ceremony.
+	 */
+	readonly generation: number;
+	bind(binding: CeremonyEgressBinding): void;
+	handle(): string | undefined;
+};
+
+/** The caller presented a handle this engine cannot verify for this ceremony (409). */
+function invalidLease(): never {
+	throw new SDKError("The engine ceremony egress lease is invalid", {
+		code: "EGRESS_LEASE_INVALID",
+		fix: "Restart the authentication ceremony to obtain a new engine-owned egress lease.",
+	});
+}
+
+/** The engine violated its own binding invariant (500); never attributable to the caller. */
+function bindingFault(message: string): never {
+	throw new SDKError(message, {
+		code: "EGRESS_LEASE_BINDING_INVALID",
+		fix: "This is an SDK or provider-runtime fault; the ceremony lease cannot bind the selected egress.",
+	});
+}
+
+function encryptionKey(key: string): Buffer {
+	return createHash("sha256").update(AEAD_KEY_DOMAIN, "utf8").update(key, "utf8").digest();
+}
+
+/** Fixed field order and JSON.stringify's compact form are the canonical AAD encoding. */
+function scopeAad(scope: CeremonyEgressLeaseScopeV1): Buffer {
+	return Buffer.from(
+		JSON.stringify({
+			version: HANDLE_VERSION,
+			tenantId: scope.tenantId,
+			providerId: scope.providerId,
+			flowId: scope.flowId,
+			affinityKey: scope.affinityKey,
+		}),
+		"utf8",
+	);
+}
+
+function encodeHandle(
+	payload: CeremonyEgressLeasePayloadV1,
+	key: string,
+	scope: CeremonyEgressLeaseScopeV1,
+): string {
+	const nonce = randomBytes(AEAD_NONCE_BYTES);
+	const cipher = createCipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+		authTagLength: AEAD_TAG_BYTES,
+	});
+	cipher.setAAD(scopeAad(scope));
+	const ciphertext = Buffer.concat([
+		cipher.update(JSON.stringify(payload), "utf8"),
+		cipher.final(),
+	]);
+	return [
+		`v${HANDLE_VERSION}`,
+		nonce.toString("base64url"),
+		ciphertext.toString("base64url"),
+		cipher.getAuthTag().toString("base64url"),
+	].join(".");
+}
+
+function isFiniteInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isPositiveFinite(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function decodeHandle(
+	handle: string,
+	key: string,
+	scope: CeremonyEgressLeaseScopeV1,
+): CeremonyEgressLeasePayloadV1 {
+	if (Buffer.byteLength(handle, "utf8") > HANDLE_MAX_BYTES) return invalidLease();
+	const parts = handle.split(".");
+	if (
+		parts.length !== 4 ||
+		parts[0] !== `v${HANDLE_VERSION}` ||
+		parts.slice(1).some((part) => !/^[A-Za-z0-9_-]+$/u.test(part))
+	) {
+		return invalidLease();
+	}
+	let parsed: unknown;
+	try {
+		const nonce = Buffer.from(parts[1]!, "base64url");
+		const ciphertext = Buffer.from(parts[2]!, "base64url");
+		const tag = Buffer.from(parts[3]!, "base64url");
+		if (
+			nonce.byteLength !== AEAD_NONCE_BYTES ||
+			tag.byteLength !== AEAD_TAG_BYTES ||
+			ciphertext.byteLength === 0
+		) {
+			return invalidLease();
+		}
+		const decipher = createDecipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+			authTagLength: AEAD_TAG_BYTES,
+		});
+		decipher.setAAD(scopeAad(scope));
+		decipher.setAuthTag(tag);
+		const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+		parsed = JSON.parse(plaintext.toString("utf8"));
+	} catch {
+		return invalidLease();
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return invalidLease();
+	const candidate = parsed as Partial<CeremonyEgressLeasePayloadV1>;
+	if (
+		candidate.version !== HANDLE_VERSION ||
+		(candidate.vendor !== "smartproxy" && candidate.vendor !== "nodemaven") ||
+		typeof candidate.proxyUrl !== "string" ||
+		!candidate.proxyUrl ||
+		!isFiniteInteger(candidate.poolIndex) ||
+		typeof candidate.affinityKey !== "string" ||
+		!candidate.affinityKey ||
+		!isFiniteInteger(candidate.refreshEpoch) ||
+		typeof candidate.tenantId !== "string" ||
+		!candidate.tenantId ||
+		typeof candidate.providerId !== "string" ||
+		!candidate.providerId ||
+		typeof candidate.flowId !== "string" ||
+		!candidate.flowId ||
+		!isFiniteInteger(candidate.mintedAtMs) ||
+		!isFiniteInteger(candidate.expiresAtMs) ||
+		candidate.expiresAtMs <= candidate.mintedAtMs ||
+		!isPositiveFinite(candidate.lifetimeMinutes)
+	) {
+		return invalidLease();
+	}
+	try {
+		const proxy = new URL(candidate.proxyUrl);
+		if (proxy.protocol !== "http:" && proxy.protocol !== "socks5:") return invalidLease();
+	} catch {
+		return invalidLease();
+	}
+	return candidate as CeremonyEgressLeasePayloadV1;
+}
+
+function bindingOf(payload: CeremonyEgressLeasePayloadV1): CeremonyEgressBinding {
+	return {
+		vendor: payload.vendor,
+		proxyUrl: payload.proxyUrl,
+		poolIndex: payload.poolIndex,
+		affinityKey: payload.affinityKey,
+		refreshEpoch: payload.refreshEpoch,
+		lifetimeMinutes: payload.lifetimeMinutes,
+	};
+}
+
+export function createCeremonyEgressLeaseRuntime(options: {
+	readonly tenantId?: string;
+	readonly providerId: string;
+	readonly flowId: string;
+	readonly affinityKey: string;
+	readonly handle?: string;
+	/** Server-only registration before a handle can reach request diagnostics. */
+	readonly onHandle?: (handle: string) => void;
+	readonly environment?: Readonly<Record<string, string | undefined>>;
+	readonly now?: () => number;
+}): CeremonyEgressLeaseRuntime {
+	const environment = options.environment ?? process.env;
+	const now = options.now ?? Date.now;
+	if (typeof options.tenantId !== "string" || !options.tenantId.trim()) {
+		throw new SDKError("A tenant is required for an engine ceremony egress lease", {
+			code: "EGRESS_LEASE_INVALID",
+			fix: "Restart the authentication ceremony with its tenant identity.",
+		});
+	}
+	const scope: CeremonyEgressLeaseScopeV1 = {
+		tenantId: options.tenantId,
+		providerId: options.providerId,
+		flowId: options.flowId,
+		affinityKey: options.affinityKey,
+	};
+	const key = readDiagnosticEnv(APIFUSE__ENGINE__CEREMONY_LEASE_KEY, environment)?.trim();
+	if (!key) {
+		throw new SDKError("The engine ceremony egress lease key is not configured", {
+			code: "EGRESS_LEASE_KEY_MISSING",
+			fix: `Configure ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} in the engine host.`,
+		});
+	}
+	// The key is the whole authenticity boundary of a handle (a verified handle's proxyUrl
+	// becomes the ceremony egress), so the documented minimum is enforced, not advisory.
+	if (Buffer.byteLength(key, "utf8") < LEASE_KEY_MIN_BYTES) {
+		throw new SDKError(
+			`The engine ceremony egress lease key is shorter than ${LEASE_KEY_MIN_BYTES} bytes`,
+			{
+				code: "EGRESS_LEASE_KEY_WEAK",
+				fix: `Set ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} to at least ${LEASE_KEY_MIN_BYTES} random bytes (for example \`openssl rand -base64 32\`).`,
+			},
+		);
+	}
+	let payload: CeremonyEgressLeasePayloadV1 | undefined;
+	let currentHandle: string | undefined;
+	let generation = 0;
+
+	const dropBinding = (): boolean => {
+		if (!payload) return false;
+		payload = undefined;
+		currentHandle = undefined;
+		generation += 1;
+		return true;
+	};
+	const dropExpiredBinding = (): boolean =>
+		payload !== undefined && now() >= payload.expiresAtMs ? dropBinding() : false;
+
+	if (options.handle !== undefined) {
+		options.onHandle?.(options.handle);
+		// Scope mismatch fails GCM authentication because scope is AAD; there is
+		// deliberately no post-decrypt scope comparison fallback.
+		payload = decodeHandle(options.handle, key, scope);
+		currentHandle = options.handle;
+		// An expired but authentic handle is not a fault: the ceremony continues on a
+		// freshly selected endpoint and the next turn receives the new handle.
+		dropExpiredBinding();
+	}
+
+	return {
+		get binding() {
+			return payload ? bindingOf(payload) : undefined;
+		},
+		dropExpiredBinding,
+		dropBinding,
+		get generation() {
+			return generation;
+		},
+		bind(binding) {
+			if (payload) {
+				// The stealth runtime reuses the bound endpoint while a binding exists and
+				// never rebinds it; a second bind is an engine invariant break.
+				return bindingFault("The ceremony egress lease is already bound");
+			}
+			if (
+				binding.affinityKey !== options.affinityKey ||
+				!binding.proxyUrl ||
+				(binding.vendor !== "smartproxy" && binding.vendor !== "nodemaven") ||
+				!isFiniteInteger(binding.poolIndex) ||
+				!isPositiveFinite(binding.lifetimeMinutes)
+			) {
+				return bindingFault("The selected egress cannot be bound to the ceremony lease");
+			}
+			const mintedAtMs = now();
+			payload = {
+				version: HANDLE_VERSION,
+				tenantId: scope.tenantId,
+				providerId: options.providerId,
+				flowId: options.flowId,
+				...binding,
+				mintedAtMs,
+				expiresAtMs: mintedAtMs + binding.lifetimeMinutes * 60_000,
+			};
+			currentHandle = encodeHandle(payload, key, scope);
+			options.onHandle?.(currentHandle);
+		},
+		handle() {
+			return currentHandle;
+		},
+	};
+}

package/src/runtime/engine-mode.ts

@@ -0,0 +1,233 @@
+import {
+	createInProcessProviderEngine,
+	PROVIDER_ENGINE_MODE_ENV,
+	type ProviderEngine,
+	type ProviderEngineMode,
+} from "../engine.js";
+import { ProviderError, ValidationError } from "../errors.js";
+
+/**
+ * Engine attachment selection. Internal on purpose: ADR-0011 removes the
+ * in-process lane, so every symbol exported here would become a breaking removal
+ * later. The server surfaces the outcome on the `provider_engine_mode` boot
+ * event instead.
+ */
+
+const KNOWN_PROVIDER_ENGINE_MODES = ["in-process", "remote"] as const;
+
+/** Mode used when neither `engineMode` nor `APIFUSE__ENGINE__MODE` names one. */
+export const DEFAULT_PROVIDER_ENGINE_MODE = "in-process" satisfies ProviderEngineMode;
+
+/** Remote engine client endpoint; engine-owned, so never declarable as a provider secret. */
+export const REMOTE_ENGINE_CLIENT_URL_ENV = "APIFUSE__ENGINE__URL";
+/** Remote engine client credential; registered with the diagnostic redactor by sensitive-values. */
+export const REMOTE_ENGINE_CLIENT_API_KEY_ENV = "APIFUSE__ENGINE__API_KEY";
+
+/** Engine env names that only mean something in remote mode. */
+const REMOTE_ONLY_ENGINE_ENV_NAMES = [
+	REMOTE_ENGINE_CLIENT_URL_ENV,
+	REMOTE_ENGINE_CLIENT_API_KEY_ENV,
+] as const;
+
+/** Where the resolved mode came from, in precedence order. */
+export type ProviderEngineModeSource = "engine" | "env" | "option" | "default";
+
+/**
+ * Non-fatal conditions worth reporting at boot:
+ * - `invalid_env_value`: `APIFUSE__ENGINE__MODE` held an unrecognized value.
+ * - `env_overrode_option`: the manifest and the host code disagreed; the manifest won.
+ * - `engine_object_overrode_requested_mode`: an explicit engine object cannot honour the requested mode.
+ * - `engine_env_ignored`: remote-only engine env is projected but the mode is not
+ *   remote (not reported for a host-supplied engine, which may consume it itself).
+ */
+export type ProviderEngineModeWarning =
+	| "invalid_env_value"
+	| "env_overrode_option"
+	| "engine_object_overrode_requested_mode"
+	| "engine_env_ignored";
+
+export interface ProviderEngineModeResolution {
+	readonly mode: ProviderEngineMode | "custom";
+	readonly source: ProviderEngineModeSource;
+	/** True for every non-remote attachment, whose removal is scheduled by ADR-0011. */
+	readonly deprecated: boolean;
+	readonly warnings: readonly ProviderEngineModeWarning[];
+}
+
+export interface ProviderEngineModeResolutionInput {
+	/** Explicit `engineMode` option passed by the host process. */
+	readonly option?: ProviderEngineMode;
+	/** Explicit engine object passed by the host; used as given when present. */
+	readonly engine?: Pick<ProviderEngine, "kind">;
+	/** Environment to read the engine env from; defaults to `process.env`. */
+	readonly environment?: Readonly<Record<string, string | undefined>>;
+}
+
+function isKnownMode(value: string): value is (typeof KNOWN_PROVIDER_ENGINE_MODES)[number] {
+	return (KNOWN_PROVIDER_ENGINE_MODES as readonly string[]).includes(value);
+}
+
+function normalize(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim().toLowerCase();
+	return trimmed === "" ? undefined : trimmed;
+}
+
+/**
+ * Resolve the engine attachment mode once at boot.
+ *
+ * Precedence: an explicit `engine` object, then `APIFUSE__ENGINE__MODE`, then the
+ * `engineMode` option, then the default. The manifest outranks the option so
+ * provider code cannot silently downgrade what the deployment asked for; every
+ * disagreement is reported in `warnings` with a truthful `source` rather than
+ * being dropped.
+ *
+ * Deployment-authored input is never fatal (an unrecognized env value is warned
+ * about and ignored). A malformed `engineMode` option is a fault in the calling
+ * code, which no manifest can reach, so it throws.
+ */
+export function resolveProviderEngineMode(
+	input: ProviderEngineModeResolutionInput = {},
+): ProviderEngineModeResolution {
+	const environment = input.environment ?? process.env;
+	const warnings: ProviderEngineModeWarning[] = [];
+
+	// Read directly: this is a mode name, not a credential, so it must not be
+	// registered with the diagnostic redactor the way readDiagnosticEnv is.
+	const rawEnv = normalize(environment[PROVIDER_ENGINE_MODE_ENV]);
+	let envMode: ProviderEngineMode | undefined;
+	if (rawEnv !== undefined) {
+		if (isKnownMode(rawEnv)) envMode = rawEnv;
+		else warnings.push("invalid_env_value");
+	}
+
+	const optionMode = normalize(input.option);
+	if (input.option !== undefined && (optionMode === undefined || !isKnownMode(optionMode))) {
+		throw new ValidationError(
+			`Invalid engineMode option "${String(input.option)}"; expected ${KNOWN_PROVIDER_ENGINE_MODES.join(" or ")}`,
+			{ fix: 'Pass engineMode: "in-process" | "remote", or omit it to use the default.' },
+		);
+	}
+	if (optionMode !== undefined && envMode !== undefined && optionMode !== envMode) {
+		warnings.push("env_overrode_option");
+	}
+
+	const requested = envMode ?? optionMode;
+	const requestedSource: ProviderEngineModeSource | undefined =
+		envMode !== undefined ? "env" : optionMode !== undefined ? "option" : undefined;
+
+	// Normalized like every other mode input: an un-normalized host `kind` would
+	// reach the boot event and /readyz verbatim and mis-score the fleet audit.
+	const engineKind =
+		input.engine === undefined ? undefined : (normalize(input.engine.kind) ?? "custom");
+	if (engineKind !== undefined) {
+		if (requested !== undefined && engineKind !== requested) {
+			warnings.push("engine_object_overrode_requested_mode");
+		}
+		return finalize(engineKind, "engine", environment, warnings);
+	}
+
+	return finalize(
+		requested ?? DEFAULT_PROVIDER_ENGINE_MODE,
+		requestedSource ?? "default",
+		environment,
+		warnings,
+	);
+}
+
+function finalize(
+	mode: ProviderEngineMode | "custom",
+	source: ProviderEngineModeSource,
+	environment: Readonly<Record<string, string | undefined>>,
+	warnings: ProviderEngineModeWarning[],
+): ProviderEngineModeResolution {
+	// Presence of the remote engine env never selects a mode (the manifest
+	// generator projects it fleet-wide before the SDK can use it), but staying
+	// silent about it would hide a half-applied cutover. Skipped for a host-supplied
+	// engine: that object may be a remote client that consumes the env itself, so
+	// claiming the env is unused would be a false report.
+	if (
+		mode !== "remote" &&
+		source !== "engine" &&
+		REMOTE_ONLY_ENGINE_ENV_NAMES.some((name) => normalize(environment[name]) !== undefined)
+	) {
+		warnings.push("engine_env_ignored");
+	}
+	// Fail-closed for the ADR-0011 audit: everything that is not the remote lane
+	// still attaches capabilities inside the pod process and is scheduled for
+	// removal, including an opaque host engine that declares no kind.
+	return { mode, source, deprecated: mode !== "remote", warnings };
+}
+
+const UNAVAILABLE_ENGINES = new WeakSet<ProviderEngine>();
+
+/** True when the engine cannot attach, so readiness must report the process as unready. */
+export function isUnavailableProviderEngine(engine: ProviderEngine): boolean {
+	return UNAVAILABLE_ENGINES.has(engine);
+}
+
+/**
+ * Engine that refuses every attachment with `reason`.
+ *
+ * Requesting a mode this release cannot serve must not crash the process: the SDK
+ * answers a structured error per request and reports the process unready, the same
+ * trade-off `provider_secrets_missing` already makes at boot. Non-retryable, so a
+ * caller-side retry loop cannot turn a configuration fault into load.
+ */
+export function createUnavailableProviderEngine(
+	kind: ProviderEngineMode,
+	reason: { message: string; code: string; fix: string },
+): ProviderEngine {
+	const engine: ProviderEngine = {
+		kind,
+		attach: () => {
+			throw new ProviderError(reason.message, {
+				code: reason.code,
+				retryable: false,
+				fix: reason.fix,
+			});
+		},
+	};
+	UNAVAILABLE_ENGINES.add(engine);
+	return engine;
+}
+
+/**
+ * Engine for a resolved mode. `remote` has no client in this release, so it
+ * resolves to an engine that fails every request instead of falling back to
+ * in-process (ADR-0011 Pitfall 2: in-process is never a fallback).
+ */
+export function createEngineForMode(mode: ProviderEngineMode | "custom"): ProviderEngine {
+	// Default-deny on the mode name, not just on "remote": the mode union is open
+	// so a later lane can be named, and falling through to in-process for an
+	// unserved lane is the silent downgrade ADR-0011 Pitfall 2 forbids.
+	if (mode === DEFAULT_PROVIDER_ENGINE_MODE) return createInProcessProviderEngine();
+	return createUnavailableProviderEngine(mode, {
+		message: `Provider engine mode "${mode}" was requested but this @apifuse/provider-sdk release only serves the ${DEFAULT_PROVIDER_ENGINE_MODE} engine`,
+		code: "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+		fix: `Unset ${PROVIDER_ENGINE_MODE_ENV} (or the engineMode option), or upgrade to a release that serves this mode.`,
+	});
+}
+
+/**
+ * Fail fast for the CLIs (`apifuse dev`, `apifuse record`). They are developer
+ * tools, not pods: an unusable mode should stop the command rather than start a
+ * server that refuses every request.
+ */
+export function assertProcessEngineModeSupported(
+	environment: Readonly<Record<string, string | undefined>> = process.env,
+): ProviderEngineModeResolution {
+	const resolution = resolveProviderEngineMode({ environment });
+	if (resolution.mode !== DEFAULT_PROVIDER_ENGINE_MODE) {
+		throw new ProviderError(
+			`Provider engine mode "${resolution.mode}" was requested but this @apifuse/provider-sdk release only serves the ${DEFAULT_PROVIDER_ENGINE_MODE} engine`,
+			{
+				code: "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+				retryable: false,
+				details: { mode: resolution.mode, source: resolution.source },
+				fix: `Unset ${PROVIDER_ENGINE_MODE_ENV}, or upgrade to a release that serves this mode.`,
+			},
+		);
+	}
+	return resolution;
+}

package/src/runtime/env.ts

@@ -1,13 +1,27 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { isEngineOwnedEnvName } from "../engine.js";
 import type { EnvContext } from "../types.js";
 
+/**
+ * A mixed-case spelling of an engine-owned name is an alias: on Windows it resolves to the
+ * engine's variable while evading an exact-name allowlist. Only the exact (upper-case) name,
+ * which engine-internal contexts allowlist explicitly, may read those values.
+ */
+function isEngineOwnedEnvAlias(key: string): boolean {
+	return isEngineOwnedEnvName(key) && key !== key.toUpperCase();
+}
+
 export function createEnvContext(allowedKeys?: string[]): EnvContext {
 	return {
 		get(key: string): string | undefined {
 			if (allowedKeys && !allowedKeys.includes(key)) {
 				return undefined;
 			}
+			if (isEngineOwnedEnvAlias(key)) {
+				return undefined;
+			}
 
-			return process.env[key];
+			return readDiagnosticEnv(key);
 		},
 	};
 }