@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 The Somewhere Authors
+
+package eu.nodepass.somewhere.quic
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import eu.nodepass.somewhere.vpn.E2eEnvironment
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.net.InetSocketAddress
+import java.net.Socket
+import java.security.MessageDigest
+import java.security.cert.X509Certificate
+import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLSocket
+import javax.net.ssl.X509TrustManager
+
+/**
+ * `pin` on the QUIC carrier, checked against the certificate a real Portal
+ * actually presents.
+ *
+ * ## Why the pin is read rather than written down
+ *
+ * A test that pins a value it also configured proves that the client agrees
+ * with itself. So the pin here is read off the Portal's own leaf over an
+ * **independent TLS connection** — a different socket, a different protocol, a
+ * different code path from the one under test — and only then handed back as
+ * `pin=`. The same shape the TLS carrier's own test uses, for the same reason.
+ *
+ * ## The control is the finding
+ *
+ * A matching pin completing the handshake proves nothing on its own: the
+ * connection would have completed anyway, because a QUIC connection with no pin
+ * verifies nothing at all, which is upstream's behaviour and this client's
+ * default. What has to be true is the other half — that one wrong nibble stops
+ * it. Both are here, and the second is the one worth reading.
+ */
+@RunWith(AndroidJUnit4::class)
+class QuicPinTest {
+    @Test
+    fun aPinReadFromThePortalsOwnCertificateCompletesTheHandshake() {
+        val portal = E2eEnvironment.requirePortal()
+        val pin = leafDigest(portal)
+        connect(portal, pin).use { connection ->
+            connection.completeHandshake()
+            assertTrue("a correct pin refused the Portal's own certificate", connection.handshakeCompleted)
+        }
+    }
+
+    @Test
+    fun oneWrongNibbleStopsTheHandshake() {
+        // The whole test. Everything else here would pass with verification
+        // switched off entirely.
+        val portal = E2eEnvironment.requirePortal()
+        val pin = leafDigest(portal).copyOf()
+        pin[0] = (pin[0].toInt() xor 0x01).toByte()
+
+        val failure =
+            runCatching {
+                connect(portal, pin).use { it.completeHandshake() }
+            }.exceptionOrNull()
+
+        assertNotNull("a QUIC connection accepted a certificate the pin does not name", failure)
+    }
+
+    @Test
+    fun aPinOfTheWrongLengthIsRefusedBeforeAnySocketIsOpened() {
+        // Neither padded nor truncated. Either would produce a connection
+        // verifying against something nobody asked for, which is worse than
+        // not connecting.
+        val portal = E2eEnvironment.requirePortal()
+        val refused =
+            runCatching { connect(portal, ByteArray(16)) }.exceptionOrNull()
+        assertTrue(
+            "a 16-byte pin should be refused at the boundary, not carried",
+            refused is IllegalArgumentException,
+        )
+    }
+
+    @Test
+    fun aPinIsThirtyTwoBytesBecauseItIsASha256() {
+        assertEquals(32, QuicConnection.PIN_LENGTH)
+    }
+
+    /**
+     * The SHA-256 of the leaf the Portal presents, over its TLS listener.
+     *
+     * The Portal serves both carriers from one certificate; if that ever stops
+     * being true this test says so by failing, which is worth knowing.
+     */
+    private fun leafDigest(portal: String): ByteArray {
+        val host = portal.substringBeforeLast(':')
+        val port = portal.substringAfterLast(':').toInt()
+        val context =
+            SSLContext.getInstance("TLS").apply {
+                init(null, arrayOf(AcceptAnything), java.security.SecureRandom())
+            }
+        val raw = Socket()
+        raw.connect(InetSocketAddress(host, port), PROBE_TIMEOUT_MILLIS)
+        val socket = context.socketFactory.createSocket(raw, host, port, true) as SSLSocket
+        socket.soTimeout = PROBE_TIMEOUT_MILLIS
+        return socket.use {
+            it.startHandshake()
+            val leaf = it.session.peerCertificates.first() as X509Certificate
+            MessageDigest.getInstance("SHA-256").digest(leaf.encoded)
+        }
+    }
+
+    private fun connect(
+        portal: String,
+        pin: ByteArray?,
+    ): QuicConnection {
+        val host = portal.substringBeforeLast(':')
+        val port = portal.substringAfterLast(':').toInt()
+        return QuicConnection.open(
+            remote = InetSocketAddress(host, port),
+            alpn = ALPN,
+            serverName = null,
+            pinSha256 = pin,
+            // No tunnel is up in this test, so there is nothing to protect
+            // against.
+            protect = { true },
+        )
+    }
+
+    /** Reads the certificate without judging it; the pin is the judgement. */
+    private object AcceptAnything : X509TrustManager {
+        override fun checkClientTrusted(
+            chain: Array<X509Certificate>,
+            authType: String,
+        ) = Unit
+
+        override fun checkServerTrusted(
+            chain: Array<X509Certificate>,
+            authType: String,
+        ) = Unit
+
+        override fun getAcceptedIssuers(): Array<X509Certificate> = emptyArray()
+    }
+
+    private companion object {
+        const val ALPN = "now/1"
+        const val PROBE_TIMEOUT_MILLIS = 10_000
+    }
+}
@@ -54,6 +54,9 @@
 #include <openssl/ssl.h>
 #include <openssl/rand.h>
 #include <openssl/err.h>
