RecoveryWords.kt

1package com.peachpasswords.vault23import org.bouncycastle.crypto.generators.HKDFBytesGenerator4import org.bouncycastle.crypto.digests.SHA256Digest5import org.bouncycastle.crypto.params.HKDFParameters6import java.math.BigInteger7import java.security.MessageDigest8import javax.crypto.spec.SecretKeySpec910private const val WORD_BITS = 1111private const val TOTAL_WORDS = 121213fun rootKeyToWords(rootKeyBytes: ByteArray): List<String> {14    require(rootKeyBytes.size == 32) { "root key must be 32 bytes" }15    val entropy16 = rootKeyBytes.copyOfRange(0, 16)16    val entropyHash = MessageDigest.getInstance("SHA-256").digest(entropy16)17    // Mask to a byte before the unsigned shift: a Byte >= 0x80 sign-extends to a18    // negative Int, so `toInt() ushr 4` would yield a 28-bit value, not the 4-bit19    // checksum. The browser reads a Uint8 (`recovery-words.ts:36`). Without the20    // mask, ~50% of root keys (SHA[0] >= 0x80) produce non-browser-parity words.21    val checksum = (entropyHash[0].toInt() and 0xff) ushr 42223    var bitsBig = BigInteger.ZERO24    for (i in 0 until 16) {25        bitsBig = bitsBig.shiftLeft(8).or(BigInteger.valueOf((rootKeyBytes[i].toInt() and 0xff).toLong()))26    }27    bitsBig = bitsBig.shiftLeft(4).or(BigInteger.valueOf(checksum.toLong()))2829    val words = ArrayList<String>(TOTAL_WORDS)30    for (i in 0 until TOTAL_WORDS) {31        val shift = (TOTAL_WORDS - 1 - i) * WORD_BITS32        val index = bitsBig.shiftRight(shift).and(BigInteger.valueOf(0x7ffL)).toInt()33        words += WORD_LIST[index]34    }35    return words36}3738fun wordsToRootKeyMaterial(words: List<String>): ByteArray {39    require(words.size == TOTAL_WORDS) { "exactly $TOTAL_WORDS words required" }4041    val indices = IntArray(words.size)42    for (i in words.indices) {43        val word = words[i].trim().lowercase()44        val index = WORD_LIST.indexOf(word)45        require(index >= 0) { "unknown word at position ${i + 1}: \"${words[i]}\"" }46        indices[i] = index47    }4849    var bitsBig = BigInteger.ZERO50    for (index in indices) {51        bitsBig = bitsBig.shiftLeft(WORD_BITS).or(BigInteger.valueOf(index.toLong()))52    }5354    val entropy = ByteArray(16)55    for (i in 0 until 16) {56        val byteShift = 124 - i * 857        entropy[i] = bitsBig.shiftRight(byteShift).and(BigInteger.valueOf(0xffL)).toByte()58    }5960    val storedChecksum = bitsBig.and(BigInteger.valueOf(0xFL)).toInt()61    val entropyHash = MessageDigest.getInstance("SHA-256").digest(entropy)62    // See rootKeyToWords: mask to a byte before the unsigned shift (browser parity).63    val computedChecksum = (entropyHash[0].toInt() and 0xff) ushr 464    require(storedChecksum == computedChecksum) { "invalid recovery words — checksum mismatch" }6566    return ByteArray(32).also { it.fill(0); System.arraycopy(entropy, 0, it, 0, entropy.size) }67}6869/**70 * Generate a random 32-byte root key and prove its words round-trip.71 *72 * The retry loop this used to carry existed only because the shipped word list73 * duplicated "abandon" at index 1, which made ~0.6% of keys undecodable. The74 * list is now the canonical 2048, so every key round-trips; the check stays as75 * an assertion because shipping a key whose words cannot be typed back is the76 * one failure this code must never allow.77 */78fun generateRecoverableRootKey(): ByteArray {79    val candidate = ByteArray(32).also(java.security.SecureRandom()::nextBytes)80    check(runCatching { wordsToRootKeyMaterial(rootKeyToWords(candidate)) }.isSuccess) {81        "generated a root key whose recovery words do not round-trip"82    }83    return candidate84}8586/** Lowercase, unseparated hex of [bytes] — the exact ASCII the browser wraps in the escrow. */87fun rootKeyToHex(bytes: ByteArray): String = bytes.joinToString("") { "%02x".format(it) }8889/** Inverse of [rootKeyToHex]; tolerant of upper/lower case. */90fun hexToRootKey(hex: String): ByteArray {91    require(hex.length % 2 == 0) { "odd-length hex" }92    return ByteArray(hex.length / 2) { i -> hex.substring(i * 2, i * 2 + 2).toInt(16).toByte() }93}9495fun deriveRecoveryKey(wordMaterial: ByteArray, salt: ByteArray): SecretKeySpec {96    val generator = HKDFBytesGenerator(SHA256Digest())97    generator.init(HKDFParameters(wordMaterial, salt, "peach-recovery-v1".encodeToByteArray()))98    val out = ByteArray(32)99    generator.generateBytes(out, 0, out.size)100    return SecretKeySpec(out, "AES")101}102103fun findInvalidWords(words: List<String>): List<Pair<Int, String>> {104    val invalid = ArrayList<Pair<Int, String>>()105    for (i in words.indices) {106        val w = words[i].trim().lowercase()107        if (w.isBlank() || WORD_LIST.indexOf(w) == -1) {108            invalid += i to words[i]109        }110    }111    return invalid112}113114fun getWordSuggestions(prefix: String, maxResults: Int = 5): List<String> {115    val p = prefix.trim().lowercase()116    if (p.length < 2) return emptyList()117    return WORD_LIST.filter { it.startsWith(p) }.take(maxResults)118}119120/**121 * BLAKE3 hash (hex) of the space-joined, trimmed, lowercased recovery words.122 * Stored in vault metadata so recovery-word entry can be verified without123 * persisting the words. Mirrors the browser's recovery-hash derivation.124 */125fun recoveryWordsHash(words: List<String>): String {126    val canonical = words.joinToString(" ") { it.trim().lowercase() }.encodeToByteArray()127    val digest = org.bouncycastle.crypto.digests.Blake3Digest(256)128    digest.update(canonical, 0, canonical.size)129    val out = ByteArray(32)130    digest.doFinal(out, 0)131    return out.joinToString("") { "%02x".format(it) }132}