feat(account): derive recovery keys from master secret

Author: pepakriz

README.md

@@ -164,6 +164,49 @@ Domain modules generally use this structure:
 - `*-utils.ts` for pure helpers.
 - `*.test.ts` beside the module it covers.
 
+## Account Seed and Key Derivation
+
+Each device account has a 128-bit master secret `S` (the `MasterKey`). For a
+path `P`, derive a child key and independent 32-byte entropy:
+
+```text
+R = BIP32.MasterKey(S)
+K = BIP32.Derive(R, P)
+E = HMAC-SHA512(
+  key = "bip-entropy-from-k",
+  message = K.privateKey
+)[0:32]
+```
+
+Payky paths follow [BIP-85](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki)
+with the BIP-39 application: `m/83696968'/39'/{language}'/{words}'/{index}'`,
+language `0'` = English. The word count encodes how much of `E` the consumer
+uses (24 words = 32 bytes, 12 words = 16 bytes). The paths must never change
+after accounts exist.
+
+| Consumer | Path `P` | Result |
+| --- | --- | --- |
+| Evolu master owner | `m/83696968'/39'/0'/24'/0'` | `E` as the 32-byte Evolu owner secret |
+| Default Spark wallet | `m/83696968'/39'/0'/12'/0'` | `E[0:16]` as the 16-byte Spark wallet secret |
+| Nostr profile `i` | `m/44'/1237'/i'/0/0` | `K.privateKey` as the Nostr private key |
+
+Nostr profile `0` follows NIP-06 and deliberately uses `K.privateKey` directly;
+using `E` would break NIP-06 compatibility. The Spark wallet secret is stored
+as hex and used as BIP-39 entropy: wallet initialization and the settings UI
+encode it as a 12-word mnemonic (never the raw secret), so the wallet can also
+be restored in any BIP-39-compatible Spark client.
+
+`S` itself is backed up as a single [SLIP-39](https://github.com/satoshilabs/slips/blob/master/slip-0039.md)
+20-word recovery mnemonic (`src/core/modules/shared/key-derivation.ts`, via
+the `slip39-ts` library), encoded as one group with a 1-of-1 threshold — there
+is currently no multi-share Shamir splitting, so the phrase is the sole backup
+of `S` and must be treated with the same care as a BIP-39 seed phrase. SLIP-39
+mnemonics use their own wordlist and checksum and are not interchangeable with
+BIP-39 mnemonics. The mnemonic's identifier is derived deterministically (see
+table above) rather than randomized, so encoding the same `S` always produces
+the same recovery phrase. 256-bit master keys and their 33-word recovery
+mnemonics are not supported.
+
 ## CLI
 
 The CLI reads `.env` files automatically. Environment variables are validated at

bin/cli-accounts.ts

@@ -14,6 +14,12 @@ import {
 } from "../src/core/modules/account/account-actions"
 import { AccountId } from "../src/core/modules/account/account-types"
 import { DeviceId } from "../src/core/modules/device/device-types"
