@apifuse/provider-sdk 2.2.0-beta.25 → 2.2.0-beta.26

package/dist/runtime/stealth.js

@@ -1,13 +1,12 @@
 import { createHash } from "node:crypto";
-import { Impit } from "impit";
 import { Cookie, CookieJar as ToughCookieJar } from "tough-cookie";
 import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, policyResolvesRegistryVendorChain, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
 import { SDKError, StealthCookieStoreVersionError, TransportError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
-import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl, } from "./redirects.js";
-import { isSensitiveKey, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, normalizeSensitiveParams, serializeRequestUrl, } from "./request-options.js";
+import { evaluateRedirectHop, isRedirectStatus, nextRedirectMethod, resolveRedirectUrl, } from "./redirects.js";
+import { isSensitiveKey, normalizeSensitiveParams, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, serializeRequestUrl, } from "./request-options.js";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
@@ -16,6 +15,13 @@ const PROXY_CONNECT_FAILURE_BODY_PATTERN = /\bproxy\b.*\b(non[\s-]?200|connect|t
 const PROXY_AUTH_DIAGNOSTIC_URL = "http://example.com/";
 const PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS = 5_000;
 const STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES = [PROXY_CONNECT_FAILURE_CODE];
+const MAX_STEALTH_REDIRECT_HOPS = 10;
+const REDIRECT_BODY_HEADERS = new Set([
+    "content-encoding",
+    "content-language",
+    "content-location",
+    "content-type",
+]);
 function sensitiveQueryParamNames(url) {
     const queryStart = url.indexOf("?");
     if (queryStart === -1)
@@ -37,25 +43,6 @@ const REMOVED_CHROME_PROFILE_NAMES = new Set([
     "chrome-130-psk",
     "edge-131",
 ]);
-const CHROME_IMPIT_BY_MAJOR = {
-    100: "chrome100",
-    101: "chrome101",
-    104: "chrome104",
-    107: "chrome107",
-    110: "chrome110",
-    116: "chrome116",
-    124: "chrome124",
-    125: "chrome125",
-    131: "chrome131",
-    136: "chrome136",
-    142: "chrome142",
-};
-const FIREFOX_IMPIT_BY_MAJOR = {
-    128: "firefox128",
-    133: "firefox133",
-    135: "firefox135",
-    144: "firefox144",
-};
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -182,47 +169,93 @@ class CookieJarImpl {
         });
     }
 }
