feat(subgroup): a birth certificate can carry its child's wallet policy (Phase 1)
SubgroupWalletPolicy and WalletPolicyTag, ["wallet", "guarded"|"unguarded"], and SubgroupBirthCertificateEvent.parseWalletPolicy. A certificate with no tag reads Undecided; one whose tag does not read, or contradicts the guardian keys beside it, reads null rather than undecided. certifies is unchanged. Nothing writes the tag yet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
fed7e67c3d
commit
f19001cd61
4 files changed
+210
-2
No files matched your search
+41
-2
@@ -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<HexKey>,
|
||||
name: String,
|
||||
path: List<Long> = SharedKeyDerivation.MARMOT_ADMIN_GROUP_PATH,
|
||||
guardians: List<GuardianDerivation.Guardian> = emptyList()
|
||||
guardians: List<GuardianDerivation.Guardian> = emptyList(),
|
||||
walletPolicy: SubgroupWalletPolicy? = null
|
||||
): Array<Array<String>> = 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<Array<String>>): 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
|
||||
|
||||
+50
@@ -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
|
||||
+49
@@ -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<String> = 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<String>): 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<Array<String>>): 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
|
||||
}
|
||||
}
|
||||
+70
@@ -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.Guardian> =
|
||||
GuardianDerivation.grant(parentMaterial.thresholdPublicKey.value.toHex(), parentChatRoomId, emptyList(), subgroupChatRoomId)
|
||||
|
||||
private fun policyTags(
|
||||
policy: SubgroupWalletPolicy?,
|
||||
guardians: List<GuardianDerivation.Guardian>,
|
||||
): Array<Array<String>> = 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<Array<String>> = SubgroupBirthCertificateEvent.assembleTags(
|
||||
|
||||
Reference in new issue
Block a user