@me2em/core 0.7.0-alpha.1 β 0.7.0-alpha.2
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 +69 -21
- package/dist/crypto/hkdf.d.ts +2 -2
- package/dist/crypto/hkdf.d.ts.map +1 -1
- package/dist/crypto/hkdf.js +4 -1
- package/dist/crypto/hkdf.js.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/seed.d.ts +18 -11
- package/dist/seed.d.ts.map +1 -1
- package/dist/seed.js +36 -14
- package/dist/seed.js.map +1 -1
- package/package.json +3 -2
- package/src/crypto/hkdf.ts +4 -1
- package/src/index.ts +3 -1
- package/src/seed.ts +48 -15
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
## π¦ Core Cryptographic Primitives
|
|
2
2
|
|
|
3
3
|
Core primitives for the Me2em authorization protocol: hierarchical
|
|
4
4
|
deterministic identities (`Identity` β `Handle` β `SubHandle`), stateless
|
|
@@ -6,8 +6,8 @@ signed sessions, and parent-signed **attestation chains** for delegatable,
|
|
|
6
6
|
externally verifiable authorization β all on Ed25519.
|
|
7
7
|
|
|
8
8
|
[](https://www.npmjs.com/package/@me2em/core)
|
|
9
|
-
[](
|
|
10
|
-
[](./LICENSE)
|
|
10
|
+
[](https://core.me2em.com)
|
|
11
11
|
|
|
12
12
|
## π― Overview
|
|
13
13
|
|
|
@@ -23,6 +23,43 @@ externally verifiable authorization β all on Ed25519.
|
|
|
23
23
|
derivation without storage.
|
|
24
24
|
- **Secure Channels** β symmetric channel keys and X25519 shared
|
|
25
25
|
secrets derived without key exchange.
|
|
26
|
+
- **BIP39 Passphrase** β optional "25th word" support: the
|
|
27
|
+
passphrase silently derives a different identity if changed.
|
|
28
|
+
- **UKS-Safe ECDH** β `deriveSharedSecret` binds both peers'
|
|
29
|
+
public keys into the KDF (`p2p-channel/v2`), preventing
|
|
30
|
+
unknown key-share attacks.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## π Terminology
|
|
35
|
+
|
|
36
|
+
Protocol terms are **domain-neutral** β each use case assigns them
|
|
37
|
+
its own meaning. The five terms most relevant to this package:
|
|
38
|
+
|
|
39
|
+
| Term | Definition |
|
|
40
|
+
|------|------------|
|
|
41
|
+
| **Identity** | Root cryptographic identity derived from a seed phrase. Constant forever. |
|
|
42
|
+
| **Handle** | A derived, attested, named key representing a distinct identity context. |
|
|
43
|
+
| **SubHandle** | A leaf child of a Handle (MAX_DEPTH = 2). |
|
|
44
|
+
| **Attestation** | A parent-signed statement binding a child key to a name and a grant. |
|
|
45
|
+
| **Session** | A stateless signed authorization token. |
|
|
46
|
+
|
|
47
|
+
**Domain interpretations** β the same primitives, read through
|
|
48
|
+
different lenses:
|
|
49
|
+
|
|
50
|
+
| Use case | Handle is⦠| SubHandle is⦠|
|
|
51
|
+
|----------|------------|----------------|
|
|
52
|
+
| **AI Agent Delegation** (UC-1) | An AI agent acting on behalf of a user | β (the agent signs sessions directly) |
|
|
53
|
+
| **IoT Device Hierarchy** (UC-2) | A physical device | A component of that device |
|
|
54
|
+
| **Multi-Context Identity** (UC-3) | A user persona (work, personal) | Delegated access within a persona |
|
|
55
|
+
| **Multi-App SSO** (UC-4) | A per-app persona of the user | β |
|
|
56
|
+
| **Deterministic Password Manager** (UC-5) | A service context | β |
|
|
57
|
+
| **E2EE Messaging** (UC-6) | The user's messaging identity | An optional device identity |
|
|
58
|
+
|
|
59
|
+
Full glossary (including Channel and material-class terms):
|
|
60
|
+
see the [root README](../../README.md).
|
|
61
|
+
|
|
62
|
+
---
|
|
26
63
|
|
|
27
64
|
## π¦ Installation
|
|
28
65
|
|
|
@@ -35,6 +72,13 @@ pnpm add @me2em/core
|
|
|
35
72
|
**Dependencies:** `@noble/curves` (Ed25519/X25519), `@noble/ed25519`,
|
|
36
73
|
`@noble/hashes` (HKDF, SHA-256), `@scure/bip39` (mnemonic handling).
|
|
37
74
|
|
|
75
|
+
> π‘ This package is self-contained. For E2EE channels, X3DH key
|
|
76
|
+
> agreement, and Argon2id use [`@me2em/crypto`](../crypto/README.md).
|
|
77
|
+
> For React hooks and seed phrase UX components use
|
|
78
|
+
> [`@me2em/react`](../react/README.md). The three packages are
|
|
79
|
+
> designed to work together β see the root
|
|
80
|
+
> [README](../../README.md) for the full package map.
|
|
81
|
+
|
|
38
82
|
## π Quick Start
|
|
39
83
|
|
|
40
84
|
```typescript
|
|
@@ -167,7 +211,7 @@ All failures throw `AttestationError` with `code` and `level`
|
|
|
167
211
|
| `SCOPE_EXCEEDED`, `TTL_EXCEEDED`, `AUDIENCE_NOT_PERMITTED`, `SESSION_OUTLIVES_ATTESTATION` | SESSION |
|
|
168
212
|
| `SUBJECT_MISMATCH` | ROOT, SUB_ATTESTATION |
|
|
169
213
|
|
|
170
|
-
"Note on error types. Failures detected during token parsing β
|
|
214
|
+
"Note on error types. Failures detected during token parsing β wrong shape, invalid Base64URL, payload over 4096 bytes, non-JSON payload, missing required fields β throw a plain `Error`, before any attestation layer is consulted. Every failure **after** parsing throws an `AttestationError`. Integration code should handle both."
|
|
171
215
|
|
|
172
216
|
### Verification modes
|
|
173
217
|
|
|
@@ -217,8 +261,7 @@ entire branch: current **and** future sessions under it.
|
|
|
217
261
|
|
|
218
262
|
The modes coexist naturally: internal telemetry verified with Mode 1,
|
|
219
263
|
external access granted via Mode 2 β see
|
|
220
|
-
[USE_CASES.md](./USE_CASES.md) for
|
|
221
|
-
charging, drone fleets, corporate messenger).
|
|
264
|
+
[USE_CASES.md](./USE_CASES.md) for all nine production scenarios.
|
|
222
265
|
|
|
223
266
|
## π API Reference
|
|
224
267
|
|
|
@@ -337,15 +380,18 @@ produce identical keys across platforms and entry points.
|
|
|
337
380
|
|
|
338
381
|
## π― Core Use Cases
|
|
339
382
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
383
|
+
Mapped to the official registry β see [USE_CASES.md](./USE_CASES.md):
|
|
384
|
+
|
|
385
|
+
- **UC-5 β Deterministic password manager** β derive secrets per service, store nothing.
|
|
386
|
+
- **UC-2 β IoT fleets with encrypted channels** β devices operate fully offline.
|
|
387
|
+
- **Stateless multi-device sync** β same seed β same handles everywhere (spans UC-3/UC-4).
|
|
388
|
+
- **UC-1 / UC-2 β Delegatable access control** β attestation chains grant scope- and
|
|
389
|
+
time-limited access, verifiable by external parties.
|
|
345
390
|
|
|
346
|
-
π **[USE_CASES.md](./USE_CASES.md)** β
|
|
347
|
-
|
|
348
|
-
|
|
391
|
+
π **[USE_CASES.md](./USE_CASES.md)** β nine scenarios: AI agents, satellite capacity
|
|
392
|
+
marketplace, drone fleet management, multi-app SSO, multi-context identity, EV
|
|
393
|
+
charging, corporate messenger, password manager, E2EE messenger β plus a production
|
|
394
|
+
Redis `RevocationChecker`.
|
|
349
395
|
|
|
350
396
|
## π Cryptographic Details
|
|
351
397
|
|
|
@@ -374,7 +420,7 @@ access marketplace, corporate messenger, and a production Redis
|
|
|
374
420
|
- Don't reuse Handles across unrelated contexts.
|
|
375
421
|
- Don't log private keys or seed phrases.
|
|
376
422
|
- Don't rely on zeroing buffers as a hard guarantee β GC/JIT may retain
|
|
377
|
-
copies (tracked in [BACKLOG](
|
|
423
|
+
copies (tracked in [BACKLOG](../../BACKLOG.md) BL-07).
|
|
378
424
|
|
|
379
425
|
## π§ͺ Testing
|
|
380
426
|
|
|
@@ -382,20 +428,22 @@ access marketplace, corporate messenger, and a production Redis
|
|
|
382
428
|
cd packages/core && pnpm test
|
|
383
429
|
```
|
|
384
430
|
|
|
385
|
-
|
|
431
|
+
186 tests cover: deterministic derivation and cross-entry-point key
|
|
386
432
|
consistency, name canonicalization, session lifecycle (create, verify,
|
|
387
433
|
tamper, expiry, iat), revocation, SubHandle constraint enforcement,
|
|
388
434
|
MAX_DEPTH leaf enforcement, attestation issue/decode/signature
|
|
389
435
|
determinism and validation, and the full `verifyAttested` chain
|
|
390
436
|
(20+ cases including nesting, wildcard permitting, revocation at every
|
|
391
|
-
level,
|
|
437
|
+
level, signature robustness, BIP39 passphrase derivation, and wordlist
|
|
438
|
+
validation).
|
|
392
439
|
|
|
393
440
|
## πΊοΈ Roadmap
|
|
394
441
|
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
442
|
+
Passphrase support has shipped (0.7.0). Remaining recommendations β
|
|
443
|
+
session lineage (`sid`), key zeroing, attestation reference compression,
|
|
444
|
+
and the full package strategy (`@me2em/crypto`, `@me2em/messenger`,
|
|
445
|
+
`@me2em/iot`) β live in [BACKLOG.md](../../BACKLOG.md). The backlog is
|
|
446
|
+
advisory and not part of the shipped API contract.
|
|
399
447
|
|
|
400
448
|
## π License
|
|
401
449
|
|
package/dist/crypto/hkdf.d.ts
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
|
|
2
1
|
/**
|
|
3
2
|
* HKDF-SHA256 wrapper for me2em protocol
|
|
4
3
|
*
|
|
@@ -9,5 +8,6 @@ import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
|
|
|
9
8
|
* @returns Derived key as Uint8Array
|
|
10
9
|
*/
|
|
11
10
|
export declare function hkdf(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Uint8Array;
|
|
12
|
-
|
|
11
|
+
/** SHA-256 hash function. */
|
|
12
|
+
export declare function sha256(input: Uint8Array): Uint8Array;
|
|
13
13
|
//# sourceMappingURL=hkdf.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hkdf.d.ts","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"hkdf.d.ts","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAClB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,UAAU,CAEZ;AAED,6BAA6B;AAC7B,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAEpD"}
|
package/dist/crypto/hkdf.js
CHANGED
|
@@ -13,5 +13,8 @@ import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
|
|
|
13
13
|
export function hkdf(ikm, salt, info, length) {
|
|
14
14
|
return nobleHkdf(nobleSha256, ikm, salt, info, length);
|
|
15
15
|
}
|
|
16
|
-
|
|
16
|
+
/** SHA-256 hash function. */
|
|
17
|
+
export function sha256(input) {
|
|
18
|
+
return nobleSha256(input);
|
|
19
|
+
}
|
|
17
20
|
//# sourceMappingURL=hkdf.js.map
|
package/dist/crypto/hkdf.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hkdf.js","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAClB,GAAe,EACf,IAAgB,EAChB,IAAgB,EAChB,MAAc;IAEd,OAAO,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,OAAO,
|
|
1
|
+
{"version":3,"file":"hkdf.js","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAClB,GAAe,EACf,IAAgB,EAChB,IAAgB,EAChB,MAAc;IAEd,OAAO,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,MAAM,CAAC,KAAiB;IACtC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}
|
package/dist/index.d.ts
CHANGED
|
@@ -29,5 +29,6 @@ export * as crypto from './crypto/index.js';
|
|
|
29
29
|
* const signature = await handle.sign(new TextEncoder().encode('data'));
|
|
30
30
|
* ```
|
|
31
31
|
*/
|
|
32
|
-
export { generateSeedPhrase, normalizeSeedPhrase, validateSeedPhrase, get32ByteSeedFromMnemonic, type SeedStrength } from './seed.js';
|
|
32
|
+
export { generateSeedPhrase, normalizeSeedPhrase, validateSeedPhrase, get32ByteSeedFromMnemonic, type SeedStrength, type SeedValidationResult } from './seed.js';
|
|
33
|
+
export { wordlist } from '@scure/bip39/wordlists/english';
|
|
33
34
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC9M,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,YAAY,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC9M,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -30,4 +30,5 @@ export * as crypto from './crypto/index.js';
|
|
|
30
30
|
* ```
|
|
31
31
|
*/
|
|
32
32
|
export { generateSeedPhrase, normalizeSeedPhrase, validateSeedPhrase, get32ByteSeedFromMnemonic } from './seed.js';
|
|
33
|
+
export { wordlist } from '@scure/bip39/wordlists/english';
|
|
33
34
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAA0B,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,OAAO,EAAoE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,uBAAuB,EAAoG,MAAM,kBAAkB,CAAC;AAC9M,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAA0B,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,OAAO,EAAoE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,uBAAuB,EAAoG,MAAM,kBAAkB,CAAC;AAC9M,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EAG1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC"}
|
package/dist/seed.d.ts
CHANGED
|
@@ -45,27 +45,34 @@ export declare function generateSeedPhrase(strength?: SeedStrength): string[];
|
|
|
45
45
|
* ```
|
|
46
46
|
*/
|
|
47
47
|
export declare function normalizeSeedPhrase(seedPhrase: string | string[]): string[];
|
|
48
|
+
export interface SeedValidationResult {
|
|
49
|
+
isValid: boolean;
|
|
50
|
+
error?: string;
|
|
51
|
+
wordCount: number;
|
|
52
|
+
invalidWords: string[];
|
|
53
|
+
}
|
|
48
54
|
/**
|
|
49
|
-
* Validates a mnemonic seed phrase against the BIP39 standard
|
|
55
|
+
* Validates a mnemonic seed phrase against the BIP39 standard with
|
|
56
|
+
* detailed feedback.
|
|
50
57
|
*
|
|
51
|
-
* Checks:
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
58
|
+
* Checks (in order):
|
|
59
|
+
* 1. Word count must be 12 or 24.
|
|
60
|
+
* 2. Each word must exist in the BIP39 English wordlist.
|
|
61
|
+
* 3. Checksum must be valid.
|
|
55
62
|
*
|
|
56
63
|
* @param words - The mnemonic phrase to validate.
|
|
57
|
-
* @returns
|
|
64
|
+
* @returns A result object with isValid, error, wordCount, and invalidWords.
|
|
58
65
|
*
|
|
59
66
|
* @example
|
|
60
67
|
* ```ts
|
|
61
68
|
* const result = validateSeedPhrase(['abandon', 'abandon', ..., 'art']);
|
|
62
|
-
* if (!result.isValid)
|
|
69
|
+
* if (!result.isValid) {
|
|
70
|
+
* console.error(result.error);
|
|
71
|
+
* console.log('Invalid words:', result.invalidWords);
|
|
72
|
+
* }
|
|
63
73
|
* ```
|
|
64
74
|
*/
|
|
65
|
-
export declare function validateSeedPhrase(words: string[]):
|
|
66
|
-
isValid: boolean;
|
|
67
|
-
error?: string;
|
|
68
|
-
};
|
|
75
|
+
export declare function validateSeedPhrase(words: string[]): SeedValidationResult;
|
|
69
76
|
/**
|
|
70
77
|
* Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
|
|
71
78
|
* This is the standard BIP39 derivation function that converts a human-readable
|
package/dist/seed.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,CAAC;AAErC;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,YAAkB,GAAG,MAAM,EAAE,CAMzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAK3E;AAED
|
|
1
|
+
{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,CAAC;AAErC;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,YAAkB,GAAG,MAAM,EAAE,CAMzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAK3E;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAmCxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,EAC7B,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,UAAU,CAAC,CAUrB"}
|
package/dist/seed.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// seed.ts
|
|
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
4
|
import { sha256 } from './crypto/hkdf.js';
|
|
@@ -53,35 +53,57 @@ export function normalizeSeedPhrase(seedPhrase) {
|
|
|
53
53
|
return words.map(word => word.toLowerCase().trim()).filter(word => word.length > 0);
|
|
54
54
|
}
|
|
55
55
|
/**
|
|
56
|
-
* Validates a mnemonic seed phrase against the BIP39 standard
|
|
56
|
+
* Validates a mnemonic seed phrase against the BIP39 standard with
|
|
57
|
+
* detailed feedback.
|
|
57
58
|
*
|
|
58
|
-
* Checks:
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
59
|
+
* Checks (in order):
|
|
60
|
+
* 1. Word count must be 12 or 24.
|
|
61
|
+
* 2. Each word must exist in the BIP39 English wordlist.
|
|
62
|
+
* 3. Checksum must be valid.
|
|
62
63
|
*
|
|
63
64
|
* @param words - The mnemonic phrase to validate.
|
|
64
|
-
* @returns
|
|
65
|
+
* @returns A result object with isValid, error, wordCount, and invalidWords.
|
|
65
66
|
*
|
|
66
67
|
* @example
|
|
67
68
|
* ```ts
|
|
68
69
|
* const result = validateSeedPhrase(['abandon', 'abandon', ..., 'art']);
|
|
69
|
-
* if (!result.isValid)
|
|
70
|
+
* if (!result.isValid) {
|
|
71
|
+
* console.error(result.error);
|
|
72
|
+
* console.log('Invalid words:', result.invalidWords);
|
|
73
|
+
* }
|
|
70
74
|
* ```
|
|
71
75
|
*/
|
|
72
76
|
export function validateSeedPhrase(words) {
|
|
73
|
-
const wordCount = words.length;
|
|
74
|
-
if (wordCount !== 12 && wordCount !== 24) {
|
|
75
|
-
return { isValid: false, error: `Seed phrase must be 12 or 24 words, got ${wordCount}` };
|
|
76
|
-
}
|
|
77
77
|
const normalized = normalizeSeedPhrase(words);
|
|
78
|
+
const invalidWords = [];
|
|
78
79
|
for (const word of normalized) {
|
|
79
80
|
if (!wordlist.includes(word)) {
|
|
80
|
-
|
|
81
|
+
invalidWords.push(word);
|
|
81
82
|
}
|
|
82
83
|
}
|
|
84
|
+
if (normalized.length !== 12 && normalized.length !== 24) {
|
|
85
|
+
return {
|
|
86
|
+
isValid: false,
|
|
87
|
+
error: `Seed phrase must be 12 or 24 words, got ${normalized.length}`,
|
|
88
|
+
wordCount: normalized.length,
|
|
89
|
+
invalidWords,
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
if (invalidWords.length > 0) {
|
|
93
|
+
return {
|
|
94
|
+
isValid: false,
|
|
95
|
+
error: `Invalid words found: ${invalidWords.join(', ')}`,
|
|
96
|
+
wordCount: normalized.length,
|
|
97
|
+
invalidWords,
|
|
98
|
+
};
|
|
99
|
+
}
|
|
83
100
|
const isValid = validateMnemonic(normalized.join(' '), wordlist);
|
|
84
|
-
return {
|
|
101
|
+
return {
|
|
102
|
+
isValid,
|
|
103
|
+
error: isValid ? undefined : 'Invalid seed phrase checksum',
|
|
104
|
+
wordCount: normalized.length,
|
|
105
|
+
invalidWords: [],
|
|
106
|
+
};
|
|
85
107
|
}
|
|
86
108
|
/**
|
|
87
109
|
* Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
|
package/dist/seed.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA,
|
|
1
|
+
{"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@me2em/core",
|
|
3
|
-
"version": "0.7.0-alpha.
|
|
3
|
+
"version": "0.7.0-alpha.2",
|
|
4
4
|
"description": "Core primitives for the Me2em authorization protocol: Identity, Handle, and Session",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -39,6 +39,7 @@
|
|
|
39
39
|
"test": "vitest run",
|
|
40
40
|
"test:coverage": "vitest run --coverage",
|
|
41
41
|
"lint": "eslint src",
|
|
42
|
-
"typecheck": "tsc --noEmit"
|
|
42
|
+
"typecheck": "tsc --noEmit",
|
|
43
|
+
"build-docs": "typedoc"
|
|
43
44
|
}
|
|
44
45
|
}
|
package/src/crypto/hkdf.ts
CHANGED
package/src/index.ts
CHANGED
package/src/seed.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// seed.ts
|
|
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
4
|
import { sha256 } from './crypto/hkdf.js';
|
|
@@ -65,36 +65,69 @@ export function normalizeSeedPhrase(seedPhrase: string | string[]): string[] {
|
|
|
65
65
|
return words.map(word => word.toLowerCase().trim()).filter(word => word.length > 0);
|
|
66
66
|
}
|
|
67
67
|
|
|
68
|
+
export interface SeedValidationResult {
|
|
69
|
+
isValid: boolean;
|
|
70
|
+
error?: string;
|
|
71
|
+
wordCount: number;
|
|
72
|
+
invalidWords: string[];
|
|
73
|
+
}
|
|
74
|
+
|
|
68
75
|
/**
|
|
69
|
-
* Validates a mnemonic seed phrase against the BIP39 standard
|
|
76
|
+
* Validates a mnemonic seed phrase against the BIP39 standard with
|
|
77
|
+
* detailed feedback.
|
|
70
78
|
*
|
|
71
|
-
* Checks:
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
79
|
+
* Checks (in order):
|
|
80
|
+
* 1. Word count must be 12 or 24.
|
|
81
|
+
* 2. Each word must exist in the BIP39 English wordlist.
|
|
82
|
+
* 3. Checksum must be valid.
|
|
75
83
|
*
|
|
76
84
|
* @param words - The mnemonic phrase to validate.
|
|
77
|
-
* @returns
|
|
85
|
+
* @returns A result object with isValid, error, wordCount, and invalidWords.
|
|
78
86
|
*
|
|
79
87
|
* @example
|
|
80
88
|
* ```ts
|
|
81
89
|
* const result = validateSeedPhrase(['abandon', 'abandon', ..., 'art']);
|
|
82
|
-
* if (!result.isValid)
|
|
90
|
+
* if (!result.isValid) {
|
|
91
|
+
* console.error(result.error);
|
|
92
|
+
* console.log('Invalid words:', result.invalidWords);
|
|
93
|
+
* }
|
|
83
94
|
* ```
|
|
84
95
|
*/
|
|
85
|
-
export function validateSeedPhrase(words: string[]):
|
|
86
|
-
const wordCount = words.length;
|
|
87
|
-
if (wordCount !== 12 && wordCount !== 24) {
|
|
88
|
-
return { isValid: false, error: `Seed phrase must be 12 or 24 words, got ${wordCount}` };
|
|
89
|
-
}
|
|
96
|
+
export function validateSeedPhrase(words: string[]): SeedValidationResult {
|
|
90
97
|
const normalized = normalizeSeedPhrase(words);
|
|
98
|
+
const invalidWords: string[] = [];
|
|
99
|
+
|
|
91
100
|
for (const word of normalized) {
|
|
92
101
|
if (!wordlist.includes(word)) {
|
|
93
|
-
|
|
102
|
+
invalidWords.push(word);
|
|
94
103
|
}
|
|
95
104
|
}
|
|
105
|
+
|
|
106
|
+
if (normalized.length !== 12 && normalized.length !== 24) {
|
|
107
|
+
return {
|
|
108
|
+
isValid: false,
|
|
109
|
+
error: `Seed phrase must be 12 or 24 words, got ${normalized.length}`,
|
|
110
|
+
wordCount: normalized.length,
|
|
111
|
+
invalidWords,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
if (invalidWords.length > 0) {
|
|
116
|
+
return {
|
|
117
|
+
isValid: false,
|
|
118
|
+
error: `Invalid words found: ${invalidWords.join(', ')}`,
|
|
119
|
+
wordCount: normalized.length,
|
|
120
|
+
invalidWords,
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
96
124
|
const isValid = validateMnemonic(normalized.join(' '), wordlist);
|
|
97
|
-
return {
|
|
125
|
+
return {
|
|
126
|
+
isValid,
|
|
127
|
+
error: isValid ? undefined : 'Invalid seed phrase checksum',
|
|
128
|
+
wordCount: normalized.length,
|
|
129
|
+
invalidWords: [],
|
|
130
|
+
};
|
|
98
131
|
}
|
|
99
132
|
|
|
100
133
|
/**
|