-function closestImpitBrowser(major, candidates) {
-    let closestMajor;
-    let closestBrowser;
-    for (const [candidateMajorText, browser] of Object.entries(candidates)) {
-        const candidateMajor = Number(candidateMajorText);
-        if (closestMajor === undefined ||
-            Math.abs(candidateMajor - major) < Math.abs(closestMajor - major)) {
-            closestMajor = candidateMajor;
-            closestBrowser = browser;
+let wreqModulePromise;
+function getWreqModule() {
+    if (!wreqModulePromise) {
+        wreqModulePromise = import("wreq-js").catch((error) => {
+            throw new SDKError(`Stealth transport is unavailable on ${process.platform}-${process.arch}: the wreq-js native binary could not be loaded.`, {
+                code: "stealth_transport_unavailable",
+                cause: error instanceof Error ? error : undefined,
+            });
+        });
+    }
+    return wreqModulePromise;
+}
+function parseProfileIdentifier(identifier) {
+    const match = /^(safari_ios|safari_ipad|firefox_android|firefox_private|chrome|edge|firefox|opera|safari|okhttp)_(\d+(?:[._]\d+)*)$/.exec(identifier.toLowerCase());
+    if (!match?.[1] || !match[2])
+        return null;
+    return {
+        family: match[1],
+        version: match[2].split(/[._]/).map(Number),
+    };
+}
+function compareVersionDistance(target, left, right) {
+    const width = Math.max(target.length, left.length, right.length);
+    for (let index = 0; index < width; index += 1) {
+        const targetPart = target[index] ?? 0;
+        const leftDistance = Math.abs((left[index] ?? 0) - targetPart);
+        const rightDistance = Math.abs((right[index] ?? 0) - targetPart);
+        if (leftDistance !== rightDistance)
+            return leftDistance - rightDistance;
+    }
+    return 0;
+}
+function closestWreqProfile(identifier, wreqProfiles) {
+    const requested = parseProfileIdentifier(identifier);
+    if (!requested)
+        return undefined;
+    let closest;
+    for (const candidateName of wreqProfiles) {
+        const candidate = parseProfileIdentifier(candidateName);
+        if (!candidate || candidate.family !== requested.family)
+            continue;
+        if (!closest ||
+            compareVersionDistance(requested.version, candidate.version, closest.version) < 0) {
+            closest = { name: candidateName, version: candidate.version };
         }
     }
-    return closestBrowser ?? "chrome142";
+    return closest?.name;
+}
+function resolveDefaultWreqProfileMapping() {
+    let profile;
+    try {
+        profile = getStealthProfile(DEFAULT_PROFILE);
+    }
+    catch (error) {
+        throw new SDKError(`Default stealth profile "${DEFAULT_PROFILE}" cannot be mapped to a wreq-js browser profile.`, { cause: error instanceof Error ? error : undefined });
+    }
+    const identifier = profile.tlsClientIdentifier?.toLowerCase() ?? "";
+    if (!parseProfileIdentifier(identifier)) {
+        throw new SDKError(`Default stealth profile "${DEFAULT_PROFILE}" cannot be mapped to a wreq-js browser profile.`);
+    }
+    return { identifier, os: profile.platform };
 }
-function resolveImpitBrowser(profileName) {
+const DEFAULT_WREQ_PROFILE_MAPPING = resolveDefaultWreqProfileMapping();
+export function resolveWreqProfile(profileName, wreqProfiles) {
     if (REMOVED_CHROME_PROFILE_NAMES.has(profileName)) {
         throw new SDKError(`Unknown stealth profile: ${profileName}`);
     }
-    let profile;
+    let identifier;
+    let os;
     try {
-        profile = getStealthProfile(profileName);
+        const profile = getStealthProfile(profileName);
+        identifier = profile.tlsClientIdentifier?.toLowerCase() ?? "";
+        os = profile.platform;
     }
     catch {
         // Preserve the previous ctx.stealth.fetch() compatibility behavior: unknown
         // profile strings still run with the transport default instead of failing
         // before the request starts. Removed built-in profile aliases above remain
         // explicit errors so callers do not accidentally pin retired fingerprints.
-        return "chrome142";
-    }
-    const identifier = profile.tlsClientIdentifier?.toLowerCase() ?? "";
-    const chromeMatch = /^(?:chrome|edge)_(\d+)/.exec(identifier);
-    if (chromeMatch?.[1]) {
-        return closestImpitBrowser(Number(chromeMatch[1]), CHROME_IMPIT_BY_MAJOR);
+        identifier = DEFAULT_WREQ_PROFILE_MAPPING.identifier;
+        os = DEFAULT_WREQ_PROFILE_MAPPING.os;
     }
-    const firefoxMatch = /^firefox_(\d+)/.exec(identifier);
-    if (firefoxMatch?.[1]) {
-        return closestImpitBrowser(Number(firefoxMatch[1]), FIREFOX_IMPIT_BY_MAJOR);
+    const browser = closestWreqProfile(identifier, wreqProfiles);
+    if (!browser) {
+        throw new SDKError(`Stealth profile "${profileName}" cannot be mapped to a wreq-js browser profile.`);
     }
-    if (identifier.startsWith("safari_")) {
-        throw new SDKError(`Stealth profile "${profileName}" uses a Safari stealth fingerprint, but TypeScript ctx.stealth uses impit which currently supports Chrome, Firefox, and OkHttp profiles only. Use a Chrome/Firefox stealth profile for ctx.stealth or ctx.browser for Safari-specific behavior.`);
-    }
-    throw new SDKError(`Stealth profile "${profileName}" cannot be mapped to an impit browser profile.`);
+    return { browser, os };
 }
 function resolveUrl(baseUrl, url) {
     return new URL(url, baseUrl).toString();
@@ -242,18 +275,6 @@ function normalizeHeaders(headers) {
 function hasOwn(object, key) {
     return Object.hasOwn(object, key);
 }
-function toImpitCookieJar(cookieJar) {
-    return {
-        setCookie(cookie, url, cb) {
-            cookieJar.setFromCookieStrings([cookie], url);
-            if (typeof cb === "function")
-                cb();
-        },
-        getCookieString(url) {
-            return cookieJar.toHeader(url);
-        },
-    };
-}
 function assertNoUnsupportedFingerprintOverrides(options) {
     if (!isRecord(options))
         return;
@@ -267,7 +288,7 @@ function assertNoUnsupportedFingerprintOverrides(options) {
         unsupported.push("stealth.h2");
     if (unsupported.length === 0)
         return;
-    throw new SDKError(`ctx.stealth.fetch uses impit-managed browser fingerprints and no longer accepts low-level stealth overrides: ${unsupported.join(", ")}. Use the profile option instead.`);
+    throw new SDKError(`ctx.stealth.fetch uses transport-managed browser fingerprints and no longer accepts low-level stealth overrides: ${unsupported.join(", ")}. Use the profile option instead.`);
 }
 function responseHeadersToRecord(headers) {
     const record = {};
@@ -348,23 +369,10 @@ function declaredContentLength(headers) {
     const parsed = Number(contentLength);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
-function abortTransportResponse(response) {
-    if (!response.abort)
-        return false;
-    try {
-        response.abort();
-    }
-    catch {
-        // The size error remains the primary failure if impit has already closed the response.
-    }
-    return true;
-}
 async function readResponseBodyWithLimit(response, maxBodyBytes) {
     const contentLength = declaredContentLength(response.headers);
     if (contentLength !== undefined && contentLength > maxBodyBytes) {
-        if (!abortTransportResponse(response)) {
-            await response.body?.cancel().catch(() => undefined);
-        }
+        await response.body?.cancel().catch(() => undefined);
         throw responseTooLargeError(maxBodyBytes, contentLength);
     }
     if (!response.body) {
@@ -382,10 +390,11 @@ async function readResponseBodyWithLimit(response, maxBodyBytes) {
             const { done, value } = await reader.read();
             if (done)
                 break;
+            if (!value)
+                continue;
             receivedBytes += value.byteLength;
             if (receivedBytes > maxBodyBytes) {
                 await reader.cancel().catch(() => undefined);
-                abortTransportResponse(response);
                 throw responseTooLargeError(maxBodyBytes, receivedBytes);
             }
             chunks.push(value);
@@ -566,31 +575,138 @@ function locationHeader(headers) {
     }
     return undefined;
 }
+function withoutRedirectBodyHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => !REDIRECT_BODY_HEADERS.has(name.toLowerCase())));
+}
+function assertStealthRedirectUrl(url) {
+    const protocol = new URL(url).protocol;
+    if (protocol !== "http:" && protocol !== "https:") {
+        throw new TransportError(`Stealth redirect target scheme "${protocol}" is not allowed`, {
+            code: "transport_invalid_url",
+            status: 0,
+        });
+    }
+}
+function discardStealthRedirectBody(response) {
+    try {
+        const cancellation = response.body?.cancel();
+        if (cancellation)
+            void cancellation.catch(() => undefined);
+    }
+    catch {
+        // Redirect handling is decided from status and headers. A cancellation
+        // failure must not replace or delay that decision.
+    }
+}
+async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options) {
+    let currentUrl = requestUrl;
+    let currentMethod = method;
+    let currentBody = options.body === undefined ? undefined : normalizeBody(options.body);
+    let currentHeaders = { ...(options.headers ?? {}) };
+    let followedHops = 0;
+    let response;
+    const deadline = options.timeout ? performance.now() + options.timeout : undefined;
+    while (true) {
+        const headers = { ...currentHeaders };
+        if (!hasHeader(headers, "Cookie")) {
+            const cookieHeader = cookieJar.toHeader(currentUrl);
+            if (cookieHeader)
+                headers.Cookie = cookieHeader;
+        }
+        const requestInit = {
+            headers: normalizeHeaders(headers),
+            method: currentMethod,
+            redirect: "manual",
+        };
+        if (currentBody !== undefined)
+            requestInit.body = currentBody;
+        await transport.clearCookies();
+        const remainingTimeout = deadline === undefined ? undefined : Math.ceil(deadline - performance.now());
+        if (remainingTimeout !== undefined && remainingTimeout <= 0) {
+            throw new TransportError("Request timed out", {
+                code: "transport_timeout",
+                status: 0,
+            });
+        }
+        if (remainingTimeout !== undefined)
+            requestInit.timeout = remainingTimeout;
+        response = await transport.fetch(currentUrl, requestInit);
+        cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers), response.url ?? currentUrl);
+        if (!isRedirectStatus(response.status) || options.redirect === "manual")
+            break;
+        if (options.redirect === "error") {
+            discardStealthRedirectBody(response);
+            throw new TransportError("Stealth request encountered a redirect", {
+                code: "transport_network_error",
+                status: 0,
+            });
+        }
+        const nextUrl = resolveRedirectUrl(response.headers.get("location") ?? undefined, response.url ?? currentUrl);
+        if (!nextUrl)
+            break;
+        if (followedHops >= MAX_STEALTH_REDIRECT_HOPS) {
+            discardStealthRedirectBody(response);
+            throw new TransportError(`Stealth request exceeded the ${MAX_STEALTH_REDIRECT_HOPS}-redirect limit`, { code: "transport_network_error", status: 0 });
+        }
+        assertStealthRedirectUrl(nextUrl);
+        discardStealthRedirectBody(response);
+        const nextMethod = nextRedirectMethod(response.status, currentMethod);
+        if (nextMethod !== currentMethod) {
+            currentBody = undefined;
+            currentHeaders = withoutRedirectBodyHeaders(currentHeaders);
+        }
+        currentMethod = nextMethod;
+        currentUrl = nextUrl;
+        followedHops += 1;
+    }
+    const normalized = await normalizeResponse(response, currentUrl, options.maxBodyBytes);
+    if (followedHops > 0)
+        normalized.redirected = true;
+    return { normalized, response };
+}
 function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     const clients = new Map();
     let closed = false;
     let hasWarnedMissingProxy = false;
     const warn = clientOptions.warn ?? console.warn;
     const cookieJar = new CookieJarImpl([], baseUrl);
-    const impitCookieJar = toImpitCookieJar(cookieJar);
-    function getClient(profileName, proxyUrl, ignoreTlsErrors) {
+    async function getClientEntry(profileName, proxyUrl, ignoreTlsErrors) {
         if (closed) {
             throw new TransportError("Stealth session is closed", { status: 0 });
         }
-        const browser = resolveImpitBrowser(profileName);
+        const wreq = await getWreqModule();
+        const { browser, os } = resolveWreqProfile(profileName, wreq.getProfiles());
         const cacheKey = JSON.stringify({ browser, proxyUrl, ignoreTlsErrors });
-        let client = clients.get(cacheKey);
-        if (!client) {
-            client = new Impit({
-                browser,
-                cookieJar: impitCookieJar,
-                ...(proxyUrl ? { proxyUrl } : {}),
-                ...(ignoreTlsErrors ? { ignoreTlsErrors: true } : {}),
-                timeout: 30_000,
-            });
-            clients.set(cacheKey, client);
+        let entry = clients.get(cacheKey);
+        if (!entry) {
+            entry = {
+                session: wreq.createSession({
+                    browser,
+                    os,
+                    ...(proxyUrl ? { proxy: proxyUrl } : {}),
+                    ...(ignoreTlsErrors ? { insecure: true } : {}),
+                    timeout: 30_000,
+                }),
+                tail: Promise.resolve(),
+            };
+            clients.set(cacheKey, entry);
+        }
+        return entry;
+    }
+    async function withClient(profileName, proxyUrl, ignoreTlsErrors, operation) {
+        const entry = await getClientEntry(profileName, proxyUrl, ignoreTlsErrors);
+        const previous = entry.tail;
+        let release;
+        entry.tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation(await entry.session);
+        }
+        finally {
+            release();
         }
-        return client;
     }
     async function resolveRequestProxy(options, proxyAttempt, refreshEpoch) {
         const resolvedProxy = await resolveProxyConfigAsync({
@@ -602,7 +718,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 proxyAttemptOffset: options?.proxyAttemptOffset,
                 retryAttemptOffset: proxyAttempt,
             }),
-            // The impit stealth transport tunnels both HTTP CONNECT and SOCKS5,
+            // The stealth transport tunnels both HTTP CONNECT and SOCKS5,
             // preserving the client TLS fingerprint end-to-end.
             transportProtocols: ["http", "socks5"],
             ...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
@@ -729,24 +845,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const profileName = options.profile ?? defaultProfile;
                         serializedUrl = serializeRequestUrl(resolveUrl(baseUrl, url), options.params, sensitiveParams);
                         const { requestUrl } = serializedUrl;
-                        const headers = { ...(options.headers ?? {}) };
-                        if (!hasHeader(headers, "Cookie")) {
-                            const cookieHeader = cookieJar.toHeader(requestUrl);
-                            if (cookieHeader)
-                                headers.Cookie = cookieHeader;
-                        }
-                        const requestInit = {
-                            headers: normalizeHeaders(headers),
-                            method,
-                            ...(options.redirect ? { redirect: options.redirect } : {}),
-                            ...(options.timeout ? { timeout: options.timeout } : {}),
-                        };
-                        if (options.body !== undefined) {
-                            requestInit.body = normalizeBody(options.body);
-                        }
-                        const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(requestUrl, requestInit);
-                        const normalized = await normalizeResponse(response, requestUrl, options.maxBodyBytes);
-                        cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
+                        const { normalized, response } = await withClient(profileName, proxy, ignoreTlsErrors, (transport) => fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options));
                         if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
                         }
@@ -1043,18 +1142,29 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         },
         close() {
             closed = true;
+            for (const client of clients.values()) {
+                void client.session
+                    .then((session) => session.close())
+                    .catch((error) => {
+                    const message = error instanceof Error ? error.message : String(error);
+                    warn(`[provider-sdk] Failed to close stealth transport session: ${message}`);
+                });
+            }
             clients.clear();
         },
     };
     return session;
     async function classifyProxyAuthDiagnostic(profileName, proxy) {
         try {
-            const response = await getClient(profileName, proxy, false).fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
-                method: "GET",
-                timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+            return await withClient(profileName, proxy, false, async (client) => {
+                await client.clearCookies();
+                const response = await client.fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
+                    method: "GET",
+                    timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+                });
+                const normalized = await normalizeResponse(response);
+                return classifyProxyAuthDiagnosticMessage(normalized.body);
             });
-            const normalized = await normalizeResponse(response);
-            return classifyProxyAuthDiagnosticMessage(normalized.body);
         }
         catch (error) {
             const message = error instanceof Error

package/dist/schema.d.ts

@@ -13,7 +13,27 @@ export declare function safeParseSchemaSync<TSchema extends SchemaLike>(schema:
 export declare const APIFUSE_SENSITIVE_META_KEY = "x-apifuse-sensitive";
 export declare const APIFUSE_SENSITIVE_KIND_META_KEY = "x-apifuse-sensitive-kind";
 export declare const APIFUSE_DESCRIPTION_KEY_META_KEY = "x-apifuse-description-key";
+export declare const APIFUSE_TEXT_TRUST_META_KEY = "x-apifuse-text-trust";
 export declare const APIFUSE_REDACTION_MARKER = "<redacted>";
+export type TextTrust = "trusted" | "untrusted";
+export interface TextTrustMetadata {
+    readonly v: 1;
+    readonly trust: TextTrust;
+    readonly carrier?: "container";
+}
+export type OutputTextTrustMap = Readonly<Record<string, TextTrust>>;
+/**
+ * Auto-trusted output leaves are string-valued `z.literal()` / `z.enum()`,
+ * patterns whose every top-level alternative is anchored at both ends and
+ * whose bodies use only finite quantifiers, have a maximum match length of 32,
+ * and contain only digits and safe punctuation in positive whitespace-free
+ * character classes, literals/escapes, and ordinary or non-capturing groups,
+ * plus the structurally constrained formats listed here. A brand is trusted
+ * only when its underlying schema meets one of those rules. Letter-bearing
+ * identifiers, length-only strings, and other formats (including email, URL,
+ * base64, and JWT) are not trusted.
+ */
+export declare const AUTO_TRUSTED_ZOD_STRING_FORMATS: readonly ["cidrv4", "cidrv6", "date", "datetime", "duration", "e164", "ipv4", "ipv6", "time"];
 export type SensitivePathSegment = string | "*";
 export type SensitivePath = readonly SensitivePathSegment[];
 export type SensitiveFieldKind = "api_key" | "authorization" | "cookie" | "credential" | "otp" | "password" | "payment_url" | "personal_data" | "phone" | "secret" | "token";
@@ -32,9 +52,12 @@ export interface SensitiveFieldOptions {
     description?: string;
 }
 export declare function describeKey<TSchema extends ZodType>(schema: TSchema, key: ProviderLocaleKey | string): TSchema;
+/** Attach output text-trust authoring metadata without changing validation. */
+export declare function textTrust<TSchema extends ZodType>(schema: TSchema, trust: TextTrust): TSchema;
 declare module "zod" {
     interface ZodType {
         describeKey(key: ProviderLocaleKey | string): this;
+        textTrust(trust: TextTrust): this;
     }
 }
 export declare function field<TSchema extends ZodType>(schema: TSchema, options?: SensitiveFieldOptions): TSchema;
@@ -69,6 +92,46 @@ export declare const fields: {
         description?: string;
     }) => ZodString;
 };
+export declare class OutputTextTrustSchemaError extends TypeError {
+    readonly code = "invalid_output_text_trust_schema";
+    constructor(value: unknown);
+}
+export declare class OutputTextTrustCollectionError extends Error {
+    readonly schemaPath: string;
+    readonly classification: "untrusted";
+    readonly code = "output_text_trust_collection_failed";
+    constructor(schemaPath: string, cause: unknown);
+}
+/**
+ * Collect every textual leaf in a Zod output schema as a deterministic
+ * schema-path-to-classification object. The path grammar is rooted at `$`:
+ * object keys are `["key"]`, arrays and record values are `[*]`, tuple slots
+ * are `[n]`, union/intersection alternatives are `<union:n>` / `<intersection:n>`,
+ * record keys are `<record-key>`, and one bounded cycle expansion is marked
+ * `<recursive>`.
+ */
+export declare function collectOutputTextTrust(schema: ZodType): OutputTextTrustMap;
+/** Report textual output paths that lack a valid explicit or auto-derived classification. */
+export declare function findUnclassifiedOutputTextPaths(schema: ZodType): string[];
+/** @internal Used by contract JSON Schema projection. */
+export declare function resolveOutputTextTrust(schema: z.core.$ZodType, inheritedUntrusted?: boolean): TextTrust | undefined;
+/** @internal Resolve both projection states from one stable schema traversal. */
+export declare function resolveOutputTextTrustProjection(schema: z.core.$ZodType): {
+    readonly inherited: TextTrust;
+    readonly local: TextTrust;
+} | undefined;
+/** @internal Whether this node can bypass or mutate descendant validation guarantees. */
+export declare function invalidatesDescendantOutputTextAutoTrust(schema: z.core.$ZodType): boolean;
+/** @internal Run output projection without evaluating dynamic fallback callbacks. */
+export declare function suppressDynamicOutputFallbacksDuring<T>(project: () => T): T;
+/** @internal Whether this mutator has a static fallback that cannot contain text. */
+export declare function mutatorReturnIsProvablyNonText(schema: z.core.$ZodType): boolean;
+/** @internal Whether this mutator has a static array fallback. */
+export declare function mutatorUsesStaticArrayFallback(schema: z.core.$ZodType): boolean;
+/** @internal Whether this default or catch was authored with a callback. */
+export declare function hasDynamicOutputFallback(schema: z.core.$ZodType): boolean;
+/** @internal Used by contract JSON Schema projection. */
+export declare function inheritsUntrustedOutputTextTrust(schema: z.core.$ZodType): boolean;
 export declare function isSensitiveSchema(schema: unknown): boolean;
 export declare function collectSensitivePaths(schema: unknown): SensitivePath[];
 export declare function redactPayload(value: unknown, paths?: readonly SensitivePath[]): unknown;