@me2em/core 0.4.4-alpha.1 → 0.6.0-alpha.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.
Files changed (92) hide show
  1. package/README.md +299 -766
  2. package/dist/attestation.d.ts +151 -0
  3. package/dist/attestation.d.ts.map +1 -0
  4. package/dist/attestation.js +279 -0
  5. package/dist/attestation.js.map +1 -0
  6. package/dist/canonical-name.d.ts +3 -0
  7. package/dist/canonical-name.d.ts.map +1 -0
  8. package/dist/canonical-name.js +12 -0
  9. package/dist/canonical-name.js.map +1 -0
  10. package/dist/crypto/derivation-paths.d.ts +41 -0
  11. package/dist/crypto/derivation-paths.d.ts.map +1 -0
  12. package/dist/crypto/derivation-paths.js +50 -0
  13. package/dist/crypto/derivation-paths.js.map +1 -0
  14. package/dist/crypto/ed25519.d.ts +52 -0
  15. package/dist/crypto/ed25519.d.ts.map +1 -0
  16. package/dist/crypto/ed25519.js +67 -0
  17. package/dist/crypto/ed25519.js.map +1 -0
  18. package/dist/crypto/hkdf.d.ts +13 -0
  19. package/dist/crypto/hkdf.d.ts.map +1 -0
  20. package/dist/crypto/hkdf.js +17 -0
  21. package/dist/crypto/hkdf.js.map +1 -0
  22. package/dist/crypto/index.d.ts +4 -0
  23. package/dist/crypto/index.d.ts.map +1 -0
  24. package/dist/crypto/index.js +5 -0
  25. package/dist/crypto/index.js.map +1 -0
  26. package/dist/crypto/init.d.ts +9 -0
  27. package/dist/crypto/init.d.ts.map +1 -0
  28. package/dist/crypto/init.js +17 -0
  29. package/dist/crypto/init.js.map +1 -0
  30. package/dist/handle.d.ts +206 -0
  31. package/dist/handle.d.ts.map +1 -0
  32. package/dist/handle.js +258 -0
  33. package/dist/handle.js.map +1 -0
  34. package/dist/identity.d.ts +123 -0
  35. package/dist/identity.d.ts.map +1 -0
  36. package/dist/identity.js +167 -0
  37. package/dist/identity.js.map +1 -0
  38. package/dist/index.d.ts +33 -0
  39. package/dist/index.d.ts.map +1 -0
  40. package/dist/index.js +33 -0
  41. package/dist/index.js.map +1 -0
  42. package/dist/seed.d.ts +83 -0
  43. package/dist/seed.d.ts.map +1 -0
  44. package/dist/seed.js +117 -0
  45. package/dist/seed.js.map +1 -0
  46. package/dist/session.d.ts +231 -0
  47. package/dist/session.d.ts.map +1 -0
  48. package/dist/session.js +454 -0
  49. package/dist/session.js.map +1 -0
  50. package/dist/subhandle.d.ts +126 -0
  51. package/dist/subhandle.d.ts.map +1 -0
  52. package/dist/subhandle.js +158 -0
  53. package/dist/subhandle.js.map +1 -0
  54. package/dist/util.d.ts +9 -0
  55. package/dist/util.d.ts.map +1 -0
  56. package/dist/util.js +34 -0
  57. package/dist/util.js.map +1 -0
  58. package/package.json +36 -12
  59. package/src/attestation.ts +364 -0
  60. package/src/canonical-name.ts +12 -0
  61. package/src/crypto/derivation-paths.ts +56 -0
  62. package/src/crypto/ed25519.ts +86 -0
  63. package/{packages/core/src → src}/crypto/hkdf.ts +2 -0
  64. package/src/crypto/index.ts +4 -0
  65. package/{packages/core/src → src}/crypto/init.ts +1 -0
  66. package/src/handle.ts +320 -0
  67. package/src/identity.ts +218 -0
  68. package/{packages/core/src → src}/index.ts +5 -1
  69. package/{packages/core/src → src}/seed.ts +41 -54
  70. package/src/session.ts +660 -0
  71. package/src/subhandle.ts +230 -0
  72. package/src/util.ts +35 -0
  73. package/.github/workflows/ci.yml +0 -0
  74. package/CODE_OF_CONDUCT.md +0 -73
  75. package/CONTRIBUTING.md +0 -145
  76. package/GOVERNANCE.md +0 -132
  77. package/SECURITY.md +0 -70
  78. package/packages/core/README.md +0 -656
  79. package/packages/core/package.json +0 -44
  80. package/packages/core/src/crypto/ed25519.ts +0 -12
  81. package/packages/core/src/crypto/index.ts +0 -2
  82. package/packages/core/src/handle.ts +0 -130
  83. package/packages/core/src/identity.ts +0 -89
  84. package/packages/core/src/session.ts +0 -47
  85. package/packages/core/test/derivation.spec.ts +0 -117
  86. package/packages/core/tsconfig.json +0 -9
  87. package/pnpm-workspace.yaml +0 -2
  88. package/specs/core.md +0 -44
  89. package/specs/openapi/server-ref.yaml +0 -10
  90. package/specs/test-vectors.json +0 -13
  91. package/tsconfig.base.json +0 -20
  92. package/typedoc.json +0 -18
