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

package/AUTHORING.md

@@ -517,6 +517,43 @@ const credentialsAuth = defineCredentialsAuth({
   `bunx playwright install chromium`, or set
   `APIFUSE__CDP_POOL__URL` for remote browser debugging.
 
+### Persisting stealth session cookies
+
+Persist `session.cookies.serialize()` as JSON when an authenticated session must
+survive a restart or move to another replica. The returned
+`StealthCookieStoreV1` has an explicit version and retains every cookie together
+with its Domain, Path, Secure, expiry, host-only, and other cookie attributes.
+Restore it with `session.cookies.deserialize()`. Unsupported future versions
+fail explicitly instead of being accepted as a partial cookie jar.
+
+Credential values are strings, so stringify the store at the credential
+boundary and parse it when rebuilding the session:
+
+```ts
+// After login (including any redirects across sibling hosts):
+const result = await session.redirects.run({ url: loginUrl });
+return {
+  credential: {
+    cookieStore: JSON.stringify(result.cookieStore),
+  },
+};
+
+// In a later operation or replica:
+const persisted = ctx.credential.get("cookieStore");
+if (persisted) {
+  session.cookies.deserialize(JSON.parse(persisted));
+}
+```
+
+`snapshot()` and `restore()` remain only for backward compatibility with flat
+`Record<string, string>` credentials. `snapshot()` enumerates cookies across all
+hosts and paths, but the flat shape is inherently lossy: duplicate names
+collapse and Domain, Path, Secure, expiry, and host-only attributes cannot be
+represented. `restore()` therefore recreates host-only `Path=/` cookies on the
+session base origin. Do not use the flat form for new persistence code. Cookie
+headers remain origin-filtered: use `toHeader(url)` for a particular request and
+never build a request header from serialized or snapshotted persistence data.
+
 ### Running the pre-submission report
 
 ```bash

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.12
+
+- Release candidate for main commit c66789c4745c72fc94ad3c10b3e0d7e5ed83fd25.
+
 ## 2.2.0-beta.11
 
 - Release candidate for main commit f6f739bd5265afe714bbace9900edc2695fcf826.

package/README.md

@@ -146,6 +146,24 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
   pseudo-header order in provider code. Chrome/Firefox-style profiles are
   supported; use `ctx.browser` when Safari-specific behavior is required.
+- **Proxy URLs for non-stealth consumers**: use `resolveProxy()` when a
+  provider-owned client outside `ctx.stealth` needs the provider's proxy, such
+  as a CAPTCHA solver that must use matching egress. Pass the provider proxy
+  policy used by the provider and consume the returned `url`; the SDK owns
+  vendor selection, allocation, failover, and URL formats. Never call proxy
+  allocator APIs or hardcode proxy vendor hostnames in provider code.
+
+  ```ts
+  import { resolveProxy } from "@apifuse/provider-sdk"
+
+  const resolvedProxy = await resolveProxy({
+    proxyPolicy,
+    affinityKey: connectionId,
+  })
+
+  if (!resolvedProxy.url) throw new Error("This login requires proxy egress")
+  const captchaTask = { proxy: resolvedProxy.url }
+  ```
 - **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
   `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
   Install local browser assets with `bunx playwright install chromium` when

package/bin/apifuse-pack-smoke.ts

@@ -59,6 +59,20 @@ try {
 	);
 
 	run("bun", ["install"], consumerDir);
+	run(
+		"bun",
+		[
+			"--eval",
+			[
+				'import { resolveProxy } from "@apifuse/provider-sdk";',
+				'if (typeof resolveProxy !== "function") throw new Error("resolveProxy is not exported");',
+				'const resolved = await resolveProxy({ proxy: "http://127.0.0.1:8080" });',
+				'if (resolved.url !== "http://127.0.0.1:8080") throw new Error("resolveProxy returned the wrong URL");',
+				'console.log("packed root resolveProxy export OK");',
+			].join("\n"),
+		],
+		consumerDir,
+	);
 
 	const cliBin = join(consumerDir, "node_modules", ".bin", "apifuse");
 	if (!existsSync(cliBin)) {

package/bin/apifuse-pack-types.ts

@@ -123,7 +123,8 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 	writeFileSync(
 		join(consumerDir, "consumer.ts"),
 		[
-			'import { ProviderError, SessionExpiredError, z } from "@apifuse/provider-sdk";',
+			'import { ProviderError, resolveProxy, SessionExpiredError, z } from "@apifuse/provider-sdk";',
+			'import type { ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, ResolvedProxyConfig } from "@apifuse/provider-sdk";',
 			'import { defineCredentialsAuth } from "@apifuse/provider-sdk/provider";',
 			'import { extractProviderContract } from "@apifuse/provider-sdk/contract";',
 			'import { AUTH_TURN_SCHEMA } from "@apifuse/provider-sdk/auth-turn";',
@@ -143,6 +144,11 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			"// Re-exported zod must keep .refine() callback parameter inference.",
 			"const refined = z.object({ shopId: z.string() }).refine((value) => value.shopId.length > 0);",
 			'const refinedString = z.string().refine((value) => value.startsWith("tabelog:"));',
+			'const proxyOptions: ProxyResolutionOptions = { proxyPolicy: { mode: "disabled" } };',
+			'const proxyProtocol: ProxyProtocol = "http";',
+			"const proxyResult: Promise<ResolvedProxyConfig> = resolveProxy(proxyOptions);",
+			'const proxySource: ProxyResolutionSource = "smartproxy-allocator";',
+			'const proxyVendor: ProxyVendorName = "smartproxy";',
 			"",
 			"export const witnesses = {",
 			"	inheritedName,",
@@ -152,6 +158,10 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			"	sessionExpired,",
 			"	refined,",
 			"	refinedString,",
+			"	proxyResult,",
+			"	proxyProtocol,",
+			"	proxySource,",
+			"	proxyVendor,",
 			"	defineCredentialsAuth,",
 			"	extractProviderContract,",
 			"	AUTH_TURN_SCHEMA,",

package/dist/config/loader.d.ts

@@ -112,10 +112,13 @@ export type ProxyTelemetrySink = {
     recordProxyAttempt?(event: ProxyAttemptTelemetryEvent): void;
     recordProxyVendorFailover?(event: ProxyVendorFailoverTelemetryEvent): void;
 };
+export type ProxyResolutionSource = "explicit" | "env" | "config" | "smartproxy-allocator" | "nodemaven-gateway";
 export type ResolvedProxyConfig = {
     shouldWarn: boolean;
     url?: string;
-    source?: "explicit" | "env" | "config" | "smartproxy-allocator" | "nodemaven-gateway";
+    /** SDK-native vendor that supplied the URL, when applicable. */
+    vendor?: ProxyVendorName;
+    source?: ProxyResolutionSource;
     protocol?: ProxyProtocol;
     diagnostics?: Record<string, string | number | boolean>;
 };
@@ -142,6 +145,11 @@ export declare function __setProxyRedisForTests(redis: ProxyRedisClient | undefi
 export declare function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number | undefined): void;
 export declare function resolveProxyConfig(options?: ProxyResolutionOptions): ResolvedProxyConfig;
 export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * Resolve the proxy URL for a provider-owned consumer such as a CAPTCHA solver.
+ * Vendor allocation and failover remain owned by the SDK.
+ */
+export declare function resolveProxy(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
 /**
  * Guard the No-MITM invariant: a resolved proxy URL must use a tunnelling scheme
  * (http CONNECT or socks5) so the client TLS handshake reaches the origin

package/dist/config/loader.js

@@ -400,6 +400,15 @@ export async function resolveProxyConfigAsync(options = {}) {
     }
     return { shouldWarn: true };
 }
+/**
+ * Resolve the proxy URL for a provider-owned consumer such as a CAPTCHA solver.
+ * Vendor allocation and failover remain owned by the SDK.
+ */
+export async function resolveProxy(options = {}) {
+    const resolved = await resolveProxyConfigAsync(options);
+    const vendor = vendorFromResolvedSource(resolved.source);
+    return vendor ? { ...resolved, vendor } : resolved;
+}
 /**
  * Each vendor's default egress protocol, chosen from live KR benchmarks. HTTP
  * CONNECT wins for nodemaven (socks5 adds ~500ms through the gateway) and ties

package/dist/errors.d.ts

@@ -17,6 +17,11 @@ export declare class ProviderError extends Error {
 export declare class SDKError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }
+/** Raised when persisted stealth cookies use a store version this SDK cannot read. */
+export declare class StealthCookieStoreVersionError extends SDKError {
+    readonly version: unknown;
+    constructor(version: unknown);
+}
 export declare class AuthError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }

package/dist/errors.js

@@ -57,6 +57,21 @@ export class SDKError extends ProviderError {
         this.name = "SDKError";
     }
 }
+/** Raised when persisted stealth cookies use a store version this SDK cannot read. */
+export class StealthCookieStoreVersionError extends SDKError {
+    version;
+    constructor(version) {
+        const displayedVersion = typeof version === "string" || typeof version === "number"
+            ? String(version)
+            : "missing or invalid";
+        super(`Unsupported stealth cookie store version: ${displayedVersion}`, {
+            code: "unsupported_stealth_cookie_store_version",
+            details: { receivedVersion: version, supportedVersions: [1] },
+        });
+        this.version = version;
+        this.name = "StealthCookieStoreVersionError";
+    }
+}
 export class AuthError extends ProviderError {
     constructor(message, options) {
         super(message, options);

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export * from "./auth.js";
 export * from "./ceremonies/index.js";
 export * from "./choice-token.js";
-export type { ApiFuseConfig, BrowserConfig, ProxyConfig, SessionConfig, } from "./config/loader.js";
-export { defineConfig, loadApiFuseConfig } from "./config/loader.js";
+export type { ApiFuseConfig, BrowserConfig, ProxyConfig, ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, ResolvedProxyConfig, SessionConfig, } from "./config/loader.js";
+export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type ProviderConfig, } from "./define.js";
 export type { DevServerOptions } from "./dev.js";
@@ -36,7 +36,7 @@ export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SEN
 export { createServerApp, type ServeOptions, serve } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";

package/dist/index.js

@@ -2,7 +2,7 @@
 export * from "./auth.js";
 export * from "./ceremonies/index.js";
 export * from "./choice-token.js";
-export { defineConfig, loadApiFuseConfig } from "./config/loader.js";
+export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, } from "./define.js";
 export { createDevServer, startDevServer } from "./dev.js";

package/dist/runtime/stealth.js

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import { Impit } from "impit";
-import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, policyResolvesRegistryVendorChain, ProxyResolutionError, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
-import { SDKError, TransportError } from "../errors.js";
+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";
@@ -49,69 +50,128 @@ const FIREFOX_IMPIT_BY_MAJOR = {
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
+const LEGACY_COOKIE_ORIGIN = "https://legacy-cookie.invalid/";
 class CookieJarImpl {
     cookies;
-    constructor(cookieStrings) {
-        this.cookies = {};
+    defaultUrl;
+    constructor(cookieStrings, defaultUrl = LEGACY_COOKIE_ORIGIN) {
+        this.cookies = new ToughCookieJar(undefined, {
+            allowSecureOnLocal: false,
+            rejectPublicSuffixes: true,
+        });
+        this.defaultUrl = this.normalizeUrl(defaultUrl) ?? LEGACY_COOKIE_ORIGIN;
         this.setFromCookieStrings(cookieStrings);
     }
-    setFromCookieStrings(cookieStrings) {
+    /**
+     * URL-less legacy operations are scoped to this jar's default URL. Session
+     * jars use the client's base URL and response jars use the response URL. A
+     * flat restore has no attributes to recover, so it creates host-only Path=/
+     * cookies for that default URL instead of making them visible to every host.
+     */
+    setFromCookieStrings(cookieStrings, url = this.defaultUrl) {
+        const cookieUrl = this.normalizeUrl(url);
+        if (!cookieUrl)
+            return;
         for (const cookieString of cookieStrings) {
-            const [nameValue] = cookieString.split(";");
-            if (!nameValue) {
-                continue;
-            }
-            const separatorIndex = nameValue.indexOf("=");
-            if (separatorIndex === -1) {
-                continue;
-            }
-            const name = nameValue.slice(0, separatorIndex).trim();
-            const value = nameValue.slice(separatorIndex + 1).trim();
-            if (name)
-                this.cookies[name] = value;
+            this.cookies.setCookieSync(cookieString, cookieUrl, { ignoreError: true });
         }
     }
-    get(name) {
-        return this.cookies[name];
+    get(name, url) {
+        return this.getAll(url)[name];
     }
-    getAll() {
-        return { ...this.cookies };
+    getAll(url) {
+        return Object.fromEntries(this.getUniqueCookies(url ?? this.defaultUrl).map((cookie) => [cookie.key, cookie.value]));
     }
-    has(name) {
-        return Object.hasOwn(this.cookies, name);
+    has(name, url) {
+        return Object.hasOwn(this.getAll(url), name);
     }
-    toString() {
-        return Object.entries(this.cookies)
-            .map(([name, value]) => `${name}=${value}`)
+    toString(url) {
+        return this.getUniqueCookies(url ?? this.defaultUrl)
+            .map((cookie) => cookie.cookieString())
             .join("; ");
     }
-    toHeader() {
-        return this.toString();
+    toHeader(url) {
+        return this.toString(url);
     }
     snapshot() {
-        return this.getAll();
+        // This compatibility view deliberately enumerates the serialized store,
+        // not getAll(defaultUrl): persistence must include sibling hosts and paths.
+        // Duplicate names still collapse because a flat map cannot represent them.
+        const entries = [];
+        for (const cookie of this.serialize().jar.cookies) {
+            if (typeof cookie.key === "string" && typeof cookie.value === "string" && cookie.key) {
+                entries.push([cookie.key, cookie.value]);
+            }
+        }
+        return Object.fromEntries(entries);
     }
     restore(cookies) {
         this.clear();
         for (const [name, value] of Object.entries(cookies)) {
-            if (name)
-                this.cookies[name] = value;
+            if (!name)
+                continue;
+            this.cookies.setCookieSync(new Cookie({ key: name, path: "/", value }), this.defaultUrl, {
+                ignoreError: true,
+            });
         }
     }
-    clear() {
-        for (const name of Object.keys(this.cookies)) {
-            delete this.cookies[name];
+    serialize() {
+        const jar = this.cookies.serializeSync();
+        if (!jar) {
+            throw new SDKError("Stealth cookie store could not be serialized", {
+                code: "stealth_cookie_store_serialize_failed",
+            });
         }
+        return { version: 1, jar };
     }
-    find(predicate) {
-        for (const [name, value] of Object.entries(this.cookies)) {
-            const cookie = `${name}=${value}`;
-            if (predicate(cookie)) {
-                return cookie;
+    deserialize(state) {
+        const version = isRecord(state) ? state.version : undefined;
+        if (version !== 1) {
+            throw new StealthCookieStoreVersionError(version);
+        }
+        // Deserialize into a new jar first so invalid state cannot partially clear
+        // or replace a live session. tough-cookie restores the cookie attributes and
+        // matching semantics represented in its own serialized format.
+        const restored = ToughCookieJar.deserializeSync(state.jar);
+        // tough-cookie 6 does not include this option in serializeSync(). Preserve
+        // the SDK's stricter setting across restoration.
+        Reflect.set(restored, "allowSecureOnLocal", false);
+        this.cookies = restored;
+    }
+    clear() {
+        this.cookies.removeAllCookiesSync();
+    }
+    find(predicate, url) {
+        for (const cookie of this.getUniqueCookies(url ?? this.defaultUrl)) {
+            const cookieString = cookie.cookieString();
+            if (predicate(cookieString)) {
+                return cookieString;
             }
         }
         return undefined;
     }
+    normalizeUrl(url) {
+        try {
+            return new URL(url).toString();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    getUniqueCookies(url) {
+        const cookieUrl = this.normalizeUrl(url);
+        if (!cookieUrl)
+            return [];
+        // tough-cookie returns longer (more-specific) paths first. Keeping the
+        // first cookie for each name prevents ambiguous duplicate-name headers.
+        const names = new Set();
+        return this.cookies.getCookiesSync(cookieUrl).filter((cookie) => {
+            if (names.has(cookie.key))
+                return false;
+            names.add(cookie.key);
+            return true;
+        });
+    }
 }
 function closestImpitBrowser(major, candidates) {
     let closestMajor;
@@ -175,13 +235,13 @@ function hasOwn(object, key) {
 }
 function toImpitCookieJar(cookieJar) {
     return {
-        setCookie(cookie, _url, cb) {
-            cookieJar.setFromCookieStrings([cookie]);
+        setCookie(cookie, url, cb) {
+            cookieJar.setFromCookieStrings([cookie], url);
             if (typeof cb === "function")
                 cb();
         },
-        getCookieString(_url) {
-            return cookieJar.toString();
+        getCookieString(url) {
+            return cookieJar.toHeader(url);
         },
     };
 }
@@ -235,7 +295,7 @@ function splitCombinedSetCookieHeader(headerValue) {
 }
 export async function normalizeResponse(response, requestUrl) {
     const headers = Object.fromEntries(response.headers.entries());
-    const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers));
+    const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
     const bodyBytes = await response.arrayBuffer();
     const body = new TextDecoder().decode(bodyBytes);
     return {
@@ -441,7 +501,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     let closed = false;
     let hasWarnedMissingProxy = false;
     const warn = clientOptions.warn ?? console.warn;
-    const cookieJar = new CookieJarImpl([]);
+    const cookieJar = new CookieJarImpl([], baseUrl);
     const impitCookieJar = toImpitCookieJar(cookieJar);
     function getClient(profileName, proxyUrl, ignoreTlsErrors) {
         if (closed) {
@@ -580,7 +640,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
                         const headers = { ...(options.headers ?? {}) };
                         if (!hasHeader(headers, "Cookie")) {
-                            const cookieHeader = cookieJar.toString();
+                            const cookieHeader = cookieJar.toHeader(requestUrl);
                             if (cookieHeader)
                                 headers.Cookie = cookieHeader;
                         }
@@ -595,7 +655,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         }
                         const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(requestUrl, requestInit);
                         const normalized = await normalizeResponse(response, requestUrl);
-                        cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
+                        cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
                         if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
                         }
@@ -735,6 +795,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             hops,
                             reason: "completed",
                             cookies: cookieJar.snapshot(),
+                            cookieStore: cookieJar.serialize(),
                         };
                     }
                     const location = locationHeader(response.headers);
@@ -755,6 +816,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             hops,
                             reason: "stopped",
                             cookies: cookieJar.snapshot(),
+                            cookieStore: cookieJar.serialize(),
                         };
                     }
                     if (!nextUrl) {
@@ -763,6 +825,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             hops,
                             reason: "missing_location",
                             cookies: cookieJar.snapshot(),
+                            cookieStore: cookieJar.serialize(),
                         };
                     }
                     if (hops.length > maxHops) {
@@ -771,6 +834,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             hops,
                             reason: "max_hops",
                             cookies: cookieJar.snapshot(),
+                            cookieStore: cookieJar.serialize(),
                         };
                     }
                     const nextMethod = nextRedirectMethod(response.status, method);
@@ -783,6 +847,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             hops,
                             reason: "loop",
                             cookies: cookieJar.snapshot(),
+                            cookieStore: cookieJar.serialize(),
                         };
                     }
                     method = nextMethod;
@@ -803,6 +868,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     hops,
                     reason: "max_hops",
                     cookies: cookieJar.snapshot(),
+                    cookieStore: cookieJar.serialize(),
                 };
             },
         },

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { SerializedCookieJar } from "tough-cookie";
 import type { infer as ZodInfer, ZodType } from "zod";
 /** Minimal Standard Schema v1 shape accepted by provider operations. */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
@@ -872,17 +873,42 @@ export interface StealthFetchOptions extends RequestOptions {
     };
 }
 export interface CookieJar {
-    get(name: string): string | undefined;
-    getAll(): Record<string, string>;
-    toString(): string;
-    find?(predicate: (cookie: string) => boolean): string | undefined;
+    /** URL-less reads use the jar's response URL or session base URL. */
+    get(name: string, url?: string): string | undefined;
+    getAll(url?: string): Record<string, string>;
+    toString(url?: string): string;
+    find?(predicate: (cookie: string) => boolean, url?: string): string | undefined;
 }
+/**
+ * Version 1 of the JSON-safe, attribute-preserving stealth cookie store.
+ * The nested jar is tough-cookie's serialized form and retains cookie origin,
+ * Path, Secure, expiry, host-only, and other RFC attributes.
+ */
+export interface StealthCookieStoreV1 {
+    readonly version: 1;
+    readonly jar: SerializedCookieJar;
+}
+/** Cookie persistence formats understood by this SDK version. */
+export type StealthCookieStore = StealthCookieStoreV1;
 export interface StealthSessionCookies extends CookieJar {
-    has(name: string): boolean;
-    setFromCookieStrings(cookieStrings: readonly string[]): void;
-    toHeader(): string;
+    has(name: string, url?: string): boolean;
+    /** URL-less writes are scoped to the session base URL. */
+    setFromCookieStrings(cookieStrings: readonly string[], url?: string): void;
+    toHeader(url?: string): string;
+    /**
+     * Returns every cookie as a flat name/value map, collapsing duplicate names.
+     * @deprecated Use serialize() for lossless, attribute-preserving persistence.
+     */
     snapshot(): Record<string, string>;
+    /**
+     * Restores flat values as host-only, Path=/ cookies on the session base URL.
+     * @deprecated Use deserialize() with state produced by serialize().
+     */
     restore(cookies: Record<string, string>): void;
+    /** Returns a versioned, JSON-safe, attribute-preserving representation of every cookie. */
+    serialize(): StealthCookieStoreV1;
+    /** Replaces the jar with a previously serialized, attribute-preserving cookie store. */
+    deserialize(state: StealthCookieStore): void;
     clear(): void;
 }
 export interface DeclarativeStealthResponse {
@@ -925,7 +951,13 @@ export interface StealthRedirectRunResult {
     final: StealthResponse;
     hops: StealthRedirectHop[];
     reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    /**
+     * Complete flat view across all redirect hosts. Attributes and duplicate names are lost.
+     * @deprecated Use cookieStore for lossless persistence.
+     */
     cookies: Record<string, string>;
+    /** Versioned, attribute-preserving cookie state accumulated across the redirect chain. */
+    cookieStore: StealthCookieStoreV1;
 }
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.11",
+	"version": "2.2.0-beta.12",
 	"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",
+		"tough-cookie": "^6.0.2",
 		"zod": "^4.4.3"
 	},
 	"repository": {

package/src/config/loader.ts

@@ -156,10 +156,19 @@ export type ProxyTelemetrySink = {
 	recordProxyVendorFailover?(event: ProxyVendorFailoverTelemetryEvent): void;
 };
 
+export type ProxyResolutionSource =
+	| "explicit"
+	| "env"
+	| "config"
+	| "smartproxy-allocator"
+	| "nodemaven-gateway";
+
 export type ResolvedProxyConfig = {
 	shouldWarn: boolean;
 	url?: string;
-	source?: "explicit" | "env" | "config" | "smartproxy-allocator" | "nodemaven-gateway";
+	/** SDK-native vendor that supplied the URL, when applicable. */
+	vendor?: ProxyVendorName;
+	source?: ProxyResolutionSource;
 	protocol?: ProxyProtocol;
 	diagnostics?: Record<string, string | number | boolean>;
 };
@@ -656,6 +665,18 @@ export async function resolveProxyConfigAsync(
 	return { shouldWarn: true };
 }
 
+/**
+ * Resolve the proxy URL for a provider-owned consumer such as a CAPTCHA solver.
+ * Vendor allocation and failover remain owned by the SDK.
+ */
+export async function resolveProxy(
+	options: ProxyResolutionOptions = {},
+): Promise<ResolvedProxyConfig> {
+	const resolved = await resolveProxyConfigAsync(options);
+	const vendor = vendorFromResolvedSource(resolved.source);
+	return vendor ? { ...resolved, vendor } : resolved;
+}
+
 /**
  * Each vendor's default egress protocol, chosen from live KR benchmarks. HTTP
  * CONNECT wins for nodemaven (socks5 adds ~500ms through the gateway) and ties

package/src/errors.ts

@@ -79,6 +79,21 @@ export class SDKError extends ProviderError {
 	}
 }
 
+/** Raised when persisted stealth cookies use a store version this SDK cannot read. */
+export class StealthCookieStoreVersionError extends SDKError {
+	constructor(public readonly version: unknown) {
+		const displayedVersion =
+			typeof version === "string" || typeof version === "number"
+				? String(version)
+				: "missing or invalid";
+		super(`Unsupported stealth cookie store version: ${displayedVersion}`, {
+			code: "unsupported_stealth_cookie_store_version",
+			details: { receivedVersion: version, supportedVersions: [1] },
+		});
+		this.name = "StealthCookieStoreVersionError";
+	}
+}
+
 export class AuthError extends ProviderError {
 	constructor(message: string, options?: ProviderErrorOptions) {
 		super(message, options);

package/src/index.ts

@@ -7,9 +7,14 @@ export type {
 	ApiFuseConfig,
 	BrowserConfig,
 	ProxyConfig,
+	ProxyProtocol,
+	ProxyResolutionOptions,
+	ProxyResolutionSource,
+	ProxyVendorName,
+	ResolvedProxyConfig,
 	SessionConfig,
 } from "./config/loader.js";
-export { defineConfig, loadApiFuseConfig } from "./config/loader.js";
+export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export {
 	canonicalJson,
 	digestProviderContract,
@@ -245,6 +250,8 @@ export type {
 	StateValue,
 	StateWriteOptions,
 	StealthClient,
+	StealthCookieStore,
+	StealthCookieStoreV1,
 	StealthFetchOptions,
 	StealthPlatform,
 	StealthProfile,

package/src/runtime/stealth.ts

@@ -1,24 +1,27 @@
 import { createHash } from "node:crypto";
 import type { Browser, ImpitOptions, ImpitResponse, RequestInit } from "impit";
 import { Impit } from "impit";
+import { Cookie, CookieJar as ToughCookieJar } from "tough-cookie";
 
 import type { ProxyResolutionOptions, ProxyVendorName } from "../config/loader.js";
 import {
 	DEFAULT_SMARTPROXY_POOL_SIZE,
 	invalidateProxyResolutionCacheAsync,
-	policyResolvesRegistryVendorChain,
 	ProxyResolutionError,
+	policyResolvesRegistryVendorChain,
 	resolvePolicyProxyPoolSpan,
 	resolvePolicyTransportAttemptCap,
 	resolveProxyConfigAsync,
 	vendorFromResolvedSource,
 } from "../config/loader.js";
-import { SDKError, TransportError } from "../errors.js";
+import { SDKError, StealthCookieStoreVersionError, TransportError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import type {
 	CookieJar,
 	HttpMethod,
 	StealthClient,
+	StealthCookieStore,
+	StealthCookieStoreV1,
 	StealthFetchOptions,
 	StealthRedirectHop,
 	StealthResponse,
@@ -127,81 +130,145 @@ function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
+const LEGACY_COOKIE_ORIGIN = "https://legacy-cookie.invalid/";
+
 class CookieJarImpl implements CookieJar {
-	private readonly cookies: Record<string, string>;
+	private cookies: ToughCookieJar;
+	private readonly defaultUrl: string;
 
-	constructor(cookieStrings: string[]) {
-		this.cookies = {};
+	constructor(cookieStrings: readonly string[], defaultUrl = LEGACY_COOKIE_ORIGIN) {
+		this.cookies = new ToughCookieJar(undefined, {
+			allowSecureOnLocal: false,
+			rejectPublicSuffixes: true,
+		});
+		this.defaultUrl = this.normalizeUrl(defaultUrl) ?? LEGACY_COOKIE_ORIGIN;
 		this.setFromCookieStrings(cookieStrings);
 	}
 
-	setFromCookieStrings(cookieStrings: readonly string[]): void {
-		for (const cookieString of cookieStrings) {
-			const [nameValue] = cookieString.split(";");
-			if (!nameValue) {
-				continue;
-			}
-
-			const separatorIndex = nameValue.indexOf("=");
-			if (separatorIndex === -1) {
-				continue;
-			}
+	/**
+	 * URL-less legacy operations are scoped to this jar's default URL. Session
+	 * jars use the client's base URL and response jars use the response URL. A
+	 * flat restore has no attributes to recover, so it creates host-only Path=/
+	 * cookies for that default URL instead of making them visible to every host.
+	 */
+	setFromCookieStrings(cookieStrings: readonly string[], url = this.defaultUrl): void {
+		const cookieUrl = this.normalizeUrl(url);
+		if (!cookieUrl) return;
 
-			const name = nameValue.slice(0, separatorIndex).trim();
-			const value = nameValue.slice(separatorIndex + 1).trim();
-			if (name) this.cookies[name] = value;
+		for (const cookieString of cookieStrings) {
+			this.cookies.setCookieSync(cookieString, cookieUrl, { ignoreError: true });
 		}
 	}
 
-	get(name: string): string | undefined {
-		return this.cookies[name];
+	get(name: string, url?: string): string | undefined {
+		return this.getAll(url)[name];
 	}
 
-	getAll(): Record<string, string> {
-		return { ...this.cookies };
+	getAll(url?: string): Record<string, string> {
+		return Object.fromEntries(
+			this.getUniqueCookies(url ?? this.defaultUrl).map((cookie) => [cookie.key, cookie.value]),
+		);
 	}
 
-	has(name: string): boolean {
-		return Object.hasOwn(this.cookies, name);
+	has(name: string, url?: string): boolean {
+		return Object.hasOwn(this.getAll(url), name);
 	}
 
-	toString(): string {
-		return Object.entries(this.cookies)
-			.map(([name, value]) => `${name}=${value}`)
+	toString(url?: string): string {
+		return this.getUniqueCookies(url ?? this.defaultUrl)
+			.map((cookie) => cookie.cookieString())
 			.join("; ");
 	}
 
-	toHeader(): string {
-		return this.toString();
+	toHeader(url?: string): string {
+		return this.toString(url);
 	}
 
 	snapshot(): Record<string, string> {
-		return this.getAll();
+		// This compatibility view deliberately enumerates the serialized store,
+		// not getAll(defaultUrl): persistence must include sibling hosts and paths.
+		// Duplicate names still collapse because a flat map cannot represent them.
+		const entries: [string, string][] = [];
+		for (const cookie of this.serialize().jar.cookies) {
+			if (typeof cookie.key === "string" && typeof cookie.value === "string" && cookie.key) {
+				entries.push([cookie.key, cookie.value]);
+			}
+		}
+		return Object.fromEntries(entries);
 	}
 
 	restore(cookies: Record<string, string>): void {
 		this.clear();
 		for (const [name, value] of Object.entries(cookies)) {
-			if (name) this.cookies[name] = value;
+			if (!name) continue;
+			this.cookies.setCookieSync(new Cookie({ key: name, path: "/", value }), this.defaultUrl, {
+				ignoreError: true,
+			});
 		}
 	}
 
-	clear(): void {
-		for (const name of Object.keys(this.cookies)) {
-			delete this.cookies[name];
+	serialize(): StealthCookieStoreV1 {
+		const jar = this.cookies.serializeSync();
+		if (!jar) {
+			throw new SDKError("Stealth cookie store could not be serialized", {
+				code: "stealth_cookie_store_serialize_failed",
+			});
 		}
+		return { version: 1, jar };
 	}
 
-	find(predicate: (cookie: string) => boolean): string | undefined {
-		for (const [name, value] of Object.entries(this.cookies)) {
-			const cookie = `${name}=${value}`;
-			if (predicate(cookie)) {
-				return cookie;
+	deserialize(state: StealthCookieStore): void {
+		const version = isRecord(state) ? state.version : undefined;
+		if (version !== 1) {
+			throw new StealthCookieStoreVersionError(version);
+		}
+
+		// Deserialize into a new jar first so invalid state cannot partially clear
+		// or replace a live session. tough-cookie restores the cookie attributes and
+		// matching semantics represented in its own serialized format.
+		const restored = ToughCookieJar.deserializeSync(state.jar);
+		// tough-cookie 6 does not include this option in serializeSync(). Preserve
+		// the SDK's stricter setting across restoration.
+		Reflect.set(restored, "allowSecureOnLocal", false);
+		this.cookies = restored;
+	}
+
+	clear(): void {
+		this.cookies.removeAllCookiesSync();
+	}
+
+	find(predicate: (cookie: string) => boolean, url?: string): string | undefined {
+		for (const cookie of this.getUniqueCookies(url ?? this.defaultUrl)) {
+			const cookieString = cookie.cookieString();
+			if (predicate(cookieString)) {
+				return cookieString;
 			}
 		}
 
 		return undefined;
 	}
+
+	private normalizeUrl(url: string): string | undefined {
+		try {
+			return new URL(url).toString();
+		} catch {
+			return undefined;
+		}
+	}
+
+	private getUniqueCookies(url: string): Cookie[] {
+		const cookieUrl = this.normalizeUrl(url);
+		if (!cookieUrl) return [];
+
+		// tough-cookie returns longer (more-specific) paths first. Keeping the
+		// first cookie for each name prevents ambiguous duplicate-name headers.
+		const names = new Set<string>();
+		return this.cookies.getCookiesSync(cookieUrl).filter((cookie) => {
+			if (names.has(cookie.key)) return false;
+			names.add(cookie.key);
+			return true;
+		});
+	}
 }
 
 function closestImpitBrowser(
@@ -282,12 +349,12 @@ function hasOwn(object: object, key: string): boolean {
 }
 function toImpitCookieJar(cookieJar: CookieJarImpl): NonNullable<ImpitOptions["cookieJar"]> {
 	return {
-		setCookie(cookie: string, _url: string, cb?: (error?: unknown) => void) {
-			cookieJar.setFromCookieStrings([cookie]);
+		setCookie(cookie: string, url: string, cb?: (error?: unknown) => void) {
+			cookieJar.setFromCookieStrings([cookie], url);
 			if (typeof cb === "function") cb();
 		},
-		getCookieString(_url: string) {
-			return cookieJar.toString();
+		getCookieString(url: string) {
+			return cookieJar.toHeader(url);
 		},
 	};
 }
@@ -341,7 +408,10 @@ export async function normalizeResponse(
 	requestUrl?: string,
 ): Promise<StealthResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
-	const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers));
+	const cookies = new CookieJarImpl(
+		setCookieHeadersFromResponse(response.headers),
+		response.url ?? requestUrl,
+	);
 	const bodyBytes = await response.arrayBuffer();
 	const body = new TextDecoder().decode(bodyBytes);
 
@@ -588,7 +658,7 @@ function createSessionFetcher(
 	let closed = false;
 	let hasWarnedMissingProxy = false;
 	const warn = clientOptions.warn ?? console.warn;
-	const cookieJar = new CookieJarImpl([]);
+	const cookieJar = new CookieJarImpl([], baseUrl);
 	const impitCookieJar = toImpitCookieJar(cookieJar);
 
 	function getClient(
@@ -757,7 +827,7 @@ function createSessionFetcher(
 						const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
 						const headers = { ...(options.headers ?? {}) };
 						if (!hasHeader(headers, "Cookie")) {
-							const cookieHeader = cookieJar.toString();
+							const cookieHeader = cookieJar.toHeader(requestUrl);
 							if (cookieHeader) headers.Cookie = cookieHeader;
 						}
 						const requestInit: StealthRequestInit = {
@@ -774,7 +844,10 @@ function createSessionFetcher(
 							requestInit,
 						);
 						const normalized = await normalizeResponse(response, requestUrl);
-						cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
+						cookieJar.setFromCookieStrings(
+							setCookieHeadersFromResponse(response.headers),
+							response.url ?? requestUrl,
+						);
 
 						if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
 							throw createProxyConnectFailureError(normalized.body);
@@ -954,6 +1027,7 @@ function createSessionFetcher(
 							hops,
 							reason: "completed",
 							cookies: cookieJar.snapshot(),
+							cookieStore: cookieJar.serialize(),
 						};
 					}
 
@@ -976,6 +1050,7 @@ function createSessionFetcher(
 							hops,
 							reason: "stopped",
 							cookies: cookieJar.snapshot(),
+							cookieStore: cookieJar.serialize(),
 						};
 					}
 
@@ -985,6 +1060,7 @@ function createSessionFetcher(
 							hops,
 							reason: "missing_location",
 							cookies: cookieJar.snapshot(),
+							cookieStore: cookieJar.serialize(),
 						};
 					}
 
@@ -994,6 +1070,7 @@ function createSessionFetcher(
 							hops,
 							reason: "max_hops",
 							cookies: cookieJar.snapshot(),
+							cookieStore: cookieJar.serialize(),
 						};
 					}
 
@@ -1007,6 +1084,7 @@ function createSessionFetcher(
 							hops,
 							reason: "loop",
 							cookies: cookieJar.snapshot(),
+							cookieStore: cookieJar.serialize(),
 						};
 					}
 					method = nextMethod;
@@ -1028,6 +1106,7 @@ function createSessionFetcher(
 					hops,
 					reason: "max_hops",
 					cookies: cookieJar.snapshot(),
+					cookieStore: cookieJar.serialize(),
 				};
 			},
 		},

package/src/types.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { SerializedCookieJar } from "tough-cookie";
 
 import type { infer as ZodInfer, ZodType } from "zod";
 
@@ -1051,18 +1052,45 @@ export interface StealthFetchOptions extends RequestOptions {
 }
 
 export interface CookieJar {
-	get(name: string): string | undefined;
-	getAll(): Record<string, string>;
-	toString(): string;
-	find?(predicate: (cookie: string) => boolean): string | undefined;
+	/** URL-less reads use the jar's response URL or session base URL. */
+	get(name: string, url?: string): string | undefined;
+	getAll(url?: string): Record<string, string>;
+	toString(url?: string): string;
+	find?(predicate: (cookie: string) => boolean, url?: string): string | undefined;
+}
+
+/**
+ * Version 1 of the JSON-safe, attribute-preserving stealth cookie store.
+ * The nested jar is tough-cookie's serialized form and retains cookie origin,
+ * Path, Secure, expiry, host-only, and other RFC attributes.
+ */
+export interface StealthCookieStoreV1 {
+	readonly version: 1;
+	readonly jar: SerializedCookieJar;
 }
 
+/** Cookie persistence formats understood by this SDK version. */
+export type StealthCookieStore = StealthCookieStoreV1;
+
 export interface StealthSessionCookies extends CookieJar {
-	has(name: string): boolean;
-	setFromCookieStrings(cookieStrings: readonly string[]): void;
-	toHeader(): string;
+	has(name: string, url?: string): boolean;
+	/** URL-less writes are scoped to the session base URL. */
+	setFromCookieStrings(cookieStrings: readonly string[], url?: string): void;
+	toHeader(url?: string): string;
+	/**
+	 * Returns every cookie as a flat name/value map, collapsing duplicate names.
+	 * @deprecated Use serialize() for lossless, attribute-preserving persistence.
+	 */
 	snapshot(): Record<string, string>;
+	/**
+	 * Restores flat values as host-only, Path=/ cookies on the session base URL.
+	 * @deprecated Use deserialize() with state produced by serialize().
+	 */
 	restore(cookies: Record<string, string>): void;
+	/** Returns a versioned, JSON-safe, attribute-preserving representation of every cookie. */
+	serialize(): StealthCookieStoreV1;
+	/** Replaces the jar with a previously serialized, attribute-preserving cookie store. */
+	deserialize(state: StealthCookieStore): void;
 	clear(): void;
 }
 
@@ -1108,7 +1136,13 @@ export interface StealthRedirectRunResult {
 	final: StealthResponse;
 	hops: StealthRedirectHop[];
 	reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+	/**
+	 * Complete flat view across all redirect hosts. Attributes and duplicate names are lost.
+	 * @deprecated Use cookieStore for lossless persistence.
+	 */
 	cookies: Record<string, string>;
+	/** Versioned, attribute-preserving cookie state accumulated across the redirect chain. */
+	cookieStore: StealthCookieStoreV1;
 }
 
 export interface StealthSession {