@me2em/core 0.4.4-alpha.1 → 0.4.4-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.
Files changed (62) hide show
  1. package/README.md +159 -373
  2. package/dist/crypto/ed25519.d.ts +12 -0
  3. package/dist/crypto/ed25519.d.ts.map +1 -0
  4. package/dist/crypto/ed25519.js +12 -0
  5. package/dist/crypto/ed25519.js.map +1 -0
  6. package/dist/crypto/hkdf.d.ts +13 -0
  7. package/dist/crypto/hkdf.d.ts.map +1 -0
  8. package/dist/crypto/hkdf.js +16 -0
  9. package/dist/crypto/hkdf.js.map +1 -0
  10. package/dist/crypto/index.d.ts +3 -0
  11. package/dist/crypto/index.d.ts.map +1 -0
  12. package/dist/crypto/index.js +3 -0
  13. package/dist/crypto/index.js.map +1 -0
  14. package/dist/crypto/init.d.ts +9 -0
  15. package/dist/crypto/init.d.ts.map +1 -0
  16. package/dist/crypto/init.js +16 -0
  17. package/dist/crypto/init.js.map +1 -0
  18. package/dist/handle.d.ts +87 -0
  19. package/dist/handle.d.ts.map +1 -0
  20. package/dist/handle.js +113 -0
  21. package/dist/handle.js.map +1 -0
  22. package/dist/identity.d.ts +43 -0
  23. package/dist/identity.d.ts.map +1 -0
  24. package/dist/identity.js +71 -0
  25. package/dist/identity.js.map +1 -0
  26. package/dist/index.d.ts +29 -0
  27. package/dist/index.d.ts.map +1 -0
  28. package/dist/index.js +29 -0
  29. package/dist/index.js.map +1 -0
  30. package/dist/seed.d.ts +96 -0
  31. package/dist/seed.d.ts.map +1 -0
  32. package/dist/seed.js +127 -0
  33. package/dist/seed.js.map +1 -0
  34. package/dist/session.d.ts +41 -0
  35. package/dist/session.d.ts.map +1 -0
  36. package/dist/session.js +37 -0
  37. package/dist/session.js.map +1 -0
  38. package/package.json +36 -12
  39. package/.github/workflows/ci.yml +0 -0
  40. package/CODE_OF_CONDUCT.md +0 -73
  41. package/CONTRIBUTING.md +0 -145
  42. package/GOVERNANCE.md +0 -132
  43. package/SECURITY.md +0 -70
  44. package/packages/core/README.md +0 -656
  45. package/packages/core/package.json +0 -44
  46. package/packages/core/test/derivation.spec.ts +0 -117
  47. package/packages/core/tsconfig.json +0 -9
  48. package/pnpm-workspace.yaml +0 -2
  49. package/specs/core.md +0 -44
  50. package/specs/openapi/server-ref.yaml +0 -10
  51. package/specs/test-vectors.json +0 -13
  52. package/tsconfig.base.json +0 -20
  53. package/typedoc.json +0 -18
  54. /package/{packages/core/src → src}/crypto/ed25519.ts +0 -0
  55. /package/{packages/core/src → src}/crypto/hkdf.ts +0 -0
  56. /package/{packages/core/src → src}/crypto/index.ts +0 -0
  57. /package/{packages/core/src → src}/crypto/init.ts +0 -0
  58. /package/{packages/core/src → src}/handle.ts +0 -0
  59. /package/{packages/core/src → src}/identity.ts +0 -0
  60. /package/{packages/core/src → src}/index.ts +0 -0
  61. /package/{packages/core/src → src}/seed.ts +0 -0
  62. /package/{packages/core/src → src}/session.ts +0 -0
package/README.md CHANGED
@@ -1,14 +1,25 @@
1
- # 📦 `@me2em/core` — Developer Documentation
1
+ # 📦 `@me2em/core` — Core Cryptographic Primitives
2
2
 
