|
1
|
+ |
/**
|
|
2
|
+ |
* One seed, one identity, one wallet.
|
|
3
|
+ |
*
|
|
4
|
+ |
* The CLI holds a single BIP-39 mnemonic and derives everything else from it:
|
|
5
|
+ |
* the Nostr identity that signs, and the wallet branch that receives. There is
|
|
6
|
+ |
* no second secret to back up and no way for the two to drift apart, because
|
|
7
|
+ |
* neither is stored — only the seed is, and both are recomputed from it.
|
|
8
|
+ |
*
|
|
9
|
+ |
* The derivation is the frozen OpenAgents profile, not a new one. The paths,
|
|
10
|
+ |
* the English word list, and the empty BIP-39 passphrase come from
|
|
11
|
+ |
* `packages/sovereign-identity/src/contract/derivation.ts`, which froze what
|
|
12
|
+ |
* Pylon shipped (`docs/sol/2026-07-20-pylon-bip39-nostr-spark-identity-recovery-audit.md`).
|
|
13
|
+ |
* `test/seed-identity.test.ts` re-derives that package's public vectors through
|
|
14
|
+ |
* this module, so a refactor here that changes anyone's `npub` fails the build
|
|
15
|
+ |
* rather than silently reissuing every identity.
|
|
16
|
+ |
*
|
|
17
|
+ |
* Why the derivation lives here rather than importing that package: the CLI
|
|
18
|
+ |
* publishes as a plain `tsc` build with no bundler, so every runtime import has
|
|
19
|
+ |
* to resolve from npm for an installed user. `@openagentsinc/sovereign-identity`
|
|
20
|
+ |
* ships TypeScript sources and depends on a Git-tarball `nostr-effect`, so it is
|
|
21
|
+ |
* a test-time cross-check here, not a runtime dependency. The crypto underneath
|
|
22
|
+ |
* is the same pinned stack both sides use: `@noble/curves` 1.8.1,
|
|
23
|
+ |
* `@noble/hashes` 1.7.1, `@scure/bip32` 1.6.2, `@scure/bip39` 1.5.4.
|
|
24
|
+ |
*
|
|
25
|
+ |
* SECRETS. This module returns the mnemonic from exactly one function,
|
|
26
|
+ |
* {@link readSeedPhrase}, and derives from it in memory. It never logs, never
|
|
27
|
+ |
* returns an `nsec` or a raw private key, and writes the seed file `0600` inside
|
|
28
|
+ |
* a `0700` directory. The public manifest {@link SeedIdentity} carries public
|
|
29
|
+ |
* identifiers only and is safe to print, store, and export.
|
|
30
|
+ |
*
|
|
31
|
+ |
* The spending rail is deliberately absent. Which rail the wallet spends over —
|
|
32
|
+ |
* self-custodial MDK/LDK, or the deterministic Spark rail Pylon v1.0 used — is
|
|
33
|
+ |
* an owner decision that is not recorded yet, so this module derives the wallet
|
|
34
|
+ |
* branch and stops. Receiving identifiers are rail-independent; spending is not.
|
|
35
|
+ |
*/
|
|
36
|
+ |
|
|
37
|
+ |
import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
38
|
+ |
import { homedir } from "node:os";
|
|
39
|
+ |
import { join } from "node:path";
|
|
40
|
+ |
|
|
41
|
+ |
import { secp256k1 } from "@noble/curves/secp256k1";
|
|
42
|
+ |
import { ripemd160 } from "@noble/hashes/ripemd160";
|
|
43
|
+ |
import { sha256 } from "@noble/hashes/sha256";
|
|
44
|
+ |
import { bytesToHex } from "@noble/hashes/utils";
|
|
45
|
+ |
import { bech32, createBase58check } from "@scure/base";
|
|
46
|
+ |
import { HDKey } from "@scure/bip32";
|
|
47
|
+ |
import { generateMnemonic, mnemonicToSeedSync, validateMnemonic } from "@scure/bip39";
|
|
48
|
+ |
import { wordlist } from "@scure/bip39/wordlists/english";
|
|
49
|
+ |
|
|
50
|
+ |
/** The frozen shared-root profile both the CLI and Pylon derive under. */
|
|
51
|
+ |
export const DERIVATION_PROFILE_ID = "openagents.legacy_unified_nostr_spark.v1";
|
|
52
|
+ |
|
|
53
|
+ |
/** Nostr identity path: NIP-06 account zero. */
|
|
54
|
+ |
export const NOSTR_DERIVATION_PATH = "m/44'/1237'/0'/0/0";
|
|
55
|
+ |
|
|
56
|
+ |
/** Wallet path: BIP-44 Bitcoin account zero, first external key. */
|
|
57
|
+ |
export const WALLET_DERIVATION_PATH = "m/44'/0'/0'/0/0";
|
|
58
|
+ |
|
|
59
|
+ |
/**
|
|
60
|
+ |
* The frozen BIP-39 passphrase. It is empty, and a non-empty one produces a
|
|
61
|
+ |
* different identity, so it is a constant here rather than an option.
|
|
62
|
+ |
*/
|
|
63
|
+ |
const BIP39_PASSPHRASE = "";
|
|
64
|
+ |
|
|
65
|
+ |
const base58check = createBase58check(sha256);
|
|
66
|
+ |
|
|
67
|
+ |
/** Mainnet pay-to-public-key-hash version byte, the standard BIP-44 pairing. */
|
|
68
|
+ |
const P2PKH_VERSION = 0x00;
|
|
69
|
+ |
|
|
70
|
+ |
/**
|
|
71
|
+ |
* The public half of one seed: what a manifest, a receipt, or a tip request may
|
|
72
|
+ |
* carry. Nothing here can spend, sign, or reconstruct the seed.
|
|
73
|
+ |
*/
|
|
74
|
+ |
export interface SeedIdentity {
|
|
75
|
+ |
/** The frozen derivation profile these identifiers were produced under. */
|
|
76
|
+ |
readonly profile: typeof DERIVATION_PROFILE_ID;
|
|
77
|
+ |
/** The NIP-19 `npub`, and the one cross-surface name for this identity. */
|
|
78
|
+ |
readonly npub: string;
|
|
79
|
+ |
/** The x-only 32-byte Nostr public key as hex. */
|
|
80
|
+ |
readonly nostrPublicKeyHex: string;
|
|
81
|
+ |
readonly nostrDerivationPath: typeof NOSTR_DERIVATION_PATH;
|
|
82
|
+ |
/** The compressed 33-byte wallet public key as hex. */
|
|
83
|
+ |
readonly walletPublicKeyHex: string;
|
|
84
|
+ |
/** The BIP-32 key fingerprint, `HASH160(pubkey)[0..4]`, as hex. */
|
|
85
|
+ |
readonly walletFingerprintHex: string;
|
|
86
|
+ |
/** The mainnet P2PKH receive address for the wallet path. */
|
|
87
|
+ |
readonly walletAddress: string;
|
|
88
|
+ |
readonly walletDerivationPath: typeof WALLET_DERIVATION_PATH;
|
|
89
|
+ |
}
|
|
90
|
+ |
|
|
91
|
+ |
/** Trim and collapse whitespace without changing the words themselves. */
|
|
92
|
+ |
const normalize = (phrase: string): string => phrase.trim().split(/\s+/).join(" ");
|
|
93
|
+ |
|
|
94
|
+ |
/** True when the phrase is a valid English BIP-39 mnemonic with a good checksum. */
|
|
95
|
+ |
export const isValidSeedPhrase = (phrase: string): boolean =>
|
|
96
|
+ |
validateMnemonic(normalize(phrase), wordlist);
|
|
97
|
+ |
|
|
98
|
+ |
/** Generate a fresh mnemonic. 12 words is 128 bits of entropy, 24 words is 256. */
|
|
99
|
+ |
export const generateSeedPhrase = (words: 12 | 24 = 12): string =>
|
|
100
|
+ |
generateMnemonic(wordlist, words === 24 ? 256 : 128);
|
|
101
|
+ |
|
|
102
|
+ |
/**
|
|
103
|
+ |
* Derive the public identity and wallet from one mnemonic.
|
|
104
|
+ |
*
|
|
105
|
+ |
* Deterministic and side-effect free: the same phrase always yields the same
|
|
106
|
+ |
* `npub` and the same wallet address, on every machine and every version.
|
|
107
|
+ |
* Throws when the phrase is not valid BIP-39 English, because deriving from a
|
|
108
|
+ |
* mistyped phrase would hand back a plausible identity nobody can recover.
|
|
109
|
+ |
*/
|
|
110
|
+ |
export const deriveSeedIdentity = (phrase: string): SeedIdentity => {
|
|
111
|
+ |
const normalized = normalize(phrase);
|
|
112
|
+ |
if (!validateMnemonic(normalized, wordlist)) {
|
|
113
|
+ |
throw new Error("The seed phrase is not a valid English BIP-39 mnemonic.");
|
|
114
|
+ |
}
|
|
115
|
+ |
const master = HDKey.fromMasterSeed(mnemonicToSeedSync(normalized, BIP39_PASSPHRASE));
|
|
116
|
+ |
try {
|
|
117
|
+ |
const nostrNode = master.derive(NOSTR_DERIVATION_PATH);
|
|
118
|
+ |
if (nostrNode.privateKey === null) throw new Error("The Nostr key could not be derived.");
|
|
119
|
+ |
const nostrPublicKey = secp256k1.getPublicKey(nostrNode.privateKey, true).slice(1);
|
|
120
|
+ |
|
|
121
|
+ |
const walletNode = master.derive(WALLET_DERIVATION_PATH);
|
|
122
|
+ |
if (walletNode.privateKey === null) throw new Error("The wallet key could not be derived.");
|
|
123
|
+ |
const walletPublicKey = secp256k1.getPublicKey(walletNode.privateKey, true);
|
|
124
|
+ |
const walletHash160 = ripemd160(sha256(walletPublicKey));
|
|
125
|
+ |
const addressPayload = new Uint8Array(21);
|
|
126
|
+ |
addressPayload[0] = P2PKH_VERSION;
|
|
127
|
+ |
addressPayload.set(walletHash160, 1);
|
|
128
|
+ |
|
|
129
|
+ |
nostrNode.wipePrivateData();
|
|
130
|
+ |
walletNode.wipePrivateData();
|
|
131
|
+ |
|
|
132
|
+ |
return {
|
|
133
|
+ |
profile: DERIVATION_PROFILE_ID,
|
|
134
|
+ |
npub: bech32.encode("npub", bech32.toWords(nostrPublicKey)),
|
|
135
|
+ |
nostrPublicKeyHex: bytesToHex(nostrPublicKey),
|
|
136
|
+ |
nostrDerivationPath: NOSTR_DERIVATION_PATH,
|
|
137
|
+ |
walletPublicKeyHex: bytesToHex(walletPublicKey),
|
|
138
|
+ |
walletFingerprintHex: bytesToHex(walletHash160.slice(0, 4)),
|
|
139
|
+ |
walletAddress: base58check.encode(addressPayload),
|
|
140
|
+ |
walletDerivationPath: WALLET_DERIVATION_PATH,
|
|
141
|
+ |
};
|
|
142
|
+ |
} finally {
|
|
143
|
+ |
master.wipePrivateData();
|
|
144
|
+ |
}
|
|
145
|
+ |
};
|
|
146
|
+ |
|
|
147
|
+ |
/**
|
|
148
|
+ |
* Where the seed lives. `OPENAGENTS_IDENTITY_DIR` moves it, which is how tests
|
|
149
|
+ |
* get an isolated identity without touching the developer's own.
|
|
150
|
+ |
*/
|
|
151
|
+ |
export const seedDirectory = (): string => {
|
|
152
|
+ |
const override = process.env["OPENAGENTS_IDENTITY_DIR"];
|
|
153
|
+ |
return override !== undefined && override.trim().length > 0
|
|
154
|
+ |
? override
|
|
155
|
+ |
: join(homedir(), ".openagents", "identity");
|
|
156
|
+ |
};
|
|
157
|
+ |
|
|
158
|
+ |
/** The seed file itself: one line, the mnemonic, mode `0600`. */
|
|
159
|
+ |
export const seedPath = (): string => join(seedDirectory(), "seed");
|
|
160
|
+ |
|
|
161
|
+ |
/** True when a seed is already stored. Presence only; the bytes stay on disk. */
|
|
162
|
+ |
export const seedPresent = (): boolean => existsSync(seedPath());
|
|
163
|
+ |
|
|
164
|
+ |
/**
|
|
165
|
+ |
* Read the stored mnemonic. This is the only function that returns secret
|
|
166
|
+ |
* material, and every caller of it either derives from it or hands it to the
|
|
167
|
+ |
* reader who asked for a backup. Returns `undefined` when no seed is stored.
|
|
168
|
+ |
*/
|
|
169
|
+ |
export const readSeedPhrase = (): string | undefined => {
|
|
170
|
+ |
const path = seedPath();
|
|
171
|
+ |
if (!existsSync(path)) return undefined;
|
|
172
|
+ |
const phrase = normalize(readFileSync(path, "utf8"));
|
|
173
|
+ |
return phrase.length === 0 ? undefined : phrase;
|
|
174
|
+ |
};
|
|
175
|
+ |
|
|
176
|
+ |
/**
|
|
177
|
+ |
* Write the mnemonic, `0600` inside a `0700` directory, after validating it.
|
|
178
|
+ |
* The validation is not politeness: an unwritable-back phrase stored here would
|
|
179
|
+ |
* be an identity that cannot be recovered from its own backup.
|
|
180
|
+ |
*/
|
|
181
|
+ |
export const writeSeedPhrase = (phrase: string): string => {
|
|
182
|
+ |
const normalized = normalize(phrase);
|
|
183
|
+ |
if (!validateMnemonic(normalized, wordlist)) {
|
|
184
|
+ |
throw new Error("The seed phrase is not a valid English BIP-39 mnemonic.");
|
|
185
|
+ |
}
|
|
186
|
+ |
const directory = seedDirectory();
|
|
187
|
+ |
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
188
|
+ |
const path = seedPath();
|
|
189
|
+ |
writeFileSync(path, `${normalized}\n`, { mode: 0o600 });
|
|
190
|
+ |
chmodSync(path, 0o600);
|
|
191
|
+ |
return path;
|
|
192
|
+ |
};
|
|
193
|
+ |
|
|
194
|
+ |
/** Remove the stored seed. Idempotent, and it deletes nothing else. */
|
|
195
|
+ |
export const forgetSeedPhrase = (): boolean => {
|
|
196
|
+ |
const path = seedPath();
|
|
197
|
+ |
if (!existsSync(path)) return false;
|
|
198
|
+ |
rmSync(path);
|
|
199
|
+ |
return true;
|
|
200
|
+ |
};
|