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

package/src/auth.ts

@@ -1,4 +1,9 @@
 import { AuthError, ProviderError } from "./errors.js";
+import {
+	declarationInvalidError,
+	DECLARATION_RULE_IDS,
+	type DeclarationViolation,
+} from "./declaration-validation.js";
 import type {
 	AuthAbortData,
 	AuthConfig,
@@ -656,6 +661,7 @@ export function defineCredentialsAuth<
 		string,
 		CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, string>
 	>;
+	validateCredentialsAuthChallenges(challenges);
 
 	return {
 		auth: {
@@ -726,3 +732,37 @@ export function defineCredentialsAuth<
 		},
 	};
 }
+
+function validateCredentialsAuthChallenges(
+	challenges: Record<
+		string,
+		CredentialsAuthChallengeDefinition<CredentialsAuthFields, readonly string[], string>
+	>,
+): void {
+	const violations: DeclarationViolation[] = [];
+	for (const [challengeId, challenge] of Object.entries(challenges)) {
+		const fieldCount =
+			challenge.fields && typeof challenge.fields === "object"
+				? Object.keys(challenge.fields).length
+				: 0;
+		const fieldsDeclared =
+			challenge.fields !== undefined && challenge.fields !== null;
+		const hasFields = fieldCount > 0;
+		const hasVerify = typeof challenge.verify === "function";
+		const hasPoll = typeof challenge.poll === "function";
+		const isInteractive = hasFields && hasVerify && !hasPoll;
+		const isPolling = !fieldsDeclared && !hasVerify && hasPoll;
+		const isHybrid = hasFields && hasVerify && hasPoll;
+		const emptyFieldsDeclared = fieldsDeclared && !hasFields;
+		if (!emptyFieldsDeclared && (isInteractive || isPolling || isHybrid)) continue;
+
+		const path = `challenges.${challengeId}`;
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.challengeShape,
+			path,
+			message: "challenge must be interactive, polling, or an explicit hybrid.",
+			fix: `Give ${path} non-empty fields plus verify, poll alone, or all three for a hybrid.`,
+		});
+	}
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}

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

@@ -114,10 +114,10 @@ Structured errors return an `error` object with `code`, `message`,
 - 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 an