3
- > Core primitives for the Me2em authorization protocol: `Identity`, `Handle`, and `Session` management with Ed25519 cryptography.
3
+ > Core primitives for the Me2em authorization protocol: `Identity`, `Handle`, and secure channel derivation with Ed25519 cryptography.
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@me2em/core.svg)](https://www.npmjs.com/package/@me2em/core)
6
- [![License](https://img.shields.io/npm/l/@me2em/core)](https://github.com/me2em-org/me2em-protocol/blob/main/LICENSE)
6
+ [![License](https://img.shields.io/npm/l/@me2em/core.svg)](https://github.com/me2em-org/me2em-protocol/blob/main/LICENSE)
7
7
  [![Docs](https://img.shields.io/badge/docs-docs.me2em.com-blue)](https://docs.me2em.com)
8
8
 
9
9
  ---
10
10
 
11
- ## 🎯 Quick Start
11
+ ## 🎯 Overview
12
+
13
+ `@me2em/core` provides the cryptographic foundation for the Me2em protocol — a decentralized multi-context identity system. It enables:
14
+
15
+ - **Hierarchical Deterministic Identities**: One seed → multiple isolated Handles
16
+ - **Zero-Knowledge Password Management**: Deterministic password derivation without storage
17
+ - **Secure Channel Communication**: Encrypted channels between Identity and Handles without key exchange
18
+ - **Stateless Authentication**: Cryptographic proof without server-side session storage
19
+
20
+ ---
21
+
22
+ ## 📦 Installation
12
23
 
13
24
  ```bash
14
25
  npm install @me2em/core
@@ -18,20 +29,30 @@ pnpm add @me2em/core
18
29
  yarn add @me2em/core
19
30
  ```
20
31
 
32
+ **Dependencies:**
33
+ - `@noble/ed25519` — Ed25519 signatures
34
+ - `@noble/hashes` — HKDF, SHA-256
35
+
36
+ ---
37
+
38
+ ## 🚀 Quick Start
39
+
40
+ ### Basic Usage
41
+
21
42
  ```typescript
22
43
  import { Identity, Handle } from '@me2em/core';
23
44
 
24
- // 1. Create or restore identity from seed
25
- const seed = 'your-32-byte-hex-seed-or-24-words';
45
+ // 1. Create Identity from seed (32 bytes)
46
+ const seed = new Uint8Array(32).fill(42); // Replace with your secure seed
26
47
  const identity = await Identity.fromSeed(seed);
27
48
 
28
- // 2. Derive a contextual handle
49
+ // 2. Derive a contextual Handle
29
50
  const workHandle = await identity.deriveHandle('work', {
30
51
  displayName: 'Alice @ Work',
31
52
  avatar: 'https://example.com/avatar.png'
32
53
  });
33
54
 
34
- // 3. Use handle for cryptographic operations
55
+ // 3. Use Handle for cryptographic operations
35
56
  const message = new TextEncoder().encode('Hello, world!');
36
57
  const signature = await workHandle.sign(message);
37
58
  const isValid = await Handle.verify(signature, message, workHandle.getPublicKey());
@@ -40,77 +61,34 @@ console.log('Handle ID:', workHandle.getId()); // base64url(publicKey)
40
61
  console.log('Signature valid:', isValid); // true
41
62
  ```
42
63
 
43
- ---
44
-
45
- ## 📚 Table of Contents
46
-
47
- 1. [Core Concepts](#-core-concepts)
48
- 2. [API Reference](#-api-reference)
49
- 3. [Use Cases](#-use-cases)
50
- 4. [Cryptographic Details](#-cryptographic-details)
51
- 5. [Integration Guide](#-integration-guide)
52
- 6. [Security Best Practices](#-security-best-practices)
53
- 7. [Testing](#-testing)
54
- 8. [Contributing](#-contributing)
55
-
56
- ---
57
-
58
- ## 🔑 Core Concepts
59
-
60
- ### Identity — Cryptographic Root
61
-
62
- `Identity` represents the root cryptographic identity derived from a seed phrase.
63
-
64
- ```
65
- Seed (32 bytes / 24 words)
66
- │
67
- ▼
68
- ┌─────────────────┐
69
- │ Identity │
70
- │ • Ed25519 key │
71
- │ • Deterministic │
72
- │ • Client-only │
73
- └─────────────────┘
74
- ```
75
-
76
- **Key properties:**
77
- - 🔐 **Never transmitted**: The root private key never leaves the client device
78
- - 🔄 **Deterministic**: Same seed → same Identity → same derived Handles
79
- - 🧩 **Stateless**: No server storage required for cryptographic operations
80
-
81
- ### Handle — Contextual Profile
82
-
83
- `Handle` is a derived Ed25519 keypair representing a specific context (work, personal, IoT device).
84
-
85
- ```
86
- Identity
87
- │
88
- ├─ deriveHandle('work') → Handle(@alice_work)
89
- ├─ deriveHandle('private') → Handle(@alice_private)
90
- └─ deriveHandle('iot-device-001') → Handle(@device_001)
91
- ```
92
-
93
- **Key properties:**
94
- - 🔗 **Cryptographically isolated**: Each Handle has its own keypair; compromise of one does not affect others
95
- - 🏷️ **Public identifier**: `Handle.getId()` returns `base64url(publicKey)` — safe to share
96
- - 📦 **Metadata support**: Attach public metadata (displayName, avatar) without revealing Identity
97
-
98
- ### Session — Scoped Access Token
64
+ ### Integration with BIP39 (Recommended)
99
65
 
100
- `Session` represents a time-limited, scoped authorization token for accessing a specific application.
66
+ For production applications, use BIP39 mnemonic phrases. `@me2em/core` provides built-in utilities to handle generation, validation, and conversion to the required 32-byte Ed25519 seed.
101
67
 
102
68
  ```typescript
103
- interface SessionOptions {
104
- audience: string; // e.g., 'https://api.myapp.com'
105
- scopes: string[]; // e.g., ['read:profile', 'write:messages']
106
- ttl?: number; // seconds until expiration (default: 3600)
107
- }
69
+ import {
70
+ Identity,
71
+ generateSeedPhrase,
72
+ get32ByteSeedFromMnemonic,
73
+ validateSeedPhrase
74
+ } from '@me2em/core';
75
+
76
+ // 1. Generate a 12-word phrase (use 256 for 24 words)
77
+ const phrase = generateSeedPhrase(128);
78
+ console.log('Your seed:', phrase.join(' '));
79
+
80
+ // 2. (Optional) Validate a user-provided phrase
81
+ const validation = validateSeedPhrase(phrase);
82
+ if (!validation.isValid) throw new Error(validation.error);
83
+
84
+ // 3. Convert to 32-byte seed and create Identity
85
+ const seedBytes = await get32ByteSeedFromMnemonic(phrase);
86
+ const identity = await Identity.fromSeed(seedBytes);
108
87
  ```
109
88
 
110
- **Key properties:**
111
- - ⏱️ **Short-lived**: Tokens expire automatically; refresh via Handle re-authentication
112
- - 🔐 **Scoped**: Each token grants only specified permissions
113
- - 🌐 **Stateless verification**: Servers verify signatures using Handle public key — no database lookup required
89
+ **Why is this better?**
90
+ BIP39 produces a 64-byte seed, but Ed25519 requires exactly 32 bytes. The `get32ByteSeedFromMnemonic` utility handles the SHA-256 hashing deterministically and safely, so you don't have to write boilerplate crypto code.
91
+
114
92
 
115
93
  ---
116
94
 
@@ -118,10 +96,12 @@ interface SessionOptions {
118
96
 
119
97
  ### `Identity` Class
120
98
 
99
+ The root cryptographic identity, derived from a seed phrase.
100
+
121
101
  ```typescript
122
102
  class Identity {
123
- // Create Identity from seed (32-byte Uint8Array or hex string)
124
- static fromSeed(seed: Uint8Array | string): Promise<Identity>;
103
+ // Create Identity from seed (32-byte Uint8Array)
104
+ static fromSeed(seed: Uint8Array): Promise<Identity>;
125
105
 
126
106
  // Derive a new Handle with optional metadata
127
107
  deriveHandle(name: string, metadata?: HandleMetadata): Promise<Handle>;
@@ -133,36 +113,66 @@ class Identity {
133
113
 
134
114
  #### `Identity.fromSeed(seed)`
135
115
 
136
- ```typescript
137
- // From hex string (64 chars = 32 bytes)
138
- const identity = await Identity.fromSeed('a1b2c3...');
116
+ Creates an Identity from a 32-byte seed.
139
117
 
140
- // From Uint8Array
141
- const seedBytes = new Uint8Array(32).fill(42);
142
- const identity = await Identity.fromSeed(seedBytes);
118
+ ```typescript
119
+ const seed = new Uint8Array(32);
120
+ crypto.getRandomValues(seed); // Generate secure random seed
121
+ const identity = await Identity.fromSeed(seed);
143
122
  ```
144
123
 
145
- ⚠️ **Security**: The seed must be kept secret. Never log, transmit, or store it in plaintext.
124
+ **Security:** The seed must be kept secret. Never log, transmit, or store it in plaintext.
146
125
 
147
126
  #### `Identity.deriveHandle(name, metadata?)`
148
127
 
128
+ Derives a new Handle deterministically from the Identity.
129
+
149
130
  ```typescript
150
- const handle = await identity.deriveHandle('work', {
151
- displayName: 'Alice Developer',
152
- avatar: 'https://example.com/alice.png',
153
- org: 'Acme Corp'
131
+ const handle = await identity.deriveHandle('google', {
132
+ displayName: 'Alice Personal',
133
+ avatar: 'https://example.com/alice.png'
154
134
  });
155
135
  ```
156
136
 
157
- - `name`: Unique identifier for this Handle within the Identity (case-insensitive, trimmed)
158
- - `metadata`: Arbitrary public data attached to the Handle (visible to servers/other users)
137
+ **Parameters:**
138
+ - `name`: Unique identifier for this Handle (case-insensitive, trimmed)
139
+ - `metadata`: Optional public data attached to the Handle
140
+
141
+ **Returns:** A `Handle` instance with its own keypair, derived deterministically from the Identity.
159
142
 
160
- Returns a `Handle` instance with its own keypair, derived deterministically from the Identity.
143
+ **Key Properties:**
144
+ - 🔁 **Deterministic**: Same seed + same name → same Handle (always)
145
+ - 🔗 **Isolated**: Each Handle has its own keypair; compromise of one does not affect others
146
+ - 🔒 **One-way**: Cannot derive Identity key from Handle key
147
+
148
+ ---
149
+
150
+ ### Seed Utilities
151
+
152
+ Built-in helpers for human-friendly key generation and validation.
153
+
154
+ ```typescript
155
+ // Generate a new phrase (128 bits = 12 words, 256 bits = 24 words)
156
+ function generateSeedPhrase(strength: 128 | 256 = 128): string[];
157
+
158
+ // Normalize input (handles extra spaces, lowercase)
159
+ function normalizeSeedPhrase(input: string | string[]): string[];
160
+
161
+ // Validate word count, wordlist, and BIP39 checksum
162
+ function validateSeedPhrase(words: string[]): { isValid: boolean; error?: string };
163
+
164
+ // Convert validated mnemonic to a secure 32-byte Uint8Array for Ed25519
165
+ async function get32ByteSeedFromMnemonic(phrase: string | string[]): Promise<Uint8Array>;
166
+ ```
167
+
168
+ ✅ **Benefit**: Developers don't need to manually manage `@scure/bip39` imports or remember to hash the 64-byte output. Everything is handled securely within the protocol.
161
169
 
162
170
  ---
163
171
 
164
172
  ### `Handle` Class
165
173
 
174
+ A derived Ed25519 keypair representing a specific context (work, personal, IoT device).
175
+
166
176
  ```typescript
167
177
  class Handle {
168
178
  // Get public identifier (safe to share)
@@ -177,7 +187,7 @@ class Handle {
177
187
  // Deterministically derive a password/secret for a specific context
178
188
  derivePassword(context: string, length?: number): string;
179
189
 
180
- // Derive a symmetric 256-bit channel key for encrypted communication
190
+ // Derive a symmetric channel key for encrypted communication
181
191
  deriveChannelKey(context: string): Uint8Array;
182
192
 
183
193
  // Accessors
@@ -236,7 +246,7 @@ if (!isValid) throw new Error('Invalid signature');
236
246
 
237
247
  #### `Handle.derivePassword(context, length?)`
238
248
 
239
- Generates a deterministic, cryptographically strong secret (e.g., a password) for a specific service, without ever exposing the private key.
249
+ Deterministically derives a secret (e.g., a password or API key) for a specific service context. The private key **never leaves this class**, ensuring maximum security.
240
250
 
241
251
  ```typescript
242
252
  // Derive a password for a specific service
@@ -247,7 +257,15 @@ const googlePassword = workHandle.derivePassword('google');
247
257
  const apiKey = workHandle.derivePassword('aws-api', 32);
248
258
  ```
249
259
 
250
- ✅ **Security Benefit**: The `privateKey` remains strictly encapsulated within the `Handle` instance. It is used internally by HKDF-SHA256 and is never returned, logged, or serialized.
260
+ **Parameters:**
261
+ - `context`: A unique identifier for the service (e.g., `'google'`, `'github'`, `'wifi-router'`)
262
+ - `length`: Length of the derived raw bytes (default: 16 bytes = ~22 chars base64url)
263
+
264
+ **Returns:** A URL-safe base64 string suitable for use as a strong password.
265
+
266
+ **Security Benefit:** The `privateKey` remains strictly encapsulated within the `Handle` instance. It is used internally by HKDF-SHA256 and is never returned, logged, or serialized.
267
+
268
+ **Use Case:** Zero-knowledge password management. No database of passwords is required on the server. If a service forces a password change, the user simply derives a new handle (e.g., `'google-v2'`) or adds a version suffix to the context.
251
269
 
252
270
  #### `Handle.deriveChannelKey(context)`
253
271
 
@@ -264,138 +282,20 @@ const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
264
282
  // Identical key, derived independently
265
283
  ```
266
284
 
267
- ✅ **Security Benefit**: The `privateKey` remains strictly encapsulated within the `Handle` instance. No key exchange protocol (ECDH, etc.) is needed — both parties derive the same key independently from the shared Handle private key.
268
-
269
- ⚠️ **Note**: This method returns raw bytes (Uint8Array), unlike `derivePassword` which returns a base64url string. Use the returned bytes directly with AES-256-GCM via Web Crypto API or similar.
270
-
271
- ---
272
-
273
- ### `Session` Class (Planned)
285
+ **Parameters:**
286
+ - `context`: Channel identifier for domain separation (e.g., `'drone-001'`, `'session-abc'`). Both parties **must** use the same context to derive the same key.
274
287
 
275
- > ⚠️ Session management is planned for v0.2. Current implementations should use custom token logic with Handle signatures.
288
+ **Returns:** 32-byte `Uint8Array` suitable for AES-256-GCM encryption.
276
289
 
277
- ```typescript
278
- // Future API (not yet implemented)
279
- const session = await handle.requestSession({
280
- audience: 'https://api.myapp.com',
281
- scopes: ['read:profile', 'write:messages'],
282
- ttl: 3600
283
- });
290
+ **Security Benefit:** The `privateKey` remains strictly encapsulated within the `Handle` instance. No key exchange protocol (ECDH, etc.) is needed — both parties derive the same key independently from the shared Handle private key.
284
291
 
285
- // Use token
286
- fetch('https://api.myapp.com/me', {
287
- headers: { Authorization: `Bearer ${session.token}` }
288
- });
289
- ```
292
+ **Note:** This method returns raw bytes (Uint8Array), unlike `derivePassword` which returns a base64url string. Use the returned bytes directly with AES-256-GCM via Web Crypto API or similar.
290
293
 
291
294
  ---
292
295
 
293
296
  ## 🎯 Use Cases
294
297
 
295
- ### 1. Multi-Context User Authentication
296
-
297
- ```typescript
298
- // User logs in with seed
299
- const identity = await Identity.fromSeed(userSeed);
300
-
301
- // Derive work handle
302
- const workHandle = await identity.deriveHandle('work', {
303
- displayName: 'Alice @ Acme',
304
- role: 'engineer'
305
- });
306
-
307
- // Authenticate to work app
308
- const workSig = await workHandle.sign(challenge);
309
- // Send workHandle.getId() + workSig to https://work.acme.com/auth
310
-
311
- // Later, derive personal handle for social app
312
- const personalHandle = await identity.deriveHandle('personal', {
313
- displayName: 'Alice',
314
- interests: ['hiking', 'photography']
315
- });
316
-
317
- // Authenticate to social app with different handle
318
- const socialSig = await personalHandle.sign(challenge);
319
- // Send personalHandle.getId() + socialSig to https://social.app/auth
320
- ```
321
-
322
- ✅ **Benefit**: One seed, multiple isolated identities. Apps see only the Handle they interact with.
323
-
324
- ---
325
-
326
- ### 2. IoT Device Hierarchy
327
-
328
- ```typescript
329
- // Root identity for device fleet
330
- const fleetIdentity = await Identity.fromSeed(fleetSeed);
331
-
332
- // Derive handle for gateway
333
- const gateway = await fleetIdentity.deriveHandle('gateway-001', {
334
- type: 'gateway',
335
- location: 'warehouse-a'
336
- });
337
-
338
- // Derive child handles for sensors (using name prefix for hierarchy)
339
- const sensor1 = await fleetIdentity.deriveHandle('gateway-001/sensor-temp', {
340
- type: 'temperature',
341
- unit: 'celsius'
342
- });
343
-
344
- const sensor2 = await fleetIdentity.deriveHandle('gateway-001/sensor-humidity', {
345
- type: 'humidity',
346
- unit: 'percent'
347
- });
348
- ```
349
-
350
- ✅ **Benefit**: Compromise of `sensor-temp` does not expose `gateway-001` or other sensors. Each device has isolated credentials.
351
-
352
- ---
353
-
354
- ### 3. Anonymous Guest Access
355
-
356
- ```typescript
357
- // Generate ephemeral seed for guest session
358
- const guestSeed = crypto.getRandomValues(new Uint8Array(32));
359
- const guestIdentity = await Identity.fromSeed(guestSeed);
360
-
361
- // Create anonymous handle
362
- const guestHandle = await guestIdentity.deriveHandle('guest', {
363
- displayName: 'Anonymous User',
364
- ephemeral: true
365
- });
366
-
367
- // Use for limited-scope access
368
- const guestSig = await guestHandle.sign(challenge);
369
- // Send to server with scope: ['read:public-content']
370
- ```
371
-
372
- ✅ **Benefit**: No email, no phone, no tracking. Guest access with cryptographic accountability.
373
-
374
- ---
375
-
376
- ### 4. Cross-App Single Sign-On (SSO)
377
-
378
- ```typescript
379
- // User authenticates once with Identity
380
- const identity = await Identity.fromSeed(seed);
381
-
382
- // App A requests session for 'app-a.example.com'
383
- const handleA = await identity.deriveHandle('app-a', { app: 'example-a' });
384
- const sessionA = { /* custom token logic */ };
385
-
386
- // App B requests session for 'app-b.example.com'
387
- const handleB = await identity.deriveHandle('app-b', { app: 'example-b' });
388
- const sessionB = { /* custom token logic */ };
389
-
390
- // User switches between apps without re-entering seed
391
- // Each app sees only its Handle, not the others
392
- ```
393
-
394
- ✅ **Benefit**: Seamless SSO with privacy isolation — apps cannot correlate user activity across services.
395
-
396
- ---
397
-
398
- ### 5. Deterministic Password Manager (Access Key Keeper)
298
+ ### 1. Deterministic Password Manager (Access Key Keeper)
399
299
 
400
300
  Instead of storing passwords in a database, derive them deterministically from the Handle. The user only needs to remember their root Seed and the service name.
401
301
 
@@ -416,9 +316,11 @@ console.log('Login:', 'alice@example.com');
416
316
  console.log('Password:', password); // Always the same for this seed + handle + context
417
317
  ```
418
318
 
419
- ✅ **Benefit**: Zero-knowledge password management. No database of passwords is required on the server. If a service forces a password change, the user simply derives a new handle (e.g., `'google-v2'`) or adds a version suffix to the context (e.g., `derivePassword('google', 16, 2)`).
319
+ ✅ **Benefit**: Zero-knowledge password management. No database of passwords is required on the server. If a service forces a password change, the user simply derives a new handle (e.g., `'google-v2'`) or adds a version suffix to the context (e.g., `derivePassword('google-v2')`).
320
+
321
+ ---
420
322
 
421
- ### 6. IoT Fleet with Encrypted Channels
323
+ ### 2. IoT Fleet with Encrypted Channels
422
324
 
423
325
  Control a fleet of devices (drones, sensors, robots) with zero-knowledge encrypted communication. The control center derives a channel key for each device, and the device independently derives the same key — no key exchange protocol required.
424
326
 
@@ -485,7 +387,7 @@ async function sendTelemetry(telemetry: object) {
485
387
 
486
388
  ---
487
389
 
488
- ### 7. Stateless Multi-Device Synchronization
390
+ ### 3. Stateless Multi-Device Synchronization
489
391
 
490
392
  A user with the same Identity on multiple devices (phone, laptop, tablet) can derive identical Handles and secrets on each device without any synchronization protocol.
491
393
 
@@ -507,7 +409,7 @@ const handleId = messengerHandle.getId(); // Identical handleId!
507
409
 
508
410
  ---
509
411
 
510
- ### 8. Break-Glass Recovery and Inheritance
412
+ ### 4. Break-Glass Recovery and Inheritance
511
413
 
512
414
  A user's entire digital identity can be recovered from a single seed phrase, even years later, on any device, without contacting any service provider.
513
415
 
@@ -534,7 +436,7 @@ const messengerChannelKey = messengerHandle.deriveChannelKey('session-2026');
534
436
 
535
437
  ---
536
438
 
537
- ### 9. Ephemeral Delegated Access
439
+ ### 5. Ephemeral Delegated Access
538
440
 
539
441
  Grant time-limited access to a contractor or temporary service by deriving a Handle with a time-bound name.
540
442
 
@@ -557,9 +459,11 @@ const contractorHandle = await identity.deriveHandle('contractor-acme-2026-12-31
557
459
 
558
460
  ✅ **Benefit**: Clean delegation without polluting the permanent identity. Expired Handles become inert cryptographic artifacts.
559
461
 
462
+ ---
463
+
560
464
  ## 🔐 Cryptographic Details
561
465
 
562
- ### Key Derivation Algorithm
466
+ ### Handle Derivation Algorithm
563
467
 
564
468
  Handles are derived using **HKDF-SHA256** with domain separation:
565
469
 
@@ -579,6 +483,25 @@ HandleId = Base64Url(HandlePublicKey)
579
483
  - 🔒 **One-way**: Cannot derive Identity key from Handle key
580
484
  - 🧩 **Isolated**: Each Handle uses independent Ed25519 keypair
581
485
 
486
+ ### Password Derivation Algorithm
487
+
488
+ Passwords are derived using **HKDF-SHA256** with the Handle's private key as input key material:
489
+
490
+ ```
491
+ PasswordBytes = HKDF-SHA256(
492
+ inputKeyMaterial = HandlePrivateKey,
493
+ salt = "me2em/secret/" + lowercase(context),
494
+ info = "me2em/secret/v1",
495
+ length = 16 (default)
496
+ )
497
+ Password = Base64Url(PasswordBytes)
498
+ ```
499
+
500
+ **Properties:**
501
+ - 🔁 **Deterministic**: Same Handle + same context → same password
502
+ - 🔐 **Encapsulated**: Private key never leaves the Handle instance
503
+ - 🧩 **Domain-separated**: Different contexts produce different passwords
504
+
582
505
  ### Channel Key Derivation
583
506
 
584
507
  Channel keys are derived using **HKDF-SHA256** with the Handle's private key as input key material:
@@ -592,7 +515,7 @@ ChannelKey = HKDF-SHA256(
592
515
  )
593
516
  ```
594
517
 
595
- **Properties**:
518
+ **Properties:**
596
519
  - 🔁 **Deterministic**: Same Handle + same context → same 32-byte key
597
520
  - 🔐 **Encapsulated**: Private key never leaves the Handle instance
598
521
  - 🧩 **Domain-separated**: Different contexts produce different keys (e.g., `'telemetry-v1'` vs `'command-v1'`)
@@ -604,91 +527,6 @@ ChannelKey = HKDF-SHA256(
604
527
  - **Hash**: SHA-512 (via `@noble/ed25519`)
605
528
  - **Encoding**: Raw bytes → base64url for transport
606
529
 
607
- ### Test Vectors
608
-
609
- See [`specs/test-vectors.json`](../../specs/test-vectors.json) for canonical derivation examples to ensure cross-implementation compatibility.
610
-
611
- Example vector:
612
- ```json
613
- {
614
- "seed_hex": "2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a",
615
- "handle_name": "work",
616
- "expected_handle_id": "pK7xJ2mN8vQ3rL5wY9zB1cD4eF6gH8iJ0kL2mN4oP6qR8sT0uV2wX4yZ6aB8cD0",
617
- "expected_public_key_hex": "a4b5c6d7e8f90123456789abcdef0123456789abcdef0123456789abcdef0123"
618
- }
619
- ```
620
-
621
- ---
622
-
623
- ## 🔌 Integration Guide
624
-
625
- ### Backend Verification (Node.js Example)
626
-
627
- ```typescript
628
- import { Handle } from '@me2em/core';
629
-
630
- // Middleware to verify Handle-signed requests
631
- export async function me2emAuthMiddleware(req: Request, res: Response, next: NextFunction) {
632
- const handleId = req.headers['x-handle-id'] as string;
633
- const signature = req.headers['x-signature'] as string;
634
- const payload = JSON.stringify(req.body);
635
-
636
- if (!handleId || !signature) {
637
- return res.status(401).json({ error: 'Missing authentication headers' });
638
- }
639
-
640
- try {
641
- // Decode base64url to Uint8Array
642
- const publicKey = base64urlToBytes(handleId);
643
- const sig = base64urlToBytes(signature);
644
- const data = new TextEncoder().encode(payload);
645
-
646
- // Verify signature
647
- const isValid = await Handle.verify(sig, data, publicKey);
648
- if (!isValid) throw new Error('Invalid signature');
649
-
650
- // Attach handle info to request for downstream use
651
- req.me2em = { handleId, publicKey };
652
- next();
653
- } catch (err) {
654
- res.status(401).json({ error: 'Authentication failed' });
655
- }
656
- }
657
-
658
- function base64urlToBytes(str: string): Uint8Array {
659
- const padding = '='.repeat((4 - (str.length % 4)) % 4);
660
- const base64 = str.replace(/-/g, '+').replace(/_/g, '/') + padding;
661
- return Uint8Array.from(atob(base64), c => c.charCodeAt(0));
662
- }
663
- ```
664
-
665
- ### Frontend Secure Key Handling
666
-
667
- ```typescript
668
- // Store encrypted seed in IndexedDB (never plaintext)
669
- import { encryptWithPin } from './crypto/local';
670
-
671
- async function saveIdentity(seed: string, pin: string) {
672
- const encrypted = await encryptWithPin(seed, pin);
673
- await db.identities.add({
674
- id: 'current',
675
- encryptedSeed: encrypted,
676
- // seed is NEVER stored in plaintext
677
- });
678
- }
679
-
680
- // Load and decrypt on login
681
- async function loadIdentity(pin: string) {
682
- const record = await db.identities.get('current');
683
- if (!record) throw new Error('No identity found');
684
-
685
- const seed = await decryptWithPin(record.encryptedSeed, pin);
686
- return Identity.fromSeed(seed);
687
- }
688
- ```
689
-
690
- ✅ **Best practice**: Use Web Crypto API or secure enclave for PIN/biometric decryption.
691
-
692
530
  ---
693
531
 
694
532
  ## 🛡️ Security Best Practices
@@ -720,7 +558,7 @@ async function loadIdentity(pin: string) {
720
558
  [Derive Handle(s) as needed]
721
559
  │
722
560
  ▼
723
- [Sign challenge / data]
561
+ [Sign challenge / data / derive password / derive channel key]
724
562
  │
725
563
  ▼
726
564
  [Zero out private key buffers] ← Critical!
@@ -736,13 +574,15 @@ async function loadIdentity(pin: string) {
736
574
  ### Unit Tests
737
575
 
738
576
  ```bash
739
- cd packages/protocol-core
577
+ cd packages/core
740
578
  pnpm test
741
579
  ```
742
580
 
743
581
  Tests cover:
744
582
  - ✅ Deterministic derivation (same seed + name → same HandleId)
745
583
  - ✅ Signature generation and verification
584
+ - ✅ Password derivation (same Handle + context → same password)
585
+ - ✅ Channel key derivation (same Handle + context → same key)
746
586
  - ✅ Edge cases (empty metadata, long names, unicode)
747
587
 
748
588
  ### Integration Test Example
@@ -768,57 +608,6 @@ test('full auth flow', async () => {
768
608
  });
769
609
  ```
770
610
 
771
- ### Cross-Implementation Testing
772
-
773
- Use [`specs/test-vectors.json`](../../specs/test-vectors.json) to verify your implementation matches the reference:
774
-
775
- ```typescript
776
- import vectors from '@me2em/core/specs/test-vectors.json';
777
-
778
- for (const vector of vectors) {
779
- const identity = await Identity.fromSeed(vector.seed_hex);
780
- const handle = await identity.deriveHandle(vector.handle_name);
781
-
782
- expect(handle.getId()).toBe(vector.expected_handle_id);
783
- expect(bytesToHex(handle.getPublicKey())).toBe(vector.expected_public_key_hex);
784
- }
785
- ```
786
-
787
- ---
788
-
789
- ## 🤝 Contributing
790
-
791
- We welcome contributions! See:
792
-
793
- - 📄 [CONTRIBUTING.md](../../CONTRIBUTING.md) — How to contribute code/docs
794
- - 🗳️ [GOVERNANCE.md](../../GOVERNANCE.md) — Project decision-making process
795
- - 🔐 [SECURITY.md](../../SECURITY.md) — Responsible disclosure policy
796
-
797
- ### Quick Start for Contributors
798
-
799
- ```bash
800
- git clone https://github.com/me2em-org/me2em-protocol.git
801
- cd me2em-protocol
802
- pnpm install
803
-
804
- # Run tests
805
- pnpm -r test
806
-
807
- # Build all packages
808
- pnpm -r build
809
-
810
- # Lint
811
- pnpm -r lint
812
- ```
813
-
814
- ### Adding a New Feature
815
-
816
- 1. Open a [Discussion](https://github.com/me2em-org/me2em-protocol/discussions) to propose the change
817
- 2. Implement in a feature branch
818
- 3. Add tests covering new functionality
819
- 4. Update `specs/core.md` if protocol behavior changes
820
- 5. Submit PR with clear description and test results
821
-
822
611
  ---
823
612
 
824
613
  ## 📦 Package Info
@@ -826,7 +615,7 @@ pnpm -r lint
826
615
  ```json
827
616
  {
828
617
  "name": "@me2em/core",
829
- "version": "0.3.0-alpha.1",
618
+ "version": "0.4.2-alpha.1",
830
619
  "type": "module",
831
620
  "main": "./dist/index.js",
832
621
  "types": "./dist/index.d.ts",
@@ -839,7 +628,8 @@ pnpm -r lint
839
628
  },
840
629
  "dependencies": {
841
630
  "@noble/ed25519": "^3.1.0",
842
- "@noble/hashes": "^2.2.0"
631
+ "@noble/hashes": "^2.2.0",
632
+ "@scure/bip39": "^1.3.0"
843
633
  },
844
634
  "engines": {
845
635
  "node": ">=18.0.0"
@@ -849,17 +639,13 @@ pnpm -r lint
849
639
 
850
640
  ---
851
641
 
852
- ## 🌐 Ecosystem
853
-
854
- This package is part of the Me2em ecosystem:
642
+ ## 🤝 Contributing
855
643
 
856
- @me2em/core ← криптография (Identity, Handle, derivePassword, deriveChannelKey)
857
- @me2em/sdk ← browser wrapper (IndexedDB, PIN, biometric, session management)
858
- @me2em/react ← UI компоненты (SeedDisplay, SeedVerification, HandleManager)
859
- @me2em/auth-middleware ← NestJS/Express middleware для Handle.verify()
860
- @me2em/server ← (опционально) готовый NestJS backend из Phase 1
644
+ We welcome contributions! See:
861
645
 
862
- 🔗 Learn more: [github.com/me2em-org](https://github.com/me2em-org) | [docs.me2em.com](https://docs.me2em.com)
646
+ - 📄 [CONTRIBUTING.md](../../CONTRIBUTING.md) — How to contribute code/docs
647
+ - 🗳️ [GOVERNANCE.md](../../GOVERNANCE.md) — Project decision-making process
648
+ - 🔐 [SECURITY.md](../../SECURITY.md) — Responsible disclosure policy
863
649
 
864
650
  ---
865
651