feat(provider): read handshake timings as microseconds, not milliseconds (#2808)

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

Author: forgetso

.changeset/handshake-timing-microseconds.md

@@ -0,0 +1,17 @@
+---
+"@prosopo/provider": patch
+"@prosopo/types": patch
+"@prosopo/types-database": patch
+---
+
+feat: switch handshake timings from milliseconds to microseconds
+
+Milliseconds bucket fast handshakes (local proxies, same-DC clients) to 0/1 and destroy the distribution shape we need for proxy detection. `time.Now()` on Linux is ~1μs precise via vDSO — μs is the honest resolution ceiling.
+
+Wire changes (must land together with the paired chaddy release):
+
+- Headers consumed by `handshakeTimingMiddleware`: `x-tls-tcp-to-chello-ms` / `x-tls-chello-to-handshake-ms` → `x-tls-tcp-to-chello-us` / `x-tls-chello-to-handshake-us`.
+- Request augmentation, `HandshakeTiming` fields, decision-machine input, `Session` shape (Zod + Mongoose schemas): `tcpToChelloMs` / `chelloToHandshakeMs` → `tcpToChelloUs` / `chelloToHandshakeUs`.
+- New sessions in `captchastorage.sessions` will now write `tcpToChelloUs` / `chelloToHandshakeUs` in μs. Historical `*Ms` fields on existing session records remain as-is (not migrated) — analytics that read both must range-scan by field name.
+
+Rollout: deploy paired chaddy image (emits `-Us` headers) simultaneously; the deploy-order window drops timing signal but no data corruption is possible (mismatched header names simply resolve to `undefined`).

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

@@ -287,11 +287,11 @@ export default (
 									// Timing values are per-connection so they come from
 									// the current request even in the dedup replay path —
 									// dedup.session was created on a different TCP conn.
-									...(req.tcpToChelloMs !== undefined && {
-										tcpToChelloMs: req.tcpToChelloMs,
+									...(req.tcpToChelloUs !== undefined && {
+										tcpToChelloUs: req.tcpToChelloUs,
 									}),
-									...(req.chelloToHandshakeMs !== undefined && {
-										chelloToHandshakeMs: req.chelloToHandshakeMs,
+									...(req.chelloToHandshakeUs !== undefined && {
+										chelloToHandshakeUs: req.chelloToHandshakeUs,
 									}),
 									// currentUrl uses the cached session's value to
 									// match the rest of the dedup routing input (score,
@@ -388,11 +388,11 @@ export default (
 					sessionMode,
 					userSitekeyIpHash,
 					logger: req.logger,
-					...(req.tcpToChelloMs !== undefined && {
-						tcpToChelloMs: req.tcpToChelloMs,
+					...(req.tcpToChelloUs !== undefined && {
+						tcpToChelloUs: req.tcpToChelloUs,
 					}),
-					...(req.chelloToHandshakeMs !== undefined && {
-						chelloToHandshakeMs: req.chelloToHandshakeMs,
+					...(req.chelloToHandshakeUs !== undefined && {
+						chelloToHandshakeUs: req.chelloToHandshakeUs,
 					}),
 				},
 				res,
@@ -544,11 +544,11 @@ export default (
 				...(entropyMathRandomFirst !== undefined && {
 					entropyMathRandomFirst,
 				}),
-				...(req.tcpToChelloMs !== undefined && {
-					tcpToChelloMs: req.tcpToChelloMs,
+				...(req.tcpToChelloUs !== undefined && {
+					tcpToChelloUs: req.tcpToChelloUs,
 				}),
-				...(req.chelloToHandshakeMs !== undefined && {
-					chelloToHandshakeMs: req.chelloToHandshakeMs,
+				...(req.chelloToHandshakeUs !== undefined && {
+					chelloToHandshakeUs: req.chelloToHandshakeUs,
 				}),
 			});
 
@@ -570,11 +570,11 @@ export default (
 					headers: flatHeaders,
 					userAgent: safeUserAgent,
 					...(req.ja4 && { ja4: req.ja4 }),
-					...(req.tcpToChelloMs !== undefined && {
-						tcpToChelloMs: req.tcpToChelloMs,
+					...(req.tcpToChelloUs !== undefined && {
+						tcpToChelloUs: req.tcpToChelloUs,
 					}),
-					...(req.chelloToHandshakeMs !== undefined && {
-						chelloToHandshakeMs: req.chelloToHandshakeMs,
+					...(req.chelloToHandshakeUs !== undefined && {
+						chelloToHandshakeUs: req.chelloToHandshakeUs,
 					}),
 					...(currentUrl && { currentUrl }),
 				},

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

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

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

@@ -140,11 +140,11 @@ export default (env: ProviderEnvironment) =>
 					userAgent,
 					...(req.ja4 && { ja4: req.ja4 }),
 					...(fingerprintProof && { fingerprintProof }),
-					...(req.tcpToChelloMs !== undefined && {
-						tcpToChelloMs: req.tcpToChelloMs,
+					...(req.tcpToChelloUs !== undefined && {
+						tcpToChelloUs: req.tcpToChelloUs,
 					}),
-					...(req.chelloToHandshakeMs !== undefined && {
-						chelloToHandshakeMs: req.chelloToHandshakeMs,
+					...(req.chelloToHandshakeUs !== undefined && {
+						chelloToHandshakeUs: req.chelloToHandshakeUs,
 					}),
 				},
 			});
@@ -188,8 +188,8 @@ export default (env: ProviderEnvironment) =>
 			}
 
 			const escalation = await buildEscalation(tasks, result, challenge, {
-				tcpToChelloMs: req.tcpToChelloMs,
-				chelloToHandshakeMs: req.chelloToHandshakeMs,
+				tcpToChelloUs: req.tcpToChelloUs,
+				chelloToHandshakeUs: req.chelloToHandshakeUs,
 			});
 			const response: PowCaptchaSolutionResponse = {
 				status: "ok",
@@ -237,8 +237,8 @@ export const buildEscalation = async (
 	// belong to a different TCP connection made during the earlier
 	// frictionless request).
 	handshakeTiming?: {
-		tcpToChelloMs?: number;
-		chelloToHandshakeMs?: number;
+		tcpToChelloUs?: number;
+		chelloToHandshakeUs?: number;
 	},
 ): Promise<PowCaptchaSolutionEscalation | undefined> => {
 	if (!result.verified || !result.routingOutput) return undefined;
@@ -296,8 +296,8 @@ export const buildEscalation = async (
 		originSession.entropyWallClockOffsetMs,
 		originSession.entropyMathRandomFirst,
 		originSession.currentUrl,
-		handshakeTiming?.tcpToChelloMs,
-		handshakeTiming?.chelloToHandshakeMs,
+		handshakeTiming?.tcpToChelloUs,
+		handshakeTiming?.chelloToHandshakeUs,
 	);
 
 	// Record the origin → escalation sessionId mapping so a /captcha/*

packages/provider/src/api/handshakeTimingMiddleware.ts

@@ -19,17 +19,17 @@ import type { ProviderEnvironment } from "@prosopo/types-env";
 import type { NextFunction, Request, Response } from "express";
 
 // Header names forwarded by the chaddy Caddy plugin per-TLS-connection.
-// Both are server-observed millisecond deltas across the TLS handshake
+// Both are server-observed microsecond deltas across the TLS handshake
 // lifecycle. Elevated values indicate the client's ClientHello traversed
 // a proxy chain before reaching Caddy — the CH bytes only reach the
 // terminating TCP stack after every hop, so the deltas inflate with the
 // full client-to-exit RTT rather than just the last-mile RTT.
-const HEADER_TCP_TO_CHELLO = "x-tls-tcp-to-chello-ms";
-const HEADER_CHELLO_TO_HANDSHAKE = "x-tls-chello-to-handshake-ms";
+const HEADER_TCP_TO_CHELLO = "x-tls-tcp-to-chello-us";
+const HEADER_CHELLO_TO_HANDSHAKE = "x-tls-chello-to-handshake-us";
 
 export interface HandshakeTiming {
-	tcpToChelloMs?: number;
-	chelloToHandshakeMs?: number;
+	tcpToChelloUs?: number;
+	chelloToHandshakeUs?: number;
 }
 
 const parseTimingHeader = (
@@ -61,12 +61,12 @@ export const getHandshakeTiming = (
 ): HandshakeTiming => {
 	const log = logger ?? getLogger("info", "provider:handshake-timing");
 	return {
-		tcpToChelloMs: parseTimingHeader(
+		tcpToChelloUs: parseTimingHeader(
 			headers[HEADER_TCP_TO_CHELLO],
 			log,
 			HEADER_TCP_TO_CHELLO,
 		),
-		chelloToHandshakeMs: parseTimingHeader(
+		chelloToHandshakeUs: parseTimingHeader(
 			headers[HEADER_CHELLO_TO_HANDSHAKE],
 			log,
 			HEADER_CHELLO_TO_HANDSHAKE,
@@ -82,20 +82,20 @@ export const handshakeTimingMiddleware = (env: ProviderEnvironment) => {
 	return async (req: Request, res: Response, next: NextFunction) => {
 		try {
 			const timing = getHandshakeTiming(req.headers, req.logger);
-			if (timing.tcpToChelloMs !== undefined) {
-				req.tcpToChelloMs = timing.tcpToChelloMs;
+			if (timing.tcpToChelloUs !== undefined) {
+				req.tcpToChelloUs = timing.tcpToChelloUs;
 			}
-			if (timing.chelloToHandshakeMs !== undefined) {
-				req.chelloToHandshakeMs = timing.chelloToHandshakeMs;
+			if (timing.chelloToHandshakeUs !== undefined) {
+				req.chelloToHandshakeUs = timing.chelloToHandshakeUs;
 			}
 			if (
-				timing.tcpToChelloMs !== undefined ||
-				timing.chelloToHandshakeMs !== undefined
+				timing.tcpToChelloUs !== undefined ||
+				timing.chelloToHandshakeUs !== undefined
 			) {
 				req.logger = req.logger.with(
 					{
-						tcpToChelloMs: timing.tcpToChelloMs,
-						chelloToHandshakeMs: timing.chelloToHandshakeMs,
+						tcpToChelloUs: timing.tcpToChelloUs,
+						chelloToHandshakeUs: timing.chelloToHandshakeUs,
 					},
 					"handshakeTiming",
 				);

packages/provider/src/express.d.ts

@@ -27,12 +27,12 @@ export interface AugmentedRequest {
 	requestId?: string;
 	ipInfo?: IPInfoResponse;
 	// Per-TLS-connection handshake timings forwarded by the chaddy Caddy
-	// plugin (X-TLS-TCP-To-Chello-Ms / X-TLS-Chello-To-Handshake-Ms).
+	// plugin (X-TLS-TCP-To-Chello-Us / X-TLS-Chello-To-Handshake-Us).
 	// Undefined when the request did not traverse a TLS-terminating
 	// Caddy with the chaddy plugin (e.g. plaintext dev requests) or when
 	// the plugin failed to capture timing for that connection.
-	tcpToChelloMs?: number;
-	chelloToHandshakeMs?: number;
+	tcpToChelloUs?: number;
+	chelloToHandshakeUs?: number;
 }
 
 declare global {
@@ -48,8 +48,8 @@ declare global {
 			logger: Logger;
 			requestId?: string;
 			ipInfo?: IPInfoResponse;
-			tcpToChelloMs?: number;
-			chelloToHandshakeMs?: number;
+			tcpToChelloUs?: number;
+			chelloToHandshakeUs?: number;
 		}
 	}
 }

packages/provider/src/tasks/frictionless/frictionlessTasks.ts

@@ -146,8 +146,8 @@ export class FrictionlessManager extends CaptchaManager {
 			entropyCryptoFingerprint: params.entropyCryptoFingerprint,
 			entropyWallClockOffsetMs: params.entropyWallClockOffsetMs,
 			entropyMathRandomFirst: params.entropyMathRandomFirst,
-			tcpToChelloMs: params.tcpToChelloMs,
-			chelloToHandshakeMs: params.chelloToHandshakeMs,
+			tcpToChelloUs: params.tcpToChelloUs,
+			chelloToHandshakeUs: params.chelloToHandshakeUs,
 		};
 	}
 
@@ -188,8 +188,8 @@ export class FrictionlessManager extends CaptchaManager {
 		entropyWallClockOffsetMs?: Session["entropyWallClockOffsetMs"],
 		entropyMathRandomFirst?: Session["entropyMathRandomFirst"],
 		currentUrl?: Session["currentUrl"],
-		tcpToChelloMs?: Session["tcpToChelloMs"],
-		chelloToHandshakeMs?: Session["chelloToHandshakeMs"],
+		tcpToChelloUs?: Session["tcpToChelloUs"],
+		chelloToHandshakeUs?: Session["chelloToHandshakeUs"],
 	): Promise<Session> {
 		const sessionRecord: Session = {
 			sessionId: `${getSessionIDPrefix(this.config.host)}-${uuidv4()}`,
@@ -224,8 +224,8 @@ export class FrictionlessManager extends CaptchaManager {
 			entropyCryptoFingerprint,
 			entropyWallClockOffsetMs,
 			entropyMathRandomFirst,
-			tcpToChelloMs,
-			chelloToHandshakeMs,
+			tcpToChelloUs,
+			chelloToHandshakeUs,
 		};
 
 		await this.db.storeSessionRecord(sessionRecord);
@@ -364,8 +364,8 @@ export class FrictionlessManager extends CaptchaManager {
 			effectiveParams.entropyWallClockOffsetMs,
 			effectiveParams.entropyMathRandomFirst,
 			effectiveParams.currentUrl,
-			effectiveParams.tcpToChelloMs,
-			effectiveParams.chelloToHandshakeMs,
+			effectiveParams.tcpToChelloUs,
+			effectiveParams.chelloToHandshakeUs,
 		);
 
 		// Fire-and-forget served-counter writes. Skipped when there's no
@@ -435,8 +435,8 @@ export class FrictionlessManager extends CaptchaManager {
 			effectiveParams.entropyWallClockOffsetMs,
 			effectiveParams.entropyMathRandomFirst,
 			effectiveParams.currentUrl,
-			effectiveParams.tcpToChelloMs,
-			effectiveParams.chelloToHandshakeMs,
+			effectiveParams.tcpToChelloUs,
+			effectiveParams.chelloToHandshakeUs,
 		);
 	}
 

packages/provider/src/tests/unit/api/handshakeTimingMiddleware.unit.test.ts

@@ -33,64 +33,64 @@ const mockLogger = (): Logger => {
 describe("getHandshakeTiming", () => {
 	it("returns both values when both headers are present and parseable", () => {
 		const headers: IncomingHttpHeaders = {
-			"x-tls-tcp-to-chello-ms": "42",
-			"x-tls-chello-to-handshake-ms": "137",
+			"x-tls-tcp-to-chello-us": "42",
+			"x-tls-chello-to-handshake-us": "137",
 		};
 		const result = getHandshakeTiming(headers, mockLogger());
-		expect(result.tcpToChelloMs).toBe(42);
-		expect(result.chelloToHandshakeMs).toBe(137);
+		expect(result.tcpToChelloUs).toBe(42);
+		expect(result.chelloToHandshakeUs).toBe(137);
 	});
 
-	it("returns 0 for legitimate zero-ms measurements", () => {
+	it("returns 0 for legitimate zero-us measurements", () => {
 		const headers: IncomingHttpHeaders = {
-			"x-tls-tcp-to-chello-ms": "0",
-			"x-tls-chello-to-handshake-ms": "0",
+			"x-tls-tcp-to-chello-us": "0",
+			"x-tls-chello-to-handshake-us": "0",
 		};
 		const result = getHandshakeTiming(headers, mockLogger());
-		expect(result.tcpToChelloMs).toBe(0);
-		expect(result.chelloToHandshakeMs).toBe(0);
+		expect(result.tcpToChelloUs).toBe(0);
+		expect(result.chelloToHandshakeUs).toBe(0);
 	});
 
 	it("returns undefined when a header is missing", () => {
 		const headers: IncomingHttpHeaders = {
-			"x-tls-tcp-to-chello-ms": "5",
+			"x-tls-tcp-to-chello-us": "5",
 		};
 		const result = getHandshakeTiming(headers, mockLogger());
-		expect(result.tcpToChelloMs).toBe(5);
-		expect(result.chelloToHandshakeMs).toBeUndefined();
+		expect(result.tcpToChelloUs).toBe(5);
+		expect(result.chelloToHandshakeUs).toBeUndefined();
 	});
 
 	it("returns undefined for both when neither header is present", () => {
 		const headers: IncomingHttpHeaders = {};
 		const result = getHandshakeTiming(headers, mockLogger());
-		expect(result.tcpToChelloMs).toBeUndefined();
-		expect(result.chelloToHandshakeMs).toBeUndefined();
+		expect(result.tcpToChelloUs).toBeUndefined();
+		expect(result.chelloToHandshakeUs).toBeUndefined();
 	});
 
 	it("rejects non-numeric header values", () => {
 		const headers: IncomingHttpHeaders = {
-			"x-tls-tcp-to-chello-ms": "not-a-number",
-			"x-tls-chello-to-handshake-ms": "137",
+			"x-tls-tcp-to-chello-us": "not-a-number",
+			"x-tls-chello-to-handshake-us": "137",
 		};
 		const result = getHandshakeTiming(headers, mockLogger());
-		expect(result.tcpToChelloMs).toBeUndefined();
-		expect(result.chelloToHandshakeMs).toBe(137);
+		expect(result.tcpToChelloUs).toBeUndefined();
+		expect(result.chelloToHandshakeUs).toBe(137);
 	});
 
 	it("rejects negative values", () => {
 		const headers: IncomingHttpHeaders = {
-			"x-tls-tcp-to-chello-ms": "-3",
+			"x-tls-tcp-to-chello-us": "-3",
 		};
 		const result = getHandshakeTiming(headers, mockLogger());
-		expect(result.tcpToChelloMs).toBeUndefined();
+		expect(result.tcpToChelloUs).toBeUndefined();
 	});
 
 	it("takes the first value when the header is repeated (string[])", () => {
 		const headers: IncomingHttpHeaders = {
-			"x-tls-tcp-to-chello-ms": ["17", "99"],
+			"x-tls-tcp-to-chello-us": ["17", "99"],
 		};
 		const result = getHandshakeTiming(headers, mockLogger());
-		expect(result.tcpToChelloMs).toBe(17);
+		expect(result.tcpToChelloUs).toBe(17);
 	});
 });