@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 CHANGED
@@ -1,4 +1,4 @@
1
- # πŸ“¦ `@me2em/core` β€” Core Cryptographic Primitives
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
  [![npm version](https://img.shields.io/npm/v/@me2em/core.svg)](https://www.npmjs.com/package/@me2em/core)
9
- [![License](https://img.shields.io/npm/l/@me2em/core.svg)](https://github.com/me2em/core/blob/main/LICENSE)
10
- [![Docs](https://img.shields.io/badge/docs-docs.me2em.com-blue)](https://docs.me2em.com)
9
+ [![License](https://img.shields.io/npm/l/@me2em/core.svg)](./LICENSE)
10
+ [![Docs](https://img.shields.io/badge/docs-core.me2em.com-blue)](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 β€” wrongshape, invalid Base64URL, payload over 4096 bytes, non-JSON payload,missing required fields β€” throw a plain Error, before any attestationlayer is consulted. Every failure after parsing throwsAttestationError. Integration code should handle both."
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 full production scenarios (EV
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
- 1. **Deterministic password manager** β€” derive secrets per service, store nothing.
341
- 2. **IoT fleets with encrypted channels** β€” devices operate fully offline.
342
- 3. **Stateless multi-device sync** β€” same seed β†’ same handles everywhere.
343
- 4. **Delegatable access control** β€” attestation chains grant scope- and
344
- time-limited access to components, verifiable by external parties.
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)** β€” EV charging stations, drone fleet
347
- access marketplace, corporate messenger, and a production Redis
348
- `RevocationChecker`.
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](./BACKLOG.md) BL-07).
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
- 166 tests cover: deterministic derivation and cross-entry-point key
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, and signature robustness).
437
+ level, signature robustness, BIP39 passphrase derivation, and wordlist
438
+ validation).
392
439
 
393
440
  ## πŸ—ΊοΈ Roadmap
394
441
 
395
- Recommendations for further development β€” including BIP39 passphrase
396
- support, revocation lineage (`sid`), key zeroing, and attestation
397
- reference compression β€” live in [BACKLOG.md](./BACKLOG.md).
398
- The backlog is advisory and not part of the shipped API contract.
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
 
@@ -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
- export { nobleSha256 as sha256 };
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":"AAGA,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAClB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,UAAU,CAEZ;AAED,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,CAAC"}
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"}
@@ -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
- export { nobleSha256 as sha256 };
16
+ /** SHA-256 hash function. */
17
+ export function sha256(input) {
18
+ return nobleSha256(input);
19
+ }
17
20
  //# sourceMappingURL=hkdf.js.map
@@ -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,EAAE,WAAW,IAAI,MAAM,EAAE,CAAC"}
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
@@ -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,EAClB,MAAM,WAAW,CAAC"}
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,EAE1B,MAAM,WAAW,CAAC"}
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
- * - Correct word count (12 or 24 words)
53
- * - All words exist in the BIP39 wordlist
54
- * - Valid checksum
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 An object with `isValid` flag and optional `error` message.
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) console.error(result.error);
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
@@ -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;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAaxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,EAC7B,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,UAAU,CAAC,CAUrB"}
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
- * - Correct word count (12 or 24 words)
60
- * - All words exist in the BIP39 wordlist
61
- * - Valid checksum
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 An object with `isValid` flag and optional `error` message.
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) console.error(result.error);
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
- return { isValid: false, error: `Invalid word: ${word}` };
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 { isValid, error: isValid ? undefined : 'Invalid seed phrase checksum' };
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,UAAU;AACV,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAW1C;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAyB,GAAG;IAC7D,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACtD,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAA6B;IAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACrC,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAe;IAChD,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;IAC/B,IAAI,SAAS,KAAK,EAAE,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,2CAA2C,SAAS,EAAE,EAAE,CAAC;IAC3F,CAAC;IACD,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;IACjE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,8BAA8B,EAAE,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,UAA6B,EAC7B,aAAqB,EAAE;IAEvB,MAAM,KAAK,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,wBAAwB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5E,wEAAwE;IACxE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}
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.1",
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
  }
@@ -21,4 +21,7 @@ export function hkdf(
21
21
  return nobleHkdf(nobleSha256, ikm, salt, info, length);
22
22
  }
23
23
 
24
- export { nobleSha256 as sha256 };
24
+ /** SHA-256 hash function. */
25
+ export function sha256(input: Uint8Array): Uint8Array {
26
+ return nobleSha256(input);
27
+ }
package/src/index.ts CHANGED
@@ -35,5 +35,7 @@ export {
35
35
  normalizeSeedPhrase,
36
36
  validateSeedPhrase,
37
37
  get32ByteSeedFromMnemonic,
38
- type SeedStrength
38
+ type SeedStrength,
39
+ type SeedValidationResult
39
40
  } from './seed.js';
41
+ export { wordlist } from '@scure/bip39/wordlists/english';
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
- * - Correct word count (12 or 24 words)
73
- * - All words exist in the BIP39 wordlist
74
- * - Valid checksum
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 An object with `isValid` flag and optional `error` message.
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) console.error(result.error);
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[]): { isValid: boolean; error?: 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
- return { isValid: false, error: `Invalid word: ${word}` };
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 { isValid, error: isValid ? undefined : 'Invalid seed phrase checksum' };
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
  /**