ba0830a3d4
Phase 0 of docs/curated-to-mantra.md, item 3. Three strings in this tree spell "mantra" for reasons that have nothing to do with the brand, and until now nothing beside them said so: `SharedKeyDerivation.TWEAK_TAG` and `ChillDkgRitualManager.HOST_KEY_DERIVATION_TAG` are inputs to hashes, and `Relays.ephemeral` is a relay that is running. Each now carries a comment saying what renaming it would cost, and docs/shared-key-derivation.md gets the paragraph that ties the three together. **The comments come from the fork, and are rewritten rather than pulled.** The Curated fork found out what these strings were the hard way: it renamed the app twice, and each time had to decide which of thousands of "mantra" tokens were the brand. Its rebrand commits (3bc8be53, e6aee792) left these three alone and wrote down why, and run through the pull's name-rewrite those commits collapse to almost nothing but those comments. They were not taken as commits, because what survives the rewrite is a sentence like "has survived two rebrands -- Mantra to Curated, Curated to Mantra", which in this repository describes rebrands that never happened. The fact they state from this side is different and worth stating plainly: the fork keeps all three byte for byte, so a Mantra member and a Curated member of one group derive one key and talk to one relay, and a rename *here* would split them as surely as a rename there. **Why comments at all, when the derivation note already has the rule.** The note's one rule is about the path a key is derived along; it never said that the tag string itself is part of the derivation, and the failure mode of renaming it is silent -- every room orphaned, every partial signature aggregating to nothing that verifies, and nothing on screen to say so. A `v2` tag is the shape a deliberate change would take, and the comments say so, so that the next person to grep for the brand finds the answer before the diff. **`ComposeAppCommonTest` moves from `press.auxiliary` to `press.mantra`.** It is the KMP template's `1 + 2 == 3`, the last file under a package the app vacated two brands ago, and the fork relocated it rather than deleting it so the source tree has one root package instead of an orphan under an empty one. Same here; it is moved with `git mv` so its history follows. No behaviour changes. :composeApp:jvmTest 736 tests, 0 failures; :composeApp:testDebugUnitTest 403 tests, 0 failures; :composeApp:m3Audit all budgets met. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
7.1 KiB
Deriving keys from a group's shared key
SharedKeyDerivation turns a group's ChillDKG threshold key into further keys the
group can sign with, at paths that look like BIP32 but deliberately are not.
What it produces
val derived = SharedKeyDerivation.derive(thresholdPublicKey) // default m/9420/0/0
derived.publicKey // XonlyPublicKey — 32 bytes, the form nostr and Marmot use
derived.cache // TweakCache — required to sign
derived.hex // publicKey as hex
The cache is not an optimisation. A FROST signing session has to be created
with a cache carrying the same tweaks, or the partial signatures aggregate to
something that verifies against a different key. Code that takes only
publicKey and later tries to sign will fail in a way that is tedious to diagnose
from the outside, because the signature is valid — just not for the key you
expected.
Everything is a pure function of the threshold key and the path, so every member's device computes the same result with no agreement round and nothing to store. Rederive rather than persist.
Why not BIP32
The paths read like BIP32 and are walked the same way, index by index. They are not BIP32, and the difference matters.
A BIP32 node is a key and a chain code. ChillDKG produces no chain code.
ParticipantFinalizeResult gives you thresholdPublicKey, secretShare,
publicShares and recovery — no chain code, because ChillDKG is not a BIP32
ceremony.
Hardened derivation is impossible here, not merely unimplemented. It is:
I = HMAC-SHA512(c_par, 0x00 || ser256(k_par) || ser32(i))
which takes the parent private key. In a FROST group nobody holds that; it
exists only as shares. No member, and no quorum of members short of reconstructing
the secret, can perform it. So m/44'/1237'/0'/0/0 — the NIP-06 nostr path — is
not derivable from a threshold key by anyone.
Non-hardened derivation is available, as an additive tweak.
t = HMAC-SHA512(c_par, serP(K_par) || ser32(i))[0:32]
K' = K + t·G
which is exactly what TweakCache.tweak does. But note where the chain code
appears: only in computing t. A FROST tweak takes t as an input, so
choosing the scalar directly removes the chain code from the problem entirely.
That is what this does:
t = SHA256("mantra/shared-key/tweak/v1" || parentXonlyKey || index-as-4-bytes)
Each scalar commits to the key being tweaked as well as the index, so steps cannot
be reordered or replayed at a different depth to reach the same key.
listOf(0L) and listOf(0L, 0L, 0L) do not collide — there is a test for it.
The mantra/ prefix is deliberate and is not a brand string: the string is an input to
the hash, so renaming it derives different keys from the same threshold key — orphaning
every room already created, and splitting devices on the new string off from devices on
the old one, since their partial signatures would no longer aggregate to one that
verifies. The Curated fork of this app keeps it byte for byte for that reason, and so
must this one. A rename is a protocol fork and would need a v2 tag, not an edit to
this one. The ChillDKG host-key tag in ChillDkgRitualManager is protected by the same
argument, and Relays.ephemeral stays on its mantra.press host for the duller reason
that it is a relay that is running.
What avoiding BIP32 also avoids
With x-only keys there is no single obvious serP(K_par): BIP32 serialises
compressed 33-byte keys, BIP340 uses 32-byte x-only, and the parity byte has to
come from somewhere. Two devices picking different conventions would silently
derive different keys rather than fail. Choosing the tweak input ourselves makes
the domain separation explicit and removes that class of bug.
Nothing is lost in exchange. No external tool can derive these children anyway — none of them has the chain code, and nostr has no way to publish one. An npub is bare bech32 over a 32-byte key with no chain code, depth or parent fingerprint; NIP-06 uses BIP32 internally but discards everything except the leaf public key.
The security property this inherits
Additive tweaking is what non-hardened BIP32 does, and it carries the same
weakness. Because t is publicly computable:
k' = k + t ⟹ k = k' − t
Anyone who learns one derived private key recovers the group's threshold key and can sign as the group with no quorum at all — defeating the entire point of the ceremony. In ordinary BIP32 this is why BIP44 hardens the first three levels: a leaked leaf costs you one account, not the wallet. That defence is unavailable here.
The mitigating factor is that a derived private key does not normally exist:
reconstructing one needs t members to collude, at which point they already have
the parent. So the rule is narrow and absolute:
Never reconstruct a derived key in the clear. Any code path that could — an export, a "reveal private key" screen, a test helper, a debugging convenience — leaks the group key, not just the key it appears to expose.
If you need many keys that cannot be linked back to one another, derivation is the wrong tool: run a ceremony per key. Each output is then independent and no single leak reaches the others.
Paths
derive and marmotGroupId both take path: List<Long>, defaulting to
MARMOT_ADMIN_GROUP_PATH (m/9420/0/0). Any depth works.
9420 is arbitrary and has to stay put: the derived key is the admin room's
id, so changing the path orphans every room already created — members would derive
a different id and stop finding the room at all.
There is no string-path parser for input. Paths are written as lists at the call
site. If one is added it must reject ' outright rather than accepting a hardened
path it cannot honour.
Recording the path
MIP-01's group data is a fixed TLS schema — version, nostrGroupId, name,
description, adminPubkeys, relays, four image fields, disappearingMessageSecs.
There is no extension map, and inventing a field would emit bytes other Marmot
clients cannot decode.
So the path rides in the description, which is the only free text MIP-01 offers:
Admins of Ubuntu Collective.
Shared key path: m/9420/0/0
formatPath, parsePath and describe round-trip this. The marker sits on its
own line and parsePath scans lines for it, so somebody rewriting the rest of the
description does not cost the group the record of how its key was derived.
Worth storing even though the path is currently a constant: it is what rebuilds
the TweakCache a signing session needs, and recomputing from the constant only
holds while the constant never changes. A room that records the path it was made
under lets a later scheme coexist with rooms already created.
parsePath refuses hardened indices — m/9420'/0/0 returns null. A hardened path
cannot have been walked here, so acting on one would derive something other than
what the room claims.
Consequence worth knowing: the path is visible to anyone in the group, in any Marmot client, since description is user-facing text. The path is not a secret and the key it derives from is not published, but the room does announce how it was made.