@@ -1,3 +1,4 @@
1
+ // seed.ts
1
2
  import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39';
2
3
  import { wordlist } from '@scure/bip39/wordlists/english';
3
4
  import { sha256 } from './crypto/hkdf.js';
@@ -6,33 +7,31 @@ export type SeedStrength = 128 | 256; // 128 bits = 12 words, 256 bits = 24 word
6
7
 
7
8
  /**
8
9
  * Utilities for BIP39 mnemonic seed phrase generation and validation.
9
- *
10
10
  * These functions provide secure, deterministic seed phrase handling
11
11
  * compatible with the BIP39 standard.
12
- *
12
+ *
13
13
  * @category Seed Utilities
14
14
  * @packageDocumentation
15
15
  */
16
16
 
17
17
  /**
18
18
  * Generates a cryptographically secure random mnemonic seed phrase.
19
- *
20
- * @param strength - The entropy strength in bits.
19
+ *
20
+ * @param strength - The entropy strength in bits.
21
21
  * - 128 bits = 12 words (standard security)
22
22
  * - 160 bits = 15 words
23
23
  * - 192 bits = 18 words
24
24
  * - 224 bits = 21 words
25
25
  * - 256 bits = 24 words (maximum security)
26
- *
27
- * @returns A Promise resolving to a space-separated mnemonic string.
28
- *
26
+ * @returns A space-separated mnemonic string split into an array of words.
27
+ *
29
28
  * @example
30
- * ```typescript
31
- * const mnemonic12 = await generateSeedPhrase(128);
32
- * // "abandon abandon abandon ... art"
33
- *
34
- * const mnemonic24 = await generateSeedPhrase(256);
35
- * // "abandon abandon abandon ... zoo" (24 words)
29
+ * ```ts
30
+ * const mnemonic12 = generateSeedPhrase(128);
31
+ * // ["abandon", "abandon", ..., "art"]
32
+ *
33
+ * const mnemonic24 = generateSeedPhrase(256);
34
+ * // ["abandon", "abandon", ..., "zoo"] (24 words)
36
35
  * ```
37
36
  */
