Fix #180: backfill fingerprints file on first verify when cert exists but no known fingerprints

Devices provisioned before fingerprint recording (pre-#111) have a valid
leaf cert on disk but an empty known-fingerprints set. Under the prior
behavior, the very first SecurityCheckWorker run trips a SelfCert Alert,
SecurityCheckPreferences flips selfCertResult to "alert", and
McpRouting.rejectIfSecurityAlert() returns 503 on every Ktor route --
OAuth and MCP are fully blocked. Acknowledging in the UI clears the
preference, but the next worker run re-alerts, so lockout is permanent
until the fingerprints file is hand-written.

Fix: when knownFingerprints is empty AND a leaf cert is presented,
treat it as trusted-on-first-sight and write its SHA-256 to the store
via storeFingerprint(). Subsequent runs take the normal matching path.
Only a truly empty set triggers backfill -- non-empty but mismatched
(including corrupt/garbage) still Alerts so real tamper signal is
preserved. If the backfill write itself fails, degrade to Warning
rather than Alert, matching the existing store-I/O-error policy.

The change is a property of the verifier only. Cert provisioning and
renewal flows are unchanged. If TLS itself was compromised before the
very first verify, the fingerprints file was never the weak link.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jason Monk 2026-04-16 16:38:16 -04:00
parent d1848db4a1
commit cecd4349e7
2 changed files with 90 additions and 7 deletions

View file

@ -12,6 +12,16 @@ import java.security.MessageDigest
*
* If the store is unreachable (I/O error), the result is a [SecurityCheckResult.Warning]
* rather than an [SecurityCheckResult.Alert], since the check could not be completed.
*
* Upgrade path (issue #180): devices provisioned before fingerprint recording
* (pre-#111) have a valid leaf cert on disk but an empty known-fingerprints set.
* Without self-healing, the very first periodic check would trip an Alert,
* lock every HTTPS route into 503, and "Acknowledge" in the UI would not stick
* because the next worker run re-alerts. On a completely empty set we treat the
* presented leaf as trusted-on-first-sight and backfill the store; subsequent
* runs then take the normal matching path. This is a property of the verifier
* only -- the cert-provisioning flow is unchanged. If TLS itself was compromised
* before the very first verify, the fingerprint file was never the weak link.
*/
class SelfCertVerifier(private val certificateStore: CertificateStore) {
@ -33,18 +43,31 @@ class SelfCertVerifier(private val certificateStore: CertificateStore) {
)
}
val leafDer = certChainDer.first()
val leafFingerprint = sha256Fingerprint(leafDer)
val leafFingerprint = sha256Fingerprint(certChainDer.first())
return if (knownFingerprints.contains(leafFingerprint)) {
SecurityCheckResult.Verified
} else {
SecurityCheckResult.Alert(
"Leaf certificate fingerprint $leafFingerprint does not match any known fingerprint"
return when {
knownFingerprints.contains(leafFingerprint) -> SecurityCheckResult.Verified
// Trust-on-first-sight backfill for pre-#111 installs whose fingerprints
// file never got written. Only applies when the set is truly empty --
// any non-empty set (including corrupt/garbage entries) must still
// Alert so a real tamper signal is preserved.
knownFingerprints.isEmpty() -> backfillAndVerify(leafFingerprint)
else -> SecurityCheckResult.Alert(
"Leaf certificate fingerprint $leafFingerprint " +
"does not match any known fingerprint"
)
}
}
private suspend fun backfillAndVerify(leafFingerprint: String): SecurityCheckResult = try {
certificateStore.storeFingerprint(leafFingerprint)
SecurityCheckResult.Verified
} catch (e: Exception) {
SecurityCheckResult.Warning(
"Could not backfill missing fingerprint: ${e.message}"
)
}
companion object {
/** Compute the colon-separated uppercase hex SHA-256 fingerprint of DER-encoded cert bytes. */
fun sha256Fingerprint(der: ByteArray): String {

View file

@ -3,6 +3,7 @@ package com.rousecontext.tunnel
import java.security.MessageDigest
import java.security.cert.X509Certificate
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertIs
import kotlinx.coroutines.runBlocking
@ -122,6 +123,65 @@ class SelfCertVerifierTest {
assertIs<SecurityCheckResult.Verified>(result)
}
@Test
fun `empty known fingerprints with valid cert - backfills and verifies (issue 180)`(): Unit =
runBlocking {
// Simulates the upgrade path from a pre-#111 build: a provisioned leaf
// cert is on disk but rouse_fingerprints.txt is missing/empty. Without
// self-healing this would be permanent Alert -> 503 lockout.
val cert = generateSelfSignedCert()
val backing = mutableSetOf<String>()
val store = SecurityCertificateStore(
certChain = listOf(cert.encoded),
knownFingerprints = backing
)
val verifier = SelfCertVerifier(store)
val result = verifier.verify(listOf(cert.encoded))
assertIs<SecurityCheckResult.Verified>(result)
val expectedFingerprint = sha256Hex(cert.encoded)
assertEquals(setOf(expectedFingerprint), backing)
// Second call must also be Verified using the backfilled fingerprint,
// confirming persistence not just in-memory evaluation.
assertIs<SecurityCheckResult.Verified>(verifier.verify(listOf(cert.encoded)))
}
@Test
fun `empty known fingerprints does not backfill when chain is empty`(): Unit = runBlocking {
val backing = mutableSetOf<String>()
val store = SecurityCertificateStore(
certChain = null,
knownFingerprints = backing
)
val verifier = SelfCertVerifier(store)
val result = verifier.verify(emptyList())
assertIs<SecurityCheckResult.Alert>(result)
assertEquals(emptySet<String>(), backing)
}
@Test
fun `garbage fingerprints content - still alerts on mismatch (no backfill)`(): Unit =
runBlocking {
// Non-empty but corrupt/garbage fingerprints must NOT silently pass.
// Only a truly empty set triggers trust-on-first-sight backfill.
val cert = generateSelfSignedCert()
val backing = mutableSetOf("not-a-real-fingerprint", "###garbage###")
val store = SecurityCertificateStore(
certChain = listOf(cert.encoded),
knownFingerprints = backing
)
val verifier = SelfCertVerifier(store)
val result = verifier.verify(listOf(cert.encoded))
assertIs<SecurityCheckResult.Alert>(result)
// The garbage entries must remain; we must not overwrite existing state.
assertEquals(setOf("not-a-real-fingerprint", "###garbage###"), backing)
}
}
/**