test(quic-interop): unit-test SslKeyLogger + ship runner snippet

Refactors SslKeyLogger to take the ClientHello random at flush() time
(removes the lookup-lambda + bindConnection ceremony) so the formatter
is testable without spinning up a real QuicConnection. Adds three
unit tests covering: the four NSS Key Log lines emitted in the right
order, flush idempotency, and lower-case hex encoding.

Also drops a checked-in implementations.json snippet
(quic-interop-runner-snippet.json) so a sibling clone of the runner
can be registered with one jq merge instead of hand-edited JSON.

https://claude.ai/code/session_01HcvfQq1ttPV9PkRoJb4nyT

quic/interop/build.gradle.kts

@@ -36,11 +36,16 @@ sourceSets {
     main {
         kotlin.srcDir("src/main/kotlin")
     }
+    test {
+        kotlin.srcDir("src/test/kotlin")
+    }
 }
 
 dependencies {
     implementation(project(":quic"))
     implementation(libs.kotlinx.coroutines.core)
+
+    testImplementation(libs.kotlin.test)
 }
 
 application {

quic/interop/plans/2026-05-06-interop-runner.md

@@ -30,14 +30,13 @@ reorder / migration scenarios that are awkward to reproduce in unit tests.
 # In our repo:
 make -C quic/interop build
 
-# In a sibling clone of quic-interop-runner, add to implementations.json:
+# In a sibling clone of quic-interop-runner, merge our entry into
-"amethyst": {
+# implementations.json (snippet checked in at quic/interop/quic-interop-runner-snippet.json):
-    "image": "amethyst-quic-interop:latest",
+jq -s '.[0] * .[1]' implementations.json \
-    "url":   "https://github.com/vitorpamplona/amethyst",
+   ../amethyst/quic/interop/quic-interop-runner-snippet.json \
-    "role":  "client"
+   > implementations.json.new && mv implementations.json.new implementations.json
-}
 
-python run.py -d -i amethyst -s aioquic -t handshake --log-dir ./logs
+python run.py -d -i amethyst -s aioquic -t handshake,chacha20 --log-dir ./logs
 ```
 
 Inspect `./logs/<run>/client_qlog/*.qlog` in qvis when something breaks.

quic/interop/quic-interop-runner-snippet.json

@@ -0,0 +1,7 @@
+{
+  "amethyst": {
+    "image": "amethyst-quic-interop:latest",
+    "url": "https://github.com/vitorpamplona/amethyst",
+    "role": "client"
+  }
+}

quic/interop/src/main/kotlin/com/vitorpamplona/quic/interop/runner/InteropClient.kt

@@ -125,9 +125,6 @@ private fun runHandshakeTest(
                             ),
                     extraSecretsListener = keyLogger?.listener,
                 )
-            // clientRandom is null until QuicConnection.start() runs the TLS
-            // state machine, so the logger reads it lazily during flush().
-            keyLogger?.bindConnection(conn)
             val driver = QuicConnectionDriver(conn, socket, scope)
             driver.start()
 
@@ -142,7 +139,7 @@ private fun runHandshakeTest(
                     else -> "failed: ${handshake.exceptionOrNull()?.message ?: "?"}"
                 }
             runCatching { driver.close() }
-            keyLogger?.flush()
+            conn.tls.clientRandom?.let { keyLogger?.flush(it) }
             delay(50)
             result
         }
@@ -179,10 +176,9 @@ private fun parseFirstTarget(requests: String): Pair<String, Int>? {
  *   CLIENT_TRAFFIC_SECRET_0 <client_random_hex> <secret_hex>
  *   SERVER_TRAFFIC_SECRET_0 <client_random_hex> <secret_hex>
  */
-private class SslKeyLogger(
+internal class SslKeyLogger(
     private val file: File,
 ) {
-    private var clientRandomLookup: (() -> ByteArray?)? = null
     private val pending = mutableListOf<Pair<String, ByteArray>>()
 
     val listener: TlsSecretsListener =
@@ -208,13 +204,8 @@ private class SslKeyLogger(
             override fun onHandshakeComplete() = Unit
         }
 
-    fun bindConnection(conn: QuicConnection) {
+    fun flush(clientRandom: ByteArray) {
-        clientRandomLookup = { conn.tls.clientRandom }
+        val randomHex = clientRandom.toHex()
-    }
-
-    fun flush() {
-        val random = clientRandomLookup?.invoke() ?: return
-        val randomHex = random.toHex()
         file.parentFile?.mkdirs()
         file.appendText(
             buildString {
@@ -232,7 +223,7 @@ private class SslKeyLogger(
     }
 }
 
-private fun ByteArray.toHex(): String =
+internal fun ByteArray.toHex(): String =
     buildString(size * 2) {
         for (b in this@toHex) {
             val v = b.toInt() and 0xff

quic/interop/src/test/kotlin/com/vitorpamplona/quic/interop/runner/SslKeyLoggerTest.kt

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quic.interop.runner
+
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class SslKeyLoggerTest {
+    @Test
+    fun `emits NSS Key Log lines for handshake and application secrets`() {
+        val tmp = File.createTempFile("ssl-keylog-test", ".log").also { it.deleteOnExit() }
+        val logger = SslKeyLogger(tmp)
+
+        logger.listener.onHandshakeKeysReady(
+            cipherSuite = 0x1301,
+            clientSecret = ByteArray(32) { 0xAA.toByte() },
+            serverSecret = ByteArray(32) { 0xBB.toByte() },
+        )
+        logger.listener.onApplicationKeysReady(
+            cipherSuite = 0x1301,
+            clientSecret = ByteArray(32) { 0xCC.toByte() },
+            serverSecret = ByteArray(32) { 0xDD.toByte() },
+        )
+
+        val clientRandom = ByteArray(32) { it.toByte() }
+        logger.flush(clientRandom)
+
+        val lines =
+            tmp
+                .readText()
+                .lineSequence()
+                .filter { it.isNotEmpty() }
+                .toList()
+        assertEquals(4, lines.size, "one line per secret")
+
+        val randomHex = clientRandom.toHex()
+        val expectedClientHs = "CLIENT_HANDSHAKE_TRAFFIC_SECRET $randomHex ${ByteArray(32) { 0xAA.toByte() }.toHex()}"
+        val expectedServerHs = "SERVER_HANDSHAKE_TRAFFIC_SECRET $randomHex ${ByteArray(32) { 0xBB.toByte() }.toHex()}"
+        val expectedClientApp = "CLIENT_TRAFFIC_SECRET_0 $randomHex ${ByteArray(32) { 0xCC.toByte() }.toHex()}"
+        val expectedServerApp = "SERVER_TRAFFIC_SECRET_0 $randomHex ${ByteArray(32) { 0xDD.toByte() }.toHex()}"
+
+        assertEquals(expectedClientHs, lines[0])
+        assertEquals(expectedServerHs, lines[1])
+        assertEquals(expectedClientApp, lines[2])
+        assertEquals(expectedServerApp, lines[3])
+    }
+
+    @Test
+    fun `flush is idempotent — second flush emits nothing`() {
+        val tmp = File.createTempFile("ssl-keylog-test", ".log").also { it.deleteOnExit() }
+        val logger = SslKeyLogger(tmp)
+
+        logger.listener.onHandshakeKeysReady(
+            cipherSuite = 0x1301,
+            clientSecret = ByteArray(32) { 1 },
+            serverSecret = ByteArray(32) { 2 },
+        )
+        logger.flush(ByteArray(32))
+        val firstLen = tmp.length()
+
+        logger.flush(ByteArray(32))
+        assertEquals(firstLen, tmp.length(), "second flush must not append")
+    }
+
+    @Test
+    fun `toHex round-trips lowercase`() {
+        val bytes = byteArrayOf(0x00, 0x0f, 0x10.toByte(), 0xff.toByte())
+        assertEquals("000f10ff", bytes.toHex())
+        assertTrue(bytes.toHex().all { it.isDigit() || it in 'a'..'f' })
+    }
+}