38
37
  export function generateSeedPhrase(strength: SeedStrength = 128): string[] {
@@ -45,42 +44,38 @@ export function generateSeedPhrase(strength: SeedStrength = 128): string[] {
45
44
 
46
45
  /**
47
46
  * Normalizes a mnemonic seed phrase by trimming whitespace and converting to lowercase.
48
- *
49
- * @param phrase - The mnemonic phrase to normalize (string or array of words).
50
- * @returns A normalized string of lowercase words separated by single spaces.
51
- *
47
+ *
48
+ * @param seedPhrase - The mnemonic phrase to normalize (string or array of words).
49
+ * @returns A normalized array of lowercase words.
50
+ *
52
51
  * @example
53
- * ```typescript
52
+ * ```ts
54
53
  * const normalized = normalizeSeedPhrase(' ABANDON abandon ART ');
55
- * // "abandon abandon art"
56
- *
57
- * const normalized2 = normalizeSeedPhrase(['abandon', ' ART ', 'zoo']);
58
- * // "abandon art zoo"
54
+ * // ["abandon", "abandon", "art"]
59
55
  * ```
60
56
  */
61
57
  export function normalizeSeedPhrase(seedPhrase: string | string[]): string[] {
62
- const words = Array.isArray(seedPhrase) ? seedPhrase : seedPhrase.trim().split(/\s+/);
58
+ const words = Array.isArray(seedPhrase)
59
+ ? seedPhrase
60
+ : seedPhrase.trim().split(/\s+/);
63
61
  return words.map(word => word.toLowerCase().trim()).filter(word => word.length > 0);
64
62
  }
65
63
 
66
64
  /**
67
65
  * Validates a mnemonic seed phrase against the BIP39 standard.
68
- *
66
+ *
69
67
  * Checks:
70
- * - Correct word count (12, 15, 18, 21, or 24 words)
68
+ * - Correct word count (12 or 24 words)
71
69
  * - All words exist in the BIP39 wordlist
72
70
  * - Valid checksum
73
- *
74
- * @param phrase - The mnemonic phrase to validate.
75
- * @returns `true` if the phrase is valid, `false` otherwise.
76
- *
71
+ *
72
+ * @param words - The mnemonic phrase to validate.
73
+ * @returns An object with `isValid` flag and optional `error` message.
74
+ *
77
75
  * @example
78
- * ```typescript
79
- * const isValid = await validateSeedPhrase('abandon abandon ... art');
80
- * // true
81
- *
82
- * const isInvalid = await validateSeedPhrase('invalid word list ...');
83
- * // false
76
+ * ```ts
77
+ * const result = validateSeedPhrase(['abandon', 'abandon', ..., 'art']);
78
+ * if (!result.isValid) console.error(result.error);
84
79
  * ```
85
80
  */
86
81
  export function validateSeedPhrase(words: string[]): { isValid: boolean; error?: string } {
@@ -88,51 +83,43 @@ export function validateSeedPhrase(words: string[]): { isValid: boolean; error?:
88
83
  if (wordCount !== 12 && wordCount !== 24) {
89
84
  return { isValid: false, error: `Seed phrase must be 12 or 24 words, got ${wordCount}` };
90
85
  }
91
-
92
86
  const normalized = normalizeSeedPhrase(words);
93
87
  for (const word of normalized) {
94
88
  if (!wordlist.includes(word)) {
95
89
  return { isValid: false, error: `Invalid word: ${word}` };
96
90
  }
97
91
  }
98
-
99
92
  const isValid = validateMnemonic(normalized.join(' '), wordlist);
100
93
  return { isValid, error: isValid ? undefined : 'Invalid seed phrase checksum' };
101
94
  }
102
95
 
103
96
  /**
104
97
  * Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
105
- *
106
98
  * This is the standard BIP39 derivation function that converts a human-readable
107
- * mnemonic into a binary seed suitable for key generation.
108
- *
109
- * @param phrase - The BIP39 mnemonic phrase (will be normalized automatically).
110
- * @param passphrase - Optional passphrase for additional security (BIP39 "25th word").
99
+ * mnemonic into a binary seed suitable for Ed25519 key generation.
100
+ *
101
+ * The resulting 64-byte BIP39 seed is hashed with SHA-256 to produce a
102
+ * deterministic 32-byte seed, as required by Ed25519.
103
+ *
104
+ * @param seedPhrase - The BIP39 mnemonic phrase (string or array of words).
111
105
  * @returns A Promise resolving to a 32-byte Uint8Array seed.
112
- *
106
+ *
113
107
  * @example
114
- * ```typescript
108
+ * ```ts
115
109
  * const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
116
110
  * // Uint8Array(32) [123, 45, 67, ...]
117
- *
118
- * const seedWithPassphrase = await get32ByteSeedFromMnemonic(
119
- * 'abandon abandon ... art',
120
- * 'mySecretPassphrase'
121
- * );
122
- * // Different seed even with same mnemonic
123
111
  * ```
124
112
  */
125
- export async function get32ByteSeedFromMnemonic(seedPhrase: string | string[]): Promise<Uint8Array> {
113
+ export async function get32ByteSeedFromMnemonic(
114
+ seedPhrase: string | string[]
115
+ ): Promise<Uint8Array> {
126
116
  const words = normalizeSeedPhrase(seedPhrase);
127
117
  const validation = validateSeedPhrase(words);
128
-
129
118
  if (!validation.isValid) {
130
119
  throw new Error(`Invalid seed phrase: ${validation.error}`);
131
120
  }
132
-
133
121
  const mnemonic = words.join(' ');
134
122
  const seed64 = await mnemonicToSeed(mnemonic);
135
-
136
123
  // Hash the 64-byte seed to get a deterministic 32-byte seed for Ed25519
137
124
  return sha256(seed64);
138
125
  }