docs/shared-key-derivation.md

# 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

```kotlin
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.

### 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.
-												docs: write down the shared-key subsystem and how Marmot membership fails

First docs in the repo -- README.md is still the stock KMP template. Three
documents plus an index, covering the parts whose behaviour is not recoverable by
reading the code: where the reasoning lives in a protocol, where a failure mode is
silent, or where a decision looked arbitrary and was not.

marmot-membership.md is the one that earns its place. Everything about adding a
member compiles, the invite reports success, and a member simply never appears --
and the reason is never in the invite code. It records that
inviteMemberToChatRoom hardcodes isOneMemberInitialGroupCreation = false and that
ChatRepository does not expose it, so every group invite takes the deferred-welcome
path including the first, when the group is still just its creator and the commit
has no audience at all. Then why that is silent rather than noisy:
MarmotInboundManager refuses future-epoch messages outright, on both wire formats,
with no queue and no replay, so a commit arriving before its recipient's welcome
is dropped and that member never advances. EPOCH_RETENTION_WINDOW retains past
epochs and does nothing for messages from ahead. Three options are set out with the
per-invite correctness table, including the honest limit that the recommended one
narrows the race without closing it.

shared-key-derivation.md argues why the paths are not BIP32 -- no chain code
exists, hardened derivation is impossible rather than unimplemented, and a FROST
tweak takes the scalar as input so the chain code leaves the problem entirely. It
records the x-only serialisation trap avoided by choosing the scalar directly, and
states the rule that must not be broken: never reconstruct a derived key in the
clear, because k = k' - t hands over the group key rather than one derived key.

shared-key-ceremony.md covers the seven kinds, the three approval gates and why
the coordinator's aggregations are deliberately not among them, faults as values
rather than exceptions, and the transcript's idempotency-by-construction. It also
writes down the invariant that produces no error when broken: pendingApproval must
mirror the gates in advance, or the screen offers an approval that does nothing --
or none while the ritual sits still.

Every factual claim was checked against the source rather than recalled, which
turned up one correction worth having: there are two future-epoch refusals, for
PrivateMessage and for Commit, so the drop covers both wire formats and not just
one.

Each document leads with the failure mode rather than the architecture, on the
grounds that a failure is what sends somebody to docs in the first place, and each
lists its known gaps -- including that none of this has run on a physical device.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

											
										
										
											2026-09-05 14:39:19 +02:00
+								# 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
 								```kotlin
 								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.
 								### 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.
-												feat(marmot): put a # in front of every group's name, and retire (#admins)

A device's room list holds two unrelated kinds of room and nothing on a row said
which. A NIP-17 room is a conversation between the people in it. A Marmot room is
a *group* -- an id its key derives, a membership baked into an MLS tree, admins
who can act for it, a signature anyone holding the id can check -- and the two
behave differently enough that guessing is a mistake.

`"Ekklesia (#admins)"` was an attempt at saying so, and it marked the wrong half.
Only the admin room got it; a subgroup got no marker at all, so as soon as a group
had one child, half the Marmot rooms on the device were unmarked. It also sorted
nowhere near the group it belonged to, and a truncated row drops a trailing suffix
first -- so the marker was missing exactly where the list is crowded enough to
need it.

**The rule is `MarmotGroupName.of`, and it runs where a room is minted rather than
where it is drawn.** The name is baked into the epoch-0 `MarmotGroupData` every
member is welcomed with, so a `#` added at display time would be a name this
device alone could see. `#Ekklesia` marks both kinds of group room, and marks them
at the front.

**Three mints, because there are three ways a Marmot room comes into existence.**
`MarmotGroupCreation.create` is the funnel for two of them -- the admin room a
group opens after its ceremony, and a subgroup -- and normalising there means
neither caller has to remember. The third, `SelectChatRoomTypeViewModel`'s
convenient room, has a random id rather than a derived one, so it has no key state
to adopt and no admin set to bake in and does not pass through that funnel; it
applies the rule itself.

**Idempotence is load-bearing, not tidiness.** A subgroup's name is derived twice
from the same bare ceremony-room subject, by two callers that never see each
other: `SubgroupManager.proposeBirthCertificate` normalises the name the parent's
quorum is asked to sign, and `MarmotGroupCreation` normalises the name the room
carries. Those two have to be the same string, or the subgroup is not called what
its parent certified -- and a certificate is a signature over the name, so a
verifier comparing them would see a real mismatch. `of` being idempotent is what
makes them agree by construction rather than by both sites being kept in step.

