feat: sign a chapter into the artifact instead of submitting one

Adding a chapter no longer creates one. It opens a signing session over a
ChapterEvent, and the chapter appears -- on every member's device at once,
authored by the room's shared key rather than by whoever pasted the text --
when enough members have signed. The same trade the dialects and artifacts
made: a submission says "I am putting this in front of the group" and the
group's only recourse afterwards is social, while a signature is the group
saying it and it takes a quorum to say. The text everybody translates from is
the group's, so the second is the honest one.

**The chunks.** This is the part chapters had that dialects and artifacts did
not. A chapter was submitted along with a ChunkEvent per paragraph, and that
cannot survive the change: a translation is of a chunk rather than of a
chapter, so a chapter without them cannot be worked on, but the chunks cannot
have their own quorum without costing one signing session per paragraph, and
they cannot be invented locally -- an invented id differs on every device, so
members would silently disagree about which chunk a translation is of while
every screen showed the same chapter.

So the chunks are split back out of the signed chapter's own text when it is
applied, in MantraChunk.chunksOf, on the pattern
MantraArtifactVersion.initialVersionOf already set. Same bytes in, same rows
out, everywhere. They are rumors, because nobody signed them; what the group
signed is the chapter they were split from.

It splits only what the group signed. A chapter that arrived as a submission
was sent with its own chunk events, written under the submitter's key, and
deriving a second set beside them would leave every paragraph in the chapter
twice under ids nothing reconciles -- including on a marmot reindex, which
replays a room's group events without anybody adding anything.

**The index.** Where a chapter sits in its version is read at proposal time
and signed into the event, rather than derived on arrival like the chunks
are. A device applying the chapter cannot recount it: it would be counting a
version other members may have added to in a different order, and the count
has to be the one the group put its signature to. The window between proposal
and quorum is longer than the old write-and-submit window was, so two chapters
proposed at once can still land on one index -- the same race as before, wider.

**What went away.** MantraDao.addChapter and its way up through the repository.
Nothing called it once the screen proposed instead, and leaving a path that
authors a chapter under a member's key while the UI insists on a quorum would
have double-created the chunks besides. MantraRepository.getChaptersForArtifactVersion
replaces the one thing it did that is still needed: counting the index.

**The screens.** AddChapterScreen loads the room, the artifact's latest
version and canSign up front, disables the FAB when either is missing the way
the dialect and artifact screens do, and on success lands on the session
rather than on an artifact the chapter is not in yet. FrostSigningScreen
described a chapter proposal by name alone, so a member was asked to sign text
whose size they could not see; it now reads name, word count and chunk count,
the way an artifact shows its url.

**Tests.** Two files, and each was checked against a broken implementation
rather than only against a working one: deriving the chunks from the clock,
inheriting the chapter's counts across every chunk, authoring the derived rows
as their reader, and losing the paragraph position are all caught, as is
splitting a chapter that arrived as a submission. SignedChapterTest runs a
real 2-of-3 quorum over an actual proposal, because the claim worth holding --
the chapter is the group's, carries proof of it, and every device splits it
into the same chunks -- is invisible when it breaks.

Not covered: applyInnerEvent's upserts, which need a database no test here
stands up, and AddChapterViewModel, which is plumbing across two dispatchers
over a template the tests already pin.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso Ngako
2026-09-06 04:15:36 +02:00
parent a805455df8
commit eb34c8edb3
13 changed files with 825 additions and 160 deletions

View File

