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

package/dist/stealth/profiles.js

@@ -194,6 +194,15 @@ export function getStealthProfile(selection = {}) {
         h2Settings: profile.h2Settings ? { ...profile.h2Settings } : undefined,
     };
 }
+/**
+ * The transport owns the browser version (Chromium follows the pinned wreq-js build), so a
+ * resolver `clientProfile` such as `safari17_0` or `chrome_149` only has to name the same
+ * browser family as the stealth session it runs on.
+ */
+export function resolverClientProfileFamily(clientProfile) {
+    const family = /^[a-z]+/u.exec(clientProfile.trim().toLowerCase())?.[0];
+    return family === "chrome" || family === "firefox" || family === "safari" ? family : undefined;
+}
 export function listStealthProfiles() {
     return SUPPORTED_STEALTH_PROFILES.map((profile) => ({ ...profile }));
 }

package/dist/testing/run.js

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { ProviderError } from "../errors.js";
 import { createProviderCache } from "../runtime/cache.js";
 import { createTestProviderChoiceContext } from "../runtime/choice.js";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
@@ -274,6 +275,11 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
     };
     const createStealthSession = () => ({
         fetch: stealthCall,
+        async replayChallenged() {
+            throw new ProviderError("Recorded transports cannot replay an engine-owned challenge", {
+                code: "REPLAY_SESSION_MISMATCH",
+            });
+        },
         cookies: {
             ...emptyCookieJar,
             has: () => false,

package/dist/types.d.ts

@@ -219,7 +219,7 @@ export interface ProviderSttConfig {
  *
  * `ProviderResolverConfig.vendors` overrides the SDK policy when declared.
  */
-export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "custom";
+export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "hypersolutions" | "custom";
 /**
  * Token-family kinds resolve to `{ form: "token" }`. Cookie-family kinds resolve
  * to `{ form: "cookies" }`; network-identity binding is defined per kind. `aws_waf`
@@ -275,6 +275,22 @@ export type ProviderChallenge = {
     readonly bmsz?: string;
     /** Bot Manager major version when known ("3" measured on zozo.jp). */
     readonly version?: string;
+} | {
+    readonly kind: "akamai_sbsd";
+    readonly pageUrl: string;
+    /**
+     * Discovered SBSD script URL. `?v=&t=` is a hard challenge and `?v=`
+     * is passive or a remembered script. A later challenge token never
+     * changes this URL.
+     */
+    readonly scriptUrl: string;
+    readonly stateCookieName: "sbsd_o" | "bm_so";
+    /**
+     * Token returned by a later `cpr_chlge` response. When present with a
+     * remembered v-only script, it selects index 0 and is appended only to
+     * the payload POST URL.
+     */
+    readonly challengeToken?: string;
 };
 export type ProviderChallengeKind = ProviderChallenge["kind"];
 /**
@@ -282,7 +298,9 @@ export type ProviderChallengeKind = ProviderChallenge["kind"];
  * per challenge kind: `aws_waf` was measured portable across residential leases
  * on buyee, while `cf_clearance` is unmeasured here and treated as scoped to the
  * identity that produced it. The provider attaches the returned cookies to its
- * own requests.
+ * own requests. `cookie_state` solutions carry no values: SBSD state lives only
+ * in the engine-owned bound jar, and a 2xx payload POST is not proof of a solve;
+ * only the next protected GET can verify it (the safe refetch is Phase 2).
  */
 export type ChallengeSolution = {
     readonly form: "token";
@@ -298,8 +316,28 @@ export type ChallengeSolution = {
      * the upstream cookie's expiry. `expires` takes precedence when both are present.
      */
     readonly sdkEstimatedExpires?: number;
+} | {
+    readonly form: "cookie_state";
+    readonly kind: "akamai_sbsd";
+    readonly outcome: "payload_accepted";
+    /** Always false until a later protected GET verifies the bound jar (Phase 2). */
+    readonly verified: false;
+    /** Name only; the identity-bound cookie value remains in the engine-owned jar. */
+    readonly stateCookieName: "sbsd_o" | "bm_so";
+    /** Epoch seconds observed on the updated state cookie, when supplied upstream. */
+    readonly expires?: number;
 };
-export interface ProviderResolverConfig {
+/**
+ * `akamai_sbsd` declarations require a transport-owned client profile because the
+ * solve runs on the provider's admitted session. Other kinds may omit it.
+ */
+export type ProviderResolverConfig = {
+    /** Optional ordered override for the SDK-owned vendor fallback chain. */
+    readonly vendors?: readonly ProviderResolverVendor[];
+    /** Challenge kinds this provider is permitted to request. */
+    readonly kinds: readonly Exclude<ProviderChallengeKind, "akamai_sbsd">[];
+    readonly clientProfile?: string;
+} | {
     /** Optional ordered override for the SDK-owned vendor fallback chain. */
     readonly vendors?: readonly ProviderResolverVendor[];
     /** Challenge kinds this provider is permitted to request. */
@@ -310,8 +348,8 @@ export interface ProviderResolverConfig {
      * challenge is served, while a Safari profile is admitted. Provider-declared
      * because only the provider knows its upstream's admission rule.
      */
-    readonly clientProfile?: string;
-}
+    readonly clientProfile: string;
+};
 export type SttAudioInput = {
     kind: "base64";
     data: string;
@@ -774,6 +812,13 @@ export type StealthProfileSelection = {
     browser: "safari";
     os?: "macos" | "ios";
 };
+/** Provider-owned opt-ins layered onto the transport-owned browser/OS profile. */
+export type ProviderStealthConfig = StealthProfileSelection & {
+    readonly challengeDetection?: {
+        /** Classify SBSD responses even when no resolver is declared (detect/report mode). */
+        readonly akamaiSbsd?: boolean;
+    };
+};
 export type BrowserEngine = "playwright-stealth" | "nodriver" | "selenium-uc";
 export interface BrowserOptions {
     headless?: boolean;
@@ -1027,9 +1072,25 @@ export interface HttpRedirectPolicy {
 export type HttpRedirectFailureReason = Exclude<RedirectRunReason, "completed">;
 export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
 export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy" | "headers"> {
+    /**
+     * Defaults to true. Set to false when callers need to inspect upstream
+     * non-2xx bodies themselves instead of converting them to TransportError.
+     *
+     * Documented exception: a non-2xx response that an opted-in SDK challenge
+     * detector classified (`response.challenge` is set) is returned, not thrown,
+     * whatever this flag says, so the classification stays observable. Callers
+     * that need the failure semantics check `response.challenge` first.
+     */
+    throwOnHttpError?: boolean;
     /**
      * Request headers. Array values and case-insensitive duplicate names are
      * combined in caller order using `", "`, matching Chrome's Fetch behavior.
+     *
+     * The stealth transport owns `host`, `connection`, `user-agent`, `sec-ch-ua`,
+     * `sec-ch-ua-mobile`, `sec-ch-ua-platform`, `accept-encoding`, and every
+     * `sec-fetch-*` header. Supplying any of them throws
+     * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` at request time; declare the request
+     * shape with `stealth.requestClass` instead.
      */
     headers?: Record<string, string | string[]>;
     method?: HttpMethod;
@@ -1049,13 +1110,26 @@ export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolic
      */
     proxyAttemptOffset?: number;
     /**
-     * SDK-specific stealth controls. Standard HTTP metadata such as language,
-     * referrer, and content type belongs in `headers`.
+     * SDK-specific stealth controls, including a per-request browser and/or OS
+     * override. Standard HTTP metadata such as language, referrer, and content
+     * type belongs in `headers`.
      */
     stealth?: StealthProfileSelection & {
-        /** Override the configured browser and/or OS for this request. */
-        /** Declare the Chrome request class when it cannot be inferred from the method. */
+        /**
+         * Declare the Chrome request class when it cannot be inferred from the
+         * method (`POST` infers `post`, everything else `navigation`). This is the
+         * replacement for hand-set `Sec-Fetch-*` headers, which the transport
+         * rejects; it drives `Sec-Fetch-Mode`/`Dest`/`User`, `Accept`, `Priority`,
+         * and `Upgrade-Insecure-Requests`.
+         */
         requestClass?: "navigation" | "xhr" | "post";
+        /**
+         * Whether a `navigation` request carries a user gesture and therefore
+         * `Sec-Fetch-User: ?1` (default `true`). Set `false` for script-driven
+         * navigations such as `location.replace`, which Chrome sends without it.
+         * Ignored for the `xhr` and `post` request classes.
+         */
+        userActivation?: boolean;
         /**
          * Use only for proxy products that terminate CONNECT with a private CA
          * instead of tunneling the origin certificate chain.
@@ -1110,6 +1184,8 @@ export interface DeclarativeStealthResponse {
     headers: Record<string, string>;
     rawHeaders: [string, string][];
     body: string;
+    /** Present only when an opted-in SDK detector returned an unresolved challenge response. */
+    challenge?: StealthChallengeClassification;
     httpVersion?: string;
     tlsInfo?: {
         protocol?: string;
@@ -1122,6 +1198,20 @@ export interface DeclarativeStealthResponse {
     bytes(): Promise<Uint8Array>;
 }
 export type StealthResponse = DeclarativeStealthResponse;
+/** Why a detected challenge response was returned to the caller instead of being solved and refetched. */
+export type StealthChallengeClassification = {
+    readonly challenge: Extract<ProviderChallenge, {
+        readonly kind: "akamai_sbsd";
+    }>;
+    /**
+     * `resolver_unavailable`: detect-only provider or no solver configured.
+     * `replay_required`: the request is not a plain GET, so it is never solved or replayed
+     * automatically. `solve_failed`: a concurrent request on the same session owned the
+     * solve and it rejected (that owner receives the error). `challenge_persisted`: the
+     * single refetch after a solve was challenged again.
+     */
+    readonly outcome: "resolver_unavailable" | "replay_required" | "solve_failed" | "challenge_persisted";
+};
 export type RequestWithMethodOptions = RequestOptions & {
     method?: string;
     body?: unknown;
@@ -1152,6 +1242,12 @@ export interface StealthRedirectRunResult {
 }
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+    /**
+     * Explicitly solve and replay one unsafe request previously classified as
+     * `replay_required`. The original method, URL, headers, and body bytes are
+     * retained by this session and may be replayed exactly once.
+     */
+    replayChallenged(response: StealthResponse): Promise<StealthResponse>;
     cookies: StealthSessionCookies;
     redirects: {
         run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
@@ -1860,8 +1956,9 @@ export interface ProviderRuntimeState {
 /**
  * The operation context exposed for one provider declaration. Capability
  * bindings are present only when their corresponding declaration is present;
- * trace and request remain ambient runtime bindings. Omitting the type
- * parameter preserves the legacy full context shape for existing annotations.
+ * platform-managed auth itself declares the credential binding. Trace and
+ * request remain ambient runtime bindings. Omitting the type parameter
+ * preserves the legacy full context shape for existing annotations.
  */
 export type ProviderContext<TConfig = Record<string, unknown>> = {
     request?: ProviderRequestContext;
@@ -1870,6 +1967,12 @@ export type ProviderContext<TConfig = Record<string, unknown>> = {
     env: EnvContext;
 } : Record<never, never>) & ("credential" extends keyof TConfig ? {
     credential: CredentialContext;
+} : TConfig extends {
+    auth: {
+        mode: "platform-managed";
+    };
+} ? {
+    credential: CredentialContext;
 } : Record<never, never>) & ("http" extends keyof TConfig ? {
     http: HttpClient;
 } : Record<never, never>) & ("files" extends keyof TConfig ? string extends keyof TConfig ? {
@@ -2047,7 +2150,7 @@ export interface ProviderDefinition<TContext = ProviderContext> {
     http?: Record<string, never> | true;
     allowedHosts?: string[];
     native?: NativeProviderConfig;
-    stealth?: StealthProfileSelection;
+    stealth?: ProviderStealthConfig;
     proxy?: ProviderProxyConfig;
     ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.57",
+	"version": "2.2.0-beta.59",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/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
@@ -109,8 +121,10 @@ Structured errors return an `error` object with `code`, `message`,
 
 - `invalid_request`: include `requestId` and `input`; omit `connection` for
   public/no-auth operations and never send `connection: null`.
-- Credentials: declare `credential.keys`, pass local-only values through
-  `connection.secrets`, and read them with `ctx.credential`.
+- Credentials: declare `credential.keys` unless `auth.mode` is `platform-managed`;
+  that mode implies an unfiltered credential capability and forbids key declarations.
+  Pass local-only values through `connection.secrets` and read them with
+  `ctx.credential`.
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
 - Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with

package/src/config/loader.ts

@@ -6,6 +6,7 @@ import path from "node:path";
 import type { Redis } from "ioredis";
 
 import type { ProviderProxyPolicy, ProviderProxyProvider, TraceConfig } from "../types.js";
+import { BoundedExpiringMap } from "../runtime/bounded-expiring-map.js";
 import {
 	NODEMAVEN_DEFAULT_PROTOCOL,
 	NODEMAVEN_FILTER_ENV,
@@ -223,7 +224,13 @@ type ProxyRedisClient = Pick<
 	"connect" | "del" | "eval" | "get" | "on" | "pttl" | "set" | "status"
 >;
 
-const proxyCache = new Map<string, CachedProxyPool>();
+// 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<string, Promise<SmartproxyAllocationResult>>();
 const invalidatedProxyKeys = new Map<string, number>();
@@ -277,6 +284,22 @@ export function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number |
 	smartproxyAllocatorDeadlineMsForTests = deadlineMs;
 }
 
+/** @internal Test-only hook for exercising the pool-cache capacity bound at a small size. */
+export function __setSmartproxyPoolCacheMaxEntriesForTests(maxEntries: number | undefined): void {
+	proxyCache = createSmartproxyPoolCache(maxEntries ?? SMARTPROXY_POOL_CACHE_MAX_ENTRIES);
+}
+
+/** @internal Test-only view of the in-memory Smartproxy cache sizes. */
+export function __getSmartproxyCacheSizesForTests(): { pools: number; tombstones: number } {
+	return { pools: proxyCache.size, tombstones: invalidatedProxyKeys.size };
+}
+
+function createSmartproxyPoolCache(
+	maxEntries: number,
+): BoundedExpiringMap<string, CachedProxyPool> {
+	return new BoundedExpiringMap(maxEntries, (pool) => pool.expiresAt);
+}
+
 function getProxyRedis(): ProxyRedisClient | undefined {
 	if (proxyRedisForTests) return proxyRedisForTests;
 	const redisUrl = redisUrlFromEnv();
@@ -760,6 +783,7 @@ export async function resolveWithVendor(
 			...allocated.pool.diagnostics,
 			poolSize: allocated.pool.urls.length,
 			poolIndex,
+			poolCacheEvictions: proxyCache.capacityEvictions,
 		},
 	};
 }
@@ -1082,8 +1106,8 @@ async function allocateSmartproxy(
 	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,
@@ -1158,7 +1182,7 @@ async function readSmartproxyRedisPool(
 	}
 	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 }),
@@ -1482,7 +1506,7 @@ async function allocateAndStoreSmartproxyPool(
 			rawConnect: true,
 		},
 	};
-	proxyCache.set(cacheKey, result);
+	proxyCache.set(cacheKey, result, allocatedAt);
 	if (options.redis && options.poolKey) {
 		const redis = options.redis;
 		const poolKey = options.poolKey;
@@ -1744,7 +1768,11 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 		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/src/declaration-validation.ts

@@ -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";
 import type {
 	HealthJourneyDefinition,
 	ProviderDefinition,
@@ -22,6 +24,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",
 } as const;
 
 export type DeclarationRuleId =
@@ -57,11 +60,15 @@ export function validateFailClosedDeclaration(provider: ProviderDefinition): voi
 	validatePinnedWireFieldPaths(provider, violations);
 	validateSchemaDeclaration(provider, violations);
 	validateProxyDeclaration(provider, violations);
+	validateResolverClientProfileDeclaration(provider, violations);
 	validateOperationDeclaration(provider, violations);
 	if (violations.length > 0) throw declarationInvalidError(violations);
 }
 
-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. */
@@ -89,6 +96,7 @@ function collectProviderDeclarationViolations(
 	validateHealthDeclaration(provider, violations);
 	validatePinnedWireFieldPaths(provider, violations);
 	validateProxyDeclaration(provider, violations);
+	validateResolverClientProfileDeclaration(provider, violations);
 }
 
 function validatePinnedWireFieldPaths(
@@ -307,6 +315,44 @@ function validateProxyDeclaration(
 	}
 }
 
+/**
+ * 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: ProviderDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	const resolver = provider.resolver;
+	if (
+		!resolver ||
+		!Array.isArray(resolver.kinds) ||
+		!resolver.kinds.some(kindRequiresClientProfile) ||
+		typeof resolver.clientProfile !== "string"
+	) {
+		return;
+	}
+	let sessionBrowser: string;
+	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: ProviderProxyPolicy): ProviderProxyProvider[] {
 	const vendors = [...(policy.providers ?? [])];
 	if (policy.provider !== undefined) vendors.push(policy.provider);

package/src/define.ts

@@ -6,8 +6,15 @@ import {
 } 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,
@@ -49,9 +56,9 @@ import type {
 	ProviderSecretDeclaration,
 	ProviderStreamEvent,
 	ProviderSttConfig,
+	ProviderStealthConfig,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
-	StealthProfileSelection,
 } from "./types.js";
 import {
 	HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
@@ -151,6 +158,7 @@ export const VALID_PROVIDER_RESOLVER_VENDORS = exhaustiveLiteralArray<ProviderRe
 	"capsolver",
 	"capmonster",
 	"2captcha",
+	"hypersolutions",
 	"custom",
 ] as const);
 export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderChallengeKind>()([
@@ -162,6 +170,7 @@ export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderCha
 	"aws_waf",
 	"akamai_sec_cpt",
 	"akamai_sensor",
+	"akamai_sbsd",
 ] as const);
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"] as const;
@@ -584,7 +593,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;
@@ -600,6 +609,7 @@ export interface ProviderDeclaration {
 	secrets?: ProviderSecretDeclaration[];
 	/** Declares the environment capability binding. A bare object states use without configuration. */
 	env?: Record<string, never> | true;
+	/** Declares credential keys; platform-managed auth declares this capability without key filtering. */
 	credential?: CredentialDeclaration;
 	/** Declares provider context metadata; this does not add a `ctx.context` member. */
 	context?: ContextDeclaration;
@@ -938,6 +948,15 @@ function validateProviderProxy(config: {
 	secrets?: ProviderSecretDeclaration[];
 }): void {
 	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}"`,
@@ -946,6 +965,22 @@ function validateProviderProxy(config: {
 				},
 			);
 		}
+		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}"`,
@@ -1162,6 +1197,14 @@ function validateProviderResolver(config: { id: string; resolver?: ProviderResol
 			},
 		);
 	}
+	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<TValue extends string>(