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

package/AUTHORING.md

@@ -130,6 +130,12 @@ not list `APIFUSE__PROXY__SMARTPROXY_APP_KEY`,
 `APIFUSE__PROXY__NODEMAVEN_PASSWORD` in provider `secrets`; `proxy` contains
 policy intent only.
 
+Hosted runtime settings are engine-owned as well: every `APIFUSE__CDP_POOL__*`
+variable, the Cloudflare OCR/STT tokens and account identifier,
+`APIFUSE__OCR__API_KEY`, `APIFUSE__CACHE__KEY_PEPPER`, and
+`APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET`. `defineProvider`
+rejects them in `secrets`; the engine reads them from its own environment.
+
 ### Factored operations
 
 `defineProvider(declaration)` returns the builder that accepts `operations`, so
@@ -501,6 +507,9 @@ SDK observability is emitted separately in the
 ```
 
 Treat this header as telemetry, not as provider-controlled public error detail.
+It is SDK-owned even when a handler returns a raw `Response`: a caller-set
+header is dropped, and a raw status of 400 or above gets a status-derived one
+(retryable only for 408, 429, and 5xx) while the body is left untouched.
 Its category, taxonomy version, retryability, and optional upstream status match
 the structured `provider_request_failed` log event.
 

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.59
+
+- Release candidate for main commit 55ae556fcf33e28a228c2d54ce76e7afa41e5dc7.
+
 ## 2.2.0-beta.58
 
 - Release candidate for main commit e137940caa8bc32ce768571a6197651e581c2270.

package/README.md

@@ -76,7 +76,14 @@ The operation request body is the same envelope used by the APIFuse gateway:
 | `requestId` | yes | Any unique string is fine for local debugging; it is echoed in structured errors. |
 | `input` | yes | The operation input after schema validation. |
 | `headers` | no | Extra caller headers to expose through `ctx.request.headers`. |
-| `connection` | no | Omit for no-auth/public operations. For credential debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+| `connectionId` | no | Connection identity only; it does not include credentials. The gateway sends it for `optional` connection mode, and only when the caller supplied a connection that passed authorization. Exposed as `ctx.request.connectionId`. |
+| `connection` | no | Credential-bearing connection data. The gateway sends it for `required` connection mode; omit it for no-auth/public (`none` mode) operations. For local debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+
+The gateway sends only `connection` for `required` mode, only `connectionId`
+for `optional` mode (and nothing when the caller passed no connection), and
+neither field for `none` mode. If a malformed or manually constructed envelope
+contains both, a non-empty nested `connection.id` takes precedence over the
+top-level `connectionId`; an empty string is treated as absent.
 
 Credential-bearing local smoke example:
 
@@ -146,7 +153,11 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
   identity with structured `stealth: { browser, os }` options; omitted `os`
-  explicitly defaults to `macos`. Do not pin a browser version
+  explicitly defaults to `macos`. The transport owns `User-Agent`,
+  `Accept-Encoding`, `sec-ch-ua*`, and every `Sec-Fetch-*` header and throws
+  `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` if you set one; declare
+  `stealth.requestClass: "navigation" | "xhr" | "post"` instead. Do not pin a
+  browser version
   or tune JA3, HTTP/2 SETTINGS, or
   pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
   are supported; use `ctx.browser` when the provider needs browser execution.
@@ -325,3 +336,8 @@ External bounty contributors should submit standalone Provider source plus
 `bun run check` / `bun run test` evidence. APIFuse maintainers own monorepo
 import, registry generation, deployment projection checks, and release
 publishing.
+
+Relayed user-generated text (listing bodies, reviews, posts) is contained by the
+platform, not by the provider. Wrap such output fields in `untrustedContent(...)`
+so the schema carries `x-apifuse-content-trust: untrusted` and
+`x-apifuse-content-provenance: external`; do not strip instruction-like prose.

package/bin/apifuse-pack-types.ts

@@ -401,6 +401,55 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-resolver-telemetry-description.ts",
+		expectedCode: "TS2353",
+		description: "resolver gateway telemetry rejects vendor error descriptions",
+		source: [
+			'import type { ResolverTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverTelemetryHeaderPayload = {",
+			"\tattempts: 0,",
+			"\tfailovers: 0,",
+			"\tvendorChain: [],",
+			"\tpollCount: 0,",
+			'\tvendorErrorDescription: "free text must stay log-only",',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-telemetry-phase.ts",
+		expectedCode: "TS2322",
+		description: "resolver gateway telemetry rejects phases outside its closed vocabulary",
+		source: [
+			'import { closedEnum, type ResolverTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverTelemetryHeaderPayload = {",
+			"\tattempts: 1,",
+			"\tfailovers: 0,",
+			'\tvendorChain: [closedEnum("hypersolutions")],',
+			"\tpollCount: 0,",
+			'\tattemptSamples: [{ v: closedEnum("hypersolutions"), p: closedEnum("solve_exchange"), o: closedEnum("error"), ms: 1 }],',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-resolver-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "resolver telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { closedEnum, ResolverTelemetryCollector, type GatewayIngestible, type ResolverTelemetryHeaderPayload, type ResolverTelemetryLogPayload, type ResolverTelemetryPhase, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"export const resolver: TelemetryContributor<ResolverTelemetryLogPayload, ResolverTelemetryHeaderPayload> = new ResolverTelemetryCollector();",
+			'const hyperPhases: ResolverTelemetryPhase[] = ["measure_ip", "fetch_script", "generate_payload", "post_payload"];',
+			'export const hyperPhaseHeader: ResolverTelemetryHeaderPayload = { attempts: 1, failovers: 0, vendorChain: [closedEnum("hypersolutions")], pollCount: 0, attemptSamples: hyperPhases.map((phase) => ({ v: closedEnum("hypersolutions"), p: closedEnum(phase), o: closedEnum("ok"), ms: 1 })) };',
+			"declare const header: ResolverTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<ResolverTelemetryHeaderPayload> = header;",
+			"",
+		].join("\n"),
+	},
 ] as const;
 
 const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));

package/bin/apifuse-record.ts

@@ -832,6 +832,12 @@ function proxyStealthSession(
 			onResponse(order, response);
 			return response;
 		},
+		replayChallenged: async (...args: Parameters<StealthSession["replayChallenged"]>) => {
+			const order = reserveOrder();
+			const response = await session.replayChallenged(...args);
+			onResponse(order, response);
+			return response;
+		},
 		cookies: session.cookies,
 		redirects: {
 			run: async (...args: Parameters<StealthSession["redirects"]["run"]>) => {

package/dist/cli/templates/provider/README.md.tpl

@@ -97,9 +97,21 @@ The `POST /v1/{operation}` body is a request envelope:
 - `requestId` is required and can be any unique local debugging string.
 - `input` contains the operation input shape.
 - `headers` is optional.
-- `connection` is optional; omit it for no-auth/public operations. For
-  credential debugging, pass `{ "id", "mode", "secrets", "metadata",
-  "externalRef" }` with local-only secret values.
+- `connectionId` is optional connection identity only and does not include
+  credentials. The gateway sends it for `optional` connection mode, and only
+  when the caller supplied a connection that passed authorization. It is
+  exposed as `ctx.request.connectionId`.
+- `connection` is optional credential-bearing connection data. The gateway
+  sends it for `required` connection mode; omit it for no-auth/public (`none`
+  mode) operations. For local debugging, pass
+  `{ "id", "mode", "secrets", "metadata", "externalRef" }` with local-only
+  secret values.
+
+The gateway sends only `connection` for `required` mode, only `connectionId`
+for `optional` mode (and nothing when the caller passed no connection), and
+neither field for `none` mode. If a malformed or manually constructed envelope
+contains both, a non-empty nested `connection.id` takes precedence over the
+top-level `connectionId`; an empty string is treated as absent.
 
 Structured errors return an `error` object with `code`, `message`,
 `requestId`, and optional `details`; validation failures include field paths in

package/dist/config/loader.d.ts

@@ -140,6 +140,13 @@ export declare function providerStateRedisUrlFromEnv(): string | undefined;
 /** @internal Test-only hook for exercising shared proxy-cache behavior. */
 export declare function __setProxyRedisForTests(redis: ProxyRedisClient | undefined): void;
 export declare function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number | undefined): void;
+/** @internal Test-only hook for exercising the pool-cache capacity bound at a small size. */
+export declare function __setSmartproxyPoolCacheMaxEntriesForTests(maxEntries: number | undefined): void;
+/** @internal Test-only view of the in-memory Smartproxy cache sizes. */
+export declare function __getSmartproxyCacheSizesForTests(): {
+    pools: number;
+    tombstones: number;
+};
 export declare function resolveProxyConfig(options?: ProxyResolutionOptions): ResolvedProxyConfig;
 export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
 /**

package/dist/config/loader.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
+import { BoundedExpiringMap } from "../runtime/bounded-expiring-map.js";
 import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_FILTER_ENV, NODEMAVEN_MAX_POOL_SIZE, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
 // "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
 // extraction API (app_key → raw ip:port pool). It is NOT the company formerly
@@ -33,7 +34,13 @@ export class ProxyResolutionError extends Error {
         this.protocol = options?.protocol;
     }
 }
-const proxyCache = new Map();
+// Keyed per (policy, affinity). Connection affinities are minted by callers, so
+// without a cap a long-lived process accumulates one pool per affinity it ever
+// saw. Evicting a still-fresh pool forces a fresh allocation (a different
+// egress endpoint) for that affinity, so the cap is generous and every
+// capacity eviction is reported as `diagnostics.poolCacheEvictions`.
+const SMARTPROXY_POOL_CACHE_MAX_ENTRIES = 10_000;
+let proxyCache = createSmartproxyPoolCache(SMARTPROXY_POOL_CACHE_MAX_ENTRIES);
 const require = createRequire(import.meta.url);
 const proxyInflight = new Map();
 const invalidatedProxyKeys = new Map();
@@ -76,6 +83,17 @@ export function __setProxyRedisForTests(redis) {
 export function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs) {
     smartproxyAllocatorDeadlineMsForTests = deadlineMs;
 }
+/** @internal Test-only hook for exercising the pool-cache capacity bound at a small size. */
+export function __setSmartproxyPoolCacheMaxEntriesForTests(maxEntries) {
+    proxyCache = createSmartproxyPoolCache(maxEntries ?? SMARTPROXY_POOL_CACHE_MAX_ENTRIES);
+}
+/** @internal Test-only view of the in-memory Smartproxy cache sizes. */
+export function __getSmartproxyCacheSizesForTests() {
+    return { pools: proxyCache.size, tombstones: invalidatedProxyKeys.size };
+}
+function createSmartproxyPoolCache(maxEntries) {
+    return new BoundedExpiringMap(maxEntries, (pool) => pool.expiresAt);
+}
 function getProxyRedis() {
     if (proxyRedisForTests)
         return proxyRedisForTests;
@@ -457,6 +475,7 @@ export async function resolveWithVendor(vendor, policy, options, context) {
             ...allocated.pool.diagnostics,
             poolSize: allocated.pool.urls.length,
             poolIndex,
+            poolCacheEvictions: proxyCache.capacityEvictions,
         },
     };
 }
@@ -695,8 +714,8 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
     const now = startedAt;
     const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
     const skipCached = invalidatedUntil > now;
-    const cached = proxyCache.get(cacheKey);
-    if (!skipCached && cached && isFresh(cached, now)) {
+    const cached = skipCached ? undefined : proxyCache.get(cacheKey, now);
+    if (cached) {
         if (shouldSoftRefresh(cached, now)) {
             void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol, ambientDefaults, sharedCache);
             return {
@@ -751,7 +770,7 @@ async function readSmartproxyRedisPool(cacheKey, startedAt) {
     const now = Date.now();
     if (!isFresh(pool, now))
         return null;
-    proxyCache.set(cacheKey, pool);
+    proxyCache.set(cacheKey, pool, now);
     return {
         pool,
         telemetry: telemetryForPool(pool, "redis_hit", startedAt, { redisReadMs }),
@@ -962,7 +981,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
             rawConnect: true,
         },
     };
-    proxyCache.set(cacheKey, result);
+    proxyCache.set(cacheKey, result, allocatedAt);
     if (options.redis && options.poolKey) {
         const redis = options.redis;
         const poolKey = options.poolKey;
@@ -1164,7 +1183,12 @@ function markSmartproxyCacheInvalidated(options = {}) {
     if (!appKey)
         return undefined;
     const cacheKey = buildSmartproxyCacheKey(policy, appKey, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);
-    invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
+    const now = Date.now();
+    for (const [key, invalidatedUntil] of invalidatedProxyKeys) {
+        if (invalidatedUntil <= now)
+            invalidatedProxyKeys.delete(key);
+    }
+    invalidatedProxyKeys.set(cacheKey, now + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
     proxyCache.delete(cacheKey);
     proxyInflight.delete(cacheKey);
     return cacheKey;

package/dist/declaration-validation.d.ts

@@ -13,6 +13,7 @@ export declare const DECLARATION_RULE_IDS: {
     readonly proxySmartproxyGeo: "proxy-smartproxy-country-only";
     readonly operationUpstreamProxy: "operation-upstream-proxy-unsupported";
     readonly pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid";
+    readonly resolverClientProfileFamily: "resolver-client-profile-family";
 };
 export type DeclarationRuleId = (typeof DECLARATION_RULE_IDS)[keyof typeof DECLARATION_RULE_IDS];
 export type DeclarationViolation = {
@@ -24,7 +25,7 @@ export type DeclarationViolation = {
 export declare function declarationInvalidError(violations: readonly DeclarationViolation[]): ProviderError;
 /** Enforces declaration rules whose runtime behavior would otherwise fail open. */
 export declare function validateFailClosedDeclaration(provider: ProviderDefinition): void;
-type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "meta" | "proxy">;
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "meta" | "proxy" | "resolver" | "stealth">;
 type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
 /** Enforces fail-closed rules that only depend on the provider declaration. */
 export declare function validateFailClosedProviderDeclaration(provider: ProviderDeclarationRulesInput): void;

package/dist/declaration-validation.js

@@ -1,6 +1,8 @@
 import { describeSchema } from "./contract-serialization.js";
 import { ProviderError } from "./errors.js";
 import { HealthScenarioSchema } from "./health-scenario.js";
+import { kindRequiresClientProfile } from "./runtime/resolver-config.js";
+import { resolverClientProfileFamily, resolveStealthProfileSelection } from "./stealth/profiles.js";
 export const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
 export const DECLARATION_RULE_IDS = {
     challengeShape: "credentials-challenge-shape",
@@ -14,6 +16,7 @@ export const DECLARATION_RULE_IDS = {
     proxySmartproxyGeo: "proxy-smartproxy-country-only",
     operationUpstreamProxy: "operation-upstream-proxy-unsupported",
     pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid",
+    resolverClientProfileFamily: "resolver-client-profile-family",
 };
 export function declarationInvalidError(violations) {
     const summary = violations
@@ -32,6 +35,7 @@ export function validateFailClosedDeclaration(provider) {
     validatePinnedWireFieldPaths(provider, violations);
     validateSchemaDeclaration(provider, violations);
     validateProxyDeclaration(provider, violations);
+    validateResolverClientProfileDeclaration(provider, violations);
     validateOperationDeclaration(provider, violations);
     if (violations.length > 0)
         throw declarationInvalidError(violations);
@@ -54,6 +58,7 @@ function collectProviderDeclarationViolations(provider, violations) {
     validateHealthDeclaration(provider, violations);
     validatePinnedWireFieldPaths(provider, violations);
     validateProxyDeclaration(provider, violations);
+    validateResolverClientProfileDeclaration(provider, violations);
 }
 function validatePinnedWireFieldPaths(provider, violations) {
     const pins = provider.meta?.contract?.pinnedWireFieldPaths;
@@ -245,6 +250,40 @@ function validateProxyDeclaration(provider, violations) {
         }
     }
 }
+/**
+ * An akamai_sbsd solve runs on the provider's own stealth session, so the declared
+ * resolver.clientProfile must name the browser family that session emulates. The
+ * stealth runtime re-checks per request (a fetch may override the browser); this
+ * rule fails the declaration instead of the first challenged request.
+ */
+function validateResolverClientProfileDeclaration(provider, violations) {
+    const resolver = provider.resolver;
+    if (!resolver ||
+        !Array.isArray(resolver.kinds) ||
+        !resolver.kinds.some(kindRequiresClientProfile) ||
+        typeof resolver.clientProfile !== "string") {
+        return;
+    }
+    let sessionBrowser;
+    try {
+        sessionBrowser = resolveStealthProfileSelection(provider.stealth).browser;
+    }
+    catch {
+        // An unsupported stealth selection is reported by the stealth runtime itself.
+        return;
+    }
+    const family = resolverClientProfileFamily(resolver.clientProfile);
+    if (family === sessionBrowser)
+        return;
+    violations.push({
+        ruleId: DECLARATION_RULE_IDS.resolverClientProfileFamily,
+        path: "resolver.clientProfile",
+        message: family
+            ? `"${resolver.clientProfile}" names ${family}, but the stealth session browser is ${sessionBrowser}.`
+            : `"${resolver.clientProfile}" does not name a supported browser family (chrome, firefox, safari).`,
+        fix: `Declare stealth.browser as the family resolver.clientProfile names, or set resolver.clientProfile to the ${sessionBrowser} profile the SBSD session runs on.`,
+    });
+}
 function declaredProxyVendors(policy) {
     const vendors = [...(policy.providers ?? [])];
     if (policy.provider !== undefined)

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderRuntimeTarget, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthProfileSelection } from "./types.js";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderRuntimeTarget, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, ProviderStealthConfig, SchemaLike, SmsOtpMatcherDefinition } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -8,8 +8,8 @@ interface ProviderImplementationProfile {
     operatorNotes?: string;
     visibility: "internal" | "operator";
 }
-export declare const VALID_PROVIDER_RESOLVER_VENDORS: readonly ["browser", "capsolver", "capmonster", "2captcha", "custom"];
-export declare const VALID_PROVIDER_CHALLENGE_KINDS: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
+export declare const VALID_PROVIDER_RESOLVER_VENDORS: readonly ["browser", "capsolver", "capmonster", "2captcha", "hypersolutions", "custom"];
+export declare const VALID_PROVIDER_CHALLENGE_KINDS: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor", "akamai_sbsd"];
 type ProviderOperation = OperationDefinition<any, any, any>;
 type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike, TContext = ProviderContext> = Omit<OperationDefinition<TInput, TOutput, TContext>, "handler"> & {
     handler(ctx: TContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
@@ -60,7 +60,7 @@ export interface ProviderDeclaration {
     /** Declares upstream host policy; this does not add a `ctx.allowedHosts` member. */
     allowedHosts?: string[];
     native?: NativeProviderConfig;
-    stealth?: StealthProfileSelection;
+    stealth?: ProviderStealthConfig;
     /** Declares proxy policy; this is provider intent and does not add a `ctx.proxy` member. */
     proxy?: ProviderProxyConfig;
     ocr?: ProviderOcrConfig;

package/dist/define.js

@@ -2,8 +2,9 @@ import ms from "ms";
 import { validateFailClosedOperationDeclaration, validateFailClosedProviderDeclaration, } from "./declaration-validation.js";
 import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
-import { isEngineOwnedProxyCredentialName, isEngineOwnedTelemetryEnvName } from "./engine.js";
+import { engineOwnedResolverCredentialTarget, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, } from "./engine.js";
 import { HealthScenarioSchema } from "./health-scenario.js";
+import { kindRequiresClientProfile } from "./runtime/resolver-config.js";
 import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
 import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
@@ -61,6 +62,7 @@ export const VALID_PROVIDER_RESOLVER_VENDORS = exhaustiveLiteralArray()([
     "capsolver",
     "capmonster",
     "2captcha",
+    "hypersolutions",
     "custom",
 ]);
 export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray()([
@@ -72,6 +74,7 @@ export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray()([
     "aws_waf",
     "akamai_sec_cpt",
     "akamai_sensor",
+    "akamai_sbsd",
 ]);
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"];
@@ -633,11 +636,27 @@ function validateProviderImplementationShape(config) {
 }
 function validateProviderProxy(config) {
     for (const secret of config.secrets ?? []) {
+        const engineName = engineOwnedResolverCredentialTarget(secret.name);
+        if (engineName !== undefined) {
+            throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned resolver credential "${secret.name}"`, {
+                fix: `Remove "${secret.name}" from provider secrets; configure the solver key only on the provider engine as ${engineName}.`,
+            });
+        }
         if (isEngineOwnedTelemetryEnvName(secret.name)) {
             throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned telemetry variable "${secret.name}"`, {
                 fix: `Remove "${secret.name}" from provider secrets; trace export is configured only on the provider engine.`,
             });
         }
+        if (isEngineOwnedRuntimeEnvName(secret.name)) {
+            throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned runtime variable "${secret.name}"`, {
+                fix: `Remove "${secret.name}" from provider secrets; the provider engine reads it from its own environment.`,
+            });
+        }
+        if (isEngineOwnedEnvName(secret.name) && !isEngineOwnedProxyCredentialName(secret.name)) {
+            throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned control variable "${secret.name}"`, {
+                fix: `Remove "${secret.name}" from provider secrets; configure it only on the provider engine.`,
+            });
+        }
         if (!isEngineOwnedProxyCredentialName(secret.name))
             continue;
         throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned proxy credential "${secret.name}"`, {
@@ -785,6 +804,11 @@ function validateProviderResolver(config) {
             fix: `Set resolver.clientProfile for provider "${config.id}" to a transport-owned profile name.`,
         });
     }
