@me2em/core 0.7.0-alpha.2 → 1.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +179 -32
- package/dist/attestation.d.ts +26 -17
- package/dist/attestation.d.ts.map +1 -1
- package/dist/attestation.js +76 -29
- package/dist/attestation.js.map +1 -1
- package/dist/canonical-name.d.ts +18 -0
- package/dist/canonical-name.d.ts.map +1 -1
- package/dist/canonical-name.js +28 -1
- package/dist/canonical-name.js.map +1 -1
- package/dist/crypto/derivation-paths.d.ts +33 -2
- package/dist/crypto/derivation-paths.d.ts.map +1 -1
- package/dist/crypto/derivation-paths.js +33 -2
- package/dist/crypto/derivation-paths.js.map +1 -1
- package/dist/crypto/derivation.d.ts +47 -0
- package/dist/crypto/derivation.d.ts.map +1 -0
- package/dist/crypto/derivation.js +68 -0
- package/dist/crypto/derivation.js.map +1 -0
- package/dist/crypto/ecdh.d.ts +19 -0
- package/dist/crypto/ecdh.d.ts.map +1 -0
- package/dist/crypto/ecdh.js +33 -0
- package/dist/crypto/ecdh.js.map +1 -0
- package/dist/crypto/ed25519.d.ts +24 -3
- package/dist/crypto/ed25519.d.ts.map +1 -1
- package/dist/crypto/ed25519.js +39 -6
- package/dist/crypto/ed25519.js.map +1 -1
- package/dist/crypto/hkdf.d.ts +10 -1
- package/dist/crypto/hkdf.d.ts.map +1 -1
- package/dist/crypto/hkdf.js +10 -1
- package/dist/crypto/hkdf.js.map +1 -1
- package/dist/crypto/index.d.ts +25 -0
- package/dist/crypto/index.d.ts.map +1 -1
- package/dist/crypto/index.js +25 -0
- package/dist/crypto/index.js.map +1 -1
- package/dist/disposed-error.d.ts +24 -0
- package/dist/disposed-error.d.ts.map +1 -0
- package/dist/disposed-error.js +39 -0
- package/dist/disposed-error.js.map +1 -0
- package/dist/errors.d.ts +67 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +54 -0
- package/dist/errors.js.map +1 -0
- package/dist/handle.d.ts +300 -14
- package/dist/handle.d.ts.map +1 -1
- package/dist/handle.js +463 -54
- package/dist/handle.js.map +1 -1
- package/dist/identity.d.ts +55 -11
- package/dist/identity.d.ts.map +1 -1
- package/dist/identity.js +105 -35
- package/dist/identity.js.map +1 -1
- package/dist/index.d.ts +9 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -4
- package/dist/index.js.map +1 -1
- package/dist/seed.d.ts +15 -11
- package/dist/seed.d.ts.map +1 -1
- package/dist/seed.js +23 -17
- package/dist/seed.js.map +1 -1
- package/dist/session.d.ts +42 -5
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +248 -117
- package/dist/session.js.map +1 -1
- package/dist/subhandle.d.ts +1 -125
- package/dist/subhandle.d.ts.map +1 -1
- package/dist/subhandle.js +12 -179
- package/dist/subhandle.js.map +1 -1
- package/dist/types.d.ts +22 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +6 -0
- package/dist/types.js.map +1 -0
- package/dist/util.d.ts +47 -0
- package/dist/util.d.ts.map +1 -1
- package/dist/util.js +72 -20
- package/dist/util.js.map +1 -1
- package/package.json +10 -4
- package/src/attestation.ts +88 -38
- package/src/canonical-name.ts +33 -1
- package/src/crypto/derivation-paths.ts +37 -2
- package/src/crypto/derivation.ts +90 -0
- package/src/crypto/ecdh.ts +37 -0
- package/src/crypto/ed25519.ts +39 -6
- package/src/crypto/hkdf.ts +10 -1
- package/src/crypto/index.ts +28 -1
- package/src/disposed-error.ts +45 -0
- package/src/errors.ts +88 -0
- package/src/handle.ts +630 -65
- package/src/identity.ts +111 -64
- package/src/index.ts +10 -6
- package/src/seed.ts +27 -17
- package/src/session.ts +336 -132
- package/src/subhandle.ts +12 -251
- package/src/types.ts +26 -0
- package/src/util.ts +78 -20
package/src/identity.ts
CHANGED
|
@@ -1,26 +1,28 @@
|
|
|
1
1
|
// identity.ts
|
|
2
2
|
import { ed } from './crypto/init.js';
|
|
3
|
-
import {
|
|
4
|
-
import { sha256 } from '@noble/hashes/sha2.js';
|
|
3
|
+
import { deriveRootKey, deriveHandleKey, deriveSubHandleKey } from './crypto/derivation.js';
|
|
5
4
|
import { Handle, type HandleMetadata } from './handle.js';
|
|
6
5
|
import { SubHandle, type SubHandleMetadata } from './subhandle.js';
|
|
7
|
-
import { DERIVATION_PATHS } from './crypto/derivation-paths.js';
|
|
8
6
|
import { normalizeName } from './canonical-name.js';
|
|
9
7
|
import { Attestation, type AttestationGrant } from './attestation.js';
|
|
8
|
+
import { DisposedError } from './disposed-error.js';
|
|
9
|
+
import { AttestationError } from './errors.js';
|
|
10
|
+
import type { Signer } from './types.js';
|
|
11
|
+
import { base64urlEncode, INSPECT_SYMBOL } from './util.js';
|
|
10
12
|
|
|
11
13
|
function parseHexSeed(hex: string): Uint8Array {
|
|
12
|
-
if (!/^[0-9a-fA-F]{
|
|
13
|
-
throw new
|
|
14
|
+
if (!/^[0-9a-fA-F]{128}$/.test(hex)) {
|
|
15
|
+
throw new AttestationError('MALFORMED', 'FORMAT', 'Seed string must be 128 hex characters');
|
|
14
16
|
}
|
|
15
|
-
const out = new Uint8Array(
|
|
16
|
-
for (let i = 0; i <
|
|
17
|
+
const out = new Uint8Array(64);
|
|
18
|
+
for (let i = 0; i < 64; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
|
|
17
19
|
return out;
|
|
18
20
|
}
|
|
19
21
|
|
|
20
22
|
/**
|
|
21
23
|
* Represents the root cryptographic identity derived from a seed phrase.
|
|
22
24
|
*
|
|
23
|
-
* An Identity is the foundation of the
|
|
25
|
+
* An Identity is the foundation of the Me2eM protocol. It allows for the
|
|
24
26
|
* hierarchical derivation of isolated {@link Handle}s and {@link SubHandle}s
|
|
25
27
|
* for different contexts (e.g., email, social, specific devices) from a
|
|
26
28
|
* single master seed, ensuring zero cross-contamination of cryptographic material.
|
|
@@ -33,25 +35,32 @@ function parseHexSeed(hex: string): Uint8Array {
|
|
|
33
35
|
*
|
|
34
36
|
* @category Core Primitives
|
|
35
37
|
*/
|
|
36
|
-
export class Identity {
|
|
37
|
-
|
|
38
|
-
|
|
38
|
+
export class Identity implements Signer {
|
|
39
|
+
#privateKey: Uint8Array;
|
|
40
|
+
#publicKey: Uint8Array;
|
|
41
|
+
#disposed = false;
|
|
39
42
|
|
|
40
43
|
private constructor(privateKey: Uint8Array) {
|
|
41
|
-
|
|
42
|
-
this
|
|
44
|
+
// Defensive copy: the caller keeps no reference to the stored bytes.
|
|
45
|
+
this.#privateKey = new Uint8Array(privateKey);
|
|
46
|
+
this.#publicKey = ed.getPublicKey(this.#privateKey);
|
|
43
47
|
}
|
|
44
48
|
|
|
45
49
|
/**
|
|
46
50
|
* Initializes a new Identity from a BIP39 mnemonic seed phrase or raw seed bytes.
|
|
47
51
|
*
|
|
48
|
-
*
|
|
52
|
+
* The seed is the full 64-byte BIP39 seed (PBKDF2-HMAC-SHA512 output,
|
|
53
|
+
* as produced by {@link get64ByteSeedFromMnemonic}). It is used as the
|
|
54
|
+
* HKDF-SHA256 input key material; HKDF info strings are unchanged.
|
|
55
|
+
*
|
|
56
|
+
* @param seed - A 64-byte raw Uint8Array seed, or a hex-encoded string of 64 bytes.
|
|
49
57
|
* @returns A Promise resolving to a new Identity instance.
|
|
50
|
-
* @throws {
|
|
58
|
+
* @throws {AttestationError} `MALFORMED`/`FORMAT` if the provided seed
|
|
59
|
+
* is not exactly 64 bytes (or the hex string is not 128 characters).
|
|
51
60
|
*
|
|
52
61
|
* @example
|
|
53
62
|
* ```ts
|
|
54
|
-
* const seed = await
|
|
63
|
+
* const seed = await get64ByteSeedFromMnemonic('abandon abandon ... art');
|
|
55
64
|
* const identity = await Identity.fromSeed(seed);
|
|
56
65
|
* ```
|
|
57
66
|
*/
|
|
@@ -60,18 +69,13 @@ export class Identity {
|
|
|
60
69
|
? parseHexSeed(seed)
|
|
61
70
|
: seed;
|
|
62
71
|
|
|
63
|
-
if (seedBytes.length !==
|
|
64
|
-
throw new
|
|
72
|
+
if (seedBytes.length !== 64) {
|
|
73
|
+
throw new AttestationError('MALFORMED', 'FORMAT', 'Invalid seed: must be 64 bytes');
|
|
65
74
|
}
|
|
66
75
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
new Uint8Array(0),
|
|
71
|
-
new TextEncoder().encode(DERIVATION_PATHS.identity),
|
|
72
|
-
32
|
|
73
|
-
);
|
|
74
|
-
return new Identity(key);
|
|
76
|
+
// Single shared derivation (PR-10): crypto/derivation.ts is the only
|
|
77
|
+
// place the root key formula lives.
|
|
78
|
+
return new Identity(deriveRootKey(seedBytes));
|
|
75
79
|
}
|
|
76
80
|
|
|
77
81
|
/**
|
|
@@ -93,15 +97,11 @@ export class Identity {
|
|
|
93
97
|
* ```
|
|
94
98
|
*/
|
|
95
99
|
async deriveHandle(name: string, metadata?: HandleMetadata): Promise<Handle> {
|
|
100
|
+
this.#assertNotDisposed();
|
|
96
101
|
name = normalizeName(name);
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
this.privateKey,
|
|
101
|
-
new Uint8Array(0),
|
|
102
|
-
info,
|
|
103
|
-
32
|
|
104
|
-
);
|
|
102
|
+
// Single shared derivation (PR-10): same formula as fromSeed's step,
|
|
103
|
+
// centralized in crypto/derivation.ts.
|
|
104
|
+
const handleKey = deriveHandleKey(this.#privateKey, name);
|
|
105
105
|
return new Handle(handleKey, name, metadata);
|
|
106
106
|
}
|
|
107
107
|
|
|
@@ -138,35 +138,39 @@ export class Identity {
|
|
|
138
138
|
subName: string,
|
|
139
139
|
metadata?: SubHandleMetadata
|
|
140
140
|
): Promise<SubHandle> {
|
|
141
|
+
this.#assertNotDisposed();
|
|
141
142
|
handleName = normalizeName(handleName);
|
|
142
143
|
const subNameNorm = normalizeName(subName);
|
|
143
144
|
|
|
144
|
-
//
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
32
|
|
152
|
-
);
|
|
153
|
-
|
|
154
|
-
// Step 2: derive the SubHandle key from the Handle key
|
|
155
|
-
const subInfo = new TextEncoder().encode(
|
|
156
|
-
DERIVATION_PATHS.subhandle(handleName, subNameNorm)
|
|
157
|
-
);
|
|
158
|
-
const subKey = hkdf(
|
|
159
|
-
sha256,
|
|
160
|
-
handleKey,
|
|
161
|
-
new Uint8Array(0),
|
|
162
|
-
subInfo,
|
|
163
|
-
32
|
|
164
|
-
);
|
|
145
|
+
// Single shared derivations (PR-10, 5.3.3): the intermediate Handle
|
|
146
|
+
// key and the SubHandle key come from crypto/derivation.ts — the
|
|
147
|
+
// exact functions Handle.deriveSubHandle uses, so both entry points
|
|
148
|
+
// are byte-identical by construction (pinned by test 5.3.3 and the
|
|
149
|
+
// golden vectors).
|
|
150
|
+
const handleKey = deriveHandleKey(this.#privateKey, handleName);
|
|
151
|
+
const subKey = deriveSubHandleKey(handleKey, handleName, subNameNorm);
|
|
165
152
|
|
|
166
153
|
const path = [handleName, subNameNorm];
|
|
167
154
|
return new SubHandle(subKey, subNameNorm, path, metadata);
|
|
168
155
|
}
|
|
169
156
|
|
|
157
|
+
/**
|
|
158
|
+
* Signs arbitrary data with the root private key (implements
|
|
159
|
+
* {@link Signer}).
|
|
160
|
+
*
|
|
161
|
+
* This is what makes an `Identity` acceptable as the `signer` argument
|
|
162
|
+
* of {@link Attestation.issue} — the raw private key never leaves the
|
|
163
|
+
* Identity.
|
|
164
|
+
*
|
|
165
|
+
* @param data - The data to be signed, as a Uint8Array.
|
|
166
|
+
* @returns A Promise resolving to the 64-byte Ed25519 signature.
|
|
167
|
+
* @throws {DisposedError} If the Identity has been disposed.
|
|
168
|
+
*/
|
|
169
|
+
async sign(data: Uint8Array): Promise<Uint8Array> {
|
|
170
|
+
this.#assertNotDisposed();
|
|
171
|
+
return ed.sign(data, this.#privateKey);
|
|
172
|
+
}
|
|
173
|
+
|
|
170
174
|
/**
|
|
171
175
|
* Issues an attestation binding a derived Handle key to its name
|
|
172
176
|
* and grant. The subject public key is always derived internally —
|
|
@@ -176,10 +180,11 @@ export class Identity {
|
|
|
176
180
|
*
|
|
177
181
|
* @param grant - Constraints verifiers will enforce for this handle
|
|
178
182
|
* and (via `subNamePatterns`) for the SubHandles it may attest.
|
|
179
|
-
* @returns An attestation signed by the Identity root key
|
|
180
|
-
*
|
|
181
|
-
*
|
|
182
|
-
* @throws {AttestationError}
|
|
183
|
+
* @returns An attestation signed by the Identity root key (the
|
|
184
|
+
* Identity passes itself to `Attestation.issue` as the {@link Signer}).
|
|
185
|
+
* Store it with the Handle — it is a public artifact, not a secret.
|
|
186
|
+
* @throws {AttestationError} `MALFORMED`/`FORMAT` if the name is not
|
|
187
|
+
* canonicalizable or the grant is invalid.
|
|
183
188
|
*
|
|
184
189
|
* @example
|
|
185
190
|
* ```ts
|
|
@@ -196,12 +201,17 @@ export class Identity {
|
|
|
196
201
|
grant: AttestationGrant,
|
|
197
202
|
opts?: { ttlSeconds?: number; expiresAt?: number; jti?: string; now?: number }
|
|
198
203
|
): Promise<Attestation> {
|
|
199
|
-
|
|
200
|
-
|
|
204
|
+
this.#assertNotDisposed();
|
|
205
|
+
// Single normalization (PR-11, 3.6): deriveHandle canonicalizes the
|
|
206
|
+
// name (NFKC → lowercase → trim) and the returned Handle carries the
|
|
207
|
+
// canonical name — pre-normalizing here ran the same name through
|
|
208
|
+
// normalizeName twice. Attestation.issue applies its own defensive
|
|
209
|
+
// canonicalization on top (its public contract).
|
|
210
|
+
const handle = await this.deriveHandle(name);
|
|
201
211
|
return Attestation.issue(
|
|
202
|
-
this
|
|
212
|
+
this,
|
|
203
213
|
handle.getPublicKey(),
|
|
204
|
-
|
|
214
|
+
handle.getName(),
|
|
205
215
|
grant,
|
|
206
216
|
opts ?? {}
|
|
207
217
|
);
|
|
@@ -210,9 +220,46 @@ export class Identity {
|
|
|
210
220
|
/**
|
|
211
221
|
* Retrieves the public key of the root Identity.
|
|
212
222
|
*
|
|
223
|
+
* The returned array is a defensive copy — mutating it does not affect
|
|
224
|
+
* the Identity.
|
|
225
|
+
*
|
|
213
226
|
* @returns A Uint8Array containing the 32-byte Ed25519 public key.
|
|
214
227
|
*/
|
|
215
228
|
getPublicKey(): Uint8Array {
|
|
216
|
-
return this
|
|
229
|
+
return new Uint8Array(this.#publicKey);
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Permanently destroys this Identity's key material.
|
|
234
|
+
*
|
|
235
|
+
* The private key bytes are zeroized; afterwards every capability method
|
|
236
|
+
* ({@link sign}, {@link deriveHandle}, {@link deriveSubHandle},
|
|
237
|
+
* {@link attestHandle}) throws a {@link DisposedError}. Informational getters
|
|
238
|
+
* ({@link getPublicKey}) keep working — public keys are not secrets.
|
|
239
|
+
*
|
|
240
|
+
* Calling `dispose()` more than once is a no-op (idempotent).
|
|
241
|
+
*/
|
|
242
|
+
dispose(): void {
|
|
243
|
+
if (this.#disposed) return;
|
|
244
|
+
this.#privateKey.fill(0);
|
|
245
|
+
this.#privateKey = new Uint8Array(0);
|
|
246
|
+
this.#disposed = true;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
#assertNotDisposed(): void {
|
|
250
|
+
if (this.#disposed) throw new DisposedError('Identity');
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* Redacted serialization contract: `JSON.stringify(identity)` exposes
|
|
255
|
+
* only the object kind and the public identifier — never key material
|
|
256
|
+
* or seed-derived state.
|
|
257
|
+
*/
|
|
258
|
+
toJSON(): { kind: string; id: string } {
|
|
259
|
+
return { kind: 'Identity', id: base64urlEncode(this.#publicKey) };
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
[INSPECT_SYMBOL](): string {
|
|
263
|
+
return `Identity(id=${base64urlEncode(this.#publicKey).slice(0, 8)}…)`;
|
|
217
264
|
}
|
|
218
265
|
}
|
package/src/index.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
export { Identity } from './identity.js';
|
|
2
|
-
export { Handle, type HandleMetadata } from './handle.js';
|
|
2
|
+
export { Handle, type HandleMetadata, type DerivePasswordOptions, type DeriveChannelKeyOptions } from './handle.js';
|
|
3
3
|
export { SubHandle, type SubHandleMetadata } from './subhandle.js';
|
|
4
|
+
export { DisposedError } from './disposed-error.js';
|
|
5
|
+
export type { Signer } from './types.js';
|
|
4
6
|
export { Session, type SessionOptions, type SessionPayload, type RevocationChecker } from './session.js';
|
|
5
7
|
export { Attestation, AttestationError, ATTESTATION_TYPE, ATTESTATION_MAX_PAYLOAD, type AttestationGrant, type AttestationPayload, type AttestationErrorCode, type AttestationLevel } from './attestation.js';
|
|
6
8
|
export * as crypto from './crypto/index.js';
|
|
@@ -9,7 +11,7 @@ export * as crypto from './crypto/index.js';
|
|
|
9
11
|
* @module @me2em/core
|
|
10
12
|
* @packageDocumentation
|
|
11
13
|
*
|
|
12
|
-
* Core cryptographic primitives for the
|
|
14
|
+
* Core cryptographic primitives for the Me2eM authorization protocol.
|
|
13
15
|
*
|
|
14
16
|
* This package provides the foundation for decentralized, multi-context
|
|
15
17
|
* identity management and secure, stateless authentication.
|
|
@@ -23,9 +25,11 @@ export * as crypto from './crypto/index.js';
|
|
|
23
25
|
*
|
|
24
26
|
* @example Basic usage
|
|
25
27
|
* ```typescript
|
|
26
|
-
* import { Identity } from '@me2em/core';
|
|
27
|
-
*
|
|
28
|
-
* const
|
|
28
|
+
* import { Identity, generateSeedPhrase, get64ByteSeedFromMnemonic } from '@me2em/core';
|
|
29
|
+
*
|
|
30
|
+
* const phrase = generateSeedPhrase(128); // 12 words (256 → 24 words)
|
|
31
|
+
* const seed = await get64ByteSeedFromMnemonic(phrase); // 64-byte BIP39 seed
|
|
32
|
+
* const identity = await Identity.fromSeed(seed);
|
|
29
33
|
* const handle = await identity.deriveHandle('user@example.com');
|
|
30
34
|
* const signature = await handle.sign(new TextEncoder().encode('data'));
|
|
31
35
|
* ```
|
|
@@ -34,7 +38,7 @@ export {
|
|
|
34
38
|
generateSeedPhrase,
|
|
35
39
|
normalizeSeedPhrase,
|
|
36
40
|
validateSeedPhrase,
|
|
37
|
-
|
|
41
|
+
get64ByteSeedFromMnemonic,
|
|
38
42
|
type SeedStrength,
|
|
39
43
|
type SeedValidationResult
|
|
40
44
|
} from './seed.js';
|
package/src/seed.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// packages/core/src/seed.ts
|
|
2
2
|
import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39';
|
|
3
3
|
import { wordlist } from '@scure/bip39/wordlists/english';
|
|
4
|
-
import {
|
|
4
|
+
import { AttestationError } from './errors.js';
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* Seed strength in bits. 128 bits → 12 words, 256 bits → 24 words.
|
|
@@ -40,7 +40,11 @@ export type SeedStrength = 128 | 256;
|
|
|
40
40
|
*/
|
|
41
41
|
export function generateSeedPhrase(strength: SeedStrength = 128): string[] {
|
|
42
42
|
if (strength !== 128 && strength !== 256) {
|
|
43
|
-
throw new
|
|
43
|
+
throw new AttestationError(
|
|
44
|
+
'MALFORMED',
|
|
45
|
+
'FORMAT',
|
|
46
|
+
'Seed strength must be 128 (12 words) or 256 (24 words)'
|
|
47
|
+
);
|
|
44
48
|
}
|
|
45
49
|
const mnemonic = generateMnemonic(wordlist, strength);
|
|
46
50
|
return mnemonic.split(' ');
|
|
@@ -131,41 +135,47 @@ export function validateSeedPhrase(words: string[]): SeedValidationResult {
|
|
|
131
135
|
}
|
|
132
136
|
|
|
133
137
|
/**
|
|
134
|
-
* Derives
|
|
135
|
-
*
|
|
136
|
-
*
|
|
138
|
+
* Derives the 64-byte BIP39 seed from a mnemonic phrase using PBKDF2
|
|
139
|
+
* (PBKDF2-HMAC-SHA512, 2048 iterations, salt `"mnemonic" + passphrase`).
|
|
140
|
+
* This is the standard BIP39 derivation: the full 512-bit seed is returned
|
|
141
|
+
* unmodified and serves as the input key material for identity derivation
|
|
142
|
+
* ({@link Identity.fromSeed} applies HKDF-SHA256 on top).
|
|
137
143
|
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
144
|
+
* Both 12-word (128-bit) and 24-word (256-bit) mnemonics produce the same
|
|
145
|
+
* 64-byte seed length, per the BIP39 standard.
|
|
140
146
|
*
|
|
141
147
|
* @param seedPhrase - The BIP39 mnemonic phrase (string or array of words).
|
|
142
148
|
* @param passphrase - Optional BIP39 passphrase ("25th word").
|
|
143
|
-
*
|
|
149
|
+
* BIP39 NFKD normalization (mnemonic and passphrase) is performed by
|
|
150
|
+
* `@scure/bip39`; this function passes the passphrase through
|
|
151
|
+
* unchanged. An empty string (default)
|
|
144
152
|
* matches phrases without a passphrase. WARNING: the passphrase
|
|
145
153
|
* is NOT recoverable — a different passphrase silently derives a
|
|
146
154
|
* completely different seed with no error indication. Store it
|
|
147
155
|
* as carefully as the mnemonic itself.
|
|
148
|
-
* @returns A Promise resolving to
|
|
156
|
+
* @returns A Promise resolving to the 64-byte Uint8Array BIP39 seed.
|
|
149
157
|
*
|
|
150
158
|
* @example
|
|
151
159
|
* ```ts
|
|
152
|
-
* const seed = await
|
|
153
|
-
* // Uint8Array(
|
|
160
|
+
* const seed = await get64ByteSeedFromMnemonic('abandon abandon ... art');
|
|
161
|
+
* // Uint8Array(64) [94, 176, 187, ...]
|
|
154
162
|
*
|
|
155
|
-
* const seedWithPassphrase = await
|
|
163
|
+
* const seedWithPassphrase = await get64ByteSeedFromMnemonic(words, 'my secret 25th word');
|
|
156
164
|
* ```
|
|
157
165
|
*/
|
|
158
|
-
export async function
|
|
166
|
+
export async function get64ByteSeedFromMnemonic(
|
|
159
167
|
seedPhrase: string | string[],
|
|
160
168
|
passphrase: string = ''
|
|
161
169
|
): Promise<Uint8Array> {
|
|
162
170
|
const words = normalizeSeedPhrase(seedPhrase);
|
|
163
171
|
const validation = validateSeedPhrase(words);
|
|
164
172
|
if (!validation.isValid) {
|
|
165
|
-
throw new
|
|
173
|
+
throw new AttestationError('MALFORMED', 'FORMAT', `Invalid seed phrase: ${validation.error}`);
|
|
166
174
|
}
|
|
167
175
|
const mnemonic = words.join(' ');
|
|
168
|
-
|
|
169
|
-
//
|
|
170
|
-
|
|
176
|
+
// Full 64-byte BIP39 seed (PBKDF2-HMAC-SHA512 output) — no post-hashing.
|
|
177
|
+
// Normalization (NFKD on mnemonic + passphrase salt) is the BIP39 layer's
|
|
178
|
+
// job — do not pre-normalize here (spec §2: implementations MUST NOT
|
|
179
|
+
// apply additional normalization on top).
|
|
180
|
+
return mnemonicToSeed(mnemonic, passphrase);
|
|
171
181
|
}
|