@@ -0,0 +1,220 @@
package press.mantra.compose.database.model
import com.vitorpamplona.quartz.nip01Core.crypto.EventHasher
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotEquals
import kotlin.test.assertTrue
import press.mantra.compose.nostr.nip30303.ChapterEvent
import press.mantra.compose.nostr.nip30303.tags.OriginalTextTag
/**
* The chunks of a chapter are derived, not delivered.
*
* The group signs a chapter and nothing else, so the chunks it splits into are
* not events anybody sent: every device builds those rows for itself out of the
* chapter it already holds. That only works while every device builds the *same*
* rows, and nothing about the ids would show it if they stopped — they are
* content hashes, opaque hex either way. What would show is two members
* translating what looks like the same paragraph into rows that never reconcile,
* with the chapter identical on both screens.
*/
class ChapterChunksTest {
private val groupKey = "a".repeat(64)
private val artifactVersionId = "b".repeat(64)
private val chatRoomId = "room"
private val twoParagraphs = "The first paragraph.\n\nThe second paragraph."
private fun signedChapter(
name: String = "Chapter 1",
originalText: String = twoParagraphs,
index: Int = 0,
createdAt: Long = 1_700_000_000,
): ChapterEvent {
val template = ChapterEvent.build(
artifactVersionId = artifactVersionId,
name = name,
originalText = originalText,
index = index,
wordCount = 6,
characterCount = originalText.length,
createdAt = createdAt,
)
// Hashed rather than made up, so two fixtures that differ are two
// different chapters here for the same reason they would be in the app.
return ChapterEvent(
id = EventHasher.hashId(
pubKey = groupKey,
createdAt = template.createdAt,
kind = template.kind,
tags = template.tags,
content = template.content
),
pubKey = groupKey,
createdAt = template.createdAt,
tags = template.tags,
content = template.content,
sig = "d".repeat(128)
)
}
@Test
fun `the derived chunks are a function of the chapter and nothing else`() {
// Every input has to come off the chapter. Reading the clock here would
// still agree with itself twice in a row -- and disagree between two
// devices that applied the same chapter minutes apart, which is the case
// nobody can reproduce on demand. So the timestamps are checked against
// the chapter's rather than against a second derivation.
val chapter = signedChapter(createdAt = 1_700_000_000)
val chunks = MantraChunk.chunksOf(chapter, chatRoomId)
assertEquals(2, chunks.size)
assertTrue(chunks.all { it.createdAt.epochSeconds == 1_700_000_000L })
}
@Test
fun `two devices derive the same chunks from the same chapter`() {
val chapter = signedChapter()
val mine = MantraChunk.chunksOf(chapter, chatRoomId)
val theirs = MantraChunk.chunksOf(chapter, chatRoomId)
assertEquals(mine.map { it.id }, theirs.map { it.id })
assertEquals(mine.map { it.createdAt }, theirs.map { it.createdAt })
}
@Test
fun `a chapter signed at a different moment derives different chunks`() {
// The chapter's own timestamp is bound into the derived ids, so two
// proposals identical but for when they were made stay two chapters with
// two sets of chunks rather than colliding on one set of rows.
val first = MantraChunk.chunksOf(signedChapter(createdAt = 1_700_000_000), chatRoomId)
val second = MantraChunk.chunksOf(signedChapter(createdAt = 1_700_000_001), chatRoomId)
assertNotEquals(first.map { it.id }, second.map { it.id })
}
@Test
fun `the derived chunks hang off the chapter and carry its text in order`() {
val chapter = signedChapter()
val chunks = MantraChunk.chunksOf(chapter, chatRoomId)
assertEquals(listOf(chapter.id, chapter.id), chunks.map { it.chapterId })
assertEquals(listOf("The first paragraph.", "The second paragraph."), chunks.map { it.text })
assertEquals(listOf(0, 1), chunks.map { it.index })
// Authored by whoever authored the chapter -- the group, once signed --
// and unsigned, because nobody signed these.
assertTrue(chunks.all { it.publicKey == groupKey })
assertTrue(chunks.all { it.signature == "" })
}
@Test
fun `each chunk counts its own paragraph rather than the chapter's`() {
// The chapter's counts describe the whole text. A chunk that inherited
// them would report every paragraph as the length of the chapter, and
// any progress measured per chunk would be wrong by that factor.
val chunks = MantraChunk.chunksOf(
signedChapter(originalText = "One two three.\n\nFour."),
chatRoomId
)
assertEquals(listOf(3, 1), chunks.map { it.wordCount })
assertEquals(listOf("One two three.".length, "Four.".length), chunks.map { it.characterCount })
}
@Test
fun `two identical paragraphs stay two chunks`() {
// Ids are content hashes, so repeated text is where they would collide
// and a chapter would silently lose a paragraph. The position is in the
// event, which is what keeps them apart.
val chunks = MantraChunk.chunksOf(
signedChapter(originalText = "Again.\n\nAgain."),
chatRoomId
)
assertEquals(2, chunks.size)
assertNotEquals(chunks[0].id, chunks[1].id)
}
@Test
fun `where a chapter sits does not change the chunks it splits into`() {
// Two chapters with the same text at different positions in the book are
// two chapters, and their chunks hang off their own chapter. The check
// that matters is that the ids differ -- chunks of chapter three must not
// be chunks of chapter one.
val first = signedChapter(index = 0)
val second = signedChapter(index = 3)
val firstChunks = MantraChunk.chunksOf(first, chatRoomId)
val secondChunks = MantraChunk.chunksOf(second, chatRoomId)
assertNotEquals(first.id, second.id)
assertEquals(firstChunks.map { it.text }, secondChunks.map { it.text })
assertNotEquals(firstChunks.map { it.id }, secondChunks.map { it.id })
}
@Test
fun `a chapter with no text to split derives no chunks`() {
assertEquals(emptyList(), MantraChunk.chunksOf(signedChapter(originalText = " "), chatRoomId))
// And a chapter that declares no text at all, which is malformed rather
// than empty: nothing to split, and nothing to throw over either.
val declared = signedChapter()
val silent = ChapterEvent(
id = declared.id,
pubKey = declared.pubKey,
createdAt = declared.createdAt,
tags = declared.tags.filterNot { it.firstOrNull() == OriginalTextTag.TAG_NAME }
.toTypedArray(),
content = declared.content,
sig = declared.sig
)
assertEquals(emptyList(), MantraChunk.chunksOf(silent, chatRoomId))
}
@Test
fun `a chapter that arrived as a submission derives nothing`() {
// Chapters used to travel as a submission with a chunk event per
// paragraph, and those rows are already on disk -- written under the
// submitter's key, with ids that have nothing to do with these. Splitting
// one again would leave every paragraph in it twice, and a replay of the
// room's group events would do it without anybody adding anything.
val submitted = signedChapter().let { chapter ->
ChapterEvent(
id = chapter.id,
pubKey = chapter.pubKey,
createdAt = chapter.createdAt,
tags = chapter.tags,
content = chapter.content,
sig = "" // A rumor: what a submission carries.
)
}
assertEquals(emptyList(), MantraChunk.chunksOf(submitted, chatRoomId))
}
@Test
fun `the derived chunk row and its event agree on the id`() {
// A chunk is read back off the wire by other code paths (an inbound
// ChunkEvent from a peer), so the row a device derives has to be the row
// that event would produce -- otherwise the same chunk arrives twice.
val chunk = MantraChunk.chunksOf(signedChapter(), chatRoomId).first()
assertEquals(chunk.id, chunk.toChunkEvent().id)
assertEquals(
chunk.id,
EventHasher.hashId(
pubKey = chunk.publicKey,
createdAt = chunk.createdAt.epochSeconds,
kind = chunk.toChunkEvent().kind,
tags = chunk.toChunkEvent().tags,
content = chunk.toChunkEvent().content
)
)
}
}