**The ceremony room keeps the bare name.** It is a NIP-17 room -- where a subgroup
is made, not the subgroup -- and prefixing it too produced two identically-named
rows, which spends the mark to say nothing. `Translators` (the ceremony) now sits
beside `#Translators` (the group it stood up), which is the distinction the `#`
exists to draw. Its subject is trimmed, so the bare name and the two normalised
ones cannot differ by whitespace.

**The `#` is drawn beside the name field, not pushed into its state.** `name` in
`SelectSubgroupAdminsViewModel` stays bare and the M3 `prefix` slot shows the
convention, because normalising on every keystroke moves the caret out from under
somebody halfway through a word. The coordinator still reads the name they are
about to get.

Four strings lose the old name -- "Create the #admins group" becomes "Create the
admin room", and the three about what "the #admins room" will sign with now say
"the admin room". Their keys are renamed with them, since the keys in this
catalogue are derived from the text. Around twenty comments, two screen previews
and seven test fixtures follow.

Docs: the ceremony note states the convention and what it replaces, and the
subgroups note's name-field section is rewritten -- it had been arguing from the
`"${parent.subject} (#admins)"` synthesis that no longer exists.
`docs/mls-skipped-keys.md` keeps its `"Frosty (#admins)"`: that is a captured
debugging log, and rewriting it would falsify a record.

Three tests. `MarmotGroupNameTest` pins the rule, idempotence included.
`MarmotGroupCreationJvmTest` pins the funnel -- a bare name in, `#Ekklesia` on both
the room row this device draws and the group data every other member reads.
`SubgroupManagerJvmTest` pins the pair that has to agree, by reading the proposed
event's tags back out of the signing session: the name the parent is asked to sign
is the name `MarmotGroupCreation` will give the room. That last one needed the
signable-parent fixture to seed host keys, since a ceremony's signer ids are
derived from them rather than stored.

**Rooms that already exist keep their names.** The name lives in the epoch-0 group
context, so renaming one is an MLS commit every member has to process -- a
different change from a naming convention, and not made here.

403 common tests, 726 jvm tests, `m3Audit` meets every budget with 0 title-case
strings and 0 dp literals.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

											
										
										
											2026-09-09 11:41:30 +02:00
+								`9420` is arbitrary and has to stay put: the derived key *is* the admin room's
-												docs: write down the shared-key subsystem and how Marmot membership fails

First docs in the repo -- README.md is still the stock KMP template. Three
documents plus an index, covering the parts whose behaviour is not recoverable by
reading the code: where the reasoning lives in a protocol, where a failure mode is
silent, or where a decision looked arbitrary and was not.

marmot-membership.md is the one that earns its place. Everything about adding a
member compiles, the invite reports success, and a member simply never appears --
and the reason is never in the invite code. It records that
inviteMemberToChatRoom hardcodes isOneMemberInitialGroupCreation = false and that
ChatRepository does not expose it, so every group invite takes the deferred-welcome
path including the first, when the group is still just its creator and the commit
has no audience at all. Then why that is silent rather than noisy:
MarmotInboundManager refuses future-epoch messages outright, on both wire formats,
with no queue and no replay, so a commit arriving before its recipient's welcome
is dropped and that member never advances. EPOCH_RETENTION_WINDOW retains past
epochs and does nothing for messages from ahead. Three options are set out with the
per-invite correctness table, including the honest limit that the recommended one
narrows the race without closing it.

shared-key-derivation.md argues why the paths are not BIP32 -- no chain code
exists, hardened derivation is impossible rather than unimplemented, and a FROST
tweak takes the scalar as input so the chain code leaves the problem entirely. It
records the x-only serialisation trap avoided by choosing the scalar directly, and
states the rule that must not be broken: never reconstruct a derived key in the
clear, because k = k' - t hands over the group key rather than one derived key.

shared-key-ceremony.md covers the seven kinds, the three approval gates and why
the coordinator's aggregations are deliberately not among them, faults as values
rather than exceptions, and the transcript's idempotency-by-construction. It also
writes down the invariant that produces no error when broken: pendingApproval must
mirror the gates in advance, or the screen offers an approval that does nothing --
or none while the ritual sits still.

Every factual claim was checked against the source rather than recalled, which
turned up one correction worth having: there are two future-epoch refusals, for
PrivateMessage and for Commit, so the drop covers both wire formats and not just
one.

Each document leads with the failure mode rather than the architecture, on the
grounds that a failure is what sends somebody to docs in the first place, and each
lists its known gaps -- including that none of this has run on a physical device.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

											
										
										
											2026-09-05 14:39:19 +02:00
+								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.