@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.
- package/README.md +159 -373
- package/dist/crypto/ed25519.d.ts +12 -0
- package/dist/crypto/ed25519.d.ts.map +1 -0
- package/dist/crypto/ed25519.js +12 -0
- package/dist/crypto/ed25519.js.map +1 -0
- package/dist/crypto/hkdf.d.ts +13 -0
- package/dist/crypto/hkdf.d.ts.map +1 -0
- package/dist/crypto/hkdf.js +16 -0
- package/dist/crypto/hkdf.js.map +1 -0
- package/dist/crypto/index.d.ts +3 -0
- package/dist/crypto/index.d.ts.map +1 -0
- package/dist/crypto/index.js +3 -0
- package/dist/crypto/index.js.map +1 -0
- package/dist/crypto/init.d.ts +9 -0
- package/dist/crypto/init.d.ts.map +1 -0
- package/dist/crypto/init.js +16 -0
- package/dist/crypto/init.js.map +1 -0
- package/dist/handle.d.ts +87 -0
- package/dist/handle.d.ts.map +1 -0
- package/dist/handle.js +113 -0
- package/dist/handle.js.map +1 -0
- package/dist/identity.d.ts +43 -0
- package/dist/identity.d.ts.map +1 -0
- package/dist/identity.js +71 -0
- package/dist/identity.js.map +1 -0
- package/dist/index.d.ts +29 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +29 -0
- package/dist/index.js.map +1 -0
- package/dist/seed.d.ts +96 -0
- package/dist/seed.d.ts.map +1 -0
- package/dist/seed.js +127 -0
- package/dist/seed.js.map +1 -0
- package/dist/session.d.ts +41 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/session.js +37 -0
- package/dist/session.js.map +1 -0
- package/package.json +36 -12
- package/.github/workflows/ci.yml +0 -0
- package/CODE_OF_CONDUCT.md +0 -73
- package/CONTRIBUTING.md +0 -145
- package/GOVERNANCE.md +0 -132
- package/SECURITY.md +0 -70
- package/packages/core/README.md +0 -656
- package/packages/core/package.json +0 -44
- package/packages/core/test/derivation.spec.ts +0 -117
- package/packages/core/tsconfig.json +0 -9
- package/pnpm-workspace.yaml +0 -2
- package/specs/core.md +0 -44
- package/specs/openapi/server-ref.yaml +0 -10
- package/specs/test-vectors.json +0 -13
- package/tsconfig.base.json +0 -20
- package/typedoc.json +0 -18
- /package/{packages/core/src → src}/crypto/ed25519.ts +0 -0
- /package/{packages/core/src → src}/crypto/hkdf.ts +0 -0
- /package/{packages/core/src → src}/crypto/index.ts +0 -0
- /package/{packages/core/src → src}/crypto/init.ts +0 -0
- /package/{packages/core/src → src}/handle.ts +0 -0
- /package/{packages/core/src → src}/identity.ts +0 -0
- /package/{packages/core/src → src}/index.ts +0 -0
- /package/{packages/core/src → src}/seed.ts +0 -0
- /package/{packages/core/src → src}/session.ts +0 -0
package/README.md
CHANGED
|
@@ -1,14 +1,25 @@
|
|
|
1
|
-
# 📦 `@me2em/core` —
|
|
1
|
+
# 📦 `@me2em/core` — Core Cryptographic Primitives
|
|
2
2
|
|
|
3
|
-
> Core primitives for the Me2em authorization protocol: `Identity`, `Handle`, and
|
|
3
|
+
> Core primitives for the Me2em authorization protocol: `Identity`, `Handle`, and secure channel derivation with Ed25519 cryptography.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@me2em/core)
|
|
6
|
-
[](https://github.com/me2em-org/me2em-protocol/blob/main/LICENSE)
|
|
6
|
+
[](https://github.com/me2em-org/me2em-protocol/blob/main/LICENSE)
|
|
7
7
|
[](https://docs.me2em.com)
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
## 🎯
|
|
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
|
|
25
|
-
const seed =
|
|
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
|
|
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
|
|
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
|
-
`
|
|
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
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
**
|
|
111
|
-
-
|
|
112
|
-
|
|
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
|
|
124
|
-
static fromSeed(seed: Uint8Array
|
|
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
|
-
|
|
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
|
-
|
|
141
|
-
const
|
|
142
|
-
|
|
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
|
-
|
|
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('
|
|
151
|
-
displayName: 'Alice
|
|
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
|
-
|
|
158
|
-
- `
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
288
|
+
**Returns:** 32-byte `Uint8Array` suitable for AES-256-GCM encryption.
|
|
276
289
|
|
|
277
|
-
|
|
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
|
-
|
|
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.
|
|
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'
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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/
|
|
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.
|
|
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
|
-
##
|
|
853
|
-
|
|
854
|
-
This package is part of the Me2em ecosystem:
|
|
642
|
+
## 🤝 Contributing
|
|
855
643
|
|
|
856
|
-
|
|
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
|
-
|
|
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
|
|