@apifuse/provider-sdk 2.2.0-beta.57 → 2.2.0-beta.59

package/src/engine.ts

@@ -1,4 +1,10 @@
 import { ProviderError } from "./errors.js";
+import {
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
+} from "./runtime/resolver-config.js";
 import {
 	OTEL_EXPORTER_OTLP_ENDPOINT,
 	OTEL_EXPORTER_OTLP_HEADERS,
@@ -55,6 +61,36 @@ export function isEngineOwnedProxyCredentialName(name: string): boolean {
 	return ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET.has(canonicalEnvName(name));
 }
 
+/** Hosted resolver credentials owned by the engine and never projected to providers. */
+export const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES = [
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
+] as const;
+
+const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET = new Set<string>(
+	ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES,
+);
+
+/**
+ * Engine variable a provider-declared secret name resolves to, or `undefined` when the
+ * name is not an engine-owned resolver credential. Provider-scoped Hyper aliases
+ * (`APIFUSE__PROVIDER__<ID>__HYPER_API_KEY`, measured on zozotown) map to the shared key.
+ */
+export function engineOwnedResolverCredentialTarget(name: string): string | undefined {
+	const canonical = canonicalEnvName(name);
+	if (ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET.has(canonical)) return canonical;
+	if (/^APIFUSE__PROVIDER__.+__HYPER_API_KEY$/u.test(canonical)) {
+		return APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY;
+	}
+	return undefined;
+}
+
+export function isEngineOwnedResolverCredentialName(name: string): boolean {
+	return engineOwnedResolverCredentialTarget(name) !== undefined;
+}
+
 /**
  * Trace-export configuration owned by the engine and forbidden in provider
  * declarations. The header variables carry collector credentials; the rest are
@@ -75,9 +111,47 @@ export function isEngineOwnedTelemetryEnvName(name: string): boolean {
 	return ENGINE_OWNED_TELEMETRY_ENV_NAME_SET.has(canonicalEnvName(name));
 }
 
+/** Engine control-plane configuration is never declarable or visible to provider code. */
+function isEngineOwnedEngineEnvName(name: string): boolean {
+	return canonicalEnvName(name).startsWith("APIFUSE__ENGINE__");
+}
+
+/**
+ * Hosted runtime settings the engine reads for OCR, STT, cache keying, choice
+ * tokens, and the CDP pool. Providers never own them: declarations are rejected
+ * and projections drop them, like the vendor credentials above.
+ */
+export const ENGINE_OWNED_RUNTIME_ENV_NAMES = [
+	"APIFUSE__STT__CLOUDFLARE_API_TOKEN",
+	"APIFUSE__OCR__CLOUDFLARE_API_TOKEN",
+	"APIFUSE__OCR__API_KEY",
+	"APIFUSE__CLOUDFLARE__ACCOUNT_ID",
+	"APIFUSE__CACHE__KEY_PEPPER",
+	"APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET",
+] as const;
+
+const ENGINE_OWNED_RUNTIME_ENV_NAME_SET = new Set<string>(ENGINE_OWNED_RUNTIME_ENV_NAMES);
+
+/** CDP pool settings form a prefix family (`APIFUSE__CDP_POOL__URL` today); the whole prefix is engine-owned. */
+const ENGINE_OWNED_CDP_POOL_ENV_PREFIX = "APIFUSE__CDP_POOL__";
+
+export function isEngineOwnedRuntimeEnvName(name: string): boolean {
+	const canonical = canonicalEnvName(name);
+	return (
+		ENGINE_OWNED_RUNTIME_ENV_NAME_SET.has(canonical) ||
+		canonical.startsWith(ENGINE_OWNED_CDP_POOL_ENV_PREFIX)
+	);
+}
+
 /** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
 export function isEngineOwnedEnvName(name: string): boolean {
-	return isEngineOwnedProxyCredentialName(name) || isEngineOwnedTelemetryEnvName(name);
+	return (
+		isEngineOwnedEngineEnvName(name) ||
+		isEngineOwnedProxyCredentialName(name) ||
+		isEngineOwnedResolverCredentialName(name) ||
+		isEngineOwnedRuntimeEnvName(name) ||
+		isEngineOwnedTelemetryEnvName(name)
+	);
 }
 
 /** Capture credentials in the engine host before constructing provider bindings. */
@@ -199,6 +273,7 @@ function declaresCapability(
 	provider: ProviderDefinition,
 	capability: ProviderCapabilityKey,
 ): boolean {
+	if (capability === "credential" && provider.auth?.mode === "platform-managed") return true;
 	return Object.hasOwn(provider, capability) && provider[capability] !== undefined;
 }
 

package/src/error-resolution.ts

@@ -10,6 +10,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"BROWSER_CDP_POOL_REQUIRED",
 	"BROWSER_RUNTIME_UNSUPPORTED",
 	"STEALTH_RUNTIME_UNSUPPORTED",
+	"STEALTH_HEADER_OVERRIDE_UNSUPPORTED",
 	"SSE_EVENT_UNDECLARED",
 	"STREAM_EVENT_TOO_LARGE",
 	"STREAM_CHUNK_TOO_LARGE",
@@ -51,6 +52,13 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"http_redirect_missing_location",
 	"http_redirect_loop",
 	"transport_invalid_url",
+	"EGRESS_LEASE_INVALID",
+	"EGRESS_LEASE_BINDING_INVALID",
+	"EGRESS_LEASE_KEY_MISSING",
+	"EGRESS_LEASE_KEY_WEAK",
+	"STEALTH_BODY_UNSUPPORTED",
+	"REPLAY_SESSION_MISMATCH",
+	"REPLAY_ALREADY_ATTEMPTED",
 	"retry_exhausted",
 	"auth_abort_unsafe_data",
 	"credentials_auth_missing_credential_keys",
@@ -117,6 +125,11 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		// contract): the upstream evaluated the request and said no under its
 		// own rules — a conflict with upstream state, never a 5xx.
 		["UPSTREAM_REJECTED", 409],
+		// Only an unverifiable or foreign handle is the caller's: key and binding
+		// faults stay unmapped (500) because the engine host, not the caller, owns them.
+		["EGRESS_LEASE_INVALID", 409],
+		["REPLAY_SESSION_MISMATCH", 409],
+		["REPLAY_ALREADY_ATTEMPTED", 409],
 		["UPSTREAM_ERROR", 502],
 		["BLOCKED", 502],
 		["OCR_UNAVAILABLE", 503],

package/src/index.ts

@@ -198,17 +198,43 @@ export {
 	type TelemetryKey,
 	type TenantNeutral,
 } from "./runtime/request-telemetry.js";
+export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
+export {
+	ResolverTelemetryCollector,
+	type ResolverCacheReadTelemetryEvent,
+	type ResolverCacheWriteTelemetryEvent,
+	type ResolverFailoverTelemetryEvent,
+	type ResolverIdentityTelemetryEvent,
+	type ResolverOutcomeTelemetryEvent,
+	type ResolverTelemetryAttemptOutcome,
+	type ResolverAttemptSample,
+	type ResolverTelemetryCacheStatus,
+	type ResolverTelemetryCacheWriteReason,
+	type ResolverTelemetryErrorClass,
+	type ResolverTelemetryHeaderPayload,
+	type ResolverTelemetryIdentitySource,
+	type ResolverTelemetryLogPayload,
+	type ResolverTelemetryOutcome,
+	type ResolverTelemetryPhase,
+	type ResolverTelemetrySink,
+	type ResolverVendorAttemptTelemetryEvent,
+} from "./runtime/resolver-telemetry.js";
 export {
 	APIFUSE__CDP_POOL__URL,
 	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
 	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
 	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
 	APIFUSE__RESOLVER__TIMEOUT_MS,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
-export type { ResolverVendorTransport } from "./runtime/resolver-vendors/types.js";
+export type {
+	ResolverPaidUsageContext,
+	ResolverVendorTransport,
+	ResolverVendorUnavailableReason,
+} from "./runtime/resolver-vendors/types.js";
 export {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -250,6 +276,8 @@ export {
 	type TraceContext,
 } from "./runtime/trace.js";
 export {
+	APIFUSE_CONTENT_PROVENANCE_META_KEY,
+	APIFUSE_CONTENT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
@@ -264,6 +292,7 @@ export {
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
+	untrustedContent,
 	z,
 } from "./schema.js";
 export {
@@ -432,6 +461,7 @@ export type {
 	ProviderRuntimeTarget,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
+	ProviderStealthConfig,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderStreamEvent,
@@ -455,6 +485,7 @@ export type {
 	StateWriteOptions,
 	StealthClient,
 	StealthBrowser,
+	StealthChallengeClassification,
 	StealthCookieStore,
 	StealthCookieStoreV1,
 	StealthFetchOptions,

package/src/lint.ts

@@ -398,7 +398,7 @@ function lintAuthModel(provider: {
 			rule: "platform-managed-no-credential-keys",
 			level: "error",
 			field: "credential.keys",
-			message: `${providerLabel} must not declare credential.keys for platform-managed auth mode.`,
+			message: `${providerLabel} must not declare credential.keys because platform-managed auth mode already implies the unfiltered credential capability.`,
 		});
 	}
 
@@ -1032,9 +1032,9 @@ function browserVersionLiteralMessage(finding: BrowserVersionLiteralFinding): st
 		case "profile":
 			return `Hardcoded stealth profile "${finding.literal}" pins a browser version and will rot. Select the browser and OS structurally, for example stealth: { browser: "chrome", os: "macos" }.`;
 		case "user-agent":
-			return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal and derive it from the structured profile, for example getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
+			return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal. ctx.stealth owns User-Agent and rejects a caller value with STEALTH_HEADER_OVERRIDE_UNSUPPORTED, so omit the header there and select the profile with stealth: { browser: "chrome", os: "macos" }. For ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
 		case "sec-ch-ua":
-			return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }; derive any explicit User-Agent with getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
+			return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }. ctx.stealth also owns User-Agent, so omit that header there as well; for ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
 	}
 }
 

package/src/provider.ts

@@ -133,9 +133,13 @@ export {
 	createProviderEnvironment,
 	createInProcessProviderEngine,
 	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_RUNTIME_ENV_NAMES,
 	ENGINE_OWNED_TELEMETRY_ENV_NAMES,
 	isEngineOwnedEnvName,
 	isEngineOwnedProxyCredentialName,
+	isEngineOwnedResolverCredentialName,
+	isEngineOwnedRuntimeEnvName,
 	isEngineOwnedTelemetryEnvName,
 	PROVIDER_CAPABILITY_KEYS,
 	PROVIDER_ENGINE_PROTOCOL_VERSION,
@@ -164,6 +168,8 @@ export {
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 } from "./runtime/choice.js";
 export {
+	APIFUSE_CONTENT_PROVENANCE_META_KEY,
+	APIFUSE_CONTENT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
@@ -178,6 +184,7 @@ export {
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
+	untrustedContent,
 	z,
 } from "./schema.js";
 export type {
@@ -261,6 +268,7 @@ export type {
 	ProviderResolvedFile,
 	ProviderRuntimeTarget,
 	ProviderRuntimeState,
+	ProviderStealthConfig,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderSupportLevel,
@@ -273,6 +281,7 @@ export type {
 	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
+	StealthChallengeClassification,
 } from "./types.js";
 export {
 	NativeEgressGrantExpiredError,

package/src/runtime/bounded-expiring-map.ts

@@ -0,0 +1,67 @@
+/**
+ * Map whose entries carry an expiry and whose size is capped.
+ *
+ * Expired entries are dropped when read and swept on every insert, so a
+ * process that keeps minting new keys does not retain dead values. When the
+ * cap is still exceeded after the sweep, the least recently used entry is
+ * evicted and counted in `capacityEvictions` so callers can tell the two
+ * kinds of removal apart. Callers pass `now` explicitly so a single timestamp
+ * is used across a lookup-then-store sequence.
+ */
+export class BoundedExpiringMap<K, V> {
+	readonly #entries = new Map<K, V>();
+	readonly #maxEntries: number;
+	readonly #expiresAt: (value: V) => number;
+	#capacityEvictions = 0;
+
+	constructor(maxEntries: number, expiresAt: (value: V) => number) {
+		if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+			throw new RangeError("maxEntries must be a positive integer");
+		}
+		this.#maxEntries = maxEntries;
+		this.#expiresAt = expiresAt;
+	}
+
+	get size(): number {
+		return this.#entries.size;
+	}
+
+	/** Entries removed to satisfy `maxEntries`; expiry removals are not counted. */
+	get capacityEvictions(): number {
+		return this.#capacityEvictions;
+	}
+
+	get(key: K, now: number): V | undefined {
+		if (!this.#entries.has(key)) return undefined;
+		const value = this.#entries.get(key) as V;
+		this.#entries.delete(key);
+		if (this.#expiresAt(value) <= now) return undefined;
+		// Re-insert so Map iteration order doubles as the LRU order.
+		this.#entries.set(key, value);
+		return value;
+	}
+
+	set(key: K, value: V, now: number): void {
+		for (const [existingKey, existing] of this.#entries) {
+			if (this.#expiresAt(existing) <= now) this.#entries.delete(existingKey);
+		}
+		this.#entries.delete(key);
+		if (this.#expiresAt(value) <= now) return;
+		this.#entries.set(key, value);
+		if (this.#entries.size > this.#maxEntries) {
+			const oldest = this.#entries.keys().next();
+			if (!oldest.done) {
+				this.#entries.delete(oldest.value);
+				this.#capacityEvictions += 1;
+			}
+		}
+	}
+
+	delete(key: K): boolean {
+		return this.#entries.delete(key);
+	}
+
+	clear(): void {
+		this.#entries.clear();
+	}
+}

package/src/runtime/cache.ts

@@ -589,6 +589,13 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 	};
 }
 
+const bypassCaches = new WeakSet<ProviderCache>();
+
+/** Internal cache capability, separate from hit/miss metadata. */
+export function isProviderCacheBypassed(cache: ProviderCache): boolean {
+	return bypassCaches.has(cache);
+}
+
 export function createBypassProviderCache(
 	options: Pick<ProviderCacheOptions, "providerId">,
 ): ProviderCache {
@@ -597,7 +604,7 @@ export function createBypassProviderCache(
 	const events: ProviderCacheLookupMeta[] = [];
 	const secretScopedKeys = new Set<string>();
 
-	return {
+	const cache: ProviderCache = {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
 			const normalized = normalizeKeyPart(parts, extra, pepper);
@@ -643,6 +650,8 @@ export function createBypassProviderCache(
 			};
 		},
 	};
+	bypassCaches.add(cache);
+	return cache;
 }
 
 export function resetProviderCacheForTests(): void {