fix(provider): plumb TLS handshake timings into escalation + short-circuit sessions (#2803)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: forgetso

.changeset/tls-timings-escalation-shortcircuit.md

@@ -0,0 +1,14 @@
+---
+"@prosopo/provider": patch
+---
+
+fix(provider): persist TLS handshake timings on escalation + short-circuit sessions
+
+`buildEscalation` (post-PoW image/puzzle escalation) and `runConfiguredCaptchaTypeShortCircuit` (sitekeys with a configured captchaType) both bypass `FrictionlessManager.setSessionParams`, so `req.tcpToChelloMs` / `req.chelloToHandshakeMs` were captured by the middleware but never landed on the resulting session record.
+
+Threads the current request's per-connection timings through both paths:
+
+- New optional `handshakeTiming` arg on `buildEscalation`, forwarded to `createSession`. Timings come from the current PoW-submit request, not from `originSession` (whose values belong to the earlier frictionless request's TCP connection).
+- New optional `tcpToChelloMs` / `chelloToHandshakeMs` on `ShortCircuitInput`, spread into the locally-built `sessionParams`.
+
+The frictionless main path (`sendCaptcha` / `registerBlockedSession`) was already correct — it merges from `setSessionParams`, which the handler populates.

packages/provider/src/api/captcha/getFrictionlessCaptchaChallenge/handler.ts

@@ -388,6 +388,12 @@ export default (
 					sessionMode,
 					userSitekeyIpHash,
 					logger: req.logger,
+					...(req.tcpToChelloMs !== undefined && {
+						tcpToChelloMs: req.tcpToChelloMs,
+					}),
+					...(req.chelloToHandshakeMs !== undefined && {
+						chelloToHandshakeMs: req.chelloToHandshakeMs,
+					}),
 				},
 				res,
 			);

packages/provider/src/api/captcha/getFrictionlessCaptchaChallenge/shortCircuit.ts

@@ -40,6 +40,8 @@ export type ShortCircuitInput = {
 	sessionMode: ModeEnum | undefined;
 	userSitekeyIpHash: string;
 	logger: Logger;
+	tcpToChelloMs?: number;
+	chelloToHandshakeMs?: number;
 };
 
 // Bypasses the bot-detection decision machine when the sitekey is configured
@@ -69,6 +71,12 @@ export const runConfiguredCaptchaTypeShortCircuit = async (
 		headers: input.flatHeaders,
 		mode: input.sessionMode,
 		userSitekeyIpHash: input.userSitekeyIpHash,
+		...(input.tcpToChelloMs !== undefined && {
+			tcpToChelloMs: input.tcpToChelloMs,
+		}),
+		...(input.chelloToHandshakeMs !== undefined && {
+			chelloToHandshakeMs: input.chelloToHandshakeMs,
+		}),
 	};
 
 	input.logger.info(() => ({

packages/provider/src/api/captcha/submitPoWCaptchaSolution.ts

@@ -187,7 +187,10 @@ export default (env: ProviderEnvironment) =>
 				}));
 			}
 
-			const escalation = await buildEscalation(tasks, result, challenge);
+			const escalation = await buildEscalation(tasks, result, challenge, {
+				tcpToChelloMs: req.tcpToChelloMs,
+				chelloToHandshakeMs: req.chelloToHandshakeMs,
+			});
 			const response: PowCaptchaSolutionResponse = {
 				status: "ok",
 				// On escalation the user is not done — they still need to clear
@@ -229,6 +232,14 @@ export const buildEscalation = async (
 	tasks: Tasks,
 	result: { verified: boolean; routingOutput?: { captchaType: CaptchaType } },
 	challenge: string,
+	// TLS handshake timings are per-connection: they must come from the
+	// current PoW-submit request, not from `originSession` (whose values
+	// belong to a different TCP connection made during the earlier
+	// frictionless request).
+	handshakeTiming?: {
+		tcpToChelloMs?: number;
+		chelloToHandshakeMs?: number;
+	},
 ): Promise<PowCaptchaSolutionEscalation | undefined> => {
 	if (!result.verified || !result.routingOutput) return undefined;
 	const routedType = result.routingOutput.captchaType;
@@ -285,6 +296,8 @@ export const buildEscalation = async (
 		originSession.entropyWallClockOffsetMs,
 		originSession.entropyMathRandomFirst,
 		originSession.currentUrl,
+		handshakeTiming?.tcpToChelloMs,
+		handshakeTiming?.chelloToHandshakeMs,
 	);
 
 	// Record the origin → escalation sessionId mapping so a /captcha/*