feat: an admin of a keyed room steps down by asking another admin

An admin's own row had no menu in a keyed room: stepping down was not
offered, because a demotion's proposer starts the rotation that takes
the demoted admin's share away, and a rotation's proposer has to keep a
share.

Step down as admin now sends a request into the room
(PromotionEvents.STEP_DOWN, 30377) and commits nothing. The remaining
admin in the lowest leaf (AdminGovernance.stepDownProposer) -- one
device, named the same everywhere, so two never propose at one epoch --
takes it up in GovernanceFollowThrough and runs the same demote its own
Remove as admin would. A request is used once, and dropped by every
device once its requester is no longer an admin. Offered only above the
floor and while another admin is there to ask.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-11-20 09:44:26 +02:00
1 parent 1ccd8c7f09
commit bb35d73c28
12 files changed
+218 -14

No files matched your search

@@ -117,6 +117,8 @@
<string name="step_down_title">Step down as admin?</string>
<string name="step_down_body">You stay in the group as a member. Only an admin can make you one again.</string>
<string name="step_down">Step down</string>
<string name="step_down_body_keyed">You stay in the group as a member. Another admin's Giza proposes it for the group to sign, and your share of the group's key is rotated away once it's done.</string>
<string name="step_down_requested">Asked the other admins; it happens once the group signs it</string>
<string name="admin_change_requested">Sent; it takes effect once a relay accepts it</string>
<string name="leave_as_admin_title">Leave the group?</string>
<string name="step_down_and_leave_body">You're an admin, so you'll step down first, then leave once a relay accepts it.</string>
@@ -983,13 +983,16 @@ abstract class MarmotOutboundDao(
// away once it lands (docs/member-admin-promotion.md, Phase 9).
if (AdminGovernance.isKeyedRoom(group)) {
check(AdminGovernance.keyedChangesAllowed(group)) { KEYED_ROOM_REFUSAL }
check(adminPublicKey != localChatRoom.chatRoom.userPublicKey) {
"In a group with a shared key, another admin removes you as admin, so the group can rotate your share away"
}
val floor = AdminGovernance.adminFloor(database, localChatRoom.chatRoom.id, group)
if (!AdminGovernance.keepsFloor(group, adminPublicKey, floor)) {
throw IllegalStateException("A group with a shared key needs at least $floor admins. Make someone else an admin first")
}
// Your own: asked of another admin, whose device proposes it and then
// rotates your share away -- a rotation's proposer has to keep a share.
if (adminPublicKey == localChatRoom.chatRoom.userPublicKey) {
PromotionManager.requestStepDown(database, localChatRoom, adminPublicKey)
return
}
val admins = group.currentAdminIdentities()
GovernanceManager.propose(
database, localChatRoom, localChatRoom.chatRoom.userPublicKey,
@@ -3,7 +3,9 @@ package mobi.giza.compose.managers
import com.vitorpamplona.marmot.groups.MarmotGroupPermissions
import com.vitorpamplona.marmot.groups.currentAdminIdentities
import com.vitorpamplona.mls.group.MlsGroup
import com.vitorpamplona.mls.tree.Credential
import com.vitorpamplona.quartz.nip01Core.core.HexKey
import com.vitorpamplona.quartz.nip01Core.core.toHexKey
import mobi.giza.compose.ExperimentalFeatures
import mobi.giza.compose.database.GizaDatabase
import mobi.giza.compose.database.model.types.DkgRitualStage
@@ -96,6 +98,35 @@ object AdminGovernance {
fun keyedChangesAllowed(group: MlsGroup): Boolean =
isKeyedRoom(group) && GovernanceGate.isGoverned(group) && ExperimentalFeatures.shareRefresh
/**
* Whether [me] may ask to stop being an admin of keyed room [group]. They cannot
* demote themselves: a demotion's proposer starts the rotation that takes their
* share away, and the proposer has to keep a share. So they ask, and
* [stepDownProposer]'s device proposes it. Never below [floor], and only while
* another admin is there to ask.
*/
fun canAskToStepDown(group: MlsGroup, me: HexKey, floor: Int): Boolean =
keyedChangesAllowed(group) &&
me in group.currentAdminIdentities() &&
keepsFloor(group, me, floor) &&
stepDownProposer(group, me) != null
/**
* The admin whose device proposes [requester]'s step-down: the one in the lowest
* leaf, [requester] apart. Read off the group's state, so every device names the
* same one and only one of them proposes -- two proposals at one epoch would be
* two commits the library cannot settle for their authors (docs/marmot-v2.md,
* Phase 8). Null when nobody else is an admin.
*/
fun stepDownProposer(group: MlsGroup, requester: HexKey): HexKey? {
val admins = group.currentAdminIdentities() - requester
return group.members()
.sortedBy { (leafIndex, _) -> leafIndex }
.firstNotNullOfOrNull { (_, leaf) ->
(leaf.credential as? Credential.Basic)?.identity?.toHexKey()?.takeIf { it in admins }
}
}
/**
* What [me] may do to each member of [group], for the member rows' menus. Empty
* when [me] does not govern the room. Removal stays offered in a keyed room,
@@ -107,7 +138,7 @@ object AdminGovernance {
return members(group).associateWith { member ->
buildSet {
if (member == me) {
if (canDemote(group, me, me)) add(MemberAction.STEP_DOWN)
if (canDemote(group, me, me) || canAskToStepDown(group, me, floor)) add(MemberAction.STEP_DOWN)
} else {
if (canPromote(group, me, member)) add(MemberAction.MAKE_ADMIN)
if (canDemote(group, me, member) && keepsFloor(group, member, floor)) add(MemberAction.REMOVE_AS_ADMIN)
@@ -37,7 +37,7 @@ object GovernanceFollowThrough {
suspend fun observe(database: GizaDatabase, keyPair: KeyPair) {
combine(
database.governanceProposalDao().observeAll(),
database.marmotInnerEventDao().observeCountByKinds(listOf(PromotionEvents.OFFER, PromotionEvents.ACCEPT, PromotionEvents.HANDOVER)),
database.marmotInnerEventDao().observeCountByKinds(listOf(PromotionEvents.OFFER, PromotionEvents.ACCEPT, PromotionEvents.HANDOVER, PromotionEvents.STEP_DOWN)),
database.groupSignedEventDao().observeByKind(GroupKeyStateEvent.KIND),
) { _, _, _ -> Unit }
.conflate()
@@ -71,6 +71,9 @@ object GovernanceFollowThrough {
announce(database, offer.chatRoomId, me, "Couldn't ask the group to make them an admin: ${it.message}")
}
}
// An admin who asked to step down, when this device is the one to propose it.
PromotionManager.followStepDowns(database, me)
PromotionManager.handoversOwed(database).forEach { proposal ->
runCatching { PromotionManager.handover(database, proposal, me) }.onFailure {
if (it is CancellationException) throw it
@@ -162,6 +162,69 @@ object PromotionManager {
announce(database, localChatRoom.chatRoom.id, me, ChatMessage.TYPE_ADMIN_OFFERED, "You accepted becoming an admin. The group signs it next")
}
// ---- stepping down, asked of another admin ---------------------------------------------------------------------
/**
* Asks, as [me], to stop being an admin of keyed room [localChatRoom]. An admin
* cannot propose their own demotion there: the rotation that takes their share
* away is started by the demotion's proposer, who has to keep a share. So the
* request goes into the room, and [followStepDowns] on
* [AdminGovernance.stepDownProposer]'s device proposes it, as that admin pressing
* **Remove as admin** would. Nothing is committed here.
*/
suspend fun requestStepDown(database: GizaDatabase, localChatRoom: LocalChatRoom, me: HexKey): HexKey {
val group = database.marmotEngine.groupFor(localChatRoom.routingId)
?: throw MarmotMissingChatGroupException("No live group for ${localChatRoom.chatRoom.id}")
check(me in group.currentAdminIdentities()) { "You're not an admin of this group" }
check(AdminGovernance.stepDownProposer(group, me) != null) { "You're the only admin. Make someone else an admin first" }
val id = send(database, localChatRoom.chatRoom.id, me, PromotionEvents.STEP_DOWN, "", PromotionEvents.stepDownTags(localChatRoom.chatRoom.id))
announce(database, localChatRoom.chatRoom.id, me, ChatMessage.TYPE_ADMIN_OFFERED, "You asked to step down as admin. The group signs it next")
return id
}
/**
* Takes up the step-down requests whose [AdminGovernance.stepDownProposer] is
* [me]: proposes each one's demotion for the group's signature, through the same
* `demote` an admin's own **Remove as admin** runs, so its rotation follows the
* same way. Run by `GovernanceFollowThrough` whenever a request arrives, and on
* start.
*
* A request is used once. The proposer's device drops it after proposing, or
* after saying in the room why it could not; every device drops one whose
* requester is no longer an admin, so a member made an admin again later is not
* stepped down by what they asked the first time.
*
* @return how many demotions were proposed.
*/
suspend fun followStepDowns(database: GizaDatabase, me: HexKey): Int {
var proposed = 0
database.marmotInnerEventDao().getByKinds(listOf(PromotionEvents.STEP_DOWN)).forEach { request ->
val requester = request.publicKey
val room = database.chatRoomDao().findChatRoomById(request.chatRoomId)
val group = room?.let { database.marmotEngine.groupFor(it.routingId) }
if (room == null || group == null || requester !in group.currentAdminIdentities()) {
database.marmotInnerEventDao().deleteById(request.id)
return@forEach
}
if (room.chatRoom.userPublicKey != me || AdminGovernance.stepDownProposer(group, requester) != me) return@forEach
val failure = runCatching { database.marmotOutboundDao().demote(room, requester) }.exceptionOrNull()
if (failure is kotlinx.coroutines.CancellationException) throw failure
database.marmotInnerEventDao().deleteById(request.id)
if (failure == null) {
proposed++
logger.i("Proposed ${requester.take(8)}…'s step-down in ${room.chatRoom.id}")
} else {
logger.w("Couldn't propose ${requester.take(8)}…'s step-down: ${failure.message}")
announce(
database, room.chatRoom.id, me, ChatMessage.TYPE_CHANGE_NOT_APPLIED,
"Couldn't ask the group to remove ${nameOf(database, requester)} as admin, as they asked: ${failure.message}",
)
}
}
return proposed
}
// ---- 3. the proposal, by the device that offered ---------------------------------------------------------------
/** This device's offers that have been accepted and not yet proposed, with their acceptance. */
@@ -28,7 +28,7 @@ import com.vitorpamplona.quartz.nip01Core.tags.dTag.DTag
object GovernanceEvents {
val ALL: Set<Kind> = setOf(
GovernanceStatementEvent.KIND, OwnCommitEvent.KIND, GovernanceCarrierEvent.KIND,
PromotionEvents.OFFER, PromotionEvents.ACCEPT, PromotionEvents.HANDOVER,
PromotionEvents.OFFER, PromotionEvents.ACCEPT, PromotionEvents.HANDOVER, PromotionEvents.STEP_DOWN,
)
/** The epoch tag every envelope names: the epoch its commit is built at. */
@@ -104,6 +104,15 @@ object PromotionEvents {
val ACCEPT: Kind = 30375
val HANDOVER: Kind = 30376
/**
* An admin of a keyed room asking to be removed as one. They cannot propose it
* themselves: the rotation that follows a demotion is started by its proposer,
* and has to be started by somebody who keeps a share. So one remaining admin's
* device proposes it for them (`PromotionManager.followStepDowns`). Signed by the
* admin stepping down, whom MLS authenticates as its sender.
*/
val STEP_DOWN: Kind = 30377
const val TARGET_TAG = "target"
const val OFFER_TAG = "offer"
const val HOST_KEY_TAG = "host"
@@ -117,5 +126,7 @@ object PromotionEvents {
fun handoverTags(chatRoomId: HexKey, target: HexKey): Array<Array<String>> =
arrayOf(DTag.assemble(chatRoomId), arrayOf(TARGET_TAG, target))
fun stepDownTags(chatRoomId: HexKey): Array<Array<String>> = arrayOf(DTag.assemble(chatRoomId))
fun value(tags: Array<Array<String>>, name: String): String? = tags.firstOrNull { it.size >= 2 && it[0] == name }?.get(1)
}
@@ -89,6 +89,7 @@ import mobi.giza.compose.resources.couldn_t_leave_the_group
import mobi.giza.compose.resources.admin_change_requested
import mobi.giza.compose.resources.stepping_down_to_leave
import mobi.giza.compose.resources.change_proposed
import mobi.giza.compose.resources.step_down_requested
import mobi.giza.compose.resources.admin_offer_sent
import mobi.giza.compose.resources.promotion_accepted
import mobi.giza.compose.ui.view.state.GovernanceStatus
@@ -244,6 +245,7 @@ fun ChatRoomDetailScreen(
val adminChangeRequested = stringResource(Res.string.admin_change_requested)
val steppingDownToLeave = stringResource(Res.string.stepping_down_to_leave)
val changeProposed = stringResource(Res.string.change_proposed)
val stepDownRequested = stringResource(Res.string.step_down_requested)
val adminOfferSent = stringResource(Res.string.admin_offer_sent)
val promotionAccepted = stringResource(Res.string.promotion_accepted)
val adminLabel = stringResource(Res.string.admin)
@@ -390,6 +392,7 @@ fun ChatRoomDetailScreen(
notify(
failure ?: when {
governed && action == MemberAction.MAKE_ADMIN -> adminOfferSent
governed && action == MemberAction.STEP_DOWN -> stepDownRequested
governed -> changeProposed
else -> adminChangeRequested
}
@@ -53,6 +53,7 @@ import mobi.giza.compose.resources.step_down_and_leave
import mobi.giza.compose.resources.step_down_and_leave_body
import mobi.giza.compose.resources.step_down_as_admin
import mobi.giza.compose.resources.step_down_body
import mobi.giza.compose.resources.step_down_body_keyed
import mobi.giza.compose.resources.step_down_title
import mobi.giza.compose.ui.theme.spacing
import mobi.giza.compose.ui.composable.widgets.Decorative
@@ -125,7 +126,7 @@ internal fun ConfirmAdminChangeDialog(
)
MemberAction.STEP_DOWN -> Triple(
stringResource(Res.string.step_down_title),
stringResource(Res.string.step_down_body),
stringResource(if (keyed) Res.string.step_down_body_keyed else Res.string.step_down_body),
stringResource(Res.string.step_down),
)
// Removal keeps the immediate action it always had.
@@ -314,10 +314,11 @@ class AdminChangesJvmTest {
)
val keyedRoom = db.chatRoomDao().findChatRoomById(keyedRoomId)!!
// Born needing the group's signature, so an admin's own step-down is refused
// outright: another admin proposes it, and the group signs.
// Born needing the group's signature. Its only admin stepping down would take
// it under its floor, so it is refused before anything is asked or committed.
val refusal = assertFailsWith<IllegalStateException> { chatRepository.demoteMember(keyedRoom, user) }
assertTrue("another admin removes you as admin" in refusal.message.orEmpty(), refusal.message)
assertTrue("at least 3 admins" in refusal.message.orEmpty(), refusal.message)
assertTrue(db.marmotInnerEventDao().getByKinds(listOf(mobi.giza.compose.nostr.frost.PromotionEvents.STEP_DOWN)).isEmpty())
assertTrue(db.marmotPublishObligationDao().getAll().isEmpty())
val keyedGroup = db.marmotEngine.groupFor(keyedRoom.routingId)!!
assertEquals(AdminLeave.CANNOT, AdminGovernance.adminLeave(keyedGroup, user))
@@ -30,6 +30,7 @@ import mobi.giza.compose.database.GizaDatabase
import mobi.giza.compose.database.builder.getRoomDatabase
import mobi.giza.compose.database.model.ChatMessage
import mobi.giza.compose.database.repository.DatabaseMarmotRepository
import mobi.giza.compose.nostr.frost.PromotionEvents
import mobi.giza.compose.nostr.frost.GovernanceCarrierEvent
import mobi.giza.compose.nostr.frost.GovernanceChange
import mobi.giza.compose.nostr.frost.GovernanceStatementEvent
@@ -434,20 +435,84 @@ class GovernanceGateJvmTest {
// --- Phase 9: demotion and removal in a keyed room, then a rotation ------------
@Test
fun `in a governed keyed room an admin is offered demoting another, never stepping down`() = runBlocking {
fun `in a governed keyed room an admin is offered demoting another, and stepping down`() = runBlocking {
governedRoom()
appIsAdmin()
mobi.giza.compose.ExperimentalFeatures.shareRefreshOverride = true
try {
val actions = AdminGovernance.memberActions(appGroup(), userHex, floor = 1)
assertTrue(mobi.giza.compose.ui.view.state.MemberAction.REMOVE_AS_ADMIN in actions[dana.hex].orEmpty())
assertFalse(mobi.giza.compose.ui.view.state.MemberAction.STEP_DOWN in actions[userHex].orEmpty(), "an admin was offered stepping down from a keyed room")
assertFalse(mobi.giza.compose.ui.view.state.MemberAction.REMOVE_AS_ADMIN in AdminGovernance.memberActions(appGroup(), userHex, floor = 2)[dana.hex].orEmpty(), "the floor was ignored")
assertTrue(mobi.giza.compose.ui.view.state.MemberAction.STEP_DOWN in actions[userHex].orEmpty(), "an admin's own row offered no step-down")
val atTheFloor = AdminGovernance.memberActions(appGroup(), userHex, floor = 2)
assertFalse(mobi.giza.compose.ui.view.state.MemberAction.REMOVE_AS_ADMIN in atTheFloor[dana.hex].orEmpty(), "the floor was ignored")
assertFalse(mobi.giza.compose.ui.view.state.MemberAction.STEP_DOWN in atTheFloor[userHex].orEmpty(), "the floor was ignored for a step-down")
} finally {
mobi.giza.compose.ExperimentalFeatures.shareRefreshOverride = null
}
}
@Test
fun `a step-down is proposed by the admin in the lowest leaf, never the one stepping down`() = runBlocking {
governedRoom()
appIsAdmin()
// Dana made the room and holds leaf 0; the app holds leaf 1.
assertEquals(dana.hex, AdminGovernance.stepDownProposer(appGroup(), userHex))
assertEquals(userHex, AdminGovernance.stepDownProposer(appGroup(), dana.hex))
}
@Test
fun `stepping down from a keyed room asks the other admins, and commits nothing`() = runBlocking {
governedRoom()
appIsAdmin()
PromotionManager.requestStepDown(db, room(), userHex)
val requests = db.marmotInnerEventDao().getByChatRoomAndKinds(roomId, listOf(PromotionEvents.STEP_DOWN))
assertEquals(listOf(userHex), requests.map { it.publicKey })
assertTrue(db.marmotPublishObligationDao().getAll().isEmpty(), "a commit went out")
assertTrue(db.governanceProposalDao().getAll().isEmpty(), "the one stepping down proposed it")
assertTrue(userHex in appGroup().currentAdminIdentities())
// Not this device's to take up: Dana's is the one that proposes it.
assertEquals(0, PromotionManager.followStepDowns(db, userHex))
assertEquals(1, db.marmotInnerEventDao().getByChatRoomAndKinds(roomId, listOf(PromotionEvents.STEP_DOWN)).size)
}
@Test
fun `the admin whose it is to propose a step-down takes the request up`() = runBlocking {
governedRoom()
appIsAdmin()
mobi.giza.compose.ExperimentalFeatures.shareRefreshOverride = true
try {
danaSays(PromotionEvents.STEP_DOWN, "", PromotionEvents.stepDownTags(roomId))
// Dana's request reaches `demote` on this device, which is the one to
// propose it. This room has two admins under a floor of three, so the
// demotion is refused there and the room says why; the request is used.
assertEquals(0, PromotionManager.followStepDowns(db, userHex))
assertTrue(lines(ChatMessage.TYPE_CHANGE_NOT_APPLIED).any { "as they asked" in it.content && "at least 3 admins" in it.content })
assertTrue(db.marmotInnerEventDao().getByChatRoomAndKinds(roomId, listOf(PromotionEvents.STEP_DOWN)).isEmpty(), "the request was kept")
} finally {
mobi.giza.compose.ExperimentalFeatures.shareRefreshOverride = null
}
}
@Test
fun `a request from someone who is no longer an admin is dropped`() = runBlocking {
governedRoom()
// A request the app sent while it was an admin, filed after it stopped being one.
db.marmotInnerEventDao().upsert(
mobi.giza.compose.database.model.MarmotInnerEvent(
id = "ab".repeat(32), publicKey = userHex, kind = PromotionEvents.STEP_DOWN,
createdAt = kotlin.time.Instant.fromEpochSeconds(1_700_000_000),
tags = PromotionEvents.stepDownTags(roomId), content = "", chatRoomId = roomId,
)
)
PromotionManager.followStepDowns(db, dana.hex)
assertTrue(db.marmotInnerEventDao().getByChatRoomAndKinds(roomId, listOf(PromotionEvents.STEP_DOWN)).isEmpty())
}
@Test
fun `a signed demotion that lands owes a rotation without the member, and asks for one`() = runBlocking {
governedRoom()
+1 -1
View File
@@ -51,7 +51,7 @@ Where the build chose differently:
| Phase 8: enrollment as `ShareRepairManager` generalised | the repair protocol unchanged but for its `n`: a request names the `n` it runs with (the new id, the table's size before it), helpers check that against their own table, and an enrollment asks no helper for approval -- the signed binding was everyone's chance to say no |
| Phase 8: `n` grows in "the stored key" | a signing session's and a repair's `n` is the generation's table size, which the enrollment grew; the ceremony's `participantCount` is left as the ceremony made it |
| Phase 9: every remaining holder's deal and confirm made automatic | the rotation is started by the proposer's device once the change lands (`GovernanceFollowThrough`), and each holder is asked once to take part, as every rotation now asks (rotate-shares-single-approval). A rotation that cannot start is said in the room and offered from the Shares section |
| Phase 9: an admin can step down in a keyed room | not offered. The rotation that has to follow is the remaining holders', so another admin proposes the demotion |
| Phase 9: an admin can step down in a keyed room | not offered at first: the rotation that has to follow is the remaining holders', so another admin proposes the demotion. Since offered as a request -- **Step down as admin** sends `PromotionEvents.STEP_DOWN` (30377), and the remaining admin in the lowest leaf (`AdminGovernance.stepDownProposer`) proposes the demotion for them, then rotates their share away as after any demotion it proposed. Leaving as an admin of a keyed room is still not offered |
| Phase 11's dialogs for every action | removal keeps the immediate action it had; promotion, demotion and stepping down ask first |
Read [marmot-v2.md](./marmot-v2.md) Phase 7 first. Removing a member, disbanding and
+21
View File
@@ -437,6 +437,27 @@ admins cannot be changed. Make the group again.
Promoting a member still needs the room's share rotation on -- a development build,
for now -- and the member accepts on their own device.
#### Stepping down, asked of another admin
With every keyed room governed, an admin's own row had no menu: an admin of a keyed
room could not step down (member-admin-promotion, Phase 9). A demotion's proposer starts
the rotation that takes the demoted admin's share away, and a rotation's proposer has to
keep a share -- so the admin stepping down cannot propose it.
They ask instead. **Step down as admin** on their own row sends a request into the room
(`PromotionEvents.STEP_DOWN`, 30377) and commits nothing. The remaining admin in the
lowest leaf (`AdminGovernance.stepDownProposer`) -- one device, named the same on every
device, so that two admins never both propose it -- two commits at one epoch the library cannot settle for their authors -- takes it up in
`GovernanceFollowThrough` and runs the same `demote` its own **Remove as admin** would:
proposed, signed by the group, then the share rotated away. The request is used once:
dropped after it is proposed or refused out loud, and by every device once its requester
is no longer an admin. It is offered only above the floor and while another admin is
there to ask.
Pinned in `GovernanceGateJvmTest`: the menu offers it, and not at the floor; asking
commits nothing and is not the asker's to take up; the lowest-leaf admin's device takes
it to `demote`; a request from someone no longer an admin is dropped.
## Out of scope
- **One-to-one chats** (D1). If they are to become robust, that needs its own plan.