feat: taking part is a rotation's only approval (rotate-shares-single-approval, Phase 2)

ShareRefreshManager.advance no longer stops before round 2 for its owner.
The gate's two reasons never needed a person: participantStep2 is the
check that stops a substituted table, and it fails the rotation out loud
before any prompt could appear; ShareRefreshConfirmation is the one
confirmation per generation, claimed with the pending share in one
transaction. pendingApproval now only answers DEAL.

No migration: confirmApprovedAt and ShareRefreshApprovalStep.CONFIRM stay
so rows written before still decode, documented as read by nothing.

Tests: the pinned gate flips (taking part alone completes the rotation,
asked once); the last to take part deals and confirms with nothing more
asked; a tampered sum fails the rotation on every device with nobody
asked; two rotations opened at once never split the group.
ShareRefreshRitualJvmTest 23/23.

Must ship with Phase 3: a rotation paused at the old second approval has
nothing left to arrive and needs the sweep to move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-11-20 00:53:49 +02:00
1 parent 18f426ca46
commit b4103bcb40
4 files changed
+133 -41

No files matched your search

@@ -74,7 +74,14 @@ data class ShareRefreshSession(
/** Secret-adjacent. Round 2's auxiliary randomness for the confirmation's signature. */
val auxRandom: HexKey,
/** When this device's owner agreed to take part: the refresh's one approval. */
val dealApprovedAt: Instant? = null,
/**
* Written by builds before docs/rotate-shares-single-approval.md, when storing
* the new share was its own approval. Read by nothing; kept rather than
* migrated away.
*/
val confirmApprovedAt: Instant? = null,
/** The furthest step this device has asked its owner about, so the request line is written once. */
@@ -1,21 +1,30 @@
package mobi.giza.compose.database.model.types
/**
* The two decisions a recipient makes in a share refresh. Each publishes
* something different and commits the member to something different.
* Everything a share refresh has ever asked a recipient. One step is still
* asked; the other is kept so rows that stored it by name still decode
* (`ShareRefreshSession.approvalRequestedThrough`).
*/
enum class ShareRefreshApprovalStep {
/**
* Deal round 1: join the refresh, and agree to the withheld list. Withholding
* Take part: deal round 1, and agree to the withheld list. Withholding
* someone takes their signing away, so every recipient decides it, not only
* the proposer.
* the proposer. **The only approval a refresh asks for**: the device does
* everything after it on its own (docs/rotate-shares-single-approval.md).
*/
DEAL,
/**
* Confirm round 2: store the new generation and say so. This is what stops a
* coordinator substituting a table the recipients never dealt, and the one
* confirmation per base generation this device will ever give.
* Was: confirm round 2, storing the new generation and saying so. **No
* longer asked**, and nothing produces it.
*
* Its two reasons never needed a person. Stopping a coordinator substituting
* a table nobody dealt is `FrostRefresh.participantStep2`'s check, which runs
* before any prompt could appear and fails the refresh out loud. The one
* confirmation per base generation is `ShareRefreshConfirmation`, claimed in
* the same transaction as the pending share. Neither depended on the tap.
* Don't put the gate back: a person shown "store your new share" has nothing
* to check that the device has not already checked.
*/
CONFIRM,
}
@@ -60,8 +60,12 @@ import mobi.giza.compose.nostr.frost.ShareRefreshEvents
* - **Every recipient takes part** (D2). A certificate needs them all; anyone
* who cannot is withheld, and repaired later.
*
* Nothing of this device's own goes out without its owner's approval, at two
* gates ([ShareRefreshApprovalStep]). [pendingApproval] mirrors them.
* Nothing of this device's own goes out until its owner agrees to take part,
* with the withheld list the proposal names ([ShareRefreshApprovalStep.DEAL]).
* That is the only gate, and [pendingApproval] mirrors it. Everything after it
* -- dealing, checking the combined result, storing the new share, confirming --
* the device does itself: the check is the device's, and a person tapping
* "store" added nothing to it (docs/rotate-shares-single-approval.md).
*/
object ShareRefreshManager {
private val logger = Logger.withTag("ShareRefreshManager")
@@ -388,6 +392,8 @@ object ShareRefreshManager {
val hostSecretKey = ChillDkgRitualManager.deriveHostSecretKey(nostrPrivateKey)
if (isRecipient) {
// The one gate: taking part, with these members withheld. Every
// step after it follows from that decision and asks nothing more.
if (session.dealApprovedAt == null) {
announceApprovalNeeded(database, session, ShareRefreshApprovalStep.DEAL)
return
@@ -412,10 +418,10 @@ object ShareRefreshManager {
session = moveTo(database, session, ShareRefreshStage.COLLECTING_ROUND_2)
if (isRecipient && ownMessage(database, session, ShareRefreshEvents.ROUND_2) == null) {
if (session.confirmApprovedAt == null) {
announceApprovalNeeded(database, session, ShareRefreshApprovalStep.CONFIRM)
return
}
// No gate here. participantStep2 is the check that stops a
// coordinator substituting a table nobody dealt, and it runs
// whoever is looking; confirmAndStore is the one-confirmation
// rule, and it holds whoever is looking.
val secretShare = base.secretShare ?: throw IllegalStateException("this device holds no share of generation ${base.generation}")
val step2 = FrostRefresh.participantStep2(hostSecretKey, secretShare, params, myId.toUInt(), ByteVector(cmsg1.hexToByteArray()), ByteVector32(session.auxRandom))
step2.fault.raiseIfFaulty("round 2", base)
@@ -583,8 +589,11 @@ object ShareRefreshManager {
/**
* What this device's owner is being asked for, or null. **Must mirror the
* gates in [advance] exactly**: drift makes the screen offer an approval that
* gate in [advance] exactly**: drift makes the screen offer an approval that
* does nothing, or none while the refresh sits still.
*
* Only ever [ShareRefreshApprovalStep.DEAL]. [ShareRefreshApprovalStep.CONFIRM]
* was a second gate until docs/rotate-shares-single-approval.md.
*/
suspend fun pendingApproval(database: GizaDatabase, session: ShareRefreshSession): ShareRefreshApprovalStep? {
if (session.stage == ShareRefreshStage.COMPLETE || session.stage == ShareRefreshStage.FAILED) return null
@@ -592,11 +601,7 @@ object ShareRefreshManager {
val base = ShareGenerations.at(database, key, session.baseGeneration) ?: return null
val myId = base.roster.firstOrNull { it.memberPublicKey == session.userPublicKey }?.participantId ?: return null
if (myId !in session.recipientIdList()) return null
if (session.dealApprovedAt == null) return ShareRefreshApprovalStep.DEAL
if (session.coordinatorRound1 != null && session.confirmApprovedAt == null &&
ownMessage(database, session, ShareRefreshEvents.ROUND_2) == null
) return ShareRefreshApprovalStep.CONFIRM
return null
return if (session.dealApprovedAt == null) ShareRefreshApprovalStep.DEAL else null
}
/** Approves the step this device's owner is being asked for, and moves on. */
@@ -605,8 +610,8 @@ object ShareRefreshManager {
val now = Clock.System.now()
when (pendingApproval(database, session)) {
ShareRefreshApprovalStep.DEAL -> update(database, session) { it.copy(dealApprovedAt = now) }
ShareRefreshApprovalStep.CONFIRM -> update(database, session) { it.copy(confirmApprovedAt = now) }
null -> return
// Never pending any more; kept so the `when` stays over the whole enum.
ShareRefreshApprovalStep.CONFIRM, null -> return
}
advance(database, localChatRoom, sessionId, nostrPrivateKey)
}
@@ -707,6 +712,7 @@ object ShareRefreshManager {
update(database, session) { it.copy(approvalRequestedThrough = step) }
val line = when (step) {
ShareRefreshApprovalStep.DEAL -> "Your approval is needed to take part in rotating the group's shares."
// Unreachable: CONFIRM is no longer asked. Kept because the enum keeps the value.
ShareRefreshApprovalStep.CONFIRM -> "Your approval is needed to store your new share."
}
announce(database, session, ChatMessage.TYPE_SHARE_REFRESH_APPROVAL_NEEDED, line, session.userPublicKey)
@@ -134,7 +134,7 @@ class ShareRefreshRitualJvmTest {
.filter { it.publicKey == device.publicKey }
.sortedWith(compareBy({ it.createdAt }, { it.kind }))
private suspend fun pump(between: List<Device>) {
private suspend fun pump(between: List<Device>, tamper: (MarmotInnerEvent) -> MarmotInnerEvent = { it }) {
var moved = true
while (moved) {
moved = false
@@ -143,8 +143,9 @@ class ShareRefreshRitualJvmTest {
outbox(from).forEach { queued ->
if (!to.received.add(queued.id)) return@forEach
moved = true
to.db.marmotInnerEventDao().upsert(queued.copy(chatRoomId = to.group.roomId))
val event = Event(queued.id, queued.publicKey, queued.createdAt.epochSeconds, queued.kind, queued.tags, queued.content, "")
val delivered = tamper(queued)
to.db.marmotInnerEventDao().upsert(delivered.copy(chatRoomId = to.group.roomId))
val event = Event(queued.id, queued.publicKey, queued.createdAt.epochSeconds, queued.kind, queued.tags, delivered.content, "")
if (ShareRefreshEvents.isShareRefreshKind(event.kind)) {
ShareRefreshManager.processRefreshPayload(to.db, to.room, event, to.publicKey, to.privateKey)
} else if (mobi.giza.compose.nostr.frost.ShareRepairEvents.isShareRepairKind(event.kind)) {
@@ -271,12 +272,12 @@ class ShareRefreshRitualJvmTest {
// ---- the approvals, counted (docs/rotate-shares-single-approval.md) ---------------------------------------------
/**
* Today's gates, pinned: taking part is not enough. With every recipient's
* owner agreeing to take part and nothing more, the rotation goes quiet with
* every recipient asked to store their new share, and nobody has stored one.
* Taking part is the only approval. With every recipient's owner agreeing to
* take part and nothing more, every device stores its new share, confirms it,
* and arrives at the new generation; and nothing ever asks to store it.
*/
@Test
fun `after taking part, every recipient is asked again before storing the new share`() = runBlocking<Unit> {
fun `after taking part, every device stores its new share without being asked again`() = runBlocking<Unit> {
val group = Group(3, 2)
val all = devicesFor(group)
val refresh = propose(all[0])
@@ -286,31 +287,100 @@ class ShareRefreshRitualJvmTest {
all.forEach { device ->
val session = device.refresh(refresh.id)!!
assertEquals(mobi.giza.compose.database.model.types.ShareRefreshApprovalStep.CONFIRM, ShareRefreshManager.pendingApproval(device.db, session), "device ${device.index}")
assertNull(device.db.keyShareDao().getGeneration(ceremonyId, 1), "device ${device.index} stored a share it was not told to")
assertTrue(outbox(device).none { it.kind == ShareRefreshEvents.ROUND_2 }, "device ${device.index} confirmed")
assertTrue(outbox(device).any { it.kind == ShareRefreshEvents.ROUND_1 }, "device ${device.index} did not deal")
assertEquals(ShareRefreshStage.COMPLETE, session.stage, "device ${device.index}")
assertNull(ShareRefreshManager.pendingApproval(device.db, session), "device ${device.index}")
assertNull(session.confirmApprovedAt, "nothing writes the old second approval")
assertEquals(ShareGenerationState.ACTIVE, device.db.keyShareDao().getGeneration(ceremonyId, 1)?.state, "device ${device.index}")
assertTrue(outbox(device).any { it.kind == ShareRefreshEvents.ROUND_2 }, "device ${device.index} did not confirm")
val lines = device.db.chatMessageDao().getChatMessagesByChatRoomId(group.roomId)
.filter { it.chatMessage.messageType == ChatMessage.TYPE_SHARE_REFRESH_APPROVAL_NEEDED }
assertEquals(1, lines.size, "device ${device.index} must be asked once")
}
}
/**
* Today's asks, pinned: three per recipient -- take part, store the new
* share, sign the new generation's key state -- before the old shares are
* deleted. The proposer is asked the first two; its device proposes the key
* state, and a proposer's signature is its proposal.
* The last recipient to take part deals at once, and confirms on the next
* pass that brings the coordinator's sum, with no call in between.
*/
@Test
fun `a recipient is asked three times before the old shares go`() = runBlocking<Unit> {
fun `the last to take part deals and then confirms with nothing more asked`() = runBlocking<Unit> {
val group = Group(3, 2)
val all = devicesFor(group)
val refresh = propose(all[0])
pump(all)
all.dropLast(1).forEach { ShareRefreshManager.approve(it.db, it.room, refresh.id, it.privateKey) }
pump(all)
val last = all.last()
assertTrue(outbox(last).none { it.kind == ShareRefreshEvents.ROUND_1 })
ShareRefreshManager.approve(last.db, last.room, refresh.id, last.privateKey)
assertTrue(outbox(last).any { it.kind == ShareRefreshEvents.ROUND_1 }, "it deals in the approve call")
pump(all)
assertTrue(outbox(last).any { it.kind == ShareRefreshEvents.ROUND_2 }, "and confirms when the sum arrives")
all.forEach { assertEquals(ShareRefreshStage.COMPLETE, it.refresh(refresh.id)?.stage) }
}
/**
* What the second approval was said to protect, protected without it: a
* coordinator's sum altered on its way fails the rotation on every device,
* and nobody arrives at a new generation.
*/
@Test
fun `a tampered sum fails the rotation with nobody asked`() = runBlocking<Unit> {
val group = Group(3, 2)
val all = devicesFor(group)
val refresh = propose(all[0])
pump(all)
all.forEach { ShareRefreshManager.approve(it.db, it.room, refresh.id, it.privateKey) }
pump(all) { event ->
if (event.kind != ShareRefreshEvents.COORDINATOR_ROUND_1) event
else event.copy(content = event.content.dropLast(2) + if (event.content.endsWith("00")) "01" else "00")
}
all.forEach { device ->
val session = device.refresh(refresh.id)!!
assertEquals(ShareRefreshStage.FAILED, session.stage, "device ${device.index}")
assertEquals(0, device.active().generation, "device ${device.index} moved to a generation")
}
assertTrue(all.drop(1).any { it.refresh(refresh.id)!!.failureReason!!.contains("Share refresh") }, "an honest recipient has to say what it found")
}
/**
* Two members open a rotation from the same generation at once. With every
* owner saying yes to everything, the group never splits: at most one
* completes, and every device that moved holds the same table.
*/
@Test
fun `two rotations opened at once never split the group`() = runBlocking<Unit> {
val group = Group(4, 2)
val all = devicesFor(group)
val first = propose(all[0])
val second = propose(all[1])
pump(all)
answerEverything(all, first.id)
answerEverything(all, second.id)
val completed = listOf(first.id, second.id).filter { id -> all.any { it.refresh(id)?.stage == ShareRefreshStage.COMPLETE } }
assertTrue(completed.size <= 1, "two rotations from one generation both completed")
val tables = all.map { it.active().generation to it.active().publicShares }.toSet()
assertEquals(1, tables.size, "devices disagree about the group's table: $tables")
}
/**
* What a recipient is asked before the old shares are deleted: to take part,
* and -- until Phase 5 -- to sign the new generation's key state. The
* proposer is asked only to take part; its device proposes the key state, and
* a proposer's signature is its proposal.
*/
@Test
fun `a recipient is asked to take part and to sign the new key state`() = runBlocking<Unit> {
val group = Group(3, 2)
val all = devicesFor(group)
val refresh = propose(all[0])
pump(all)
val asks = answerEverything(all, refresh.id)
val rotation = listOf(
Ask.Rotation(mobi.giza.compose.database.model.types.ShareRefreshApprovalStep.DEAL),
Ask.Rotation(mobi.giza.compose.database.model.types.ShareRefreshApprovalStep.CONFIRM),
)
val rotation = listOf(Ask.Rotation(mobi.giza.compose.database.model.types.ShareRefreshApprovalStep.DEAL))
assertEquals(rotation, asks[0], "the proposer")
all.drop(1).forEach { device -> assertEquals(rotation + Ask.KeyState, asks[device.index], "device ${device.index}") }
all.forEach { device ->