feat(subgroup): the child's quorum holds its certificate to the policy it joined under (Phase 5)

SubgroupManager.refuseKeyState: a child signer refuses a key state whose
birth certificate decides a wallet policy other than the one its own
ceremony announced at the join gate -- undecided included. A ceremony
from an older build announced none and holds the certificate to nothing.
proposeSubgroupKeyState refuses the same thing before asking.

GroupKeyStateManager.parentageOf drops a state whose certificate's policy
does not read or contradicts its guardian keys, so a corrupt policy never
reads as undecided.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-10-23 22:02:49 +02:00
1 parent 44a15e9bc2
commit 52ca030c8b
5 files changed
+129 -2

No files matched your search

@@ -1,5 +1,6 @@
package com.machankura.bennu.compose.managers
import com.machankura.bennu.compose.nostr.frost.GroupKeyStateEvent
import fr.acinq.bitcoin.OutPoint
import com.machankura.bennu.compose.database.model.GroupTransaction
import com.machankura.bennu.compose.database.model.types.FrostSigningSubject
@@ -571,6 +572,22 @@ object FrostSigningManager {
}
}
// A subgroup's key state carries its birth certificate, and the
// certificate's wallet policy has to be the one this group was made
// under: every admin was shown it at the join gate, so joining was
// agreeing to it. A certificate proposed later, by a parent admin
// resuming the flow, under another one would be the child signing a
// decision none of its members agreed to. [key] is the child's own
// ceremony here, which is where the policy was filed.
// `docs/subgroup-wallet-policy.md`, Phase 5.
unsignedEvents.forEach { rebuilt ->
if (rebuilt.kind != GroupKeyStateEvent.KIND) return@forEach
SubgroupManager.refuseKeyState(key, rebuilt)?.let { reason ->
logger.w("Signing proposal $sessionId carries a key state that $reason; dropping")
return null
}
}
val session = FrostSigningSession(
id = sessionId,
chatRoomId = localChatRoom.chatRoom.id,
@@ -423,6 +423,19 @@ object GroupKeyStateManager {
return null
}
// A wallet policy present and unreadable must never look absent: an
// undecided child is offered both wallets, so a corrupt `guarded` would
// hand it the plain one its parent took away -- the lesson of
// [GroupKeyStateEvent.claimsParentage], one tag further on.
// `docs/subgroup-wallet-policy.md`.
if (SubgroupBirthCertificateEvent.parseWalletPolicy(certificate.tags) == null) {
logger.w(
"Key state for $announced carries a certificate whose wallet policy does not " +
"read, or contradicts its guardian keys; dropping"
)
return null
}
return Parentage(
SubgroupParentage(parentChatRoomId = parentChatRoomId, certificate = certificate)
)
@@ -1,5 +1,6 @@
package com.machankura.bennu.compose.managers
import com.machankura.bennu.compose.nostr.frost.GroupKeyStateEvent
import com.machankura.bennu.compose.database.model.subgroupWalletPolicy
import com.machankura.bennu.compose.nostr.subgroup.isDecided
import com.machankura.bennu.compose.nostr.subgroup.SubgroupWalletPolicy
@@ -477,6 +478,12 @@ object SubgroupManager {
"cannot name a parent yet"
)
// Every other child signer refuses a certificate under another policy, so
// proposing it would only stall a quorum -- see [refuseKeyState].
refusePolicy(key, certificate.toEvent())?.let { reason ->
throw IllegalStateException("$parentChatRoomId's certificate for $subgroupChatRoomId $reason")
}
return GroupKeyStateManager.propose(
database = database,
localChatRoom = ceremonyRoom,
@@ -490,6 +497,33 @@ object SubgroupManager {
)
}
/**
* Why a child signer should not sign [keyState] under [key], its own
* ceremony, or null when it may: the birth certificate it carries decides a
* wallet policy other than the one the ceremony announced.
*
* Every admin was shown that policy at the join gate, so joining was agreeing
* to it. A certificate proposed later under another -- by a parent admin
* resuming the flow, or one whose device read the parent differently -- would
* be the child signing a decision none of its members agreed to. A ceremony
* that announced none, from an older build, has nothing to hold the
* certificate to. `docs/subgroup-wallet-policy.md`, Phase 5.
*/
fun refuseKeyState(key: DkgSession, keyState: Event): String? {
val certificate = GroupKeyStateEvent.parseBirthCertificate(keyState.tags) ?: return null
return refusePolicy(key, certificate)
}
private fun refusePolicy(key: DkgSession, certificate: Event): String? {
val agreed = key.subgroupWalletPolicy ?: return null
val certified = SubgroupBirthCertificateEvent.parseWalletPolicy(certificate.tags)
return if (certified.isDecided(agreed)) {
null
} else {
"carries a certificate whose wallet policy is not the one this group was made under ($agreed)"
}
}
/**
* A subgroup as the parent's own record has it, plus whatever this device
* happens to hold about it.
@@ -1,5 +1,7 @@
package com.machankura.bennu.compose.managers
import com.machankura.bennu.compose.nostr.subgroup.tags.WalletPolicyTag
import com.machankura.bennu.compose.nostr.subgroup.SubgroupWalletPolicy
import com.vitorpamplona.quartz.nip10Notes.TextNoteEvent
import com.vitorpamplona.quartz.nip01Core.metadata.MetadataEvent
import com.vitorpamplona.quartz.nip65RelayList.AdvertisedRelayListEvent
@@ -764,7 +766,8 @@ class GroupKeyStateTest {
parent: String = parentChatRoomId,
subgroupKey: String = thresholdPublicKey,
certificatePath: List<Long> = path,
author: KeyMaterial = otherKeyMaterial
author: KeyMaterial = otherKeyMaterial,
extraTags: Array<Array<String>> = emptyArray()
): Event = signedByRoom(
kind = SubgroupBirthCertificateEvent.KIND,
content = subgroupChatRoomId,
@@ -775,7 +778,7 @@ class GroupKeyStateTest {
adminPublicKeys = listOf("a".repeat(64), "b".repeat(64), "c".repeat(64)),
name = "Translation team",
path = certificatePath
),
) + extraTags,
author = author
)
@@ -886,6 +889,31 @@ class GroupKeyStateTest {
assertNull(GroupKeyStateManager.stateFrom(chatRoomId, keyStateWithParent(certificate = wrongKey)))
}
@Test
fun `a state whose certificate's wallet policy does not read is dropped`() {
// Present and unreadable must not read as absent: an undecided child is
// offered both wallets, so a corrupt policy would hand it the one its
// parent took away. docs/subgroup-wallet-policy.md, Phase 5.
listOf(
arrayOf(arrayOf("wallet", "maybe")),
arrayOf(WalletPolicyTag.assemble(SubgroupWalletPolicy.GUARDED)),
arrayOf(WalletPolicyTag.assemble(SubgroupWalletPolicy.UNGUARDED), WalletPolicyTag.assemble(SubgroupWalletPolicy.UNGUARDED)),
).forEach { extraTags ->
assertNull(
GroupKeyStateManager.stateFrom(chatRoomId, keyStateWithParent(certificate = birthCertificate(extraTags = extraTags))),
"a certificate with ${extraTags.joinToString { it.joinToString() }} was believed",
)
}
}
@Test
fun `a state whose certificate decides a wallet policy keeps it`() {
val unguarded = birthCertificate(extraTags = arrayOf(WalletPolicyTag.assemble(SubgroupWalletPolicy.UNGUARDED)))
val state = GroupKeyStateManager.stateFrom(chatRoomId, keyStateWithParent(certificate = unguarded))
assertEquals(unguarded.toJson(), state?.birthCertificateJson)
}
@Test
fun `a parentage survives the trip through the tags`() {
val certificate = birthCertificate()
@@ -1,5 +1,7 @@
package com.machankura.bennu.compose.managers
import com.machankura.bennu.compose.nostr.subgroup.SubgroupParentage
import com.machankura.bennu.compose.nostr.frost.GroupKeyStateEvent
import com.machankura.bennu.compose.nostr.subgroup.tags.WalletPolicyTag
import com.machankura.bennu.compose.nostr.subgroup.WalletPolicyReading
import com.machankura.bennu.compose.nostr.subgroup.SubgroupWalletPolicy
@@ -716,6 +718,39 @@ class SubgroupManagerJvmTest {
)
}
/** A child key state carrying [certificate], unsigned -- the refusal reads its tags and nothing else. */
private fun keyStateCarrying(certificate: Event) = Event(
id = "e".repeat(64),
pubKey = childRoomId,
createdAt = 1_700_000_000,
kind = GroupKeyStateEvent.KIND,
tags = GroupKeyStateEvent.assembleTags(
chatRoomId = childRoomId,
dkgSessionId = "child-ceremony",
path = path,
parent = SubgroupParentage(parentRoomId, certificate),
),
content = "",
sig = "",
)
@Test
fun `a child signer refuses a certificate under a policy its ceremony did not announce`(): Unit = runBlocking {
val parentRoom = parentWith(listOf(alice, bob))
val unguarded = proposedCertificate(parentRoom, ceremonyUnder(SubgroupWalletPolicy.UNGUARDED))
val guarded = proposedCertificate(parentRoom, ceremonyUnder(SubgroupWalletPolicy.GUARDED))
val undecided = proposedCertificate(parentRoom, ceremonyUnder(null))
// The admins joined a guarded subgroup.
val ceremony = ceremonyUnder(SubgroupWalletPolicy.GUARDED)
assertNotNull(SubgroupManager.refuseKeyState(ceremony, keyStateCarrying(unguarded)))
assertNotNull(SubgroupManager.refuseKeyState(ceremony, keyStateCarrying(undecided)), "undecided is not what they agreed to either")
assertNull(SubgroupManager.refuseKeyState(ceremony, keyStateCarrying(guarded)))
// An older build's ceremony announced nothing, and has nothing to hold a certificate to.
assertNull(SubgroupManager.refuseKeyState(ceremonyUnder(null), keyStateCarrying(unguarded)))
}
// ---- fixtures ----------------------------------------------------------
/** The certificate [parentRoom] is asked to sign for the child, as the session holds it. */