quic: expose QUIC certificates as JS X509Certificate, not raw handles

pimterry · aduh95 · commit 04a17fe6f0fd · 2026-06-21T00:20:28.000+02:00
Signed-off-by: Tim Perry <pimterry@gmail.com> PR-URL: #63191 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ethan Arrowood <ethan@arrowood.dev> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
diff --git a/doc/api/quic.md b/doc/api/quic.md
@@ -1422,23 +1422,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: v26.2.0
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: v26.2.0
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4442,6 +4443,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
@@ -152,6 +152,10 @@ const {
   isKeyObject,
 } = require('internal/crypto/keys');
 
+const {
+  InternalX509Certificate,
+} = require('internal/crypto/x509');
+
 const {
   FileHandle,
   kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
   }
 
   /**
-   * The local certificate as an object, or undefined if not available.
-   * @type {object|undefined}
+   * The local certificate as a {@link crypto.X509Certificate}, or undefined
+   * if no local certificate is available. Server sessions return their
+   * configured certificate; client sessions return undefined unless a
+   * client certificate was sent.
+   * @type {crypto.X509Certificate|undefined}
    */
   get certificate() {
     assertIsQuicSession(this);
     if (this.destroyed) return undefined;
-    return this.#inner.certificate ??= this.#handle.getCertificate();
+    if (this.#inner.certificate === undefined) {
+      const handle = this.#handle.getCertificate();
+      this.#inner.certificate = handle ? new InternalX509Certificate(handle) : null;
+    }
+    return this.#inner.certificate ?? undefined;
   }
 
   /**
-   * The peer's certificate as an object, or undefined if the peer did
-   * not present a certificate or the session is destroyed.
-   * @type {object|undefined}
+   * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+   * if the peer did not present a certificate or the session is destroyed.
+   * @type {crypto.X509Certificate|undefined}
    */
   get peerCertificate() {
     assertIsQuicSession(this);
     if (this.destroyed) return undefined;
-    return this.#inner.peerCertificate ??= this.#handle.getPeerCertificate();
+    if (this.#inner.peerCertificate === undefined) {
+      const handle = this.#handle.getPeerCertificate();
+      this.#inner.peerCertificate = handle ?
+        new InternalX509Certificate(handle) :
+        null;
+    }
+    return this.#inner.peerCertificate ?? undefined;
   }
 
   /**
diff --git a/test/parallel/test-quic-session-properties.mjs b/test/parallel/test-quic-session-properties.mjs
@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import { hasQuic, skip, mustCall, hasCrypto } from '../common/index.mjs';
+import * as fixtures from '../common/fixtures.mjs';
 import assert from 'node:assert';
 
 const { ok, strictEqual } = assert;
 
+if (!hasCrypto)
+  skip('missing crypto');
+
+const { X509Certificate } = await import('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+const expectedCert = new X509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if (!hasQuic) {
   skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
   // Own certificate.
   const cert = serverSession.certificate;
-  ok(cert);
+  ok(cert instanceof X509Certificate);
+  strictEqual(cert.subject, expectedCert.subject);
+  strictEqual(cert.issuer, expectedCert.issuer);
+  strictEqual(cert.fingerprint256, expectedCert.fingerprint256);
 
   // Peer certificate (client's cert — not set in this
   // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 const peerCert = clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCert instanceof X509Certificate);
+strictEqual(peerCert.subject, expectedCert.subject);
+strictEqual(peerCert.issuer, expectedCert.issuer);
+strictEqual(peerCert.fingerprint256, expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 const keyInfo = clientSession.ephemeralKeyInfo;
