Address PR #1985 review feedback on connection-info TLVs

- Gate the SSL TLV branch on PP2_CLIENT_SSL (0x01), not just presence:
  a proxy can legally emit an SSL TLV with client=0x00 (TLS not used),
  and connectionInfo.tls was truthy regardless, so request.protocol
  reported "https" for a cleartext client (hdbjeff, blocking).
- Document that alpn/authority/ja3/ja4 are raw, unvalidated TLV payloads
  (hdbjeff, non-blocking).
- Add explicit connectionInfo getters (returning undefined) on
  BunRequest/UwsRequest for API-surface consistency with the existing
  authorized/peerCertificate getters (Ethan-Arrowood, non-blocking).
- Regression tests for an SSL TLV with client=0x00, with and without
  the CERT_CONN bit set alongside it.

Co-Authored-By: Claude Opus <noreply@anthropic.com>

Author: kriszyp

server/serverHelpers/Request.ts

@@ -419,6 +419,10 @@ export class BunRequest {
 	get mtlsConfig() {
 		return undefined;
 	}
+	get connectionInfo() {
+		// No PROXY v2 decoding on the Bun.serve() path
+		return undefined;
+	}
 	get body() {
 		return this.#body || (this.#body = new BunRequestBody(this._webRequest));
 	}
@@ -535,6 +539,10 @@ export class UwsRequest {
 	get mtlsConfig() {
 		return undefined;
 	}
+	get connectionInfo() {
+		// TLS terminated upstream — no PROXY v2 decoding at this hop.
+		return undefined;
+	}
 	get body() {
 		// Bodyless requests get an already-ended empty stream so consumers can still read it uniformly.
 		if (!this.#body) {

server/serverHelpers/proxyProtocol.ts

@@ -43,6 +43,7 @@ const PP2_SUBTYPE_SSL_CIPHER = 0x23;
 const PP2_TYPE_JA3 = 0xe0;
 const PP2_TYPE_JA4 = 0xe1;
 const PP2_TYPE_CLIENT_CERT = 0xe2;
+const PP2_CLIENT_SSL = 0x01;
 const PP2_CLIENT_CERT_CONN = 0x02;
 
 /** TLS facts the fronting proxy observed on the terminated connection. */
@@ -65,17 +66,22 @@ export interface ForwardedTlsInfo {
  * Connection-level facts forwarded by a trusted proxy over a PROXY v2 header.
  * Present on `request.connectionInfo` only when a v2 header was decoded; every
  * field is optional since a given route forwards only what it's configured to.
+ *
+ * `alpn`, `authority`, `ja3`, and `ja4` are raw TLV payloads: decoded as bytes
+ * (latin1/UTF-8) with no grammar or length validation beyond the enclosing
+ * PROXY header's bounds. Validate before placing them in headers, logs, cache
+ * keys, or other security-sensitive contexts.
  */
 export interface ConnectionInfo {
-	/** Negotiated ALPN protocol, e.g. "h2" (PP2 TLV 0x01). */
+	/** Negotiated ALPN protocol, e.g. "h2" (PP2 TLV 0x01). Raw, unvalidated. */
 	alpn?: string;
-	/** SNI hostname from the ClientHello (PP2 TLV 0x02). */
+	/** SNI hostname from the ClientHello (PP2 TLV 0x02). Raw, unvalidated. */
 	authority?: string;
 	/** TLS facts from the SSL TLV (0x20); present when the proxy terminated TLS. */
 	tls?: ForwardedTlsInfo;
-	/** Client JA3 fingerprint, 32-char MD5 hex (PP2 TLV 0xE0). */
+	/** Client JA3 fingerprint, 32-char MD5 hex (PP2 TLV 0xE0). Raw, unvalidated. */
 	ja3?: string;
-	/** Client JA4 fingerprint (PP2 TLV 0xE1). */
+	/** Client JA4 fingerprint (PP2 TLV 0xE1). Raw, unvalidated. */
 	ja4?: string;
 	/** Verified mTLS client certificate chain (DER, leaf first) from PP2 0xE2 TLVs. */
 	clientCertChain?: Buffer[];
@@ -170,10 +176,16 @@ function decodeV2(buffer: Buffer): ProxyHeaderDecision {
 			info.authority = buffer.toString('utf8', valueStart, valueEnd);
 		} else if (type === PP2_TYPE_SSL && valueLength >= 5) {
 			// struct pp2_tlv_ssl: client(1) verify(4, 0 = verified ok), then sub-TLVs.
-			certPresented = (buffer[valueStart] & PP2_CLIENT_CERT_CONN) !== 0;
-			const verifyOk = buffer.readUInt32BE(valueStart + 1) === 0;
-			tls = { verified: certPresented && verifyOk };
-			parseSslSubTlvs(buffer, valueStart + 5, valueEnd, tls);
+			// Only PP2_CLIENT_SSL means the client actually connected over TLS; a
+			// CERT_CONN bit without it is internally inconsistent (a client cert
+			// is a TLS construct) and reported alongside, not on its own.
+			const clientBits = buffer[valueStart];
+			if ((clientBits & PP2_CLIENT_SSL) !== 0) {
+				certPresented = (clientBits & PP2_CLIENT_CERT_CONN) !== 0;
+				const verifyOk = buffer.readUInt32BE(valueStart + 1) === 0;
+				tls = { verified: certPresented && verifyOk };
+				parseSslSubTlvs(buffer, valueStart + 5, valueEnd, tls);
+			}
 		} else if (type === PP2_TYPE_JA3 && valueLength > 0) {
 			info.ja3 = buffer.toString('latin1', valueStart, valueEnd);
 		} else if (type === PP2_TYPE_JA4 && valueLength > 0) {

unitTests/server/serverHelpers/proxyProtocol.test.js

@@ -72,9 +72,9 @@ function tlv(type, value) {
 	return Buffer.concat([header, value]);
 }
 
-function sslTlv({ certPresented = true, verify = 0 } = {}) {
+function sslTlv({ certPresented = true, verify = 0, clientSsl = true } = {}) {
 	const value = Buffer.alloc(5);
-	value[0] = 0x01 | (certPresented ? 0x02 : 0); // PP2_CLIENT_SSL | PP2_CLIENT_CERT_CONN
+	value[0] = (clientSsl ? 0x01 : 0) | (certPresented ? 0x02 : 0); // PP2_CLIENT_SSL | PP2_CLIENT_CERT_CONN
 	value.writeUInt32BE(verify, 1);
 	return tlv(0x20, value);
 }
@@ -187,6 +187,25 @@ describe('proxyProtocol decodeProxyHeader', () => {
 		assert.strictEqual(info.clientCertChain, undefined);
 	});
 
+	it('ignores an SSL TLV whose client field does not report PP2_CLIENT_SSL', () => {
+		// client = 0x00: no SSL, no cert-conn — the proxy is not claiming TLS was used.
+		// With no other TLVs, no connectionInfo fields are populated at all.
+		const header = buildV2Header({ tlvs: [sslTlv({ clientSsl: false, certPresented: false }), tlv(0xe2, CLIENT_DER)] });
+		assert.strictEqual(decodeProxyHeader(header).connectionInfo, undefined);
+	});
+
+	it('ignores CERT_CONN without PP2_CLIENT_SSL as internally inconsistent', () => {
+		// client = CERT_CONN only, no SSL bit: asserts a client cert without asserting TLS.
+		// JA3 alongside proves the TLV loop keeps parsing past the ignored SSL TLV.
+		const header = buildV2Header({
+			tlvs: [sslTlv({ clientSsl: false, certPresented: true }), tlv(0xe2, CLIENT_DER), tlv(0xe0, Buffer.from('0123456789abcdef0123456789abcdef'))],
+		});
+		const info = decodeProxyHeader(header).connectionInfo;
+		assert.strictEqual(info.tls, undefined);
+		assert.strictEqual(info.clientCertChain, undefined);
+		assert.strictEqual(info.ja3, '0123456789abcdef0123456789abcdef');
+	});
+
 	it('captures ALPN, authority, JA3, JA4, and SSL version/cipher TLVs', () => {
 		const sslWithSubTlvs = Buffer.concat([
 			Buffer.from([0x01 | 0x02]), // client: SSL | CERT_CONN