@prosopo/provider 5.6.2 → 5.6.4

package/dist/cjs/api/captcha/contextAwareValidation.cjs

@@ -1,27 +1,47 @@
 let _prosopo_types = require("@prosopo/types");
 //#region src/api/captcha/contextAwareValidation.ts
 /**
-* Determines the context type based on the webView flag
+* Determines the context a request belongs to — its device family crossed
+* with whether it is running in a webview.
+*
+* `userAgent` is the raw header value, not the hashed one carried on the
+* decrypted payload. The entropy sweep classifies stored sessions from the
+* same header through the same function, so the two sides agree on which
+* bucket a session lands in.
+*
+* @param userAgent - Raw `user-agent` request header
 * @param webView - Whether the request is from a WebView
-* @returns The context type (Webview or Default)
 */
-function determineContextType(webView) {
-	return webView ? _prosopo_types.ContextType.Webview : _prosopo_types.ContextType.Default;
+function determineContextType(userAgent, webView) {
+	return (0, _prosopo_types.contextTypeFromSession)(userAgent, webView);
 }
 /**
-* Gets the threshold for a specific context type from client settings
+* Whether the client has this context configured.
+*
+* A context the customer has not enabled is not validated at all — the
+* request passes through this stage untouched. That is a change from the
+* pre-device-type behaviour, where configuring a single context validated
+* *every* request against it: with six contexts, applying a tablet baseline
+* to desktop traffic would reject real users wholesale.
+*/
+function isContextConfigured(settings, contextType) {
+	return (0, _prosopo_types.expandContexts)(settings.contextAware?.contexts)[contextType] !== void 0;
+}
+/**
+* Gets the threshold for a specific context type from client settings.
+*
+* Falls back to the global default when the context is unconfigured, so a
+* caller that skipped `isContextConfigured` still gets a sane number rather
+* than NaN.
+*
 * @param settings - Client settings
 * @param contextType - The context type to get the threshold for
 * @returns The threshold for the context type, or the global threshold if not configured
 */
 function getContextThreshold(settings, contextType) {
-	const contextAware = settings.contextAware;
-	if (contextAware === void 0) return _prosopo_types.contextAwareThresholdDefault;
-	const contexts = contextAware.contexts;
-	let contextConfig;
-	if (contexts !== void 0) contextConfig = contexts[contextType];
-	return contextConfig?.threshold ?? _prosopo_types.contextAwareThresholdDefault;
+	return (0, _prosopo_types.expandContexts)(settings.contextAware?.contexts)[contextType]?.threshold ?? _prosopo_types.contextAwareThresholdDefault;
 }
 //#endregion
 exports.determineContextType = determineContextType;
 exports.getContextThreshold = getContextThreshold;
+exports.isContextConfigured = isContextConfigured;

package/dist/cjs/api/captcha/getFrictionlessCaptchaChallenge/accessPolicy.cjs

@@ -31,7 +31,7 @@ var handleAccessPolicy = async (input, res) => {
 			}
 		}));
 		await tasks.frictionlessManager.registerBlockedSession({
-			solvedImagesCount: clientRecord.settings.imageMaxRounds,
+			solvedImagesCount: (0, _prosopo_types.resolveImageRoundsBounds)(clientRecord.settings).max,
 			userSitekeyIpHash: input.userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.ACCESS_POLICY_BLOCK,
 			siteKey: input.dapp,
@@ -55,7 +55,7 @@ var handleAccessPolicy = async (input, res) => {
 			}
 		}));
 		await tasks.frictionlessManager.registerBlockedSession({
-			solvedImagesCount: clientRecord.settings.imageMaxRounds,
+			solvedImagesCount: (0, _prosopo_types.resolveImageRoundsBounds)(clientRecord.settings).max,
 			userSitekeyIpHash: input.userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.AUTO_BAN_SCORE,
 			siteKey: input.dapp,
@@ -87,7 +87,7 @@ var handleAccessPolicy = async (input, res) => {
 			handled: true,
 			response: res.json(await tasks.frictionlessManager.sendImageCaptcha({
 				...captchaTypeBaseParams,
-				solvedImagesCount: userAccessPolicy.solvedImagesCount ? Math.min(userAccessPolicy.solvedImagesCount, clientRecord.settings.imageMaxRounds) : clientRecord.settings.imageMaxRounds
+				solvedImagesCount: userAccessPolicy.solvedImagesCount ? (0, _prosopo_types.clampImageRounds)(userAccessPolicy.solvedImagesCount, clientRecord.settings) : (0, _prosopo_types.resolveImageRoundsBounds)(clientRecord.settings).max
 			}))
 		};
 	}
@@ -116,7 +116,10 @@ var handleAccessPolicy = async (input, res) => {
 		require_honeypotResponse.attachHoneypot(res, clientRecord);
 		return {
 			handled: true,
-			response: res.json(await tasks.frictionlessManager.sendPuzzleCaptcha(captchaTypeBaseParams))
+			response: res.json(await tasks.frictionlessManager.sendPuzzleCaptcha({
+				...captchaTypeBaseParams,
+				...userAccessPolicy.solvedImagesCount !== void 0 && { solvedImagesCount: userAccessPolicy.solvedImagesCount }
+			}))
 		};
 	}
 	return {

package/dist/cjs/api/captcha/getFrictionlessCaptchaChallenge/decisionMachine.cjs

@@ -24,7 +24,7 @@ var runDecisionMachine = async (input, handle) => {
 		require_metrics.recordFrictionlessDecision("missing_token");
 		require_honeypotResponse.attachHoneypot(res, clientRecord);
 		return res.json(await tasks.frictionlessManager.sendImageCaptcha({
-			solvedImagesCount: Math.min(3, clientRecord.settings.imageMaxRounds),
+			solvedImagesCount: (0, _prosopo_types.clampImageRounds)(3, clientRecord.settings),
 			userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.MISSING_TOKEN,
 			siteKey: dapp,
@@ -43,7 +43,7 @@ var runDecisionMachine = async (input, handle) => {
 		require_metrics.recordFrictionlessDecision("missing_head_hash");
 		require_honeypotResponse.attachHoneypot(res, clientRecord);
 		return res.json(await tasks.frictionlessManager.sendImageCaptcha({
-			solvedImagesCount: Math.min(2, clientRecord.settings.imageMaxRounds),
+			solvedImagesCount: (0, _prosopo_types.clampImageRounds)(2, clientRecord.settings),
 			userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.MISSING_HEAD_HASH,
 			siteKey: dapp,
@@ -62,7 +62,7 @@ var runDecisionMachine = async (input, handle) => {
 		require_metrics.recordFrictionlessDecision("decryption_failed");
 		require_honeypotResponse.attachHoneypot(res, clientRecord);
 		return res.json(await tasks.frictionlessManager.sendImageCaptcha({
-			solvedImagesCount: Math.min(3, clientRecord.settings.imageMaxRounds),
+			solvedImagesCount: (0, _prosopo_types.clampImageRounds)(3, clientRecord.settings),
 			userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.DECRYPTION_FAILED,
 			siteKey: dapp,
@@ -102,7 +102,7 @@ var runDecisionMachine = async (input, handle) => {
 		}));
 		require_metrics.recordFrictionlessDecision("auto_ban_score");
 		await tasks.frictionlessManager.registerBlockedSession({
-			solvedImagesCount: clientRecord.settings.imageMaxRounds,
+			solvedImagesCount: (0, _prosopo_types.resolveImageRoundsBounds)(clientRecord.settings).max,
 			userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.AUTO_BAN_SCORE,
 			siteKey: dapp,
@@ -122,7 +122,7 @@ var runDecisionMachine = async (input, handle) => {
 		require_metrics.recordFrictionlessDecision("webview_detected");
 		require_honeypotResponse.attachHoneypot(res, clientRecord);
 		return res.json(await tasks.frictionlessManager.sendImageCaptcha({
-			solvedImagesCount: Math.min(env.config.captchas.solved.count * 2, clientRecord.settings.imageMaxRounds),
+			solvedImagesCount: (0, _prosopo_types.clampImageRounds)(env.config.captchas.solved.count * 2, clientRecord.settings),
 			userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.WEBVIEW_DETECTED,
 			siteKey: dapp,
@@ -141,7 +141,7 @@ var runDecisionMachine = async (input, handle) => {
 		require_metrics.recordFrictionlessDecision("timestamp_too_old");
 		require_honeypotResponse.attachHoneypot(res, clientRecord);
 		return res.json(await tasks.frictionlessManager.sendImageCaptcha({
-			solvedImagesCount: require_frictionlessTasksUtils.timestampDecayFunction(input.timestamp, clientRecord.settings.imageMaxRounds),
+			solvedImagesCount: (0, _prosopo_types.clampImageRounds)(require_frictionlessTasksUtils.timestampDecayFunction(input.timestamp, clientRecord.settings.imageMaxRounds), clientRecord.settings),
 			userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.OLD_TIMESTAMP,
 			siteKey: dapp,
@@ -149,7 +149,7 @@ var runDecisionMachine = async (input, handle) => {
 			headers: flatHeaders
 		}));
 	}
-	const scoredImageRounds = Math.min(require_constants.getRoundsFromTriggeredDetectors(env.config.captchas.solved.count, input.triggeredDetectors), clientRecord.settings.imageMaxRounds);
+	const scoredImageRounds = (0, _prosopo_types.clampImageRounds)(require_constants.getRoundsFromTriggeredDetectors(env.config.captchas.solved.count, input.triggeredDetectors), clientRecord.settings);
 	const botImageThreshold = input.botImageThreshold;
 	if (botImageThreshold > input.botThreshold && Number(botScore) > input.botThreshold && Number(botScore) < botImageThreshold) {
 		req.logger.info(() => ({
@@ -215,7 +215,7 @@ var runDecisionMachine = async (input, handle) => {
 		require_metrics.recordFrictionlessDecision("missing_current_url");
 		require_honeypotResponse.attachHoneypot(res, clientRecord);
 		return res.json(await tasks.frictionlessManager.sendImageCaptcha({
-			solvedImagesCount: Math.min(env.config.captchas.solved.count, clientRecord.settings.imageMaxRounds),
+			solvedImagesCount: (0, _prosopo_types.clampImageRounds)(env.config.captchas.solved.count, clientRecord.settings),
 			userSitekeyIpHash,
 			reason: _prosopo_types.FrictionlessReason.MISSING_CURRENT_URL,
 			siteKey: dapp,
@@ -265,7 +265,7 @@ var runUserAgentMismatchCheck = async (input, handle) => {
 	require_metrics.recordFrictionlessDecision("user_agent_mismatch");
 	require_honeypotResponse.attachHoneypot(res, input.clientRecord);
 	return res.json(await input.tasks.frictionlessManager.sendImageCaptcha({
-		solvedImagesCount: require_frictionlessTasksUtils.timestampDecayFunction(input.timestamp, input.clientRecord.settings.imageMaxRounds),
+		solvedImagesCount: (0, _prosopo_types.clampImageRounds)(require_frictionlessTasksUtils.timestampDecayFunction(input.timestamp, input.clientRecord.settings.imageMaxRounds), input.clientRecord.settings),
 		userSitekeyIpHash: input.userSitekeyIpHash,
 		reason: _prosopo_types.FrictionlessReason.USER_AGENT_MISMATCH,
 		siteKey: input.dapp,
@@ -277,14 +277,8 @@ var runContextAwareValidation = async (input, handle) => {
 	const { tasks, clientRecord, dapp, user } = input;
 	const { req, res, next } = handle;
 	if (!clientRecord.settings.contextAware?.enabled) return null;
-	const contexts = clientRecord.settings.contextAware?.contexts || {};
-	const hasDefault = contexts[_prosopo_types.ContextType.Default] !== void 0;
-	const hasWebview = contexts[_prosopo_types.ContextType.Webview] !== void 0;
-	let contextType;
-	if (hasDefault && hasWebview) contextType = require_contextAwareValidation.determineContextType(input.webView);
-	else if (hasDefault) contextType = _prosopo_types.ContextType.Default;
-	else if (hasWebview) contextType = _prosopo_types.ContextType.Webview;
-	if (!contextType) return null;
+	const contextType = require_contextAwareValidation.determineContextType(req.headers["user-agent"], input.webView);
+	if (!require_contextAwareValidation.isContextConfigured(clientRecord.settings, contextType)) return null;
 	const clientEntropy = await tasks.frictionlessManager.getClientContextEntropy(clientRecord.account, contextType);
 	if (!clientEntropy) return null;
 	if (!input.decryptedHeadHash) {
@@ -314,7 +308,7 @@ var runContextAwareValidation = async (input, handle) => {
 	require_metrics.recordFrictionlessDecision("context_aware_failed");
 	require_honeypotResponse.attachHoneypot(res, clientRecord);
 	return res.json(await tasks.frictionlessManager.sendImageCaptcha({
-		solvedImagesCount: Math.min(require_constants.getRoundsFromSimScore(sim), clientRecord.settings.imageMaxRounds),
+		solvedImagesCount: (0, _prosopo_types.clampImageRounds)(require_constants.getRoundsFromSimScore(sim), clientRecord.settings),
 		userSitekeyIpHash: input.userSitekeyIpHash,
 		reason: _prosopo_types.FrictionlessReason.CONTEXT_AWARE_VALIDATION_FAILED,
 		siteKey: dapp,

package/dist/cjs/api/captcha/getFrictionlessCaptchaChallenge/handler.cjs

@@ -316,6 +316,9 @@ var handler_default = (env, userAccessRulesStorage) => async (req, res, next) =>
 			countryCode,
 			score: botScore,
 			imageMaxRounds: clientRecord.settings.imageMaxRounds,
+			imageMinRounds: clientRecord.settings.imageMinRounds,
+			frictionlessTypes: clientRecord.settings.frictionlessTypes,
+			baseImageRounds: env.config.captchas.solved.count,
 			platform: require_devicePlatform.derivePlatform(safeUserAgent, webView, { ...typeof ipInfoMobile === "boolean" && { isMobile: ipInfoMobile } }),
 			raw: {
 				headers: flatHeaders,

package/dist/cjs/api/captcha/getFrictionlessCaptchaChallenge/shortCircuit.cjs

@@ -64,7 +64,7 @@ var runConfiguredCaptchaTypeShortCircuit = async (input, res) => {
 	switch (configuredType) {
 		case _prosopo_types.CaptchaType.image: return res.json(await input.tasks.frictionlessManager.sendImageCaptcha({
 			...sessionParams,
-			solvedImagesCount: Math.min(input.env.config.captchas.solved.count, input.clientRecord.settings.imageMaxRounds)
+			solvedImagesCount: (0, _prosopo_types.clampImageRounds)(input.env.config.captchas.solved.count, input.clientRecord.settings)
 		}));
 		case _prosopo_types.CaptchaType.pow: return res.json(await input.tasks.frictionlessManager.sendPowCaptcha(sessionParams));
 		case _prosopo_types.CaptchaType.puzzle: return res.json(await input.tasks.frictionlessManager.sendPuzzleCaptcha(sessionParams));

package/dist/cjs/api/captcha/getImageCaptchaChallenge.cjs

@@ -101,7 +101,7 @@ var getImageCaptchaChallenge_default = (env, userAccessRulesStorage) => async (r
 		const trafficVerdict = require_trafficFilterRequestTime.applyTrafficFilterAtRequestTime(req.ipInfo, clientRecord.settings?.trafficFilter, req.logger);
 		const trafficSolvedImagesCount = trafficVerdict.kind === "challenge" ? trafficVerdict.solvedImagesCount : void 0;
 		const captchaConfig = {
-			solved: { count: Math.min(trafficSolvedImagesCount || solvedImagesCount || userAccessPolicy?.solvedImagesCount || deferredParamsPolicy?.solvedImagesCount || env.config.captchas.solved.count, clientRecord.settings.imageMaxRounds ?? _prosopo_types.imageMaxRoundsDefault) },
+			solved: { count: (0, _prosopo_types.clampImageRounds)(trafficSolvedImagesCount || solvedImagesCount || userAccessPolicy?.solvedImagesCount || deferredParamsPolicy?.solvedImagesCount || env.config.captchas.solved.count, clientRecord.settings) },
 			unsolved: { count: userAccessPolicy?.unsolvedImagesCount || deferredParamsPolicy?.unsolvedImagesCount || env.config.captchas.unsolved.count }
 		};
 		if (validSessionId && simdReadings) await tasks.frictionlessManager.decryptAndAttachSimdReadingsIfAbsent(validSessionId, simdReadings, _prosopo_types.SimdReadingsStage.challenge).catch((updateErr) => {

package/dist/cjs/api/captcha/submitPoWCaptchaSolution.cjs

@@ -1,5 +1,6 @@
 const require_validateAddress = require("../validateAddress.cjs");
-const require_puzzleRenderer = require("../../tasks/puzzle/puzzleRenderer.cjs");
+const require_puzzleDifficulty = require("../../tasks/puzzle/puzzleDifficulty.cjs");
+const require_captchaTypeSelection = require("../../tasks/captchaTypeSelection.cjs");
 const require_devicePlatform = require("../../utils/devicePlatform.cjs");
 const require_tasks = require("../../tasks/tasks.cjs");
 const require_apiToggleMaintenanceModeEndpoint = require("../admin/apiToggleMaintenanceModeEndpoint.cjs");
@@ -8,6 +9,7 @@ const require_rawTlsSignalsMiddleware = require("../rawTlsSignalsMiddleware.cjs"
 let _prosopo_common = require("@prosopo/common");
 let _prosopo_types = require("@prosopo/types");
 let _prosopo_util = require("@prosopo/util");
+let _prosopo_puzzle_assets = require("@prosopo/puzzle-assets");
 //#region src/api/captcha/submitPoWCaptchaSolution.ts
 var submitPoWCaptchaSolution_default = (env) => async (req, res, next) => {
 	if (require_apiToggleMaintenanceModeEndpoint.getMaintenanceMode()) {
@@ -95,6 +97,9 @@ var submitPoWCaptchaSolution_default = (env) => async (req, res, next) => {
 			tcpToChelloUs: req.tcpToChelloUs,
 			chelloToHandshakeUs: req.chelloToHandshakeUs,
 			...require_rawTlsSignalsMiddleware.rawTlsSignalsForSession(req)
+		}, {
+			frictionlessTypes: clientRecord.settings?.frictionlessTypes,
+			imageMaxRounds: clientRecord.settings?.imageMaxRounds
 		});
 		const response = {
 			status: "ok",
@@ -128,7 +133,7 @@ var submitPoWCaptchaSolution_default = (env) => async (req, res, next) => {
 * Exported for unit testing only — the handler above is the production entry
 * point.
 */
-var buildEscalation = async (tasks, result, challenge, perConnectionSignals) => {
+var buildEscalation = async (tasks, result, challenge, perConnectionSignals, siteConstraints) => {
 	if (!result.verified || !result.routingOutput) return void 0;
 	const routedType = result.routingOutput.captchaType;
 	if (routedType !== _prosopo_types.CaptchaType.image && routedType !== _prosopo_types.CaptchaType.puzzle) return;
@@ -137,9 +142,21 @@ var buildEscalation = async (tasks, result, challenge, perConnectionSignals) =>
 	const originSession = await tasks.db.getSessionRecordBySessionId(powRecord.sessionId);
 	if (!originSession) return void 0;
 	const routed = result.routingOutput;
-	const escalatedType = require_puzzleRenderer.downgradePuzzleIfUnavailable(routed.captchaType);
+	const escalatedType = require_captchaTypeSelection.coerceToEnabledCaptchaType(routed.captchaType, siteConstraints?.frictionlessTypes);
+	if (escalatedType === _prosopo_types.CaptchaType.pow) return void 0;
+	const imageMaxRounds = siteConstraints?.imageMaxRounds ?? _prosopo_types.imageMaxRoundsDefault;
+	const escalationPuzzleOverrides = (() => {
+		if (escalatedType !== _prosopo_types.CaptchaType.puzzle) return void 0;
+		const level = require_puzzleDifficulty.severityToPuzzleDifficulty(routed.solvedImagesCount ?? originSession.solvedImagesCount, tasks.config.captchas.solved.count);
+		if (level === 0) return void 0;
+		const difficulty = require_puzzleDifficulty.samplePuzzleDifficulty(level, _prosopo_puzzle_assets.DEFAULT_RENDER_SETTINGS.holeDarken);
+		return {
+			puzzleTolerance: difficulty.tolerance,
+			puzzle: difficulty.puzzle
+		};
+	})();
 	const selectionReason = routed.reason ?? originSession.reason;
-	const newSession = await tasks.frictionlessManager.createSession(originSession.token, originSession.score, originSession.threshold, originSession.scoreComponents, originSession.ipAddress, escalatedType, originSession.siteKey ?? powRecord.dappAccount, escalatedType === _prosopo_types.CaptchaType.image ? routed.solvedImagesCount ?? originSession.solvedImagesCount : void 0, void 0, originSession.userSitekeyIpHash, originSession.webView, originSession.iFrame, originSession.decryptedHeadHash, selectionReason, void 0, void 0, originSession.ipInfo, originSession.headers, originSession.mode, originSession.simdReadings, originSession.entropyMathRandomFingerprint, originSession.entropyCryptoFingerprint, originSession.entropyWallClockOffsetMs, originSession.entropyMathRandomFirst, originSession.bundleId, originSession.currentUrl, perConnectionSignals?.tcpToChelloUs, perConnectionSignals?.chelloToHandshakeUs, true, originSession.iframeUrl, originSession.isProtect, originSession.sessionId, originSession.g, void 0, originSession.i, originSession.sw, originSession.md, originSession.bn, originSession.fs, perConnectionSignals && {
+	const newSession = await tasks.frictionlessManager.createSession(originSession.token, originSession.score, originSession.threshold, originSession.scoreComponents, originSession.ipAddress, escalatedType, originSession.siteKey ?? powRecord.dappAccount, escalatedType === _prosopo_types.CaptchaType.image ? Math.min(routed.solvedImagesCount ?? originSession.solvedImagesCount ?? tasks.config.captchas.solved.count, imageMaxRounds) : void 0, void 0, originSession.userSitekeyIpHash, originSession.webView, originSession.iFrame, originSession.decryptedHeadHash, selectionReason, void 0, void 0, originSession.ipInfo, originSession.headers, originSession.mode, originSession.simdReadings, originSession.entropyMathRandomFingerprint, originSession.entropyCryptoFingerprint, originSession.entropyWallClockOffsetMs, originSession.entropyMathRandomFirst, originSession.bundleId, originSession.currentUrl, perConnectionSignals?.tcpToChelloUs, perConnectionSignals?.chelloToHandshakeUs, true, originSession.iframeUrl, originSession.isProtect, originSession.sessionId, originSession.g, void 0, originSession.i, originSession.sw, originSession.md, originSession.bn, originSession.fs, perConnectionSignals && {
 		synNs: perConnectionSignals.synNs,
 		synackNs: perConnectionSignals.synackNs,
 		ackNs: perConnectionSignals.ackNs,
@@ -149,7 +166,7 @@ var buildEscalation = async (tasks, result, challenge, perConnectionSignals) =>
 		tcpOptsFlags: perConnectionSignals.tcpOptsFlags,
 		tcpOptsOrder: perConnectionSignals.tcpOptsOrder,
 		tcpWindow: perConnectionSignals.tcpWindow
-	});
+	}, escalationPuzzleOverrides);
 	if (tasks.writeQueue) await tasks.writeQueue.cacheSessionEscalation(powRecord.sessionId, newSession.sessionId);
 	return {
 		captchaType: escalatedType,

package/dist/cjs/api/captcha/trafficFilterRequestTime.cjs

@@ -72,7 +72,7 @@ var handleFrictionlessTrafficFilter = async (input, res) => {
 		logDispatch(_prosopo_types.CaptchaType.image);
 		response = await input.frictionlessManager.sendImageCaptcha({
 			...baseParams,
-			solvedImagesCount: verdict.solvedImagesCount ? Math.min(verdict.solvedImagesCount, input.clientRecord.settings.imageMaxRounds) : input.clientRecord.settings.imageMaxRounds
+			solvedImagesCount: verdict.solvedImagesCount ? (0, _prosopo_types.clampImageRounds)(verdict.solvedImagesCount, input.clientRecord.settings) : (0, _prosopo_types.resolveImageRoundsBounds)(input.clientRecord.settings).max
 		});
 	} else if (verdict.captchaType === _prosopo_types.CaptchaType.pow) {
 		logDispatch(_prosopo_types.CaptchaType.pow);

package/dist/cjs/tasks/captchaTypeSelection.cjs

@@ -0,0 +1,53 @@
+const require_puzzleRenderer = require("./puzzle/puzzleRenderer.cjs");
+let _prosopo_types = require("@prosopo/types");
+//#region src/tasks/captchaTypeSelection.ts
+/**
+* Resolve a requested captcha type against what the site permits and what
+* this provider can render.
+*
+* Call this at every point a session's captchaType is DECIDED, never at the
+* point one is served: `/captcha/puzzle` answers with a puzzle-shaped
+* response and nothing else, so a session minted as a type we cannot fulfil
+* strands the user on INCORRECT_CAPTCHA_TYPE. There are two such mint sites —
+* `sendCaptcha` in frictionlessTasks (which every frictionless path funnels
+* through, after the routing machine has had its say) and `buildEscalation`
+* in submitPoWCaptchaSolution.
+*
+* Because it sits after routing, this covers every upstream selector
+* transitively: the score ladder, the no-measurement gates, access-policy
+* Restrict rules, traffic-filter category policies, routing-machine actions
+* and detector-generated rules.
+*
+* Coercion only ever narrows. A disabled type falls back to the other
+* interactive type if that is permitted, and to PoW otherwise — never the
+* reverse, so this can't hand a user a harder challenge than was asked for.
+*/
+var coerceToEnabledCaptchaType = (requested, frictionlessTypes, logger) => {
+	const types = (0, _prosopo_types.resolveFrictionlessTypes)(frictionlessTypes);
+	const puzzleAllowed = types.puzzle && require_puzzleRenderer.isPuzzleRenderAvailable();
+	const imageAllowed = types.image;
+	const resolved = (() => {
+		switch (requested) {
+			case _prosopo_types.CaptchaType.pow: return _prosopo_types.CaptchaType.pow;
+			case _prosopo_types.CaptchaType.puzzle:
+				if (puzzleAllowed) return _prosopo_types.CaptchaType.puzzle;
+				return imageAllowed ? _prosopo_types.CaptchaType.image : _prosopo_types.CaptchaType.pow;
+			case _prosopo_types.CaptchaType.image:
+				if (imageAllowed) return _prosopo_types.CaptchaType.image;
+				return puzzleAllowed ? _prosopo_types.CaptchaType.puzzle : _prosopo_types.CaptchaType.pow;
+		}
+	})();
+	if (resolved !== requested) logger?.info(() => ({
+		msg: "Captcha type coerced to an enabled type",
+		data: {
+			requested,
+			served: resolved,
+			imageEnabled: types.image,
+			puzzleEnabled: types.puzzle,
+			puzzleRenderable: require_puzzleRenderer.isPuzzleRenderAvailable()
+		}
+	}));
+	return resolved;
+};
+//#endregion
+exports.coerceToEnabledCaptchaType = coerceToEnabledCaptchaType;

package/dist/cjs/tasks/frictionless/frictionlessTasks.cjs

@@ -3,10 +3,12 @@ const require_decisionMachineRunner = require("../decisionMachine/decisionMachin
 const require_dnsEventUrl = require("../../api/dnsEventUrl.cjs");
 const require_lang = require("../../rules/lang.cjs");
 const require_captchaManager = require("../captchaManager.cjs");
+const require_puzzleDifficulty = require("../puzzle/puzzleDifficulty.cjs");
+const require_captchaTypeSelection = require("../captchaTypeSelection.cjs");
 const require_getBotScore = require("../detection/getBotScore.cjs");
-const require_puzzleRenderer = require("../puzzle/puzzleRenderer.cjs");
 const require_routingMachine = require("./routingMachine.cjs");
 let _prosopo_types = require("@prosopo/types");
+let _prosopo_puzzle_assets = require("@prosopo/puzzle-assets");
 let uuid = require("uuid");
 //#region src/tasks/frictionless/frictionlessTasks.ts
 var DEFAULT_MAX_TIMESTAMP_AGE = 600 * 1e3;
@@ -190,15 +192,24 @@ var FrictionlessManager = class extends require_captchaManager.CaptchaManager {
 			powDifficulty: captchaType === _prosopo_types.CaptchaType.pow ? effectiveParams.powDifficulty : void 0
 		};
 		const routed = this.routingContext ? await require_routingMachine.applyRouter(this.decisionMachineRunner, this.usageCounters, baseline, this.routingContext, this.logger) : baseline;
-		const finalCaptchaType = require_puzzleRenderer.downgradePuzzleIfUnavailable(routed.captchaType, this.logger);
+		const finalCaptchaType = require_captchaTypeSelection.coerceToEnabledCaptchaType(routed.captchaType, this.routingContext?.frictionlessTypes, this.logger);
 		const requestedSolvedImagesCount = routed.solvedImagesCount ?? effectiveParams.solvedImagesCount;
-		const imageRoundsCeiling = this.routingContext?.imageMaxRounds;
-		const finalSolvedImagesCount = finalCaptchaType === _prosopo_types.CaptchaType.image ? requestedSolvedImagesCount !== void 0 && imageRoundsCeiling !== void 0 ? Math.min(requestedSolvedImagesCount, imageRoundsCeiling) : requestedSolvedImagesCount : void 0;
+		const imageRoundsBounds = this.routingContext ?? {};
+		const finalSolvedImagesCount = finalCaptchaType === _prosopo_types.CaptchaType.image ? requestedSolvedImagesCount !== void 0 ? (0, _prosopo_types.clampImageRounds)(requestedSolvedImagesCount, imageRoundsBounds) : requestedSolvedImagesCount : void 0;
 		const finalPowDifficulty = finalCaptchaType === _prosopo_types.CaptchaType.pow ? routed.powDifficulty ?? effectiveParams.powDifficulty : void 0;
-		const finalPuzzleOverrides = finalCaptchaType === _prosopo_types.CaptchaType.puzzle ? {
-			...routed.puzzleTolerance !== void 0 && { puzzleTolerance: routed.puzzleTolerance },
-			...routed.puzzle && { puzzle: routed.puzzle }
-		} : {};
+		const finalPuzzleOverrides = finalCaptchaType === _prosopo_types.CaptchaType.puzzle ? (() => {
+			const level = require_puzzleDifficulty.severityToPuzzleDifficulty(requestedSolvedImagesCount, this.routingContext?.baseImageRounds ?? this.config.captchas.solved.count);
+			const difficulty = level > 0 ? require_puzzleDifficulty.samplePuzzleDifficulty(level, _prosopo_puzzle_assets.DEFAULT_RENDER_SETTINGS.holeDarken) : void 0;
+			const tolerance = routed.puzzleTolerance ?? difficulty?.tolerance;
+			const puzzle = routed.puzzle || difficulty ? {
+				...difficulty?.puzzle ?? {},
+				...routed.puzzle ?? {}
+			} : void 0;
+			return {
+				...tolerance !== void 0 && { puzzleTolerance: tolerance },
+				...puzzle !== void 0 && { puzzle }
+			};
+		})() : {};
 		const finalReason = routed.reason ?? effectiveParams.reason;
 		const blocked = finalCaptchaType === _prosopo_types.CaptchaType.image ? effectiveParams.blocked : void 0;
 		const sessionRecord = await this.createSession(effectiveParams.token, effectiveParams.score, effectiveParams.threshold, effectiveParams.scoreComponents, effectiveParams.ipAddress, finalCaptchaType, effectiveParams.siteKey, finalSolvedImagesCount, finalPowDifficulty, effectiveParams.userSitekeyIpHash, effectiveParams.webView ?? false, effectiveParams.iFrame ?? false, effectiveParams.decryptedHeadHash, finalReason, blocked, void 0, effectiveParams.ipInfo, effectiveParams.headers, effectiveParams.mode, effectiveParams.simdReadings, effectiveParams.entropyMathRandomFingerprint, effectiveParams.entropyCryptoFingerprint, effectiveParams.entropyWallClockOffsetMs, effectiveParams.entropyMathRandomFirst, effectiveParams.bundleId, effectiveParams.currentUrl, effectiveParams.tcpToChelloUs, effectiveParams.chelloToHandshakeUs, void 0, effectiveParams.iframeUrl, effectiveParams.isProtect, void 0, effectiveParams.g, effectiveParams.matchedRule, effectiveParams.i, effectiveParams.sw, effectiveParams.md, effectiveParams.bn, effectiveParams.fs, {

package/dist/cjs/tasks/puzzle/puzzleDifficulty.cjs

@@ -0,0 +1,208 @@
+const require_stratifiedSampler = require("./stratifiedSampler.cjs");
+//#region src/tasks/puzzle/puzzleDifficulty.ts
+/**
+* Minimum gap that must remain between `decoyHoleDarken` and `holeDarken`.
+*
+* The real cutout has to stay the deepest region on the frame or a human
+* cannot tell target from decoy at all. But pushed too far apart, a solver
+* simply thresholds on brightness and ignores shape. The ladder walks
+* `decoyHoleDarken` down toward `holeDarken` as difficulty rises; this floor
+* is what stops it crossing over. Enforced by clamping every sampled value,
+* not by trusting the band table to be authored correctly.
+*/
+var MIN_DECOY_HOLE_DARKEN_MARGIN = .04;
+/**
+* L0 reproduces the shipped defaults (decoyCount 5, decoyEdgeDarkness 20,
+* decoyHoleDarken 0.7, tolerance 15, pieceScale 0.15-0.45) so a site that
+* never escalates sees no change in behaviour.
+*
+* The numbers above L0 are STARTING POINTS, not calibrated values. They need
+* validating against observed human first-attempt solve rate per level,
+* segmented by device class — see the shadow-calibration note on
+* `severityToPuzzleDifficulty`.
+*/
+var PUZZLE_DIFFICULTY_LEVELS = [
+	{
+		level: 0,
+		tolerance: {
+			min: 14,
+			max: 16
+		},
+		decoyCount: {
+			min: 4,
+			max: 6
+		},
+		decoyHoleDarken: {
+			min: .68,
+			max: .72
+		},
+		decoyEdgeDarkness: {
+			min: 18,
+			max: 22
+		},
+		pieceScale: {
+			min: .15,
+			max: .45
+		}
+	},
+	{
+		level: 1,
+		tolerance: {
+			min: 12,
+			max: 15
+		},
+		decoyCount: {
+			min: 6,
+			max: 10
+		},
+		decoyHoleDarken: {
+			min: .66,
+			max: .7
+		},
+		decoyEdgeDarkness: {
+			min: 20,
+			max: 24
+		},
+		pieceScale: {
+			min: .14,
+			max: .4
+		}
+	},
+	{
+		level: 2,
+		tolerance: {
+			min: 10,
+			max: 13
+		},
+		decoyCount: {
+			min: 10,
+			max: 16
+		},
+		decoyHoleDarken: {
+			min: .64,
+			max: .68
+		},
+		decoyEdgeDarkness: {
+			min: 22,
+			max: 27
+		},
+		pieceScale: {
+			min: .12,
+			max: .34
+		}
+	},
+	{
+		level: 3,
+		tolerance: {
+			min: 8,
+			max: 11
+		},
+		decoyCount: {
+			min: 16,
+			max: 26
+		},
+		decoyHoleDarken: {
+			min: .62,
+			max: .66
+		},
+		decoyEdgeDarkness: {
+			min: 25,
+			max: 30
+		},
+		pieceScale: {
+			min: .1,
+			max: .28
+		}
+	},
+	{
+		level: 4,
+		tolerance: {
+			min: 6,
+			max: 9
+		},
+		decoyCount: {
+			min: 26,
+			max: 40
+		},
+		decoyHoleDarken: {
+			min: .6,
+			max: .64
+		},
+		decoyEdgeDarkness: {
+			min: 28,
+			max: 34
+		},
+		pieceScale: {
+			min: .09,
+			max: .22
+		}
+	}
+];
+var toleranceSampler = require_stratifiedSampler.createStratifiedSampler();
+var decoyCountSampler = require_stratifiedSampler.createStratifiedSampler();
+var decoyHoleDarkenSampler = require_stratifiedSampler.createStratifiedSampler();
+var decoyEdgeDarknessSampler = require_stratifiedSampler.createStratifiedSampler();
+var clampDifficultyLevel = (level, maxLevel = 3) => {
+	const ceiling = Math.min(maxLevel, PUZZLE_DIFFICULTY_LEVELS.length - 1);
+	if (!Number.isFinite(level)) return 0;
+	return Math.max(0, Math.min(Math.floor(level), ceiling));
+};
+/**
+* Map the severity currency every existing call-site already speaks — image
+* rounds — onto a difficulty level.
+*
+* Severity is expressed as rounds ABOVE the site's ordinary count rather than
+* an absolute, because the baseline (`env.config.captchas.solved.count`, or a
+* rule's own `solvedImagesCount`) varies per site. "Two more rounds than
+* normal" means the same thing everywhere; "four rounds" does not.
+*
+* Keeping one ordering here means the score ladder, the no-measurement gates,
+* detector rules and traffic-filter policies cannot drift apart on what
+* counts as more severe.
+*/
+var severityToPuzzleDifficulty = (requestedImageRounds, baseImageRounds, maxLevel = 3) => {
+	if (requestedImageRounds === void 0) return 0;
+	const excess = requestedImageRounds - baseImageRounds;
+	if (!Number.isFinite(excess) || excess <= 0) return clampDifficultyLevel(0, maxLevel);
+	if (excess <= 2) return clampDifficultyLevel(1, maxLevel);
+	if (excess <= 4) return clampDifficultyLevel(2, maxLevel);
+	if (excess <= 6) return clampDifficultyLevel(3, maxLevel);
+	return clampDifficultyLevel(4, maxLevel);
+};
+/**
+* Draw a concrete puzzle config from a level's bands.
+*
+* Sampling is server-side and per-challenge, and is deliberately NOT derived
+* from anything the client supplies (sessionId, token, ip, timestamp). A
+* client-derived seed would let a bot replay a request to obtain the same
+* render, or precompute one offline.
+*
+* `pieceScale` is passed through as a range rather than drawn here: the
+* renderer's own stratified piece-size draw consumes it in
+* `resolvePuzzlePieceSize`, and sampling twice would narrow the distribution.
+*/
+var samplePuzzleDifficulty = (level, holeDarken, maxLevel = 3) => {
+	const index = clampDifficultyLevel(level, maxLevel);
+	const band = PUZZLE_DIFFICULTY_LEVELS[index];
+	const decoyHoleDarkenFloor = holeDarken + MIN_DECOY_HOLE_DARKEN_MARGIN;
+	const sampledDecoyHoleDarken = decoyHoleDarkenSampler.sample(band.decoyHoleDarken.min, band.decoyHoleDarken.max);
+	return {
+		level: index,
+		tolerance: toleranceSampler.sampleInt(band.tolerance.min, band.tolerance.max),
+		puzzle: {
+			decoyCount: decoyCountSampler.sampleInt(band.decoyCount.min, band.decoyCount.max),
+			decoyEdgeDarkness: decoyEdgeDarknessSampler.sampleInt(band.decoyEdgeDarkness.min, band.decoyEdgeDarkness.max),
+			decoyHoleDarken: Math.min(1, Math.max(decoyHoleDarkenFloor, sampledDecoyHoleDarken)),
+			pieceScale: {
+				min: band.pieceScale.min,
+				max: band.pieceScale.max
+			}
+		}
+	};
+};
+//#endregion
+exports.MIN_DECOY_HOLE_DARKEN_MARGIN = MIN_DECOY_HOLE_DARKEN_MARGIN;
+exports.PUZZLE_DIFFICULTY_LEVELS = PUZZLE_DIFFICULTY_LEVELS;
+exports.clampDifficultyLevel = clampDifficultyLevel;
+exports.samplePuzzleDifficulty = samplePuzzleDifficulty;
+exports.severityToPuzzleDifficulty = severityToPuzzleDifficulty;