@apifuse/provider-sdk 2.2.0-beta.12 → 2.2.0-beta.13

package/dist/types.d.ts

@@ -699,6 +699,12 @@ export interface ProviderProxyPolicy {
         affinity?: ProviderProxySessionAffinity;
         lifetimeMinutes?: number;
         poolSize?: number;
+        /**
+         * Seconds before hard sticky expiry at which native connections receive
+         * the `expiring` event so the provider can drain and reconnect cleanly.
+         * Declared by the provider; the SDK does not assume a default cut point.
+         */
+        drainLeadSeconds?: number;
     };
 }
 export type ProviderProxyConfig = boolean | ProviderProxyPolicy;
@@ -840,6 +846,11 @@ export interface HttpRetrySummary {
 export interface RequestOptions {
     headers?: Record<string, string>;
     params?: RequestParams;
+    /**
+     * Query parameters whose values contain credentials or other secret material.
+     * They are sent like `params`, but redacted from SDK errors, traces, and recorded fixtures.
+     */
+    sensitiveParams?: Record<string, string>;
     proxy?: string;
     timeout?: number;
     /**
@@ -854,6 +865,12 @@ export interface StealthFetchOptions extends RequestOptions {
     method?: HttpMethod;
     body?: string | Buffer;
     redirect?: "follow" | "manual" | "error";
+    /**
+     * Maximum decoded response-body bytes to buffer. When set, the stealth
+     * transport aborts the response and throws `response_too_large` if the
+     * declared or streamed body exceeds this limit.
+     */
+    maxBodyBytes?: number;
     /**
      * Offsets policy-managed proxy pool selection for caller-managed retries.
      * Use when a request receives an upstream challenge page rather than a
@@ -1020,6 +1037,139 @@ export interface HttpClient {
     stream(url: string, options?: RequestWithMethodOptions): Promise<HttpStreamResponse>;
     sse(url: string, options?: RequestWithMethodOptions): Promise<AsyncIterable<SseMessage>>;
 }
+/** Request-scoped file reference accepted by provider operation inputs. */
+export interface ProviderFileRef {
+    readonly type: "request_file";
+    readonly id: string;
+    readonly filename: string;
+    readonly mime_type?: string;
+    readonly size: number;
+    readonly sha256?: string;
+}
+/** File body resolved from a request-scoped {@link ProviderFileRef}. */
+export type ProviderResolvedFile = Omit<ProviderFileRef, "mime_type"> & {
+    readonly mimeType?: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    stream(): ReadableStream<Uint8Array>;
+};
+/** Resolver supplied by runtimes that accept request-scoped file inputs. */
+export interface ProviderFilesContext {
+    has(input: string | ProviderFileRef): boolean;
+    resolve(input: string | ProviderFileRef): Promise<ProviderResolvedFile>;
+}
+export type NativeTcpTlsMode = "required" | "allowed" | "disabled";
+export interface NativeTcpPortRange {
+    readonly start: number;
+    readonly end: number;
+}
+/** Static native TCP egress declared by a provider. */
+export interface NativeTcpEgressRule {
+    readonly host: string;
+    readonly ports: readonly number[];
+    readonly tls: NativeTcpTlsMode;
+}
+/**
+ * Bounded native TCP egress discovered through a declared bootstrap endpoint.
+ * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ */
+export interface NativeTcpDynamicEgressRule {
+    readonly sourceHost?: string;
+    readonly sourceHostSuffixes?: readonly string[];
+    readonly sourcePorts?: readonly number[];
+    readonly sourcePortRanges?: readonly NativeTcpPortRange[];
+    readonly targetHostSuffixes: readonly string[];
+    readonly targetPorts?: readonly number[];
+    readonly targetPortRanges?: readonly NativeTcpPortRange[];
+    readonly tls: NativeTcpTlsMode;
+    readonly ttlMs?: number;
+    readonly maxGrants?: number;
+}
+/** Common TCP/TLS connection input supported by the native runtime. */
+export interface NativeNetworkConnectInput {
+    readonly host: string;
+    readonly port: number;
+    readonly serverName?: string;
+    readonly rejectUnauthorized?: boolean;
+    /**
+     * Maximum time without a successful socket read before the connection is
+     * closed. Opt-in; when absent, reads can remain pending indefinitely.
+     */
+    readonly idleTimeoutMs?: number;
+    /** Maximum time allowed to establish the TCP/SOCKS/TLS connection. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Overrides the credential-derived sticky affinity key. */
+    readonly affinityKey?: string;
+}
+export type NativeNetworkConnectOptions = Omit<NativeNetworkConnectInput, "serverName" | "rejectUnauthorized">;
+export type NativeTlsConnectOptions = NativeNetworkConnectInput;
+export interface NativeNetworkDynamicGrantOptions {
+    readonly sourceHost: string;
+    readonly sourcePort: number;
+    readonly host: string;
+    readonly port: number;
+    readonly tls: NativeTcpTlsMode;
+    readonly ttlMs?: number;
+}
+export interface NativeNetworkEgressGrant {
+    revoke(): void;
+}
+/** Consumer-facing alias used by native TCP providers. */
+export type NativeTcpEgressGrant = NativeNetworkEgressGrant;
+/** Resolved egress identity for a native connection routed through a proxy. */
+export interface NativeProxyEgressInfo {
+    readonly vendor: ProviderProxyProvider;
+    readonly sticky: boolean;
+    /** Vendor sticky session id (sid). Absent for rotating sessions. */
+    readonly sessionId?: string;
+    /** Hard expiry of the sticky binding, ISO 8601. */
+    readonly expiresAt?: string;
+}
+export type NativeProxyExpiringReason = "sticky_expiry";
+export interface NativeProxyExpiringEvent {
+    readonly expiresAt: string;
+    readonly leadSeconds: number;
+    readonly reason: NativeProxyExpiringReason;
+}
+/**
+ * Cooperative drain handler. The SDK awaits this before closing a socket whose
+ * sticky proxy binding is about to expire, then force-closes at hard expiry.
+ */
+export type NativeProxyDrainHandler = (event: NativeProxyExpiringEvent) => void | Promise<void>;
+/** Typed reason recorded when the SDK closes a native connection intentionally. */
+export interface NativeNetworkCloseReason {
+    readonly code: string;
+    readonly message: string;
+}
+/** Byte-oriented connection returned by the native TCP/TLS runtime. */
+export interface NativeNetworkConnection {
+    /** Present when the connection was routed through a proxy. */
+    readonly proxy?: NativeProxyEgressInfo;
+    /** Present after an SDK-planned close, such as sticky proxy expiry. */
+    readonly closeReason?: NativeNetworkCloseReason;
+    /** Register a cooperative drain handler for sticky-expiry reconnects. */
+    onExpiring?(handler: NativeProxyDrainHandler): void;
+    read(): Promise<Uint8Array | null>;
+    write(data: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+}
+export interface NativeNetworkClient {
+    connectTcp(input: NativeNetworkConnectOptions): Promise<NativeNetworkConnection>;
+    connectTls(input: NativeTlsConnectOptions): Promise<NativeNetworkConnection>;
+    grantTcpEgress(input: NativeNetworkDynamicGrantOptions): NativeNetworkEgressGrant;
+}
+export interface NativeContext {
+    readonly network: NativeNetworkClient;
+}
+/** Consumer-facing alias for the native capability on provider contexts. */
+export type NativeProviderContext = NativeContext;
+export interface NativeProviderConfig {
+    readonly network?: {
+        readonly tcp?: readonly NativeTcpEgressRule[];
+        readonly dynamicTcp?: readonly NativeTcpDynamicEgressRule[];
+    };
+}
 export interface ProviderCacheKeyOptions {
     /**
      * Additional field names to omit from stable key material. The SDK always
@@ -1351,6 +1501,8 @@ export interface FlowContext {
     tenantId: string;
     providerId: string;
     http: HttpClient;
+    /** Present when the selected runtime supplies native network capabilities. */
+    readonly native?: NativeProviderContext;
     stealth: StealthClient;
     env: EnvContext;
     credential?: CredentialContext;
@@ -1436,6 +1588,10 @@ export interface ProviderContext {
     credential: CredentialContext;
     request?: ProviderRequestContext;
     http: HttpClient;
+    /** Present for requests carrying runtime-resolvable file references. */
+    readonly files?: ProviderFilesContext;
+    /** Present when the selected runtime supplies native network capabilities. */
+    readonly native?: NativeProviderContext;
     cache: ProviderCache;
     state: ProviderRuntimeState;
     stealth: StealthClient;
@@ -1512,6 +1668,11 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
     fixtures?: {
         request: InferSchemaOutput<TInput>;
         response: InferSchemaOutput<TOutput>;
+        /**
+         * KST calendar date when `response` evidence was captured. Date fields in
+         * the response align with this date, not a resolved relative request date.
+         */
+        recordedAt?: string;
     };
     upstream?: {
         baseUrl?: string;
@@ -1570,6 +1731,7 @@ export interface ProviderDefinition {
      */
     deployment?: ProviderDeploymentOverrides;
     allowedHosts?: string[];
+    native?: NativeProviderConfig;
     stealth?: {
         profile: string;
         platform: StealthPlatform;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.12",
+	"version": "2.2.0-beta.13",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -114,6 +114,7 @@
 		"puppeteer-extra-plugin-stealth": "^2.11.2",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
+		"socks": "^2.8.9",
 		"tough-cookie": "^6.0.2",
 		"zod": "^4.4.3"
 	},

package/src/define.ts

@@ -2,6 +2,7 @@ import ms from "ms";
 
 import { ProviderError, ValidationError } from "./errors.js";
 import { safeParseSchemaSync } from "./schema.js";
+import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
 import type {
 	AuthConfig,
 	BrowserEngine,
@@ -20,6 +21,7 @@ import type {
 	OperationSseTransport,
 	OperationTransport,
 	OperationWebSocketTransport,
+	NativeProviderConfig,
 	ProviderAccessConfig,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
@@ -205,6 +207,7 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	 */
 	deployment?: ProviderDeploymentOverrides;
 	allowedHosts?: string[];
+	native?: NativeProviderConfig;
 	stealth?: {
 		profile: string;
 		platform: StealthPlatform;
@@ -437,7 +440,7 @@ function validateProviderProxy(config: {
 		}
 		rejectUnknownFields(
 			proxy.session,
-			new Set(["affinity", "lifetimeMinutes", "poolSize"]),
+			new Set(["affinity", "lifetimeMinutes", "poolSize", "drainLeadSeconds"]),
 			"proxy.session",
 		);
 		if (proxy.session.affinity !== undefined) {
@@ -460,6 +463,34 @@ function validateProviderProxy(config: {
 				`Provider "${config.id}" has invalid proxy.session.poolSize: must be a positive integer.`,
 			);
 		}
+		const drainLeadSeconds = proxy.session.drainLeadSeconds;
+		if (
+			drainLeadSeconds !== undefined &&
+			(!Number.isFinite(drainLeadSeconds) || drainLeadSeconds <= 0)
+		) {
+			throw new ValidationError(
+				`Provider "${config.id}" has invalid proxy.session.drainLeadSeconds: must be a positive number of seconds.`,
+				{
+					fix: `Use proxy.session.drainLeadSeconds: 120 to receive the sticky-expiry drain event 120s before hard expiry.`,
+				},
+			);
+		}
+		// A drain lead longer than the sticky lifetime would fire the expiring
+		// event before the session is even established, so the provider would
+		// never get a usable window. Reject the contradiction at build time.
+		if (
+			drainLeadSeconds !== undefined &&
+			lifetime !== undefined &&
+			Number.isFinite(lifetime) &&
+			drainLeadSeconds >= lifetime * 60
+		) {
+			throw new ValidationError(
+				`Provider "${config.id}" has proxy.session.drainLeadSeconds (${drainLeadSeconds}s) greater than or equal to proxy.session.lifetimeMinutes (${lifetime}m).`,
+				{
+					fix: `Lower drainLeadSeconds below the sticky lifetime so the drain event leaves a usable session window.`,
+				},
+			);
+		}
 	}
 	// Every credentialed vendor in a required-mode chain must declare its
 	// provider secret(s) so a missing credential fails at build/validation time,
@@ -2040,6 +2071,26 @@ function validateOperationFixtures(
 					fix: `Add operations.${operationName}.handler as an async function with signature (ctx, input) => Promise<output>`,
 				},
 			);
+		if (operation.fixtures?.recordedAt !== undefined) {
+			const recordedAt = operation.fixtures.recordedAt;
+			const parsed =
+				typeof recordedAt === "string"
+					? new Date(`${recordedAt}T00:00:00.000Z`)
+					: new Date(Number.NaN);
+			const isCalendarDate =
+				typeof recordedAt === "string" &&
+				/^\d{4}-\d{2}-\d{2}$/.test(recordedAt) &&
+				!Number.isNaN(parsed.getTime()) &&
+				parsed.toISOString().slice(0, 10) === recordedAt;
+			const kstToday = new Date(Date.now() + 9 * 60 * 60 * 1000).toISOString().slice(0, 10);
+			if (!isCalendarDate || recordedAt > kstToday)
+				throw new ValidationError(
+					`Fixture recordedAt must be a valid, non-future KST calendar date for provider "${providerId}" operation "${operationName}"`,
+					{
+						fix: `Set operations.${operationName}.fixtures.recordedAt to the KST capture date in YYYY-MM-DD format; it must not be in the future.`,
+					},
+				);
+		}
 		if (operation.fixtures?.request !== undefined) {
 			const result = safeParseSchemaSync(
 				operation.input,
@@ -2073,6 +2124,31 @@ function validateOperationFixtures(
 	}
 }
 
+function resolveOperationFixtureRequests<TOperations extends Record<string, ProviderOperation>>(
+	operations: TOperations,
+): TOperations {
+	let changed = false;
+	const resolvedOperations = Object.fromEntries(
+		Object.entries(operations).map(([operationName, operation]) => {
+			if (operation.fixtures?.request === undefined) return [operationName, operation];
+			const request = resolveHealthCheckInputDateTokens(operation.fixtures.request);
+			if (request === operation.fixtures.request) return [operationName, operation];
+			changed = true;
+			return [
+				operationName,
+				{
+					...operation,
+					fixtures: {
+						...operation.fixtures,
+						request,
+					},
+				},
+			];
+		}),
+	) as TOperations;
+	return changed ? resolvedOperations : operations;
+}
+
 /**
  * Shallow shape guard only: the `deployment` object is passed through
  * verbatim and deliberately not deep-validated by the SDK — the APIFuse
@@ -2093,6 +2169,7 @@ export function defineProvider<
 	config: TConfig & AuthStartNoInputGuard<TConfig>,
 ): ProviderDefinition & { operations: OperationMapConfig<TOperations> } {
 	validateProviderShape(config);
+	const operations = resolveOperationFixtureRequests(config.operations);
 	if (!CONNECTOR_ID_REGEX.test(config.id))
 		throw new ProviderError(`Invalid provider id: "${config.id}"`, {
 			fix: 'Use lowercase alphanumeric with dashes, e.g., "korea-air-quality"',
@@ -2125,7 +2202,7 @@ export function defineProvider<
 		config.healthProbe ?? config.healthMonitor,
 		config.healthProbe !== undefined ? "healthProbe" : "healthMonitor",
 	);
-	validateOperationFixtures(config.id, config.operations);
+	validateOperationFixtures(config.id, operations);
 	validateProviderDeployment(config.id, config.deployment);
 	validateProviderProxy(config);
 	validateProviderStt(config);
@@ -2149,6 +2226,7 @@ export function defineProvider<
 		// are owned by the APIFuse registry builder, not the SDK.
 		deployment: config.deployment,
 		allowedHosts: config.allowedHosts,
+		native: config.native,
 		stealth: config.stealth,
 		proxy: config.proxy,
 		stt: config.stt,
@@ -2160,7 +2238,7 @@ export function defineProvider<
 		credential: config.credential,
 		context: config.context,
 		meta: config.meta,
-		operations: config.operations,
+		operations,
 		// Transitional healthMonitor → healthProbe alias: mirror whichever field
 		// was declared onto both so old and new consumers keep working.
 		healthMonitor: config.healthMonitor ?? config.healthProbe,

package/src/fixture-sanitization.ts

@@ -0,0 +1,247 @@
+import type { JsonValue } from "./contract-json.js";
+
+export const REDACTED_FIXTURE_VALUE = "[REDACTED]";
+
+const OPAQUE_TOKEN = /^[A-Za-z0-9_+/=.:~-]+$/;
+const OPAQUE_TOKEN_RUN = /[A-Za-z0-9_+/=.:~-]{24,}/g;
+const URL_RUN = /https?:\/\/[^\s"'<>]+/gi;
+const PEM_PRIVATE_KEY =
+	/-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/g;
+
+/** Matches credential field names without treating benign prefixes such as `author` as `auth`. */
+export function isSensitiveFixtureKey(key: string): boolean {
+	const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
+	const candidates = [normalized, normalized.replace(/(?:value|payload|header)$/, "")];
+	return candidates.some(
+		(candidate) =>
+			/^(?:authorization|authentication|auth|bearer|cookie|credential|password|passwd|privatekey|secret|session|sessionid|token)$/.test(
+				candidate,
+			) ||
+			/^(?:api|client|service|access|consumer)(?:key|secret|token)$/.test(candidate) ||
+			/(?:authorization|credential|password|passwd|privatekey|secret|sessionid|token)$/.test(
+				candidate,
+			),
+	);
+}
+
+/**
+ * Returns JSON fixture data with credential-bearing keys and heuristic-confirmed string secrets
+ * replaced. Ordinary short prose and identifiers are retained.
+ */
+export function sanitizeFixture(value: JsonValue): JsonValue {
+	if (Array.isArray(value)) {
+		return value.map((item) => sanitizeFixture(item));
+	}
+
+	if (typeof value === "string") return sanitizeFixtureString(value);
+	if (value === null || typeof value !== "object") return value;
+
+	return Object.fromEntries(
+		Object.entries(value).map(([key, entryValue]) => [
+			key,
+			isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeFixture(entryValue),
+		]),
+	);
+}
+
+/** Applies the shared credential-key policy to ordinary JSON fixtures. */
+export function sanitizeOrdinaryFixture(value: JsonValue): JsonValue {
+	if (Array.isArray(value)) return value.map((item) => sanitizeOrdinaryFixture(item));
+	if (value === null || typeof value !== "object") return value;
+	return Object.fromEntries(
+		Object.entries(value).map(([key, entryValue]) => [
+			key,
+			isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeOrdinaryFixture(entryValue),
+		]),
+	);
+}
+
+/** Sanitizes a primitive fixture string only when textual-secret heuristics match. */
+export function sanitizeFixtureString(value: string): string {
+	let sanitized = value.replace(PEM_PRIVATE_KEY, REDACTED_FIXTURE_VALUE);
+	const retainedUrls: string[] = [];
+	sanitized = sanitized.replace(URL_RUN, (url) => {
+		const index =
+			retainedUrls.push(isCredentialBearingUrl(url) ? sanitizeUrlForLogs(url) : url) - 1;
+		return `APIFUSEURL${index}X`;
+	});
+	sanitized = redactSensitiveAssignments(sanitized);
+	sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate) =>
+		isSensitiveFixtureValue(candidate) ? REDACTED_FIXTURE_VALUE : candidate,
+	);
+	sanitized = sanitized.replace(
+		/APIFUSEURL(\d+)X/g,
+		(_match, index: string) => retainedUrls[Number(index)] ?? REDACTED_FIXTURE_VALUE,
+	);
+	return sanitized;
+}
+
+/** True for opaque values that are unsafe to retain in paths or unstructured text. */
+export function isSensitiveFixtureValue(value: string): boolean {
+	const candidate = decodePathSegment(value);
+	if (/^bot(?:\d{6,}:)?[A-Za-z0-9_-]{16,}$/i.test(candidate)) return true;
+	if (/^\d{6,}:[A-Za-z0-9_-]{20,}$/.test(candidate)) return true;
+	if (/^(?:gh[opusr]_|sk[-_]|xox[baprs]-)[A-Za-z0-9_-]{16,}$/i.test(candidate)) return true;
+	if (!OPAQUE_TOKEN.test(candidate) || candidate.length < 24) return false;
+	if (/^[a-f0-9]{32,}$/i.test(candidate)) return true;
+	return shannonEntropy(candidate) >= 3.5;
+}
+
+/** Sanitizes every path segment and values following a credential-like segment name. */
+export function sanitizePathname(pathname: string): string {
+	const segments = pathname.split("/");
+	return segments
+		.map((segment, index) => {
+			if (!segment) return segment;
+			const decoded = decodePathSegment(segment);
+			const previous = index > 0 ? decodePathSegment(segments[index - 1] as string) : "";
+			if (
+				isSensitivePathSegment(decoded) ||
+				isCredentialPathKey(previous) ||
+				isSensitiveFixtureValue(decoded)
+			) {
+				return REDACTED_FIXTURE_VALUE;
+			}
+			return segment;
+		})
+		.join("/");
+}
+
+function isCredentialPathKey(key: string): boolean {
+	const finalPathPart = key.split("/").at(-1) ?? "";
+	const baseSegment = finalPathPart.split(";", 1)[0] ?? "";
+	return isSensitiveFixtureKey(baseSegment.split(/[=:]/, 1)[0] ?? "");
+}
+
+function isSensitivePathSegment(segment: string): boolean {
+	return segment
+		.split(/[;/]/)
+		.some((part) => isSensitiveFixtureKey(part.split(/[=:]/, 1)[0] ?? ""));
+}
+
+/** Removes userinfo, query values, fragments, and credential-like path segments from log URLs. */
+export function sanitizeUrlForLogs(value: string): string {
+	try {
+		const parsed = new URL(value, "https://fixture.invalid");
+		const queryMarker = parsed.search ? `?${REDACTED_FIXTURE_VALUE}` : "";
+		const path = sanitizePathname(parsed.pathname);
+		if (parsed.origin === "https://fixture.invalid" && !hasExplicitOrigin(value)) {
+			return `${path}${queryMarker}`;
+		}
+		return `${parsed.origin}${path}${queryMarker}`;
+	} catch {
+		return sanitizePathname(value.split(/[?#]/, 1)[0]);
+	}
+}
+
+/**
+ * Returns query-free request provenance with each path segment scrubbed for credential-like values.
+ * Origins, URL userinfo, query values, and fragments are never persisted in request provenance.
+ */
+export function requestPathForFixture(value: string): string {
+	try {
+		return sanitizePathname(new URL(value, "https://fixture.invalid").pathname);
+	} catch {
+		const path = value.split(/[?#]/, 1)[0];
+		return sanitizePathname(path.startsWith("/") ? path : `/${path}`);
+	}
+}
+
+/** Scrubs secrets and terminal/log control characters before diagnostic text is emitted. */
+export function sanitizeDiagnosticText(value: string): string {
+	let sanitized = value
+		.replace(URL_RUN, (url) => sanitizeUrlForLogs(url))
+		.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED_FIXTURE_VALUE}`);
+	sanitized = redactSensitiveAssignments(sanitized);
+	sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate, offset: number, source: string) => {
+		if (/^(?:request|trace|correlation)[-_]?id[:=]/i.test(candidate)) return candidate;
+		const prefix = source.slice(Math.max(0, offset - 32), offset);
+		if (/(?:request|trace|correlation)[-_]?id\s*[:=]\s*$/i.test(prefix)) return candidate;
+		return isSensitiveFixtureValue(candidate) ? REDACTED_FIXTURE_VALUE : candidate;
+	});
+	return encodeDiagnosticControls(sanitized);
+}
+
+function redactSensitiveAssignments(value: string): string {
+	return value.replace(
+		/((["']?)([\w-]+)\2\s*[:=]\s*)("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;&]+)/gi,
+		(match, prefix: string, _quote: string, key: string, assignmentValue: string) => {
+			if (!isSensitiveFixtureKey(key) && key.toLowerCase() !== "key") return match;
+			const quote = assignmentValue.startsWith('"')
+				? '"'
+				: assignmentValue.startsWith("'")
+					? "'"
+					: "";
+			return `${prefix}${quote}${REDACTED_FIXTURE_VALUE}${quote}`;
+		},
+	);
+}
+
+function isCredentialBearingUrl(value: string): boolean {
+	try {
+		const parsed = new URL(value);
+		return (
+			parsed.username !== "" ||
+			parsed.password !== "" ||
+			parsed.hash !== "" ||
+			parsed.search !== "" ||
+			parsed.pathname.split("/").some((segment, index, segments) => {
+				const decoded = decodePathSegment(segment);
+				const previous = decodePathSegment(segments[index - 1] ?? "");
+				return (
+					isSensitiveFixtureKey(decoded) ||
+					isCredentialPathKey(previous) ||
+					isSensitiveFixtureValue(decoded)
+				);
+			})
+		);
+	} catch {
+		return false;
+	}
+}
+
+function encodeDiagnosticControls(value: string): string {
+	let result = "";
+	for (const character of value) {
+		const code = character.codePointAt(0) ?? 0;
+		if (code === 0x0a || code === 0x0d || code === 0x2028 || code === 0x2029) {
+			result += " ";
+		} else if (
+			(code >= 0 && code <= 0x1f) ||
+			(code >= 0x7f && code <= 0x9f) ||
+			code === 0x061c ||
+			code === 0x200e ||
+			code === 0x200f ||
+			(code >= 0x202a && code <= 0x202e) ||
+			(code >= 0x2066 && code <= 0x2069)
+		) {
+			result += `\\u${code.toString(16).padStart(4, "0")}`;
+		} else {
+			result += character;
+		}
+	}
+	return result;
+}
+
+function decodePathSegment(value: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+
+function hasExplicitOrigin(value: string): boolean {
+	return /^[a-z][a-z\d+.-]*:\/\//i.test(value);
+}
+
+function shannonEntropy(value: string): number {
+	const counts = new Map<string, number>();
+	for (const character of value) counts.set(character, (counts.get(character) ?? 0) + 1);
+	let entropy = 0;
+	for (const count of counts.values()) {
+		const probability = count / value.length;
+		entropy -= probability * Math.log2(probability);
+	}
+	return entropy;
+}

package/src/index.ts

@@ -70,6 +70,20 @@ export {
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
+export {
+	createNativeNetworkClient,
+	deriveNativeCredentialAffinityKey,
+	NativeIdleTimeoutError,
+	NativeNetworkError,
+	NativeProxyExpiredError,
+	resolveNativeGatewayProxy,
+	type NativeGatewayProxy,
+	type NativeGatewayProxyResolutionInput,
+	type NativeGatewayProxySynthesizer,
+	type NativeGatewayProxySynthesisInput,
+	type NativeNetworkClientOptions,
+	type NativeNetworkErrorCode,
+} from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
 export { generateInsights } from "./runtime/insights.js";
 export {
@@ -179,6 +193,26 @@ export type {
 	Iso3166Alpha2CountryCode,
 	Iso4217CurrencyCode,
 	Iso8601Duration,
+	NativeContext,
+	NativeNetworkClient,
+	NativeNetworkCloseReason,
+	NativeNetworkConnection,
+	NativeNetworkConnectInput,
+	NativeNetworkConnectOptions,
+	NativeNetworkDynamicGrantOptions,
+	NativeNetworkEgressGrant,
+	NativeProviderConfig,
+	NativeProviderContext,
+	NativeProxyDrainHandler,
+	NativeProxyEgressInfo,
+	NativeProxyExpiringEvent,
+	NativeProxyExpiringReason,
+	NativeTcpDynamicEgressRule,
+	NativeTcpEgressGrant,
+	NativeTcpEgressRule,
+	NativeTcpPortRange,
+	NativeTcpTlsMode,
+	NativeTlsConnectOptions,
 	OperationAnnotations,
 	OperationApprovalPolicy,
 	OperationContractMetadata,
@@ -213,6 +247,8 @@ export type {
 	ProviderContext,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
+	ProviderFileRef,
+	ProviderFilesContext,
 	ProviderHealthMonitorConfig,
 	ProviderHealthProbeConfig,
 	ProviderLocale,
@@ -229,6 +265,7 @@ export type {
 	ProviderPublicConnectionMode,
 	ProviderPublicProfile,
 	ProviderReviewed,
+	ProviderResolvedFile,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
 	ProviderStateDurationString,