From 9ea4b81c1f9692d6c234ca779c69e140738b49f3 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 1 Aug 2026 00:14:17 +0000 Subject: [PATCH] feat(quartz): size-enforcing Hex.decode64/128 and encode64/128 Adds exact-size codec entry points to the Hex utility so 32-byte pubkeys/event ids (64 chars) and 64-byte signatures (128 chars) with the wrong size or invalid characters are rejected instead of silently decoded: - decode64 / decode128 throw IllegalArgumentException; the OrNull variants return null for untrusted input. - encode64 / encode128 require exactly 32 / 64 input bytes. The decode is single-pass: character validation is folded into the decode loop via a sign-bit OR-accumulator (the lookup table yields -1 for invalid chars), so it is faster than the isHex64 + decode two-pass combination. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Hwv6XwT9mwGUQc57zH4ky4 --- .../com/vitorpamplona/quartz/utils/Hex.kt | 70 +++++++++++ .../quartz/utils/HexExactSizeTest.kt | 113 ++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/utils/HexExactSizeTest.kt diff --git a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Hex.kt b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Hex.kt index 49137ac8aa..18f457d6d1 100644 --- a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Hex.kt +++ b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Hex.kt @@ -36,6 +36,8 @@ package com.vitorpamplona.quartz.utils * val hex = Hex.encode(bytes) // ByteArray -> lower-case hex * val bytes = Hex.decode(hex) // hex (any case) -> ByteArray * if (Hex.isHex64(id)) { ... } // is this a valid 32-byte hex id? + * val id = Hex.decode64(idHex) // exactly 64 chars or it throws + * val sig = Hex.decode128OrNull(sigHex) // exactly 128 chars or null * ``` */ object Hex { @@ -188,6 +190,74 @@ object Hex { } } + /** + * Decodes a 32-byte pubkey/event id, accepting only exactly 64 hex chars + * (upper or lower case). Throws [IllegalArgumentException] on any other + * length or on non-hex characters — use [decode64OrNull] for untrusted + * input. Single pass: validation is folded into the decode, so this is + * faster than `isHex64` + [decode]. + */ + fun decode64(hex: String): ByteArray = decode64OrNull(hex) ?: throw IllegalArgumentException("Invalid 64-char hex $hex") + + /** Like [decode64] but returns null instead of throwing. */ + fun decode64OrNull(hex: String): ByteArray? = if (hex.length == 64) decodeExactOrNull(hex, 32) else null + + /** + * Decodes a 64-byte value (a Schnorr signature), accepting only exactly + * 128 hex chars (upper or lower case). Throws [IllegalArgumentException] + * on any other length or on non-hex characters — use [decode128OrNull] + * for untrusted input. + */ + fun decode128(hex: String): ByteArray = decode128OrNull(hex) ?: throw IllegalArgumentException("Invalid 128-char hex $hex") + + /** Like [decode128] but returns null instead of throwing. */ + fun decode128OrNull(hex: String): ByteArray? = if (hex.length == 128) decodeExactOrNull(hex, 64) else null + + /** + * Decodes [hex] into [byteLen] bytes, or null if any char is not a hex + * digit. The caller has already checked `hex.length == 2 * byteLen`. + * Validation is free: the lookup table yields -1 for invalid chars, which + * keeps the OR-accumulator negative, so one sign check at the end covers + * every char with no branches inside the loop. + */ + private fun decodeExactOrNull( + hex: String, + byteLen: Int, + ): ByteArray? = + try { + val out = ByteArray(byteLen) + var acc = 0 + var c = 0 + for (i in 0 until byteLen) { + val b = (hexToByte[hex[c++].code] shl 4) or hexToByte[hex[c++].code] + acc = acc or b + out[i] = b.toByte() + } + if (acc < 0) null else out + } catch (_: IndexOutOfBoundsException) { + // chars above 0xFF (e.g. emoji) fall outside the lookup table + null + } + + /** + * Encodes a 32-byte pubkey/event id as a 64-char lower-case hex string. + * Throws [IllegalArgumentException] when [input] is not exactly 32 bytes. + */ + fun encode64(input: ByteArray): String { + require(input.size == 32) { "Expected 32 bytes, got ${input.size}" } + return encode(input) + } + + /** + * Encodes a 64-byte value (a Schnorr signature) as a 128-char lower-case + * hex string. Throws [IllegalArgumentException] when [input] is not + * exactly 64 bytes. + */ + fun encode128(input: ByteArray): String { + require(input.size == 64) { "Expected 64 bytes, got ${input.size}" } + return encode(input) + } + /** Encodes [input] as a lower-case hex string (two chars per byte). */ fun encode(input: ByteArray): String { val out = CharArray(input.size * 2) diff --git a/quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/utils/HexExactSizeTest.kt b/quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/utils/HexExactSizeTest.kt new file mode 100644 index 0000000000..2b9f4a5c94 --- /dev/null +++ b/quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/utils/HexExactSizeTest.kt @@ -0,0 +1,113 @@ +/* + * 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.quartz.utils + +import kotlin.test.Test +import kotlin.test.assertContentEquals +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith +import kotlin.test.assertNull + +class HexExactSizeTest { + val id64 = "48a72b485d38338627ec9d427583551f9af4f016c739b8ec0d6313540a8b12cf" + val sig128 = id64 + "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9" + + @Test + fun decode64RoundTrip() { + assertEquals(id64, Hex.encode64(Hex.decode64(id64))) + assertContentEquals(Hex.decode(id64), Hex.decode64(id64)) + assertContentEquals(Hex.decode(id64), Hex.decode64OrNull(id64)) + } + + @Test + fun decode64AcceptsUpperCase() { + assertContentEquals(Hex.decode(id64), Hex.decode64(id64.uppercase())) + } + + @Test + fun decode64RejectsWrongLengths() { + assertFailsWith { Hex.decode64("") } + assertFailsWith { Hex.decode64(id64.drop(1)) } + assertFailsWith { Hex.decode64(id64.drop(2)) } + assertFailsWith { Hex.decode64(id64 + "ab") } + assertFailsWith { Hex.decode64(sig128) } + + assertNull(Hex.decode64OrNull("")) + assertNull(Hex.decode64OrNull(id64.drop(2))) + assertNull(Hex.decode64OrNull(id64 + "ab")) + assertNull(Hex.decode64OrNull(sig128)) + } + + @Test + fun decode64RejectsInvalidChars() { + // every position, both a plain non-hex char and an emoji (code > 0xFF) + for (i in 0 until 64) { + val withG = id64.substring(0, i) + "g" + id64.substring(i + 1) + assertNull(Hex.decode64OrNull(withG), withG) + assertFailsWith { Hex.decode64(withG) } + } + val withEmoji = "🥰" + id64.drop(2) + assertNull(Hex.decode64OrNull(withEmoji)) + assertFailsWith { Hex.decode64(withEmoji) } + } + + @Test + fun decode128RoundTrip() { + assertEquals(sig128, Hex.encode128(Hex.decode128(sig128))) + assertContentEquals(Hex.decode(sig128), Hex.decode128(sig128)) + assertContentEquals(Hex.decode(sig128), Hex.decode128OrNull(sig128.uppercase())) + } + + @Test + fun decode128RejectsWrongLengthsAndInvalidChars() { + assertFailsWith { Hex.decode128("") } + assertFailsWith { Hex.decode128(id64) } + assertFailsWith { Hex.decode128(sig128.drop(2)) } + assertFailsWith { Hex.decode128(sig128 + "ab") } + + assertNull(Hex.decode128OrNull(id64)) + assertNull(Hex.decode128OrNull(sig128.dropLast(1) + "x")) + assertNull(Hex.decode128OrNull("🥰" + sig128.drop(2))) + } + + @Test + fun encodeRejectsWrongSizes() { + assertFailsWith { Hex.encode64(ByteArray(31)) } + assertFailsWith { Hex.encode64(ByteArray(33)) } + assertFailsWith { Hex.encode64(ByteArray(64)) } + assertFailsWith { Hex.encode128(ByteArray(32)) } + assertFailsWith { Hex.encode128(ByteArray(63)) } + assertFailsWith { Hex.encode128(ByteArray(65)) } + } + + @Test + fun randomsMatchGenericDecode() { + for (i in 0..1000) { + val id = RandomInstance.bytes(32) + assertEquals(Hex.encode(id), Hex.encode64(id)) + assertContentEquals(id, Hex.decode64(Hex.encode64(id))) + + val sig = RandomInstance.bytes(64) + assertEquals(Hex.encode(sig), Hex.encode128(sig)) + assertContentEquals(sig, Hex.decode128(Hex.encode128(sig))) + } + } +}