-  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
-  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
-  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
-  (`nodriver` is Python-runtime only), then install local Chromium with
+  SDK stealth `profile`; the TypeScript stealth runtime uses `wreq-js` internally
+  and supports Chrome, Firefox, and Safari profiles. Use `ctx.browser` only when
+  the provider needs browser execution; TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only). Install local Chromium with
   `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
 
 ## Next steps

package/src/contract-serialization.ts

@@ -64,14 +64,12 @@ function isZodSchema(schema: SchemaLike): schema is ZodType {
 	return schema instanceof z.ZodType;
 }
 
-function zodJsonSchema(schema: ZodType): JsonValue | undefined {
-	try {
-		const jsonSchema = z.toJSONSchema(schema);
-		return toJsonValue(jsonSchema);
-	} catch (error) {
-		if (error instanceof Error) return undefined;
-		throw error;
+function zodJsonSchema(schema: ZodType): JsonValue {
+	const jsonSchema = toJsonValue(z.toJSONSchema(schema));
+	if (jsonSchema === undefined) {
+		throw new TypeError("z.toJSONSchema() returned a non-JSON value");
 	}
+	return jsonSchema;
 }
 
 function getSchemaTypeName(schema: SchemaLike): string | undefined {

package/src/declaration-validation.ts

@@ -0,0 +1,202 @@
+import { describeSchema } from "./contract-serialization.js";
+import { ProviderError } from "./errors.js";
+import type {
+	HealthJourneyDefinition,
+	ProviderDefinition,
+	ProviderProxyPolicy,
+	ProviderProxyProvider,
+} from "./types.js";
+
+export const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
+
+export const DECLARATION_RULE_IDS = {
+	challengeShape: "credentials-challenge-shape",
+	journeyExecutable: "health-journey-executable",
+	schemaSerializable: "operation-schema-serializable",
+	proxyExplicitPolicy: "proxy-explicit-policy",
+	proxyVendorExclusive: "proxy-vendor-fields-exclusive",
+	proxyNoMixedVendors: "proxy-no-mixed-vendors",
+	proxySmartproxyGeo: "proxy-smartproxy-country-only",
+	operationUpstreamProxy: "operation-upstream-proxy-unsupported",
+} as const;
+
+export type DeclarationRuleId =
+	(typeof DECLARATION_RULE_IDS)[keyof typeof DECLARATION_RULE_IDS];
+
+export type DeclarationViolation = {
+	ruleId: DeclarationRuleId;
+	path: string;
+	message: string;
+	fix: string;
+};
+
+export function declarationInvalidError(
+	violations: readonly DeclarationViolation[],
+): ProviderError {
+	const summary = violations
+		.map((violation) => `${violation.path} [${violation.ruleId}]: ${violation.message}`)
+		.join("\n");
+	return new ProviderError(
+		`Provider declaration is invalid (${violations.length} violation${violations.length === 1 ? "" : "s"}).${summary ? `\n${summary}` : ""}`,
+		{
+			code: DECLARATION_INVALID_CODE,
+			details: { violations: [...violations] },
+			fix: "Apply every violation's fix hint, then validate the declaration again.",
+		},
+	);
+}
+
+/** Enforces declaration rules whose runtime behavior would otherwise fail open. */
+export function validateFailClosedDeclaration(provider: ProviderDefinition): void {
+	const violations: DeclarationViolation[] = [];
+	validateHealthDeclaration(provider, violations);
+	validateSchemaDeclaration(provider, violations);
+	validateProxyDeclaration(provider, violations);
+	validateOperationDeclaration(provider, violations);
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}
+
+function validateHealthDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
+		if (!journey || typeof journey !== "object") continue;
+		if (typeof journey.run !== "function") {
+			const journeyPath = healthJourneyPath(journey, index);
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.journeyExecutable,
+				path: `${journeyPath}.run`,
+				message: "coversOperations cannot provide health coverage without executable run logic.",
+				fix: `Add an async run(ctx) implementation to ${journeyPath}.`,
+			});
+		}
+	}
+
+	// NOTE: healthCheck.cases[].enabled is intentionally NOT validated here.
+	// self-test.ts reports a gated case as status "skipped" with skipReason
+	// "disabled", so the skip is visible in results rather than silent — it is a
+	// supported conditional-execution feature, not a class-1 silent no-op.
+}
+
+function healthJourneyPath(journey: HealthJourneyDefinition, index: number): string {
+	return typeof journey.id === "string" && journey.id.length > 0
+		? `healthJourneys.${journey.id}`
+		: `healthJourneys[${index}]`;
+}
+
+function validateSchemaDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {
+		const schemaEntries: Array<[string, unknown]> = [
+			[`operations.${operationId}.input`, operation.input],
+			[`operations.${operationId}.output`, operation.output],
+		];
+		// SSE event schemas reach contract extraction the same way input/output do,
+		// so a transform-bearing event schema would abort extraction at runtime while
+		// passing declaration checks. Validate them under the same rule.
+		const transport = operation.transport;
+		if (transport?.kind === "sse") {
+			for (const [eventName, eventSchema] of Object.entries(transport.events ?? {})) {
+				schemaEntries.push([
+					`operations.${operationId}.transport.events.${eventName}`,
+					eventSchema,
+				]);
+			}
+		}
+		for (const [path, schema] of schemaEntries) {
+			try {
+				describeSchema(schema as Parameters<typeof describeSchema>[0]);
+			} catch (error) {
+				const reason = error instanceof Error ? error.message : String(error);
+				violations.push({
+					ruleId: DECLARATION_RULE_IDS.schemaSerializable,
+					path,
+					message: `schema conversion to JSON Schema failed: ${reason}`,
+					fix: `Replace unsupported constructs in ${path} so z.toJSONSchema() succeeds.`,
+				});
+			}
+		}
+	}
+}
+
+const MANAGED_PROXY_VENDORS = new Set<ProviderProxyProvider>(["smartproxy", "nodemaven"]);
+const STATIC_PROXY_VENDORS = new Set<ProviderProxyProvider>(["custom", "decodo"]);
+
+function validateProxyDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	if (provider.proxy === true) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.proxyExplicitPolicy,
+			path: "proxy",
+			message: "proxy: true does not require resolvable proxy egress.",
+			fix: 'Replace proxy: true with an explicit policy such as proxy: { mode: "required", providers: ["smartproxy"] }.',
+		});
+		return;
+	}
+	if (!provider.proxy || typeof provider.proxy !== "object") return;
+
+	const policy = provider.proxy as ProviderProxyPolicy;
+	const hasProvider = policy.provider !== undefined;
+	const hasProviders = policy.providers !== undefined;
+	if (hasProvider && hasProviders) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.proxyVendorExclusive,
+			path: "proxy",
+			message: "provider and providers are ambiguous when declared together.",
+			fix: "Keep either proxy.provider or proxy.providers, and remove the other field.",
+		});
+	}
+
+	const vendors = declaredProxyVendors(policy);
+	if (
+		vendors.some((vendor) => MANAGED_PROXY_VENDORS.has(vendor)) &&
+		vendors.some((vendor) => STATIC_PROXY_VENDORS.has(vendor))
+	) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.proxyNoMixedVendors,
+			path: hasProviders ? "proxy.providers" : "proxy.provider",
+			message: "managed and deprecated static proxy vendors cannot share a chain.",
+			fix: "Use only smartproxy/nodemaven vendors, or only deprecated static markers, in one policy.",
+		});
+	}
+
+	if (vendors.includes("smartproxy")) {
+		for (const field of ["subdivision", "city"] as const) {
+			if (policy.geo?.[field] === undefined) continue;
+			const path = `proxy.geo.${field}`;
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.proxySmartproxyGeo,
+				path,
+				message: `smartproxy cannot honor ${field}-level geo targeting.`,
+				fix: `Remove ${path} or use a vendor chain that can honor it.`,
+			});
+		}
+	}
+}
+
+function declaredProxyVendors(policy: ProviderProxyPolicy): ProviderProxyProvider[] {
+	const vendors = [...(policy.providers ?? [])];
+	if (policy.provider !== undefined) vendors.push(policy.provider);
+	return vendors;
+}
+
+function validateOperationDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {
+		if (!operation.upstream?.proxy) continue;
+		const path = `operations.${operationId}.upstream.proxy`;
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.operationUpstreamProxy,
+			path,
+			message: "operation-level proxy policy is not wired into operation execution.",
+			fix: `Remove ${path} and declare the effective policy at provider.proxy.`,
+		});
+	}
+}

package/src/define.ts

@@ -1,5 +1,6 @@
 import ms from "ms";
 
+import { validateFailClosedDeclaration } from "./declaration-validation.js";
 import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
 import {
@@ -152,6 +153,8 @@ export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderCha
 	"hcaptcha",
 	"cloudflare_interstitial",
 	"aws_waf",
+	"akamai_sec_cpt",
+	"akamai_sensor",
 ] as const);
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
@@ -759,7 +762,12 @@ function validateProviderResolver(config: { id: string; resolver?: ProviderResol
 			fix: `Set resolver for provider "${config.id}" to { vendors: ["2captcha"], kinds: ["turnstile"] }.`,
 		});
 	}
-	rejectUnknownFields(resolver, new Set(["vendors", "kinds"]), "resolver", config.id);
+	rejectUnknownFields(
+		resolver,
+		new Set(["vendors", "kinds", "clientProfile"]),
+		"resolver",
+		config.id,
+	);
 	validateResolverLiteralArray(
 		resolver.vendors,
 		"resolver.vendors",
@@ -772,6 +780,17 @@ function validateProviderResolver(config: { id: string; resolver?: ProviderResol
 		VALID_PROVIDER_CHALLENGE_KINDS,
 		config.id,
 	);
+	if (
+		resolver.clientProfile !== undefined &&
+		(typeof resolver.clientProfile !== "string" || !resolver.clientProfile.trim())
+	) {
+		throw new ValidationError(
+			`Provider "${config.id}" has invalid resolver.clientProfile: must be a non-empty string.`,
+			{
+				fix: `Set resolver.clientProfile for provider "${config.id}" to a transport-owned profile name.`,
+			},
+		);
+	}
 }
 
 function validateResolverLiteralArray<TValue extends string>(
@@ -2511,7 +2530,7 @@ export function defineProvider<
 			`Provider "${config.id}" cannot define browser config unless runtime is "browser"`,
 			{ fix: 'Set runtime: "browser" or remove the browser config' },
 		);
-	return {
+	const provider: ProviderDefinition & { operations: OperationMapConfig<TOperations> } = {
 		id: config.id,
 		version: config.version,
 		runtime: config.runtime,
@@ -2540,4 +2559,6 @@ export function defineProvider<
 		healthProbe: config.healthProbe ?? config.healthMonitor,
 		healthJourneys: config.healthJourneys,
 	};
+	validateFailClosedDeclaration(provider);
+	return provider;
 }

package/src/index.ts

@@ -113,6 +113,7 @@ export {
 	invalidateResolverSolution,
 	type ResolverRuntimeOptions,
 } from "./runtime/resolver.js";
+export type { ResolverVendorTransport } from "./runtime/resolver-vendors/types.js";
 export {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,

package/src/lint.ts

@@ -27,9 +27,97 @@ type ProviderAuthLike = {
 	exchange?: unknown;
 };
 
+// Operations that perform an auth-lifecycle action belong on the single
+// `auth.flow` interface, never on a provider operation:
+//   - entry (login / signin / authenticate) => auth.flow.start/continue
+//   - exit  (logout / signout / disconnect) => auth.flow.abort
+//
+// Matching works on `-`/`_` separated segments rather than a raw substring or a
+// leading anchor, so `shop-logout`, `shop_logout` and `user-sign-out-everywhere`
+// are all recognised: a domain prefix does not make the operation any less of an
+// auth-lifecycle action, and operation ids may use either separator.
+//
+// Vocabulary is split into two tiers because auth words collide with ordinary
+// domain verbs. Measured against the live fleet plus synthetic domain ids:
+//   - `authorize-payment`, `revoke-invitation`, `unlink-record`,
+//     `disconnect-device` are domain actions that never touch the connection
+//     credential, so these verbs are NOT matched as segments;
+//   - the same verbs as a complete operation id (`authorize`, `revoke`) do
+//     refer to the credential itself, so they are matched only in that form.
+// `exchange`, `callback`, `connect`, `session`, `token`, `credential`,
+// `password` and `otp` stay out entirely for the same reason.
+const AUTH_LIFECYCLE_SEGMENT_WORDS = new Set([
+	"login",
+	"logout",
+	"signin",
+	"signout",
+	"signup",
+	"authenticate",
+	"reauth",
+	"auth",
+]);
+
+// Ambiguous as a prefix, unambiguous when they are the whole operation id.
+const AUTH_LIFECYCLE_WHOLE_ID_WORDS = new Set([
+	"authorize",
+	"revoke",
+	"unlink",
+	"disconnect",
+]);
+
+// A verb stem followed by a direction word across two segments: `sign-out`,
+// `user_sign_up_flow`, and the spelled-out `log-in` / `shop-log-out` forms
+// (their fused equivalents `login`/`logout` live in the segment set above).
+// `sign` pairs match anywhere; `log` pairs match only at the END of the id,
+// because mid-id `log` is the noun in domain phrases measured against real
+// fleets (`audit-log-in-range`, `change-log-out-of-band` are reads of a log,
+// while `shop-log-out` is a logout).
+const AUTH_DIRECTION_PAIRS: ReadonlyMap<
+	string,
+	{ directions: ReadonlySet<string>; endOnly: boolean }
+> = new Map([
+	["sign", { directions: new Set(["in", "out", "up"]), endOnly: false }],
+	["log", { directions: new Set(["in", "out"]), endOnly: true }],
+]);
+
+// Legacy anchored form kept for token-plumbing words whose bare use is only
+// auth-related when it leads the operation id (`exchange-code`, `refresh`).
 const AUTH_OPERATION_ID_PATTERN =
 	/^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
 
+function isAuthLifecycleOperationId(operationId: string, authMode: string): boolean {
+	const segments = operationId.toLowerCase().split(/[-_]+/).filter(Boolean);
+
+	if (segments.some((segment) => AUTH_LIFECYCLE_SEGMENT_WORDS.has(segment))) return true;
+
+	// A verb stem + direction spread across two segments (`sign-out`,
+	// `sign_up`, `shop-log-out`); see AUTH_DIRECTION_PAIRS for positioning.
+	if (
+		segments.some((segment, index) => {
+			const pair = AUTH_DIRECTION_PAIRS.get(segment);
+			if (pair === undefined || index + 1 >= segments.length) return false;
+			if (!pair.directions.has(segments[index + 1] as string)) return false;
+			return pair.endOnly ? index + 2 === segments.length : true;
+		})
+	) {
+		return true;
+	}
+
+	if (segments.length === 1 && AUTH_LIFECYCLE_WHOLE_ID_WORDS.has(segments[0] as string)) {
+		return true;
+	}
+
+	// The legacy anchored pattern keeps its original scope. It matches ordinary
+	// domain ids such as `exchange-rates` and `refresh-catalog`, so extending it
+	// to `oauth2_proxied` would spread that behavior to providers it never
+	// applied to; proxied providers are covered by the segment tiers above.
+	if (authMode === "credentials" || authMode === "oauth2") {
+		return AUTH_OPERATION_ID_PATTERN.test(operationId);
+	}
+
+	return false;
+}
+
 type ProviderContractMetaLike = {
 	publicSchemaFieldNames?: "normalized";
 };
@@ -1265,14 +1353,21 @@ export function lintProvider(
 
 	if (provider.operations) {
 		const authMode = provider.auth?.mode;
-		if (authMode === "credentials" || authMode === "oauth2") {
+		// Every authenticated mode owns an auth.flow; `oauth2_proxied` was
+		// previously exempt, which let auth-lifecycle operations ship on
+		// proxied providers unchecked.
+		if (
+			authMode === "credentials" ||
+			authMode === "oauth2" ||
+			authMode === "oauth2_proxied"
+		) {
 			for (const operationKey of Object.keys(provider.operations)) {
-				if (AUTH_OPERATION_ID_PATTERN.test(operationKey)) {
+				if (isAuthLifecycleOperationId(operationKey, authMode)) {
 					diagnostics.push({
 						rule: "auth-operation-unsupported",
 						level: "error",
 						field: `operations.${operationKey}`,
-						message: `Provider "${provider.id ?? "unknown"}" operation "${operationKey}" looks like a login/token/session exchange endpoint. Authenticated providers must expose login through the single auth.flow interface because Gateway persists only auth.flow complete turn data.credential as the connection credential. Move this logic into auth.flow.continue instead of a provider operation.`,
+						message: `Provider "${provider.id ?? "unknown"}" operation "${operationKey}" performs an auth-lifecycle action (login, logout, token exchange or similar). Authenticated providers must expose the whole credential lifecycle through the single auth.flow interface because Gateway persists only auth.flow complete turn data.credential as the connection credential, and an operation that mutates the session outside that interface leaves the stored connection stale. Move sign-in logic into auth.flow.start/continue and sign-out/disconnect logic into auth.flow.abort (served by POST /auth/disconnect) instead of a provider operation.`,
 					});
 				}
 			}

package/src/runtime/resolver-vendors/bindings.ts

@@ -1,30 +1,55 @@
 import type { ProviderChallenge, ProviderChallengeKind } from "../../types.js";
 import type { ResolverIssuingIdentity } from "./types.js";
 
+type ResolverChallengeBinding = {
+	readonly cacheable: boolean;
+	readonly identityBinding: "none" | "identity_scoped" | "portable";
+	readonly directCacheable: boolean;
+};
+
+// An IP-bound artifact minted without any recorded egress identity is unsafe to
+// share. The Akamai kinds therefore reject direct caching, while Cloudflare
+// keeps its pre-existing direct-cache behavior pending measurement.
 export const RESOLVER_CHALLENGE_BINDINGS = {
-	aws_waf: "portable",
-	cloudflare_interstitial: "identity_scoped",
-} as const satisfies Partial<
-	Readonly<Record<ProviderChallengeKind, "identity_scoped" | "portable">>
->;
+	turnstile: { cacheable: false, identityBinding: "none", directCacheable: false },
+	recaptcha_v2: { cacheable: false, identityBinding: "none", directCacheable: false },
+	recaptcha_v3: { cacheable: false, identityBinding: "none", directCacheable: false },
+	hcaptcha: { cacheable: false, identityBinding: "none", directCacheable: false },
+	cloudflare_interstitial: {
+		cacheable: true,
+		identityBinding: "identity_scoped",
+		directCacheable: true,
+	},
+	aws_waf: { cacheable: true, identityBinding: "portable", directCacheable: true },
+	akamai_sec_cpt: {
+		cacheable: true,
+		identityBinding: "identity_scoped",
+		directCacheable: false,
+	},
+	akamai_sensor: {
+		cacheable: true,
+		identityBinding: "identity_scoped",
+		directCacheable: false,
+	},
+} as const satisfies Readonly<Record<ProviderChallengeKind, ResolverChallengeBinding>>;
+
+export function resolverChallengeIsCacheable(challenge: ProviderChallenge): boolean {
+	return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].cacheable;
+}
+
+export function resolverChallengeAllowsDirectCache(challenge: ProviderChallenge): boolean {
+	return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].directCacheable;
+}
 
 export function resolverChallengeIsIdentityScoped(challenge: ProviderChallenge): boolean {
-	return (
-		RESOLVER_CHALLENGE_BINDINGS[challenge.kind as keyof typeof RESOLVER_CHALLENGE_BINDINGS] ===
-		"identity_scoped"
-	);
+	return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "identity_scoped";
 }
 
 export function resolverChallengeIssuingIdentity(
 	challenge: ProviderChallenge,
 	identity: ResolverIssuingIdentity,
 ): ResolverIssuingIdentity {
-	const binding = (
-		RESOLVER_CHALLENGE_BINDINGS as Partial<
-			Readonly<Record<ProviderChallengeKind, "identity_scoped" | "portable">>
-		>
-	)[challenge.kind];
-	if (binding === "portable") {
+	if (RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "portable") {
 		return { userAgent: identity.userAgent };
 	}
 	return identity;

package/src/runtime/resolver-vendors/browser.ts

@@ -1,4 +1,4 @@
-import { isProviderError, ProviderError } from "../../errors.js";
+import { isProviderError } from "../../errors.js";
 import type {
 	BrowserClient,
 	BrowserCookie,
@@ -9,6 +9,7 @@ import type {
 import { type BrowserClientOptions, createBrowserClient } from "../browser.js";
 import type { TraceRecorder } from "../trace.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
+import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
 import {
 	type ResolverIdentity,
 	type ResolverVendorAdapter,
@@ -35,11 +36,6 @@ export interface BrowserResolverVendorOptions {
 	readonly createClient?: BrowserClientFactory;
 }
 
-export type BrowserResolverSolution = Extract<ChallengeSolution, { readonly form: "cookies" }> & {
-	/** Unix seconds from the cookie that proved the challenge cleared. */
-	readonly expires?: number;
-};
-
 export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
 	readonly id: "browser";
 	solve(
@@ -47,7 +43,7 @@ export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
 		identity: ResolverIdentity | undefined,
 		signal: AbortSignal,
 		traceRecorder?: TraceRecorder,
-	): Promise<BrowserResolverSolution>;
+	): Promise<Extract<ChallengeSolution, { readonly form: "cookies" }>>;
 }
 
 class BrowserSolveTimeoutError extends Error {
@@ -155,38 +151,20 @@ function isSupportedKind(kind: string): kind is SupportedBrowserChallengeKind {
 	return Object.hasOwn(SUCCESS_COOKIE_NAMES, kind);
 }
 
-function normalizedHostname(hostname: string): string {
-	return hostname.trim().toLowerCase().replace(/\.$/, "");
-}
-
-function assertChallengeHostAllowed(pageUrl: string, allowedHosts: readonly string[]): void {
-	const challengeHost = normalizedHostname(new URL(pageUrl).hostname);
-	const isAllowed = allowedHosts.some((host) => {
-		const declaredHost = normalizedHostname(host);
-		return declaredHost.length > 0 && !declaredHost.includes("*") && declaredHost === challengeHost;
-	});
-	if (isAllowed) return;
-
-	throw new ProviderError(`Resolver challenge host "${challengeHost}" is not declared`, {
-		code: "RESOLVER_HOST_NOT_ALLOWED",
-		fix: "Add the exact challenge hostname to the provider's allowedHosts declaration.",
-	});
-}
-
 function cookieDomainSpecificity(cookie: BrowserCookie): number {
-	return normalizedHostname(cookie.domain.replace(/^\./, "")).length;
+	return normalizedResolverHostname(cookie.domain.replace(/^\./, "")).length;
 }
 
 function isHostOnlyCookieFor(cookie: BrowserCookie, hostname: string): boolean {
 	return (
 		!cookie.domain.startsWith(".") &&
-		normalizedHostname(cookie.domain) === normalizedHostname(hostname)
+		normalizedResolverHostname(cookie.domain) === normalizedResolverHostname(hostname)
 	);
 }
 
 function cookieAppliesToUrl(cookie: BrowserCookie, url: URL): boolean {
-	const cookieDomain = normalizedHostname(cookie.domain.replace(/^\./, ""));
-	const requestHostname = normalizedHostname(url.hostname);
+	const cookieDomain = normalizedResolverHostname(cookie.domain.replace(/^\./, ""));
+	const requestHostname = normalizedResolverHostname(url.hostname);
 	const domainMatches =
 		cookieDomain.length > 0 &&
 		(requestHostname === cookieDomain ||
@@ -226,7 +204,7 @@ async function solveInPage(
 	successCookieName: string,
 	pollIntervalMs: number,
 	signal: AbortSignal,
-): Promise<BrowserResolverSolution> {
+): Promise<Extract<ChallengeSolution, { readonly form: "cookies" }>> {
 	await raceWithAbort(() => page.goto(pageUrl), signal);
 
 	while (true) {
@@ -345,7 +323,7 @@ export function createBrowserResolverVendorAdapter(
 			if (!isSupportedKind(challenge.kind)) {
 				throw new TypeError(`Browser resolver does not support ${challenge.kind}`);
 			}
-			assertChallengeHostAllowed(challenge.pageUrl, options.allowedHosts);
+			assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
 			const challengeKind = challenge.kind;
 			callerSignal.throwIfAborted();