+#include <openssl/sha.h>
+#include <openssl/mem.h>
+#include <openssl/pool.h>
 
 // Refusals that are this bridge's own, kept clear of ngtcp2's error space,
 // which is negative and small.
@@ -127,6 +130,16 @@ struct quic_conn {
     ngtcp2_ccerr last_error;
     char message[192];
 
+    // The certificate this connection will accept, and nothing else.
+    //
+    // SHA-256 of the leaf's DER encoding, which is what a `pin=` parameter
+    // carries and what the TLS carrier already compares. Absent is the ordinary
+    // case and means no verification at all -- upstream's own behaviour when a
+    // node names neither `sni` nor `pin`, and what every URL current dashboards
+    // emit produces.
+    uint8_t pin[SHA256_DIGEST_LENGTH];
+    int has_pin;
+
     // Datagrams waiting to go out, and ones that arrived. Both are FIFO, kept
     // as head/tail so a busy flow does not walk the list to append.
     struct quic_datagram *tx_head, *tx_tail;
@@ -450,6 +463,62 @@ static int fill_addr(struct sockaddr_storage *out, socklen_t *outlen,
     return -1;
 }
 
+// Accepts exactly one certificate: the one whose DER encoding hashes to the pin.
+//
+// The chain is deliberately not consulted. A pinned certificate is commonly
+// self-signed, and checking the chain first would reject the very certificate
+// the pin names -- the TLS carrier makes the same choice for the same reason.
+//
+// Constant time, through CRYPTO_memcmp. A short-circuiting comparison leaks how
+// many leading bytes matched, which is enough to find a matching prefix one byte
+// at a time; that it would take a new handshake per byte makes it slow, not
+// impossible.
+static enum ssl_verify_result_t verify_pin(SSL *ssl, uint8_t *out_alert) {
+    ngtcp2_crypto_conn_ref *ref;
+    struct quic_conn *c;
+    const STACK_OF(CRYPTO_BUFFER) *chain;
+    const CRYPTO_BUFFER *leaf;
+    uint8_t digest[SHA256_DIGEST_LENGTH];
+
+    ref = (ngtcp2_crypto_conn_ref *)SSL_get_app_data(ssl);
+    c = ref ? (struct quic_conn *)ref->user_data : NULL;
+    if (!c || !c->has_pin) {
+        // Installed without a pin to compare against. Refusing is the only safe
+        // answer: this callback exists because verification was asked for.
+        if (c) {
+            say(c, "the verification callback could not find the pin it was installed for");
+        }
+        *out_alert = SSL_AD_INTERNAL_ERROR;
+        return ssl_verify_invalid;
+    }
+
+    chain = SSL_get0_peer_certificates(ssl);
+    if (!chain || sk_CRYPTO_BUFFER_num(chain) == 0) {
+        say(c, "the peer presented no certificate to pin against");
+        *out_alert = SSL_AD_BAD_CERTIFICATE;
+        return ssl_verify_invalid;
+    }
+
+    leaf = sk_CRYPTO_BUFFER_value(chain, 0);
+    SHA256(CRYPTO_BUFFER_data(leaf), CRYPTO_BUFFER_len(leaf), digest);
+    if (CRYPTO_memcmp(digest, c->pin, sizeof(digest)) != 0) {
+        // The presented digest goes into the message. A mismatch has two very
+        // different causes -- a wrong `pin=`, or a Portal serving a different
+        // certificate on this listener than on the one the pin was taken from
+        // -- and they are indistinguishable without it.
+        char hex[2 * SHA256_DIGEST_LENGTH + 1];
+        size_t i;
+        for (i = 0; i < SHA256_DIGEST_LENGTH; i++) {
+            snprintf(hex + i * 2, 3, "%02x", digest[i]);
+        }
+        snprintf(c->message, sizeof(c->message),
+                 "the certificate does not match the pin; it presented %s", hex);
+        *out_alert = SSL_AD_BAD_CERTIFICATE;
+        return ssl_verify_invalid;
+    }
+    return ssl_verify_ok;
+}
+
 static int ssl_init(struct quic_conn *c, const char *server_name,
                     const uint8_t *alpn, size_t alpnlen) {
     uint8_t wire[256];
@@ -492,6 +561,13 @@ static int ssl_init(struct quic_conn *c, const char *server_name,
     if (server_name && server_name[0] != '\0') {
         SSL_set_tlsext_host_name(c->ssl, server_name);
     }
+
+    // Only when a pin was given. Without one this stays at BoringSSL's client
+    // default, which verifies nothing -- the state every node that names
+    // neither `sni` nor `pin` is in, and the one upstream is in too.
+    if (c->has_pin) {
+        SSL_set_custom_verify(c->ssl, SSL_VERIFY_PEER, verify_pin);
+    }
     return 0;
 }
 
@@ -614,11 +690,11 @@ JNIEXPORT jlong JNICALL
 Java_eu_nodepass_somewhere_quic_QuicConnection_nativeOpen(
     JNIEnv *env, jclass clazz, jbyteArray local_ip, jint local_port,
     jbyteArray remote_ip, jint remote_port, jstring server_name,
-    jbyteArray alpn) {
+    jbyteArray alpn, jbyteArray pin) {
     (void)clazz;
     struct quic_conn *c;
     jbyte local_buf[16], remote_buf[16], alpn_buf[255];
-    jsize local_len, remote_len, alpn_len;
+    jsize local_len, remote_len, alpn_len, pin_len = 0;
     const char *name = NULL;
     int ok;
 
@@ -630,6 +706,15 @@ Java_eu_nodepass_somewhere_quic_QuicConnection_nativeOpen(
         alpn_len > 255) {
         return 0;
     }
+    // A pin of the wrong length is refused here rather than truncated or
+    // padded. Either would produce a connection that verifies against
+    // something nobody asked for, which is worse than not connecting.
+    if (pin) {
+        pin_len = (*env)->GetArrayLength(env, pin);
+        if (pin_len != SHA256_DIGEST_LENGTH) {
+            return 0;
+        }
+    }
     (*env)->GetByteArrayRegion(env, local_ip, 0, local_len, local_buf);
     (*env)->GetByteArrayRegion(env, remote_ip, 0, remote_len, remote_buf);
     (*env)->GetByteArrayRegion(env, alpn, 0, alpn_len, alpn_buf);
@@ -643,6 +728,11 @@ Java_eu_nodepass_somewhere_quic_QuicConnection_nativeOpen(
     c->conn_ref.user_data = c;
     ngtcp2_ccerr_default(&c->last_error);
 
+    if (pin_len == SHA256_DIGEST_LENGTH) {
+        (*env)->GetByteArrayRegion(env, pin, 0, pin_len, (jbyte *)c->pin);
+        c->has_pin = 1;
+    }
+
     if (fill_addr(&c->local_addr, &c->local_addrlen, (uint8_t *)local_buf,
                   (size_t)local_len, local_port) != 0 ||
         fill_addr(&c->remote_addr, &c->remote_addrlen, (uint8_t *)remote_buf,
 
@@ -52,7 +52,33 @@ sealed interface CertificateVerification {
      */
     data class Pin(
         val sha256: String,
-    ) : CertificateVerification
+    ) : CertificateVerification {
+        /**
+         * The same value as bytes, for the carriers that compare it there.
+         *
+         * The TLS path compares hex strings because it has a certificate object
+         * to hash; the QUIC path hands 32 bytes across a JNI boundary to be
+         * compared in C. One conversion, here, so the two cannot disagree about
+         * what a pin is.
+         */
+        val bytes: ByteArray
+            get() =
+                ByteArray(sha256.length / 2) { index ->
+                    ((digit(sha256[index * 2]) shl 4) or digit(sha256[index * 2 + 1])).toByte()
+                }
+
+        private fun digit(character: Char): Int =
+            when (character) {
+                in '0'..'9' -> character - '0'
+                in 'a'..'f' -> character - 'a' + 10
+                in 'A'..'F' -> character - 'A' + 10
+                // Unreachable through the parser, which accepts lower-case hex
+                // of exactly the right length and nothing else. Stated rather
+                // than assumed, because a pin built by hand and silently
+                // mistranslated would verify against an arbitrary digest.
+                else -> throw IllegalStateException("a pin holds hex and nothing else")
+            }
+    }
 
     val isVerified: Boolean get() = this !is Skipped
 }