diff --git a/docs/README.md b/docs/README.md index 2194da9a..0747c1c5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,7 @@ the [retired](./retired/) notes now. | [subgroups.md](./subgroups.md) | a group making another group — the four ceremonies, what the parent's signature actually covers, and why the child's key is fresh rather than derived | | [ceremony-creation.md](./ceremony-creation.md) | one place to start a key ceremony — how joining a subgroup's ceremony opened a second one for the parent room, the screen that showed a ceremony and offered to start one in the same button, and the removal of the nip30303 documents, whose kinds collided with the ceremony's, leaving the member chronicle with nothing to carry and nothing to say | | [frost-batch-signing.md](./frost-batch-signing.md) | signing several events in one ceremony — why one nonce can never cover two messages, and the phased schema, wire and UI work that follows from it | +| [frost-re-enrollment.md](./frost-re-enrollment.md) | re-issuing every member's share under the same group key — the zero-sharing construction, why enrollment alone is not a refresh, candidate-signed epoch activation, and the old-quorum compromise boundary | | [frost-session-resend.md](./frost-session-resend.md) | asking the members who never got a signing proposal to look again — why a proposer can repeat only what it wrote, why a member's availability signal needs no repeating, and the one half that has to come from the silent member's own device | | [marmot-membership.md](./marmot-membership.md) | how members join an MLS group, and the epoch race that makes a missing member look like a successful invite | | [member-chronicle.md](./member-chronicle.md) | handing a member added after the work was done the group's signed record — why the events are not on the wire at all, and why the room's id is enough to verify them | diff --git a/docs/frost-re-enrollment.md b/docs/frost-re-enrollment.md new file mode 100644 index 00000000..2bc17f21 --- /dev/null +++ b/docs/frost-re-enrollment.md @@ -0,0 +1,225 @@ +# FROST re-enrollment + +**Status: protocol specification, implementation in progress.** + +Re-enrollment is a proactive share refresh: every member of an existing FROST group +receives a newly generated share of the **same threshold public key**. It is not a fresh +ChillDKG ceremony, an enrollment of a new participant, or a repair of an existing share. + +The existing `FrostEnrollment` API turns a `(t, n)` group into a `(t, n + 1)` group and +repairs a share by reproducing it. Its native specification explicitly says that it does +not refresh keys. Re-enrollment needs a different primitive and a new application +ceremony. + +## Security boundary + +A refresh supersedes shares for the group's future operation. It does **not** revoke an +old threshold quorum. Any `t` shares from one old epoch still describe the same group +secret and can still produce signatures that verify against the unchanged group key. + +The protection a refresh buys is against an adversary collecting fewer than `t` shares in +several different epochs. Honest members must delete their previous shares, and old and +new shares must never be accepted into one signing session. + +A group that suspects a threshold of current shares is compromised must run a new DKG and +move to the room derived from the new key. Re-enrollment cannot solve that case. + +## Scope + +The first protocol version keeps all of these fixed: + +- the threshold public key and the Marmot room id derived from it; +- the derivation path and any subgroup birth certificate; +- `t`, `n`, member identities and their FROST signer ids; +- the share-holder roster. + +It runs in an existing Marmot room. Every share holder must eventually participate: +signing needs `t`, but refreshing every member's share requires all `n` to stage and +acknowledge a candidate. Membership changes, threshold changes, NIP-17-only groups and +automatic refreshes are separate work. + +A share epoch is an application-level FROST version. It is unrelated to an MLS epoch. + +## Cryptographic construction + +Write `f` for the current sharing polynomial, `x = f(0)` for the group secret and +`Y = xG` for the group public key. Participant `i` currently holds `s_i = f(x_i)` and has +public share `P_i = s_iG`. + +Each participant independently generates a degree-at-most-`t - 1` polynomial with a zero +constant term: + +``` +g_i(X) = a_i1 X + a_i2 X^2 + ... + a_i(t-1) X^(t-1) +``` + +The participant publishes commitments to every non-constant coefficient, `a_i,k G`, and +sends `g_i(x_j)` privately to participant `j`. The zero constant is implicit; no point at +infinity is serialised as a public key. + +Recipient `j` verifies each evaluation against its dealer's public commitments, then +computes: + +``` +s'_j = s_j + sum_i g_i(x_j) +P'_j = P_j + sum_i sum_k x_j^k (a_i,k G) +``` + +The resulting polynomial and group key are: + +``` +f' = f + sum_i g_i +f'(0) = f(0) = x +s'_jG = P'_j +``` + +The candidate public-share table must also pass `frostThresholdInfoValidate` against the +independently authenticated threshold public key. A per-recipient evaluation check names +a faulty dealer; the final public-share check catches any remaining inconsistency. + +### Randomness and replay + +Each dealer uses fresh uniform randomness for every refresh session. The derivation is +domain-separated by the protocol version, refresh session id, group key, old and new share +epochs, threshold and ordered participant ids. + +Recomputing one session from its stored seed reproduces identical commitments and +evaluations, which makes redelivery safe. A failed refresh gets a new session id and fresh +randomness. Randomness is never reused between sessions. + +## Ceremony + +```text +coordinator -> everyone: proposal +participant -> everyone: public coefficient commitments +participant -> each other participant privately: one evaluation +participant -> coordinator and everyone: READY(candidate transcript hash) +a quorum, using candidate shares: sign the next key-epoch state +every device, independently: atomically activate the candidate and retire old secrets +``` + +### Proposal + +The proposal fixes the protocol version, session id, room and root DKG ids, current and +next share epochs, threshold, participant ids and previous signed key-state event id. +Every receiver checks these against its local key state. A proposal publishes nothing on a +member's behalf until that member approves joining. + +### Commitments and evaluations + +Public commitments travel as Marmot protocol events. Private evaluations travel only in +`MarmotDirectMessage`: NIP-44 to one recipient, a sender-signed seal bound to the MLS +sender identity, and `MarmotInnerEvent` as the outbound and inbound store. They never go +through `GiftWrapPayload`, a relay broadcast request or an ordinary chat row. + +A message is keyed by `(session, sender, recipient, kind)`. The first payload wins. A +conflicting redelivery is ignored rather than allowed to change the ceremony. + +### Candidate and READY + +Once all commitments and evaluations are present and valid, each device derives and stores +its candidate secret share and the complete candidate public-share table without making +them active. It checks its own candidate against its public share and validates the whole +table against the threshold key. + +`READY` commits to a canonical transcript hash covering the protocol version, session id, +room and key identifiers, both epochs, roster, threshold, previous key-state event and +ordered commitments. Activation requires matching `READY` messages from all `n` members. + +### Activation + +Any member holding the complete transcript may propose activation. A threshold of members +then signs a new key-epoch state **with their candidate shares**. Activation uses a new +signing session with fresh nonce seeds. If it fails, retrying creates another signing +session with fresh seeds; the verified candidate is retained and the share refresh is not +rerun. + +The signed state names the unchanged threshold key, root DKG id, derivation path and +parentage, plus the next share epoch, refresh session id, transcript hash, previous +key-state event id and candidate public-share hash. It travels on a new kind so an old +build cannot adopt it accidentally. + +A device applies it only after checking the group signature, room derivation, epoch +successor, previous state, transcript and its own staged candidate. In one database +transaction it: + +- replaces the root `DkgSession`'s secret and public shares and increments its share epoch; +- installs the new `GroupKeyState` epoch; +- completes the refresh session and fences superseded signing sessions; +- clears staged candidates and secret refresh inputs; +- schedules any remaining old-secret cleanup. + +A device that knows a higher signed epoch but lacks its matching candidate blocks signing +and asks for replay. It does not silently fall back to its old share. + +## Signing rules + +Every signing session records its share epoch. Proposal acceptance, nonce generation, +partial signing, aggregation, completion and resend all require that epoch to match the +active key epoch. Activation sessions are the only exception and can use only the named, +staged candidate. + +Post-genesis signing uses an epoch-aware proposal kind that old builds do not route. An +old proposal or key-state event cannot move a device backwards. Key states are ordered by +share epoch before timestamp; conflicting states at one epoch are an error, not a race won +by the newest timestamp. + +## Failure and recovery + +Before `READY`, a participant may cancel. Cancellation deletes pending secret material and +leaves the old epoch active. + +After broadcasting `READY`, a participant retains its candidate until activation or an +unambiguously abandoned refresh. A valid signed activation takes precedence over a local +failure display. This avoids deleting a candidate after other members have already signed +its activation. + +Messages are persisted before dispatch and all advancement is idempotent. Resends reuse +stored bytes. A private resend wraps the same evaluation afresh for the current MLS +generation; it never regenerates a polynomial. A different member can take over activation +from the stored transcript. + +After activation, original ChillDKG recovery data and round randomness no longer describe +the active share and are scrubbed. Private evaluations are scrubbed from refresh and inner +event rows. Cleanup is idempotent and resumes at startup. SQLite checkpoints can reduce +residual copies, but exported backups and filesystem snapshots are outside the ceremony's +reach and the UI must not claim otherwise. + +A refreshed share is not recoverable from the profile recovery phrase alone. Current-epoch +repair uses `FrostEnrollment` in repair mode, with an independently authenticated group +key, a validated current public-share table, an expected current public share, and +explicit helper approval. Production availability requires this repair path or an explicit +decision to accept loss of signing on reinstall. + +## Persistence + +The root `DkgSession` id and signer mapping remain stable. Its share fields describe the +current epoch rather than necessarily the original ChillDKG output. + +Existing rows start at share epoch zero. New refresh session and message tables store the +inputs needed to recompute every native step. Activation-signing rows name their refresh +session. Transcript rows name their refresh session just as they already name DKG and +signing sessions. + +Migration must be additive: rebuilding a signing or DKG table risks its child rows and +cascades. An upgrade by itself changes no share material and starts no ceremony. + +## Verification and rollout gates + +The native module needs deterministic vectors, algebra and fault tests, constant-time +secret arithmetic, cleansing on failure, and tests on JVM and native targets. App tests +need real multi-device refreshes, every threshold signer subset, mixed-epoch rejection, +out-of-order delivery, malicious dealers, activation retry, crash recovery, downgrade +rejection and proof that private values never enter a transcript or relay queue. + +Implementation ships dark in this order: crypto, schema, transport, manager, UI. Activation +requires `READY` from all `n`, which is also the proof that every member runs a compatible +build. General availability additionally requires independent cryptographic review, +physical Android and iOS ceremonies, and a working current-epoch repair flow. + +The project's standard gates remain: + +```bash +./gradlew :composeApp:m3Audit +./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest +```