Files
giza-kmp/docs/shared-key-derivation.md
T
Kgothatso NgakoandClaude Opus 5 3bc8be535a refactor: rebrand mantra to curated, and the five names that stay
`press.mantra.{compose,android,desktop}` becomes `com.it.curated.{compose,android,desktop}`
across 680 file moves, and the app is Curated everywhere a user can see it. The work
that mattered was not the rename; it was deciding which of the 6355 occurrences of
"mantra" were the brand and which were something else wearing it.

**"Mantra" was two words in one tree, and only one of them is a brand.** 1369 of the
tokens belong to a domain model -- `MantraArtifact`, `MantraChapter`, `MantraChunk`,
`MantraDialect`, the seven `MantraTranslation*` types, their 15 DAOs and
`MantraRepository` -- and those 12 entity classes declare no `tableName`, so Room takes
the class name as the SQLite table name. A blanket `s/Mantra/Curated/` renames 12 live
tables, which is not a rename but a v20 with 12 `@RenameTable` specs and a regenerated
schema. Asked, the decision was brand surface only, so the domain keeps its name and the
database keeps every one of its tables. The count is the check: the same 1369 tokens are
present before and after, and Room found all 19 existing schemas at the moved directory
and generated no stray -- which is what proves no table moved.

**Renamed instead is the set of names that only ever meant "this app".** `CuratedApp`,
`CuratedApplication`, `CuratedGlobal`, `CuratedNavHost`, `CuratedNavigationSuite`,
`CuratedShapes`, `CuratedConverters`, `defaultCuratedDir`, and `CuratedDatabase` with its
constructor and test. `CuratedDatabase` is safe to rename precisely because the entity
classes were not: the `@Database` class name picks the schema *directory*
(`composeApp/schemas/com.it.curated.compose.database.CuratedDatabase/`), never a table,
so the 19 schema files move unmodified and the AutoMigration chain from 1 is untouched.

**`com.it.curated` is the applicationId; the namespace is `com.it.curated.android`.**
These were one value before, and splitting them is what lets the identifier land verbatim
as the app's store identity while `BuildConfig` and the manifest's relative
`android:name=".CuratedApplication"` keep resolving against the android source package.
The debug build is `com.it.curated.debug` via the existing suffix.

**The generated resources package moved because `rootProject.name` did.** Compose
Resources derives it from the root project, so `Mantra` -> `Curated` silently turns
`mantra.composeapp.generated.resources` into `curated.composeapp.generated.resources` and
breaks all 501 imports at once. They are rewritten, along with the two string keys that
carried the brand -- `mantra` -> `curated` and `sign_in_is_not_yet_available_while_mantra_is`
-- and their three call sites. The seven `docs/scripts/` tools and `m3-audit.sh` hardcode
the UI source path, so they moved too; the audit passing is the evidence they still see
the whole tree rather than an empty one.

**Two hash inputs and a hostname keep the old name, and now say why.**
`SharedKeyDerivation.TWEAK_TAG` and `ChillDkgRitualManager.HOST_KEY_DERIVATION_TAG` are
`"mantra/..."` strings that are fed to SHA256. Renaming them derives different keys from
the same seed: every room already created is orphaned, every completed ChillDKG becomes
unrecoverable, and a Curated client and a Mantra client sharing a group derive different
keys from one threshold key, so their partial signatures aggregate to something that
verifies against nothing. That is a protocol fork and belongs in a `v2` tag, not in a
rebrand. `Relays.ephemeral` stays on `wss://ephemeral.mantra.press` for the duller reason
that it is a relay that is running and is in the bootstrap, publish, finder and DM sets;
pointing it at a name nobody has stood up takes the app off the network. All three sites,
and `docs/shared-key-derivation.md`, now carry the reasoning, because the failure mode of
each is silent and the next reader will otherwise finish the job.

**iOS had never been moved off the brand before this one.** `Config.xcconfig` still read
`PRODUCT_NAME=Torch` with a bundle id of `ac.aux.compose.Aux` -- two brands ago -- so a
Curated repo built a Torch.app. It is now `Curated` / `com.it.curated`, with the pbxproj's
three product references renamed to match. This is wider than Mantra -> Curated and is
called out for that reason; it is also unverified here, because the build gates the ios
targets behind `isMacOsX` and this was built on linux. In the same spirit the last stale
`press.auxiliary.compose` file -- a KMP template test asserting `1 + 2 == 3` -- was
relocated rather than deleted, so the source tree has one root package instead of an
orphan under the vacated one.

**Three things still say the old names on purpose and are not oversights.**
`UserAgent.APP_NAME` and `CLIENT_NAME` still read `"Torch"`, which a previous rename left
deliberately: it goes on the wire to relay operators and is a network identity rather
than a content one. `.gitea/workflows/material-design-conformance.yml` triggers on
`branches: [mantra]` because that is still the branch's real name. And
`docs/material-design-conformance.md:278` records that the top bar once read `"Torch"`
while the window title read `"Mantra"` -- a finding about a past defect, which rewriting
would falsify.

1136 tests pass -- 733 in `:composeApp:jvmTest`, 403 in `:composeApp:testDebugUnitTest` --
`:composeApp:compileDebugKotlinAndroid` is clean, and `m3Audit` meets every budget.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-10 00:53:05 +02:00

6.7 KiB
Raw Blame History

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 did not change when the app was rebranded to Curated. 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 Curated off from any Mantra peer in a shared group. A rename is a protocol fork and would need a v2 tag, not an edit to this one.

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.