quic: improve peer cert verification

On the client, add verifyPeer: 'auto', 'strict', and
'manual' modes. The 'strict' mode will reject invalid
certs at the handshake layer, while the 'manual' mode
allows the application to inspect the peer cert and decide
whether to trust it or not. The 'auto' mode is the default
and will reject invalid certs at a middle layer after the
onhandshake event.
Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode/Opus 4.6
PR-URL: #63483
Backport-PR-URL: #64675
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Author: jasnell

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);

doc/api/quic.md

@@ -3018,6 +3018,32 @@ value, PING frames will be sent automatically to keep the connection alive
 before the idle timeout fires. The value should be less than the effective
 idle timeout (`maxIdleTimeout` transport parameter) to be useful.
 
+#### `sessionOptions.verifyPeer` (client only)
+
+* Type: {string} One of `'strict'`, `'auto'`, or `'manual'`.
+***Default:**`'auto'`
+
+Controls how the client handles server certificate validation:
+
+*`'strict'` — OpenSSL aborts the TLS handshake immediately if the server's
+ certificate fails validation. The `session.opened` promise rejects with a
+ TLS error. The application cannot inspect the certificate or the error
+ details. This is the most secure mode.
+
+*`'auto'` — The TLS handshake completes regardless of validation result.
+ If validation fails, the `session.opened` promise is rejected with an error
+ containing the validation reason, and the session is destroyed. The
+`onhandshake` callback (if set) fires before rejection, allowing diagnostic
+ logging. This is the default and matches the behavior of `tls.connect()`
+ with `rejectUnauthorized: true`.
+
+*`'manual'` — The TLS handshake completes regardless of validation result.
+ The `session.opened` promise resolves with the handshake info, which includes
+`validationErrorReason` and `validationErrorCode` if validation failed. The
+ application is responsible for checking these values and deciding whether to
+ continue. Use this mode for custom validation logic, certificate pinning, or
+ intentionally accepting self-signed certificates.
+
 #### `sessionOptions.servername` (client only)
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -183,6 +183,7 @@ const {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kOwner,
  kRemoveSession,
@@ -382,6 +383,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [version] The QUIC version
  * @property {number} [minVersion] The minimum acceptable QUIC version
  * @property {'use'|'ignore'|'default'} [preferredAddressPolicy] The preferred address policy
+ * @property {'strict'|'auto'|'manual'} [verifyPeer='auto'] Peer certificate verification policy (client only)
  * @property {ApplicationOptions} [application] The application options
  * @property {TransportParams} [transportParams] The transport parameters
  * @property {string} [servername] The server name identifier (client only)
@@ -2628,6 +2630,11 @@ class QuicSession {
 onkeylog: undefined,
 onqlog: undefined,
 pendingQlog: undefined,
+// Default to 'manual' (no auto-rejection). Client sessions override
+// this via kVerifyPeer in kConnect. Server sessions keep 'manual'
+// because server-side cert validation is handled by rejectUnauthorized
+// at the C++ level.
+verifyPeer: 'manual',
 handshakeInfo: undefined,
 /** @type {QuicSessionPath|undefined} */
 path: undefined,
@@ -3844,6 +3851,22 @@ class QuicSession {
 safeCallbackInvoke(inner.onhandshake,this,info);
 }
 
+// In 'auto' mode, reject the connection if peer certificate validation
+// failed. In 'manual' mode, resolve regardless and let the application
+// decide. In 'strict' mode, the handshake already failed at the C++
+// level (SSL_VERIFY_PEER) so we won't reach here.
+if(inner.verifyPeer==='auto'&&validationErrorReason!==undefined){
+consterr=newERR_QUIC_TRANSPORT_ERROR(
+0,`Peer certificate validation failed: ${validationErrorReason}`+
+` [${validationErrorCode}]`);
+inner.pendingOpen.reject?.(err);
+inner.pendingOpen.resolve=undefined;
+inner.pendingOpen.reject=undefined;
+inner.handshakeCompleted=true;
+this.destroy();
+return;
+}
+
 inner.pendingOpen.resolve?.(info);
 inner.pendingOpen.resolve=undefined;
 inner.pendingOpen.reject=undefined;
@@ -3855,6 +3878,14 @@ class QuicSession {
 returnthis.#inner.handshakeCompleted;
 }
 
+get[kVerifyPeer](){
+returnthis.#inner.verifyPeer;
+}
+
+set[kVerifyPeer](value){
+this.#inner.verifyPeer=value;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4306,6 +4337,10 @@ class QuicEndpoint {
 // Set callbacks before any async work to avoid missing events
 // that fire during or immediately after the handshake.
 applyCallbacks(session,options);
+// Store the verifyPeer policy for use in the handshake handler.
+if(options.verifyPeer!==undefined){
+session[kVerifyPeer]=options.verifyPeer;
+}
 returnsession;
 }
 
@@ -4959,6 +4994,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  datagramDropPolicy ='drop-oldest',
  drainingPeriodMultiplier =3,
  maxDatagramSendAttempts =5,
+ verifyPeer ='auto',
 // HTTP/3 application-specific options. Nested under `application`
 // to separate protocol-specific settings from transport-level ones.
  application =kEmptyObject,
@@ -5005,6 +5041,9 @@ function processSessionOptions(options, config = kEmptyObject) {
 validateOneOf(datagramDropPolicy,'options.datagramDropPolicy',
 ['drop-oldest','drop-newest']);
 
+validateOneOf(verifyPeer,'options.verifyPeer',
+['strict','auto','manual']);
+
 validateInteger(drainingPeriodMultiplier,'options.drainingPeriodMultiplier',
 3,255);
 
@@ -5054,7 +5093,14 @@ function processSessionOptions(options, config = kEmptyObject) {
 preferredAddressIpv4: preferredAddressIpv4?.[kSocketAddressHandle],
 preferredAddressIpv6: preferredAddressIpv6?.[kSocketAddressHandle],
 },
-tls: processTlsOptions(options,forServer),
+tls: {
+ ...processTlsOptions(options,forServer),
+// Forward strict mode to C++ so SSL_VERIFY_PEER is set on the
+// client SSL_CTX. For 'auto' and 'manual' modes, the handshake
+// completes regardless and the result is handled in JS.
+verifyPeerStrict: verifyPeer==='strict',
+},
+ verifyPeer,
  qlog,
  maxPayloadSize,
  unacknowledgedPacketThreshold,

lib/internal/quic/symbols.js

@@ -38,6 +38,7 @@ const kFinishClose = Symbol('kFinishClose');
 constkGoaway=Symbol('kGoaway');
 constkHandshake=Symbol('kHandshake');
 constkHandshakeCompleted=Symbol('kHandshakeCompleted');
+constkVerifyPeer=Symbol('kVerifyPeer');
 constkHeaders=Symbol('kHeaders');
 constkKeylog=Symbol('kKeylog');
 constkListen=Symbol('kListen');
@@ -70,6 +71,7 @@ module.exports = {
  kGoaway,
  kHandshake,
  kHandshakeCompleted,
+ kVerifyPeer,
  kHeaders,
  kInspect,
  kKeylog,

src/quic/bindingdata.h

@@ -164,6 +164,7 @@ class SessionManager;
 V(unacknowledged_packet_threshold, "unacknowledgedPacketThreshold") \
 V(validate_address, "validateAddress") \
 V(verify_client, "verifyClient") \
+V(verify_peer_strict, "verifyPeerStrict") \
 V(verify_private_key, "verifyPrivateKey") \
 V(version, "version")
 

src/quic/tlscontext.cc

@@ -500,6 +500,14 @@ SSLCtxPointer TLSContext::Initialize(Environment* env) {
 SSL_CTX_set_session_cache_mode(
  ctx.get(), SSL_SESS_CACHE_CLIENT | SSL_SESS_CACHE_NO_INTERNAL);
 SSL_CTX_sess_set_new_cb(ctx.get(), OnNewSession);
+
+// In strict mode, set SSL_VERIFY_PEER so OpenSSL aborts the
+// handshake if the server's certificate fails validation. In
+// non-strict modes, verification still occurs but the handshake
+// completes regardless — the result is surfaced to JS.
+if (options_.verify_peer_strict) {
+SSL_CTX_set_verify(ctx.get(), SSL_VERIFY_PEER, nullptr);
+ }
 break;
  }
  }
@@ -706,7 +714,8 @@ Maybe<TLSContext::Options> TLSContext::Options::From(Environment* env,
  env, &options, params, state.name##_string())
 
 if (!SET(verify_client) || !SET(reject_unauthorized) ||
- !SET(enable_early_data) || !SET(enable_tls_trace) || !SET(alpn) ||
+ !SET(verify_peer_strict) || !SET(enable_early_data) ||
+ !SET(enable_tls_trace) || !SET(alpn) ||
  !SET(servername) || !SET(ciphers) || !SET(groups) ||
  !SET(verify_private_key) || !SET(keylog) || !SET(port) ||
  !SET(authoritative) || !SET_VECTOR(crypto::KeyObjectData, keys) ||
@@ -730,6 +739,8 @@ std::string TLSContext::Options::ToString() const {
  (verify_client ? std::string("yes") : std::string("no"));
  res += prefix + "reject unauthorized: " +
  (reject_unauthorized ? std::string("yes") : std::string("no"));
+ res += prefix + "verify peer strict: " +
+ (verify_peer_strict ? std::string("yes") : std::string("no"));
  res += prefix + "enable early data: " +
  (enable_early_data ? std::string("yes") : std::string("no"));
  res += prefix + "enable_tls_trace: " +

src/quic/tlscontext.h

@@ -207,6 +207,14 @@ class TLSContext final : public MemoryRetainer,
 // This option is only used by the server side.
 bool reject_unauthorized = true;
 
+// When true, the client will set SSL_VERIFY_PEER so that OpenSSL
+// aborts the handshake if the server's certificate fails validation.
+// This is the "strict" verify_peer mode. When false (the default),
+// the handshake completes regardless and VerifyPeerIdentity is
+// called after to surface errors to JS. This option is only used
+// by the client side.
+bool verify_peer_strict = false;
+
 // When true (the default), the server accepts 0-RTT early data
 // from clients with valid session tickets. When false, early data
 // is disabled and clients must complete a full handshake before

test/common/quic.mjs

@@ -44,9 +44,13 @@ async function listen(callback, options = {}) {
 asyncfunctionconnect(address,options={}){
 const{
  alpn ='quic-test',
+// Test helper defaults to 'manual' because tests use self-signed
+// certs without a CA. Tests that want to verify cert validation
+// behavior should set verifyPeer explicitly.
+ verifyPeer ='manual',
  ...rest
 }=options;
-returnquic.connect(address,{ alpn, ...rest});
+returnquic.connect(address,{ alpn,verifyPeer,...rest});
 }
 
 export{

test/parallel/test-quic-address-validation.mjs

@@ -37,6 +37,7 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'quic-test',
+verifyPeer: 'manual',
 servername: 'localhost',
 });
 

test/parallel/test-quic-alpn-h3.mjs

@@ -35,6 +35,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 
 constclientSession=awaitconnect(serverEndpoint.address,{
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 asyncfunctioncheckClient(){

test/parallel/test-quic-alpn.mjs

@@ -41,6 +41,7 @@ notStrictEqual(serverEndpoint.address, undefined);
 constclientSession=awaitconnect(serverEndpoint.address,{
 alpn: 'proto-b',
 servername: 'localhost',
+verifyPeer: 'manual',
 });
 
 awaitPromise.all([serverOpened.promise,checkSession(clientSession)]);