View File

@@ -0,0 +1,282 @@
package press.mantra.compose.managers
import com.vitorpamplona.quartz.nip01Core.core.Event
import com.vitorpamplona.quartz.nip01Core.core.hexToByteArray
import com.vitorpamplona.quartz.nip01Core.crypto.EventHasher
import com.vitorpamplona.quartz.nip01Core.crypto.Nip01Crypto
import fr.acinq.bitcoin.ByteVector
import fr.acinq.bitcoin.ByteVector32
import fr.acinq.bitcoin.PrivateKey
import fr.acinq.bitcoin.crypto.frost.Frost
import fr.acinq.bitcoin.crypto.frost.IndividualNonce
import fr.acinq.bitcoin.crypto.frost.KeyMaterial
import fr.acinq.bitcoin.crypto.frost.SecretNonce
import fr.acinq.bitcoin.crypto.frost.Session
import fr.acinq.bitcoin.crypto.frost.TweakCache
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
import press.mantra.compose.database.model.FrostSigningSession
import press.mantra.compose.database.model.MantraChapter
import press.mantra.compose.database.model.MantraChunk
import press.mantra.compose.extensions.toHex
import press.mantra.compose.nostr.nip30303.ChapterEvent
/**
* A chapter the group signed, from proposal to rows, against real FROST.
*
* Adding a chapter used to write a row and submit it, along with a submission
* per paragraph; the rows said the submitter wrote them, because they had. Now
* the group signs the chapter, and the claim this test exists to hold is that
* the chapter every device ends up with is the group's: authored by the
* threshold key, carrying a signature that verifies, with an id every member
* arrives at independently -- and that the chunks each device splits out of it
* are the same chunks.
*
* None of that is visible when it breaks. A row whose author is the proposer
* looks exactly like a row whose author is the group -- both are opaque hex --
* and a group that disagrees about the ids has two chapters that look like one.
*/
class SignedChapterTest {
private val participants = 3
private val threshold = 2
/** The member who pasted the text. Nothing they own should end up on the rows. */
private val proposer = "9".repeat(64)
private val artifactVersionId = "b".repeat(64)
private val originalText = "The first paragraph.\n\nThe second paragraph."
/** Stands in for a completed ceremony; the test is about what gets signed, not the DKG. */
private val keyMaterial: KeyMaterial = Frost.trustedDealerKeygen(
thresholdSecretKey = PrivateKey(
ByteVector32("1c0ffee0000000000000000000000000000000000000000000000000000000a1")
),
nParticipants = participants,
threshold = threshold
)
/**
* The room the group signs in: derived from its key at the admin path, which
* is what makes the room's id and the key it signs as one value.
*/
private val room: SharedKeyDerivation.Derived = SharedKeyDerivation.derive(
thresholdPublicKey = keyMaterial.thresholdPublicKey.value.toHex(),
path = SharedKeyDerivation.MARMOT_ADMIN_GROUP_PATH
)
private val tweakCache: TweakCache = room.cache
/** The group's nostr identity here, which is also [chatRoomId]. */
private val groupPubKey = room.hex
private val chatRoomId = room.hex
private fun proposalTemplate(
name: String = "Chapter 1",
text: String = originalText,
index: Int = 0,
) = ChapterEvent.build(
artifactVersionId = artifactVersionId,
name = name,
originalText = text,
index = index,
wordCount = 6,
characterCount = text.length,
createdAt = 1_700_000_000L,
)
/**
* Exactly what `FrostSigningManager.unsignedEventOf` does, and it must stay
* exactly that: the proposer's fields re-authored under the group's key.
*/
private fun unsignedEventOf(template: com.vitorpamplona.quartz.nip01Core.signers.EventTemplate<*>) = Event(
id = EventHasher.hashId(
pubKey = groupPubKey,
createdAt = template.createdAt,
kind = template.kind,
tags = template.tags,
content = template.content
),
pubKey = groupPubKey,
createdAt = template.createdAt,
kind = template.kind,
tags = template.tags,
content = template.content,
sig = ""
)
private fun sessionOver(unsignedEvent: Event) = FrostSigningSession(
id = "s".repeat(64),
chatRoomId = chatRoomId,
coordinatorPublicKey = proposer,
userPublicKey = proposer,
dkgSessionId = "k".repeat(64),
threshold = threshold,
participantCount = participants,
signerId = 0,
derivationPath = SharedKeyDerivation.formatPath(),
unsignedEventJson = unsignedEvent.toJson(),
eventId = unsignedEvent.id,
nonceRandom = "f".repeat(64)
)
/** A quorum signing the session's event, in the manager's order. */
private fun groupSignature(session: FrostSigningSession): String {
val message = ByteVector(session.eventId.hexToByteArray())
val signerIds = listOf(0, 1)
val nonces = signerIds.map { signerId ->
SecretNonce.generate(
sessionRandom = ByteVector32("a".repeat(63) + "${signerId + 1}"),
secretShare = keyMaterial.secretShares[signerId],
publicShare = keyMaterial.publicShares[signerId],
tweakedThresholdPublicKey = tweakCache.tweakedPublicKey,
message = message,
extraInput = null
)
}
val signingSession = Session.create(
aggregatedNonce = IndividualNonce.aggregate(nonces.map { it.second }).right!!,
signerIds = signerIds.map { it.toUInt() },
signerPublicShares = signerIds.map { keyMaterial.publicShares[it] },
nParticipants = participants,
threshold = threshold,
tweakCache = tweakCache,
message = message
)
val partials = signerIds.mapIndexed { position, signerId ->
signingSession.sign(
nonces[position].first,
keyMaterial.secretShares[signerId],
signerId.toUInt()
).right!!
}
return signingSession.aggregateSigs(partials).right!!.toByteArray().toHex()
}
/** Everything from the form to the rows a device holds afterwards. */
private fun signedChapterEvent(
name: String = "Chapter 1",
text: String = originalText,
index: Int = 0,
): ChapterEvent {
val session = sessionOver(unsignedEventOf(proposalTemplate(name, text, index)))
val signed = FrostSigningManager.signedEvent(session, groupSignature(session))
return ChapterEvent(
signed.id, signed.pubKey, signed.createdAt, signed.tags, signed.content, signed.sig
)
}
@Test
fun `the chapter the group signs is authored by the group, not the proposer`() {
val chapter = MantraChapter.fromChapterEvent(signedChapterEvent(), chatRoomId)
assertNotNull(chapter)
assertEquals(groupPubKey, chapter.publicKey)
assertNotEquals(proposer, chapter.publicKey)
}
@Test
fun `the group it is authored by is the room it was signed in`() {
// Signing runs at the room's derivation path, so the author is the room's
// own id rather than the bare threshold key. That is what lets anybody
// holding the row check it without being told which key to expect -- and
// it is why the path a session signs at cannot come from the proposer.
val chapter = MantraChapter.fromChapterEvent(signedChapterEvent(), chatRoomId)
assertEquals(chatRoomId, chapter?.publicKey)
assertNotEquals(
keyMaterial.thresholdPublicKey.xOnly().value.toHex(),
chapter?.publicKey,
"a chapter must be signed by the room's key, not by the group's root key"
)
}
@Test
fun `the row's id is the id the group put its signature to`() {
// Every device builds this row from the same signed event, so the id has
// to be the one that was signed rather than anything recomputed from the
// proposer. Otherwise members converge on nothing and each holds its own
// copy of what is meant to be one chapter.
val session = sessionOver(unsignedEventOf(proposalTemplate()))
val signed = FrostSigningManager.signedEvent(session, groupSignature(session))
val chapter = MantraChapter.fromChapterEvent(
ChapterEvent(signed.id, signed.pubKey, signed.createdAt, signed.tags, signed.content, signed.sig),
chatRoomId
)
assertEquals(session.eventId, chapter?.id)
}
@Test
fun `the signature on the row verifies against the row's own id and author`() {
// The payoff of signing rather than submitting: the row carries proof the
// group made it, checkable by anybody holding it.
val chapter = MantraChapter.fromChapterEvent(signedChapterEvent(), chatRoomId)
assertNotNull(chapter)
assertTrue(
Nip01Crypto.verify(
signature = chapter.signature.hexToByteArray(),
hash = chapter.id.hexToByteArray(),
pubKey = chapter.publicKey.hexToByteArray()
),
"a chapter row should carry a signature the group's key made over its own id"
)
}
@Test
fun `what the form asked for is what the group signed`() {
// The fields travel as tags through a session that knows nothing about
// chapters. Anything dropped in there is signed away silently -- and the
// original text most of all, since the chunks are split out of it.
val chapter = MantraChapter.fromChapterEvent(
signedChapterEvent(name = "In Detention", index = 2),
chatRoomId
)
assertEquals("In Detention", chapter?.name)
assertEquals(originalText, chapter?.originalText)
assertEquals(artifactVersionId, chapter?.artifactVersionId)
assertEquals(2, chapter?.index)
}
@Test
fun `the chapter arrives with the chunks it splits into`() {
// Nothing sends these rows: each device derives them from the chapter it
// just applied. A translation is of a chunk rather than of a chapter, so
// a chapter that arrives without them cannot be worked on.
val signed = signedChapterEvent()
val chapter = MantraChapter.fromChapterEvent(signed, chatRoomId)
val chunks = MantraChunk.chunksOf(signed, chatRoomId)
assertEquals(2, chunks.size)
assertTrue(chunks.all { it.chapterId == chapter?.id })
assertEquals(listOf("The first paragraph.", "The second paragraph."), chunks.map { it.text })
assertTrue(chunks.all { it.publicKey == groupPubKey })
// Derived, not signed: the group signed the chapter they were split from.
assertTrue(chunks.all { it.signature == "" })
}
@Test
fun `two members derive the same chunks from the chapter their group signed`() {
// The reason the chunks can be derived at all. Both members hold the same
// signed bytes, so both have to land on the same rows -- if they do not,
// a translation one of them writes is of a chunk the other does not have.
val signed = signedChapterEvent()
val mine = MantraChunk.chunksOf(signed, chatRoomId)
val theirs = MantraChunk.chunksOf(signed, chatRoomId)
assertEquals(mine.map { it.id }, theirs.map { it.id })
}
}