+    if (resolver.kinds.some(kindRequiresClientProfile) && resolver.clientProfile === undefined) {
+        throw new ValidationError(`Provider "${config.id}" must declare resolver.clientProfile for akamai_sbsd.`, {
+            fix: `Set resolver.clientProfile for provider "${config.id}" to the transport-owned profile used by its Akamai session.`,
+        });
+    }
 }
 function validateResolverLiteralArray(value, field, validValues, providerId) {
     if (!Array.isArray(value)) {

package/dist/engine.d.ts

@@ -4,6 +4,15 @@ export declare const PROVIDER_ENGINE_PROTOCOL_VERSION: "provider-engine.v1";
 /** Credential names owned by the engine and forbidden in provider declarations. */
 export declare const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__PROXY__SMARTPROXY_APP_KEY", "APIFUSE__PROXY__NODEMAVEN_USERNAME", "APIFUSE__PROXY__NODEMAVEN_PASSWORD"];
 export declare function isEngineOwnedProxyCredentialName(name: string): boolean;
+/** Hosted resolver credentials owned by the engine and never projected to providers. */
+export declare const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__RESOLVER__2CAPTCHA__API_KEY", "APIFUSE__RESOLVER__CAPSOLVER__API_KEY", "APIFUSE__RESOLVER__CAPMONSTER__API_KEY", "APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY"];
+/**
+ * Engine variable a provider-declared secret name resolves to, or `undefined` when the
+ * name is not an engine-owned resolver credential. Provider-scoped Hyper aliases
+ * (`APIFUSE__PROVIDER__<ID>__HYPER_API_KEY`, measured on zozotown) map to the shared key.
+ */
+export declare function engineOwnedResolverCredentialTarget(name: string): string | undefined;
+export declare function isEngineOwnedResolverCredentialName(name: string): boolean;
 /**
  * Trace-export configuration owned by the engine and forbidden in provider
  * declarations. The header variables carry collector credentials; the rest are
@@ -11,6 +20,13 @@ export declare function isEngineOwnedProxyCredentialName(name: string): boolean;
  */
 export declare const ENGINE_OWNED_TELEMETRY_ENV_NAMES: readonly ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_HEADERS", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_SERVICE_NAME", "OTEL_RESOURCE_ATTRIBUTES"];
 export declare function isEngineOwnedTelemetryEnvName(name: string): boolean;
+/**
+ * Hosted runtime settings the engine reads for OCR, STT, cache keying, choice
+ * tokens, and the CDP pool. Providers never own them: declarations are rejected
+ * and projections drop them, like the vendor credentials above.
+ */
+export declare const ENGINE_OWNED_RUNTIME_ENV_NAMES: readonly ["APIFUSE__STT__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__API_KEY", "APIFUSE__CLOUDFLARE__ACCOUNT_ID", "APIFUSE__CACHE__KEY_PEPPER", "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET"];
+export declare function isEngineOwnedRuntimeEnvName(name: string): boolean;
 /** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
 export declare function isEngineOwnedEnvName(name: string): boolean;
 /** Capture credentials in the engine host before constructing provider bindings. */

package/dist/engine.js

@@ -1,4 +1,5 @@
 import { ProviderError } from "./errors.js";
+import { APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, } from "./runtime/resolver-config.js";
 import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME, } from "./runtime/otlp.js";
 /** Versioned envelope protocol used by out-of-process engine transports. */
 export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1";