+import {
+  createMasterKey,
+  deriveDefaultSparkWalletSecret,
+  SparkSecretSchema,
+  sparkSecretToMnemonic,
+} from "../src/core/modules/shared/key-derivation"
 import {
   AccountKindSchema,
   FiatCurrencySchema,
@@ -42,7 +48,7 @@ const accountsWithDetailsQuery = createQuery((db) =>
       evoluJsonObjectFrom(
         eb
           .selectFrom("accountSpark")
-          .select(["accountSpark.mnemonic"])
+          .select(["accountSpark.secret"])
           .whereRef("accountSpark.id", "=", "account.id")
       ).as("spark"),
       evoluJsonObjectFrom(
@@ -77,7 +83,7 @@ const accountWithDetailsByIdQuery = (id: AccountId) =>
         evoluJsonObjectFrom(
           eb
             .selectFrom("accountSpark")
-            .select(["accountSpark.mnemonic"])
+            .select(["accountSpark.secret"])
             .whereRef("accountSpark.id", "=", "account.id")
         ).as("spark"),
         evoluJsonObjectFrom(
@@ -159,8 +165,8 @@ export const registerAccountsCommand =
             currency: FiatCurrencySchema.optional().describe(
               "c;Currency for IBAN or cash register accounts"
             ),
-            mnemonic: NonEmptyString255Schema.optional().describe(
-              "m;Spark wallet mnemonic"
+            secret: SparkSecretSchema.optional().describe(
+              "s;Spark wallet secret as 16-byte hex"
             ),
           },
           async action(_, options) {
@@ -194,16 +200,16 @@ export const registerAccountsCommand =
             }
 
             if (options.kind === "spark") {
-              if (options.mnemonic === undefined) {
-                printInvalidAccountInput("Spark account requires --mnemonic.")
+              if (options.secret === undefined) {
+                printInvalidAccountInput("Spark account requires --secret.")
                 return
               }
 
               const id = await run.orThrow(
                 createAccount({
                   ...root,
                   spark: {
-                    mnemonic: options.mnemonic,
+                    secret: options.secret,
                   },
                 })
               )
@@ -253,27 +259,21 @@ export const registerAccountsCommand =
               },
             })
 
-            const { wallet, mnemonic } = await SparkWallet.initialize({
+            const secret = deriveDefaultSparkWalletSecret(createMasterKey())
+            const { wallet } = await SparkWallet.initialize({
+              mnemonicOrSeed: sparkSecretToMnemonic(secret),
               options: {
                 network,
               },
             })
 
             try {
-              if (mnemonic === undefined) {
-                printInvalidAccountInput(
-                  "Spark wallet did not return a mnemonic."
-                )
-                return
-              }
-
-              const accountMnemonic = NonEmptyString255Schema.parse(mnemonic)
               const id = await run.orThrow(
                 createAccount({
                   deviceId: options.deviceId ?? null,
                   name: options.name,
                   spark: {
-                    mnemonic: accountMnemonic,
+                    secret,
                   },
                 })
               )
@@ -283,7 +283,8 @@ export const registerAccountsCommand =
                   id,
                   name: options.name,
                   network,
-                  mnemonic,
+                  secret,
+                  mnemonic: sparkSecretToMnemonic(secret),
                 })}`
               )
             } finally {
@@ -309,8 +310,8 @@ export const registerAccountsCommand =
             currency: FiatCurrencySchema.optional().describe(
               "c;Currency for IBAN or cash register accounts"
             ),
-            mnemonic: NonEmptyString255Schema.optional().describe(
-              "m;Spark wallet mnemonic"
+            secret: SparkSecretSchema.optional().describe(
+              "s;Spark wallet secret as 16-byte hex"
             ),
           },
           async action(_, options) {
@@ -339,7 +340,7 @@ export const registerAccountsCommand =
                   deviceId: options.deviceId,
                   name: options.name,
                   spark: {
-                    mnemonic: options.mnemonic,
+                    secret: options.secret,
                   },
                 })
               )

bun.lock

@@ -42,6 +42,8 @@
     "@evolu/web": "3.0.0-next.1",
     "@faker-js/faker": "10.5.0",
     "@fontsource-variable/geist": "5.2.9",
+    "@noble/hashes": "2.0.1",
+    "@scure/bip32": "1.7.0",
     "@scure/bip39": "2.2.0",
     "@scure/btc-signer": "2.2.0",
     "@sentry/react": "10.63.0",
@@ -68,6 +70,7 @@
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "shadcn": "4.13.0",
+    "slip39-ts": "0.1.13",
     "sonner": "2.0.7",
     "tailwind-merge": "3.6.0",
     "tailwindcss": "4.3.2",

package.json

@@ -5,11 +5,12 @@ import { UAParser } from "ua-parser-js"
 import { deviceEvoluAtom } from "@/atoms/device-evolu"
 import { evoluCounterAtom } from "@/atoms/evolu-counter.ts"
 import {
-  createAccountMnemonic,
+  createAccountMasterKey,
   insertAccount,
   loadActiveAccountRow,
 } from "@/core/evolu/device-account.ts"
 import type { DeviceId } from "@/core/modules/device/device-types.ts"
+import { masterKeyToMnemonic } from "@/core/modules/shared/key-derivation.ts"
 import { NonEmptyString255 } from "@/core/modules/shared/schema.ts"
 
 const getDeviceId = () => {
@@ -49,7 +50,9 @@ const activeAccountRowAtom = atom(async (get) => {
   const deviceEvolu = await get(deviceEvoluAtom)
   const activeAccountRow = await loadActiveAccountRow(deviceEvolu)
 
-  return activeAccountRow ?? insertAccount(deviceEvolu, createAccountMnemonic())
+  return (
+    activeAccountRow ?? insertAccount(deviceEvolu, createAccountMasterKey())
+  )
 })
 
 export const accountAtom = atom(async (get) => {
@@ -72,9 +75,20 @@ export const accountAtom = atom(async (get) => {
 
   return {
     id: row.id,
-    mnemonic: row.mnemonic,
+    masterKey: row.masterKey,
     name: row.name,
     transports: row.transports,
     device,
   }
 })
+
+/**
+ * Split out from `accountAtom` because deriving the SLIP-39 recovery phrase
+ * runs a costly PBKDF2-based encoding — only the screens that actually
+ * display it should pay for it, not every consumer of the account (Evolu
+ * bootstrap, `useAppRun`, ...).
+ */
+export const recoveryMnemonicAtom = atom(async (get) => {
+  const account = await get(accountAtom)
+  return masterKeyToMnemonic(account.masterKey)
+})

src/atoms/account.ts

@@ -11,7 +11,7 @@ export const evoluAtom = atom(async (get) => {
   const run = get(runAtom)
   const evolu = await run.orThrow(
     createAppEvolu({
-      mnemonic: account.mnemonic,
+      masterKey: account.masterKey,
       transports: [],
     })
   )
@@ -25,11 +25,5 @@ export const evoluAtom = atom(async (get) => {
       evolu.useOwner(evolu.appOwner, account.transports)
     : undefined
 
-  const appOwner = evolu.appOwner
-  if (appOwner.mnemonic === null || appOwner.mnemonic === undefined)
-    throw new Error(
-      "App owner mnemonic is not set. Please create a new account."
-    )
-
   return evolu
 })

src/atoms/evolu.ts

@@ -1,7 +1,7 @@
 import { type KyselyNotNull, sqliteTrue } from "@evolu/common"
 import { Link } from "@tanstack/react-router"
 import { ReceiptIcon } from "lucide-react"
-import { useMemo } from "react"
+import { type ReactNode, useMemo } from "react"
 import { Badge } from "@/components/ui/badge.tsx"
 import { Button } from "@/components/ui/button.tsx"
 import {
@@ -464,17 +464,36 @@ function PaymentDetailOptionalRow({
   return <PaymentDetailRow label={label} value={value} />
 }
 
-function PaymentDetailRow({
+export function PaymentDetailRow({
   label,
   value,
+  stacked,
+  emphasize,
+  children,
 }: {
   readonly label: string
-  readonly value: string
+  readonly value?: string
+  readonly stacked?: boolean
+  readonly emphasize?: boolean
+  readonly children?: ReactNode
 }) {
   return (
-    <div className="flex items-start justify-between gap-4 text-sm">
+    <div
+      className={
+        stacked
+          ? "flex flex-col gap-1 text-sm"
+          : "flex items-start justify-between gap-4 text-sm"
+      }
+    >
       <span className="text-muted-foreground">{label}</span>
-      <span className="max-w-56 break-all text-right font-medium">{value}</span>
+      <span
+        className={cn(
+          stacked ? undefined : "max-w-56 break-all text-right",
+          emphasize ? "font-semibold" : "font-medium"
+        )}
+      >
+        {children ?? value}
+      </span>
     </div>
   )
 }