diff --git a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEvent.kt b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEvent.kt index e0af2e31..ae39b90a 100644 --- a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEvent.kt +++ b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEvent.kt @@ -12,6 +12,7 @@ import com.machankura.bennu.compose.nostr.frost.tags.FrostDerivationPathTag import com.machankura.bennu.compose.nostr.subgroup.tags.GuardianTag import com.machankura.bennu.compose.nostr.subgroup.tags.SubgroupKeyTag import com.machankura.bennu.compose.nostr.subgroup.tags.SubgroupParentTag +import com.machankura.bennu.compose.nostr.subgroup.tags.WalletPolicyTag /** * A group saying, with a quorum, that another group is its child. @@ -65,6 +66,15 @@ import com.machankura.bennu.compose.nostr.subgroup.tags.SubgroupParentTag * the key that check needs and nobody else needs it: the parent's quorum can * already spend through its own leaf whatever the others would let it. * + * ### The wallet policy + * + * A certificate may carry a [WalletPolicyTag]: the parent deciding whether the + * child's wallet is guarded or unguarded, rather than leaving it to the child -- + * `docs/subgroup-wallet-policy.md`. A guarded certificate carries the guardian + * keys and an unguarded one carries none, and [parseWalletPolicy] refuses one + * whose policy and keys disagree. Like the keys, the policy is not among the + * checks in [certifies]: it is read where it is used. + * * ### What [certifies] deliberately does not check * * The name and the `p` tags are the **founding** roster. A certificate is signed @@ -111,7 +121,8 @@ object SubgroupBirthCertificateEvent { adminPublicKeys: List, name: String, path: List = SharedKeyDerivation.MARMOT_ADMIN_GROUP_PATH, - guardians: List = emptyList() + guardians: List = emptyList(), + walletPolicy: SubgroupWalletPolicy? = null ): Array> = arrayOf( DTag.assemble(subgroupChatRoomId), SubgroupParentTag.assemble(parentChatRoomId), @@ -119,7 +130,35 @@ object SubgroupBirthCertificateEvent { FrostDerivationPathTag.assemble(path), arrayOf(NAME_TAG_NAME, name) ) + adminPublicKeys.distinct().map { PTag.assemble(it, null) } + - guardians.map(GuardianTag::assemble) + guardians.map(GuardianTag::assemble) + + listOfNotNull(walletPolicy?.let(WalletPolicyTag::assemble)) + + /** + * What the certificate says about the child's wallet: [WalletPolicyReading.Undecided] + * when it carries no policy, as every certificate from before policies does, + * and null when the reading cannot be used -- + * + * - a `wallet` tag that does not read, or two of them; + * - guardian keys that do not read; + * - a policy that contradicts the keys beside it: `guarded` with none, or + * `unguarded` with some. + * + * A certificate that says one thing in its policy and another in its keys is + * not a thing to guess the meaning of, and a policy present and unreadable + * must never read as absent -- that would hand the child the choice the + * parent took away. + */ + fun parseWalletPolicy(tags: Array>): WalletPolicyReading? { + val guardians = parseGuardians(tags) ?: return null + return when (val tag = WalletPolicyTag.parseOne(tags)) { + WalletPolicyTag.Result.Absent -> WalletPolicyReading.Undecided + WalletPolicyTag.Result.Unreadable -> null + is WalletPolicyTag.Result.Present -> when (tag.policy) { + SubgroupWalletPolicy.GUARDED -> WalletPolicyReading.Decided(tag.policy).takeIf { guardians.isNotEmpty() } + SubgroupWalletPolicy.UNGUARDED -> WalletPolicyReading.Decided(tag.policy).takeIf { guardians.isEmpty() } + } + } + } /** * The guardian keys the parent grants the child, nearest first -- empty for a diff --git a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupWalletPolicy.kt b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupWalletPolicy.kt new file mode 100644 index 00000000..37421d03 --- /dev/null +++ b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupWalletPolicy.kt @@ -0,0 +1,50 @@ +package com.machankura.bennu.compose.nostr.subgroup + +/** + * What a parent decided, at a subgroup's birth, about the subgroup's wallet -- + * `docs/subgroup-wallet-policy.md`. + * + * Chosen by the coordinator on the subgroup picker, carried on the ceremony + * proposal so every admin sees it before joining, and signed by the parent's + * quorum into the birth certificate. Every honest device then offers, signs, + * derives and watches only the wallet it allows. + * + * Not a rule the chain enforces: the child's key is the child's, and a quorum of + * modified clients can sign whatever it likes with it. It is the parent's signed + * decision, which every client running this app keeps. + */ +enum class SubgroupWalletPolicy(val tagValue: String) { + /** + * The child can only open a guarded wallet, and its certificate carries the + * guardian keys that wallet's leaves are built from. A guarded group's own + * subgroups are guarded too. + */ + GUARDED("guarded"), + + /** + * The child can only open a plain wallet. Its certificate carries no guardian + * keys, so nothing above it can reach its wallet or anything beneath it. + */ + UNGUARDED("unguarded"); + + companion object { + fun fromTagValue(value: String): SubgroupWalletPolicy? = entries.firstOrNull { it.tagValue == value } + } +} + +/** What a birth certificate says about the child's wallet. */ +sealed interface WalletPolicyReading { + /** The parent decided, and signed it. */ + data class Decided(val policy: SubgroupWalletPolicy) : WalletPolicyReading + + /** + * No policy tag: a certificate from before policies, which leaves the choice + * to the child -- a guarded wallet if its certificate carries keys, a plain + * one beside it either way. + */ + data object Undecided : WalletPolicyReading +} + +/** Whether this reading is the parent having decided [policy]. */ +fun WalletPolicyReading?.isDecided(policy: SubgroupWalletPolicy): Boolean = + (this as? WalletPolicyReading.Decided)?.policy == policy diff --git a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/tags/WalletPolicyTag.kt b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/tags/WalletPolicyTag.kt new file mode 100644 index 00000000..41048607 --- /dev/null +++ b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/nostr/subgroup/tags/WalletPolicyTag.kt @@ -0,0 +1,49 @@ +package com.machankura.bennu.compose.nostr.subgroup.tags + +import com.machankura.bennu.compose.nostr.subgroup.SubgroupWalletPolicy + +/** + * A subgroup's wallet policy, as its parent decided it: + * + * ``` + * ["wallet", "guarded" | "unguarded"] + * ``` + * + * On a key ceremony's proposal it is what the coordinator chose, shown to every + * admin before they join; on a birth certificate it is the parent's quorum + * signing that choice. See `SubgroupWalletPolicy` and + * `docs/subgroup-wallet-policy.md`. + * + * Shape only, as `GuardianTag` is. Whether a policy agrees with the guardian + * keys beside it is the certificate's question, not the tag's. + */ +object WalletPolicyTag { + const val TAG_NAME = "wallet" + + fun assemble(policy: SubgroupWalletPolicy): Array = arrayOf(TAG_NAME, policy.tagValue) + + /** The policy [tag] names, or null when it is not a wallet tag or names no policy this build knows. */ + fun parse(tag: Array): SubgroupWalletPolicy? { + if (tag.size < 2 || tag[0] != TAG_NAME) return null + return SubgroupWalletPolicy.fromTagValue(tag[1]) + } + + /** + * The policy [tags] carry: null for none, the policy for exactly one readable + * tag -- and [Unreadable] when a tag *named* `wallet` fails to read or there + * are two, so that a policy present and unreadable is never mistaken for one + * absent. + */ + fun parseOne(tags: Array>): Result { + val named = tags.filter { it.isNotEmpty() && it[0] == TAG_NAME } + if (named.isEmpty()) return Result.Absent + if (named.size > 1) return Result.Unreadable + return parse(named.single())?.let { Result.Present(it) } ?: Result.Unreadable + } + + sealed interface Result { + data object Absent : Result + data object Unreadable : Result + data class Present(val policy: SubgroupWalletPolicy) : Result + } +} diff --git a/composeApp/src/commonTest/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEventTest.kt b/composeApp/src/commonTest/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEventTest.kt index 0fbf30f5..f8380920 100644 --- a/composeApp/src/commonTest/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEventTest.kt +++ b/composeApp/src/commonTest/kotlin/com/machankura/bennu/compose/nostr/subgroup/SubgroupBirthCertificateEventTest.kt @@ -20,6 +20,7 @@ import com.machankura.bennu.compose.extensions.toHex import com.machankura.bennu.compose.managers.GuardianDerivation import com.machankura.bennu.compose.managers.SharedKeyDerivation import com.machankura.bennu.compose.nostr.subgroup.tags.GuardianTag +import com.machankura.bennu.compose.nostr.subgroup.tags.WalletPolicyTag /** * What a birth certificate is allowed to convince a member of. @@ -375,6 +376,75 @@ class SubgroupBirthCertificateEventTest { assertNull(SubgroupBirthCertificateEvent.parseGuardians(broken.toTypedArray())) } + @Test + fun `a guarded certificate carries its keys and reads as guarded`() { + val tags = policyTags(SubgroupWalletPolicy.GUARDED, guardians = grant()) + + assertEquals(WalletPolicyReading.Decided(SubgroupWalletPolicy.GUARDED), SubgroupBirthCertificateEvent.parseWalletPolicy(tags)) + assertEquals(grant(), SubgroupBirthCertificateEvent.parseGuardians(tags)) + } + + @Test + fun `an unguarded certificate carries no keys and reads as unguarded`() { + val tags = policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = emptyList()) + + assertEquals(WalletPolicyReading.Decided(SubgroupWalletPolicy.UNGUARDED), SubgroupBirthCertificateEvent.parseWalletPolicy(tags)) + assertEquals(emptyList(), SubgroupBirthCertificateEvent.parseGuardians(tags)) + } + + @Test + fun `a certificate from before policies reads as undecided, with keys or without`() { + assertEquals(WalletPolicyReading.Undecided, SubgroupBirthCertificateEvent.parseWalletPolicy(certificate().tags)) + assertEquals(WalletPolicyReading.Undecided, SubgroupBirthCertificateEvent.parseWalletPolicy(policyTags(null, guardians = grant()))) + } + + @Test + fun `a policy that contradicts its keys, or does not read, reads as nothing`() { + // Each of these must not fall back to undecided: that would hand the + // child the choice its parent took away. + val contradictions = mapOf( + "guarded with no keys" to policyTags(SubgroupWalletPolicy.GUARDED, guardians = emptyList()), + "unguarded with keys" to policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = grant()), + "two policies" to policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = emptyList()) + WalletPolicyTag.assemble(SubgroupWalletPolicy.UNGUARDED), + "an unknown policy" to policyTags(null, guardians = emptyList()) + arrayOf(WalletPolicyTag.TAG_NAME, "maybe"), + "an empty policy" to policyTags(null, guardians = emptyList()) + arrayOf(WalletPolicyTag.TAG_NAME), + ) + + contradictions.forEach { (what, tags) -> + assertNull(SubgroupBirthCertificateEvent.parseWalletPolicy(tags), "a certificate with $what was read") + } + } + + @Test + fun `a policy does not touch what a certificate certifies`() { + // Lineage stays six questions. A certificate whose policy reads as nothing + // is still the parent's word that the child is its child. + listOf( + policyTags(SubgroupWalletPolicy.GUARDED, guardians = grant()), + policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = emptyList()), + policyTags(SubgroupWalletPolicy.GUARDED, guardians = emptyList()), + ).forEach { tags -> + assertTrue(SubgroupBirthCertificateEvent.certifies(certificate(tags = tags), subgroupChatRoomId, parentChatRoomId)) + } + } + + private fun grant(): List = + GuardianDerivation.grant(parentMaterial.thresholdPublicKey.value.toHex(), parentChatRoomId, emptyList(), subgroupChatRoomId) + + private fun policyTags( + policy: SubgroupWalletPolicy?, + guardians: List, + ): Array> = SubgroupBirthCertificateEvent.assembleTags( + subgroupChatRoomId = subgroupChatRoomId, + parentChatRoomId = parentChatRoomId, + thresholdPublicKey = childKey, + adminPublicKeys = admins, + name = name, + path = path, + guardians = guardians, + walletPolicy = policy, + ) + private fun certificate( content: String = subgroupChatRoomId, tags: Array> = SubgroupBirthCertificateEvent.assembleTags(