@@ -20,6 +21,31 @@ function canonicalEnvName(name) {
 export function isEngineOwnedProxyCredentialName(name) {
     return ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET.has(canonicalEnvName(name));
 }
+/** Hosted resolver credentials owned by the engine and never projected to providers. */
+export const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES = [
+    APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+    APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+    APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+    APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
+];
+const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET = new Set(ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES);
+/**
+ * Engine variable a provider-declared secret name resolves to, or `undefined` when the
+ * name is not an engine-owned resolver credential. Provider-scoped Hyper aliases
+ * (`APIFUSE__PROVIDER__<ID>__HYPER_API_KEY`, measured on zozotown) map to the shared key.
+ */
+export function engineOwnedResolverCredentialTarget(name) {
+    const canonical = canonicalEnvName(name);
+    if (ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET.has(canonical))
+        return canonical;
+    if (/^APIFUSE__PROVIDER__.+__HYPER_API_KEY$/u.test(canonical)) {
+        return APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY;
+    }
+    return undefined;
+}
+export function isEngineOwnedResolverCredentialName(name) {
+    return engineOwnedResolverCredentialTarget(name) !== undefined;
+}
 /**
  * Trace-export configuration owned by the engine and forbidden in provider
  * declarations. The header variables carry collector credentials; the rest are
@@ -37,9 +63,38 @@ const ENGINE_OWNED_TELEMETRY_ENV_NAME_SET = new Set(ENGINE_OWNED_TELEMETRY_ENV_N
 export function isEngineOwnedTelemetryEnvName(name) {
     return ENGINE_OWNED_TELEMETRY_ENV_NAME_SET.has(canonicalEnvName(name));
 }
+/** Engine control-plane configuration is never declarable or visible to provider code. */
+function isEngineOwnedEngineEnvName(name) {
+    return canonicalEnvName(name).startsWith("APIFUSE__ENGINE__");
+}
+/**
+ * Hosted runtime settings the engine reads for OCR, STT, cache keying, choice
+ * tokens, and the CDP pool. Providers never own them: declarations are rejected
+ * and projections drop them, like the vendor credentials above.
+ */
+export const ENGINE_OWNED_RUNTIME_ENV_NAMES = [
+    "APIFUSE__STT__CLOUDFLARE_API_TOKEN",
+    "APIFUSE__OCR__CLOUDFLARE_API_TOKEN",
+    "APIFUSE__OCR__API_KEY",
+    "APIFUSE__CLOUDFLARE__ACCOUNT_ID",
+    "APIFUSE__CACHE__KEY_PEPPER",
+    "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET",
+];
+const ENGINE_OWNED_RUNTIME_ENV_NAME_SET = new Set(ENGINE_OWNED_RUNTIME_ENV_NAMES);
+/** CDP pool settings form a prefix family (`APIFUSE__CDP_POOL__URL` today); the whole prefix is engine-owned. */
+const ENGINE_OWNED_CDP_POOL_ENV_PREFIX = "APIFUSE__CDP_POOL__";
+export function isEngineOwnedRuntimeEnvName(name) {
+    const canonical = canonicalEnvName(name);
+    return (ENGINE_OWNED_RUNTIME_ENV_NAME_SET.has(canonical) ||
+        canonical.startsWith(ENGINE_OWNED_CDP_POOL_ENV_PREFIX));
+}
 /** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
 export function isEngineOwnedEnvName(name) {
-    return isEngineOwnedProxyCredentialName(name) || isEngineOwnedTelemetryEnvName(name);
+    return (isEngineOwnedEngineEnvName(name) ||
+        isEngineOwnedProxyCredentialName(name) ||
+        isEngineOwnedResolverCredentialName(name) ||
+        isEngineOwnedRuntimeEnvName(name) ||
+        isEngineOwnedTelemetryEnvName(name));
 }
 /** Capture credentials in the engine host before constructing provider bindings. */
 export function readEngineProxyCredentials(environment = process.env) {

package/dist/error-resolution.js

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