@me2em/core 0.4.4-alpha.2 β 0.7.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.
- package/README.md +294 -546
- package/dist/attestation.d.ts +151 -0
- package/dist/attestation.d.ts.map +1 -0
- package/dist/attestation.js +279 -0
- package/dist/attestation.js.map +1 -0
- package/dist/canonical-name.d.ts +3 -0
- package/dist/canonical-name.d.ts.map +1 -0
- package/dist/canonical-name.js +12 -0
- package/dist/canonical-name.js.map +1 -0
- package/dist/crypto/derivation-paths.d.ts +41 -0
- package/dist/crypto/derivation-paths.d.ts.map +1 -0
- package/dist/crypto/derivation-paths.js +50 -0
- package/dist/crypto/derivation-paths.js.map +1 -0
- package/dist/crypto/ed25519.d.ts +48 -8
- package/dist/crypto/ed25519.d.ts.map +1 -1
- package/dist/crypto/ed25519.js +63 -8
- package/dist/crypto/ed25519.js.map +1 -1
- package/dist/crypto/hkdf.d.ts.map +1 -1
- package/dist/crypto/hkdf.js +1 -0
- package/dist/crypto/hkdf.js.map +1 -1
- package/dist/crypto/index.d.ts +1 -0
- package/dist/crypto/index.d.ts.map +1 -1
- package/dist/crypto/index.js +2 -0
- package/dist/crypto/index.js.map +1 -1
- package/dist/crypto/init.d.ts.map +1 -1
- package/dist/crypto/init.js +1 -0
- package/dist/crypto/init.js.map +1 -1
- package/dist/handle.d.ts +149 -35
- package/dist/handle.d.ts.map +1 -1
- package/dist/handle.js +180 -40
- package/dist/handle.js.map +1 -1
- package/dist/identity.d.ts +99 -19
- package/dist/identity.d.ts.map +1 -1
- package/dist/identity.js +128 -32
- package/dist/identity.js.map +1 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -1
- package/dist/seed.d.ts +38 -39
- package/dist/seed.d.ts.map +1 -1
- package/dist/seed.js +36 -41
- package/dist/seed.js.map +1 -1
- package/dist/session.d.ts +207 -17
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +428 -11
- package/dist/session.js.map +1 -1
- package/dist/subhandle.d.ts +126 -0
- package/dist/subhandle.d.ts.map +1 -0
- package/dist/subhandle.js +182 -0
- package/dist/subhandle.js.map +1 -0
- package/dist/util.d.ts +9 -0
- package/dist/util.d.ts.map +1 -0
- package/dist/util.js +34 -0
- package/dist/util.js.map +1 -0
- package/package.json +3 -3
- package/src/attestation.ts +364 -0
- package/src/canonical-name.ts +12 -0
- package/src/crypto/derivation-paths.ts +56 -0
- package/src/crypto/ed25519.ts +82 -8
- package/src/crypto/hkdf.ts +2 -0
- package/src/crypto/index.ts +3 -1
- package/src/crypto/init.ts +1 -0
- package/src/handle.ts +227 -42
- package/src/identity.ts +164 -35
- package/src/index.ts +5 -1
- package/src/seed.ts +59 -59
- package/src/session.ts +637 -24
- package/src/subhandle.ts +254 -0
- package/src/util.ts +35 -0
package/README.md
CHANGED
|
@@ -1,23 +1,28 @@
|
|
|
1
1
|
# π¦ `@me2em/core` β Core Cryptographic Primitives
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Core primitives for the Me2em authorization protocol: hierarchical
|
|
4
|
+
deterministic identities (`Identity` β `Handle` β `SubHandle`), stateless
|
|
5
|
+
signed sessions, and parent-signed **attestation chains** for delegatable,
|
|
6
|
+
externally verifiable authorization β all on Ed25519.
|
|
4
7
|
|
|
5
8
|
[](https://www.npmjs.com/package/@me2em/core)
|
|
6
|
-
[](https://github.com/me2em
|
|
9
|
+
[](https://github.com/me2em/core/blob/main/LICENSE)
|
|
7
10
|
[](https://docs.me2em.com)
|
|
8
11
|
|
|
9
|
-
---
|
|
10
|
-
|
|
11
12
|
## π― Overview
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- **
|
|
16
|
-
|
|
17
|
-
- **
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
14
|
+
- **Hierarchical Deterministic Identities** β one seed β isolated
|
|
15
|
+
`Handle`s and `SubHandle`s (MAX_DEPTH = 2), derived offline via HKDF.
|
|
16
|
+
- **Stateless Authentication** β self-contained signed session tokens,
|
|
17
|
+
verified without server-side storage, with optional revocation.
|
|
18
|
+
- **Attestations** β a parent cryptographically binds a child key to a
|
|
19
|
+
name and a grant (audiences, scopes, TTL caps, name patterns). Chains
|
|
20
|
+
are verified **offline by third parties using only the root public
|
|
21
|
+
key** β the root private key never leaves its owner.
|
|
22
|
+
- **Zero-Knowledge Password Management** β deterministic password
|
|
23
|
+
derivation without storage.
|
|
24
|
+
- **Secure Channels** β symmetric channel keys and X25519 shared
|
|
25
|
+
secrets derived without key exchange.
|
|
21
26
|
|
|
22
27
|
## π¦ Installation
|
|
23
28
|
|
|
@@ -25,632 +30,375 @@
|
|
|
25
30
|
npm install @me2em/core
|
|
26
31
|
# or
|
|
27
32
|
pnpm add @me2em/core
|
|
28
|
-
# or
|
|
29
|
-
yarn add @me2em/core
|
|
30
33
|
```
|
|
31
34
|
|
|
32
|
-
**Dependencies:**
|
|
33
|
-
- `@
|
|
34
|
-
- `@noble/hashes` β HKDF, SHA-256
|
|
35
|
-
|
|
36
|
-
---
|
|
35
|
+
**Dependencies:** `@noble/curves` (Ed25519/X25519), `@noble/ed25519`,
|
|
36
|
+
`@noble/hashes` (HKDF, SHA-256), `@scure/bip39` (mnemonic handling).
|
|
37
37
|
|
|
38
38
|
## π Quick Start
|
|
39
39
|
|
|
40
|
-
### Basic Usage
|
|
41
|
-
|
|
42
40
|
```typescript
|
|
43
|
-
import { Identity,
|
|
41
|
+
import { Identity, Session } from '@me2em/core';
|
|
44
42
|
|
|
45
|
-
// 1. Create Identity from
|
|
46
|
-
const seed = new Uint8Array(32).fill(42); //
|
|
43
|
+
// 1. Create an Identity from a 32-byte seed
|
|
44
|
+
const seed = new Uint8Array(32).fill(42); // use a CSPRNG in production
|
|
47
45
|
const identity = await Identity.fromSeed(seed);
|
|
48
46
|
|
|
49
47
|
// 2. Derive a contextual Handle
|
|
50
|
-
const
|
|
51
|
-
displayName: '
|
|
52
|
-
avatar: 'https://example.com/avatar.png'
|
|
48
|
+
const station = await identity.deriveHandle('station-001', {
|
|
49
|
+
displayName: 'Station Berlin #001',
|
|
53
50
|
});
|
|
54
51
|
|
|
55
|
-
// 3.
|
|
56
|
-
const
|
|
57
|
-
|
|
58
|
-
|
|
52
|
+
// 3. Derive a SubHandle with constraints
|
|
53
|
+
const connector = await station.deriveSubHandle('connector-ccs', {
|
|
54
|
+
allowedAudiences: ['ev-app.com'],
|
|
55
|
+
allowedScopes: ['charge:start', 'charge:stop'],
|
|
56
|
+
maxSessionTtl: 7200,
|
|
57
|
+
});
|
|
59
58
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
59
|
+
// 4. Create a stateless session (signed by the SubHandle)
|
|
60
|
+
const session = await Session.create(connector, {
|
|
61
|
+
audience: 'ev-app.com',
|
|
62
|
+
scopes: ['charge:start'],
|
|
63
|
+
ttl: 1800,
|
|
64
|
+
});
|
|
63
65
|
|
|
64
|
-
|
|
66
|
+
console.log(session.token); // base64url(payload).base64url(signature)
|
|
67
|
+
```
|
|
65
68
|
|
|
66
|
-
|
|
69
|
+
### Integration with BIP39 (recommended)
|
|
67
70
|
|
|
68
71
|
```typescript
|
|
69
|
-
import {
|
|
70
|
-
Identity,
|
|
71
|
-
|
|
72
|
-
get32ByteSeedFromMnemonic,
|
|
73
|
-
validateSeedPhrase
|
|
72
|
+
import {
|
|
73
|
+
Identity, generateSeedPhrase,
|
|
74
|
+
get32ByteSeedFromMnemonic, validateSeedPhrase,
|
|
74
75
|
} from '@me2em/core';
|
|
75
76
|
|
|
76
|
-
|
|
77
|
-
const
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
// 2. (Optional) Validate a user-provided phrase
|
|
81
|
-
const validation = validateSeedPhrase(phrase);
|
|
82
|
-
if (!validation.isValid) throw new Error(validation.error);
|
|
77
|
+
const phrase = generateSeedPhrase(128); // 12 words (256 β 24 words)
|
|
78
|
+
const check = validateSeedPhrase(phrase);
|
|
79
|
+
if (!check.isValid) throw new Error(check.error);
|
|
83
80
|
|
|
84
|
-
// 3. Convert to 32-byte seed and create Identity
|
|
85
81
|
const seedBytes = await get32ByteSeedFromMnemonic(phrase);
|
|
86
82
|
const identity = await Identity.fromSeed(seedBytes);
|
|
87
83
|
```
|
|
88
84
|
|
|
89
|
-
|
|
90
|
-
|
|
85
|
+
> β οΈ Passphrases (BIP39 "25th word") ARE supported:
|
|
86
|
+
> `get32ByteSeedFromMnemonic(words, passphrase)`. The passphrase is
|
|
87
|
+
> case-sensitive, not recoverable, and silently derives a different
|
|
88
|
+
> identity if mistyped. Store it with the same care as the words.
|
|
91
89
|
|
|
90
|
+
## π Attestations (verifiable delegation)
|
|
92
91
|
|
|
93
|
-
|
|
92
|
+
An **attestation** is a parent-signed statement:
|
|
94
93
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
### `Identity` Class
|
|
98
|
-
|
|
99
|
-
The root cryptographic identity, derived from a seed phrase.
|
|
100
|
-
|
|
101
|
-
```typescript
|
|
102
|
-
class Identity {
|
|
103
|
-
// Create Identity from seed (32-byte Uint8Array)
|
|
104
|
-
static fromSeed(seed: Uint8Array): Promise<Identity>;
|
|
94
|
+
> "the public key `K` belongs to the name `N` and is valid within grant `G`".
|
|
105
95
|
|
|
106
|
-
|
|
107
|
-
|
|
96
|
+
Chains (`root β handle β subhandle β session`) let **third parties verify
|
|
97
|
+
sessions offline using only the root *public* key** β with grant
|
|
98
|
+
constraints enforced at verification time, not just at creation.
|
|
108
99
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
100
|
+
```text
|
|
101
|
+
Identity ββattestHandleβββΆ Handle (e.g. a charging station, issued once)
|
|
102
|
+
β offline, no Identity, no network:
|
|
103
|
+
ββ deriveSubHandle('connector-ccs')
|
|
104
|
+
ββ attestSubHandle('connector-ccs', grant)
|
|
105
|
+
ββ Session.create(subHandle, ...)
|
|
106
|
+
βΌ
|
|
107
|
+
third-party verifier: verifyAttested(token, rootPublicKey, [A, B], audience)
|
|
112
108
|
```
|
|
113
109
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
Creates an Identity from a 32-byte seed.
|
|
110
|
+
### Issuing
|
|
117
111
|
|
|
118
112
|
```typescript
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
#### `Identity.deriveHandle(name, metadata?)`
|
|
127
|
-
|
|
128
|
-
Derives a new Handle deterministically from the Identity.
|
|
113
|
+
// Root owner (once per handle lifetime):
|
|
114
|
+
const A = await identity.attestHandle('station-001', {
|
|
115
|
+
audiences: ['ev-app.com'],
|
|
116
|
+
scopes: ['charge:start', 'charge:stop', 'charge:status'],
|
|
117
|
+
maxSessionTtl: 7200,
|
|
118
|
+
subNamePatterns: ['connector-*', 'meter-*'], // wildcard: trailing '*' only
|
|
119
|
+
});
|
|
129
120
|
|
|
130
|
-
|
|
131
|
-
const
|
|
132
|
-
|
|
133
|
-
|
|
121
|
+
// Handle (autonomous, offline, per subhandle):
|
|
122
|
+
const B = await station.attestSubHandle('connector-ccs', {
|
|
123
|
+
audiences: ['ev-app.com'],
|
|
124
|
+
scopes: ['charge:start', 'charge:stop'],
|
|
125
|
+
maxSessionTtl: 7200,
|
|
134
126
|
});
|
|
135
127
|
```
|
|
136
128
|
|
|
137
|
-
**
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
**Returns:** A `Handle` instance with its own keypair, derived deterministically from the Identity.
|
|
142
|
-
|
|
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
|
|
129
|
+
The attested public key is always **derived internally** β a parent
|
|
130
|
+
cannot attest a foreign key, and `B.subjectId` always equals the key
|
|
131
|
+
reconstructed via `identity.deriveSubHandle('station-001', 'connector-ccs')`.
|
|
151
132
|
|
|
152
|
-
|
|
133
|
+
### Verifying (on any third-party server)
|
|
153
134
|
|
|
154
135
|
```typescript
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
//
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
136
|
+
import { Session, AttestationError } from '@me2em/core';
|
|
137
|
+
|
|
138
|
+
try {
|
|
139
|
+
const s = await Session.verifyAttested(
|
|
140
|
+
session.token,
|
|
141
|
+
rootPublicKey, // Uint8Array β public key only
|
|
142
|
+
[A.token, B.token], // chain, root first; length 1 for handle sessions
|
|
143
|
+
'ev-app.com',
|
|
144
|
+
revocationChecker?, // optional; checks attestation and session jti
|
|
145
|
+
);
|
|
146
|
+
await startCharging(s.path![1]);
|
|
147
|
+
} catch (e) {
|
|
148
|
+
if (e instanceof AttestationError) {
|
|
149
|
+
console.error(e.code, e.level); // e.g. SCOPE_EXCEEDED / SESSION
|
|
150
|
+
}
|
|
151
|
+
throw new Error('Unauthorized');
|
|
152
|
+
}
|
|
166
153
|
```
|
|
167
154
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
155
|
+
### Error model
|
|
156
|
+
|
|
157
|
+
All failures throw `AttestationError` with `code` and `level`
|
|
158
|
+
(`ROOT | HANDLE_ATTESTATION | SUB_ATTESTATION | SESSION | FORMAT`):
|
|
159
|
+
|
|
160
|
+
| code | levels |
|
|
161
|
+
|---|---|
|
|
162
|
+
| `MALFORMED`, `CHAIN_INCOMPLETE` | FORMAT |
|
|
163
|
+
| `BAD_SIGNATURE` | ROOT, HANDLE_ATTESTATION, SESSION |
|
|
164
|
+
| `EXPIRED`, `NOT_YET_VALID`, `REVOKED` | ROOT, HANDLE_ATTESTATION, SESSION |
|
|
165
|
+
| `PATH_MISMATCH` | ROOT, HANDLE_ATTESTATION, SESSION |
|
|
166
|
+
| `NAME_NOT_PERMITTED`, `SCOPE_EXCEEDED`, `TTL_EXCEEDED` | ROOT |
|
|
167
|
+
| `SCOPE_EXCEEDED`, `TTL_EXCEEDED`, `AUDIENCE_NOT_PERMITTED`, `SESSION_OUTLIVES_ATTESTATION` | SESSION |
|
|
168
|
+
| `SUBJECT_MISMATCH` | ROOT, SUB_ATTESTATION |
|
|
169
|
+
|
|
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."
|
|
171
|
+
|
|
172
|
+
### Verification modes
|
|
173
|
+
|
|
174
|
+
The library provides two ways to verify a session token. Both answer the
|
|
175
|
+
same question β *"is this signature valid, unexpired, unrevoked, and what
|
|
176
|
+
does it allow?"* β but they differ in **who is able to verify** and in
|
|
177
|
+
**what is actually enforced**.
|
|
178
|
+
|
|
179
|
+
**Mode 1 β `Session.verifyStateless` (direct verification).**
|
|
180
|
+
The verifier re-derives the signer's public key from the token's
|
|
181
|
+
`hNm`/`hPath` using an `Identity` instance and checks the signature.
|
|
182
|
+
Re-derivation requires the **private root key**, so Mode 1 is only
|
|
183
|
+
available to the key holder itself or to backend infrastructure trusted
|
|
184
|
+
with the root. Scopes, audience, TTL and revocation are checked from the
|
|
185
|
+
token itself β but SubHandle *constraints* (`allowedScopes`,
|
|
186
|
+
`maxSessionTtl`, β¦) are enforced only at session **creation**. A party
|
|
187
|
+
that has obtained a SubHandle private key can sign a session with any
|
|
188
|
+
scopes and TTL, and Mode 1 verification will accept it.
|
|
189
|
+
|
|
190
|
+
**Mode 2 β `Session.verifyAttested` (attestation-chain verification).**
|
|
191
|
+
The verifier checks the session signature against the key bound by a
|
|
192
|
+
parent-signed attestation, and each attestation against its parent's
|
|
193
|
+
signature, up to the root **public** key. Because every chain link
|
|
194
|
+
carries a signed grant, the verifier **enforces grants at verification
|
|
195
|
+
time**: session scopes must fit the grant, TTL caps and audiences hold,
|
|
196
|
+
and child grants must nest inside parent grants. This makes delegation
|
|
197
|
+
externally verifiable β a partner service verifies sessions with the
|
|
198
|
+
root public key only β and revoking an attestation `jti` disables the
|
|
199
|
+
entire branch: current **and** future sessions under it.
|
|
200
|
+
|
|
201
|
+
**Which mode should I use?**
|
|
202
|
+
|
|
203
|
+
| Situation | Mode |
|
|
204
|
+
|---|---|
|
|
205
|
+
| Verifier is your own trusted backend that already holds the root key | Mode 1 |
|
|
206
|
+
| Verifier is a third party / partner / customer who must not receive the root private key | Mode 2 |
|
|
207
|
+
| You need branch revocation (disable a device, an employee, a sold deal entirely) | Mode 2 |
|
|
208
|
+
| SubHandle constraints must be *enforced*, not just advisory | Mode 2 |
|
|
209
|
+
|
|
210
|
+
| | `Session.verifyStateless` (Mode 1) | `Session.verifyAttested` (Mode 2) |
|
|
211
|
+
|---|---|---|
|
|
212
|
+
| Verifier needs | `Identity` (**private** root) | root **public** key + chain |
|
|
213
|
+
| Trust model | verifier is the root owner | any third party |
|
|
214
|
+
| SubHandle constraints | enforced at creation only | **enforced at verification** |
|
|
215
|
+
| Revoke a handle/branch | per-session `jti` only | revoke attestation `jti` |
|
|
216
|
+
| Use when | closed perimeter, own services | external audiences, delegation, selling access |
|
|
217
|
+
|
|
218
|
+
The modes coexist naturally: internal telemetry verified with Mode 1,
|
|
219
|
+
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).
|
|
171
222
|
|
|
172
|
-
|
|
223
|
+
## π API Reference
|
|
173
224
|
|
|
174
|
-
|
|
225
|
+
### `Identity`
|
|
175
226
|
|
|
176
227
|
```typescript
|
|
177
|
-
class
|
|
178
|
-
//
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
// Verify a signature using a public key (static method)
|
|
185
|
-
static verify(signature: Uint8Array, data: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
|
|
186
|
-
|
|
187
|
-
// Deterministically derive a password/secret for a specific context
|
|
188
|
-
derivePassword(context: string, length?: number): string;
|
|
189
|
-
|
|
190
|
-
// Derive a symmetric channel key for encrypted communication
|
|
191
|
-
deriveChannelKey(context: string): Uint8Array;
|
|
192
|
-
|
|
193
|
-
// Accessors
|
|
194
|
-
getName(): string;
|
|
195
|
-
getMetadata(): HandleMetadata | undefined;
|
|
228
|
+
class Identity {
|
|
229
|
+
static fromSeed(seed: Uint8Array | string): Promise<Identity>; // 32 bytes or 64-char hex
|
|
230
|
+
deriveHandle(name: string, metadata?: HandleMetadata): Promise<Handle>;
|
|
231
|
+
deriveSubHandle(handleName: string, subName: string,
|
|
232
|
+
metadata?: SubHandleMetadata): Promise<SubHandle>; // atomic, for verification
|
|
233
|
+
attestHandle(name: string, grant: AttestationGrant,
|
|
234
|
+
opts?: { ttlSeconds?, expiresAt?, jti?, now? }): Promise<Attestation>;
|
|
196
235
|
getPublicKey(): Uint8Array;
|
|
197
236
|
}
|
|
198
237
|
```
|
|
199
238
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
Returns a URL-safe base64 string representing the Handle's public key:
|
|
203
|
-
|
|
204
|
-
```typescript
|
|
205
|
-
const handleId = handle.getId();
|
|
206
|
-
// Example: "pK7xJ2mN8vQ3rL5wY9zB1cD4eF6gH8iJ0kL2mN4oP6qR8sT0uV2wX4yZ6aB8cD0"
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
This is the identifier you send to servers for authentication and routing.
|
|
210
|
-
|
|
211
|
-
#### `Handle.sign(data)`
|
|
212
|
-
|
|
213
|
-
Signs arbitrary binary data using Ed25519:
|
|
214
|
-
|
|
215
|
-
```typescript
|
|
216
|
-
const payload = new TextEncoder().encode('{"action":"post","content":"Hello"}');
|
|
217
|
-
const signature = await handle.sign(payload);
|
|
218
|
-
|
|
219
|
-
// Send to server:
|
|
220
|
-
fetch('https://api.example.com/endpoint', {
|
|
221
|
-
method: 'POST',
|
|
222
|
-
headers: {
|
|
223
|
-
'X-Handle-ID': handle.getId(),
|
|
224
|
-
'Content-Type': 'application/json'
|
|
225
|
-
},
|
|
226
|
-
body: JSON.stringify({
|
|
227
|
-
payload: btoa(String.fromCharCode(...payload)),
|
|
228
|
-
signature: btoa(String.fromCharCode(...signature))
|
|
229
|
-
})
|
|
230
|
-
});
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
#### `Handle.verify(signature, data, publicKey)`
|
|
234
|
-
|
|
235
|
-
Static method for server-side signature verification:
|
|
236
|
-
|
|
237
|
-
```typescript
|
|
238
|
-
// Server receives: handleId, signature, payload
|
|
239
|
-
const publicKey = Uint8Array.from(atob(handleId), c => c.charCodeAt(0));
|
|
240
|
-
const data = Uint8Array.from(atob(payload), c => c.charCodeAt(0));
|
|
241
|
-
const sig = Uint8Array.from(atob(signature), c => c.charCodeAt(0));
|
|
242
|
-
|
|
243
|
-
const isValid = await Handle.verify(sig, data, publicKey);
|
|
244
|
-
if (!isValid) throw new Error('Invalid signature');
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
#### `Handle.derivePassword(context, length?)`
|
|
248
|
-
|
|
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.
|
|
239
|
+
### `Handle`
|
|
250
240
|
|
|
251
241
|
```typescript
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
//
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
242
|
+
class Handle {
|
|
243
|
+
getId(): string; // base64url of the public key
|
|
244
|
+
getName(): string; // canonical (normalized) name
|
|
245
|
+
getMetadata(): HandleMetadata | undefined;
|
|
246
|
+
getPublicKey(): Uint8Array;
|
|
247
|
+
getPath(): string[] | undefined; // undefined for Handle, path for SubHandle
|
|
248
|
+
sign(data: Uint8Array): Promise<Uint8Array>;
|
|
249
|
+
static verify(sig: Uint8Array, data: Uint8Array, pub: Uint8Array): Promise<boolean>;
|
|
250
|
+
derivePassword(context: string, length?: number): string; // base64url secret
|
|
251
|
+
deriveChannelKey(context: string): Uint8Array; // 32-byte AES key
|
|
252
|
+
deriveSharedSecret(otherPublicKey: Uint8Array): Promise<Uint8Array>; // X25519 + HKDF
|
|
253
|
+
deriveSubHandle(name: string, metadata?: SubHandleMetadata): Promise<SubHandle>;
|
|
254
|
+
attestSubHandle(subName: string, grant: AttestationGrant,
|
|
255
|
+
opts?: { ttlSeconds?, expiresAt?, jti?, now? }): Promise<Attestation>;
|
|
256
|
+
validateSessionOptions(options: { audience: string; scopes: string[]; ttl: number }): void;
|
|
257
|
+
}
|
|
258
258
|
```
|
|
259
259
|
|
|
260
|
-
|
|
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.
|
|
269
|
-
|
|
270
|
-
#### `Handle.deriveChannelKey(context)`
|
|
271
|
-
|
|
272
|
-
Derives a symmetric 256-bit key for establishing a secure, encrypted communication channel between the Identity (controller) and this Handle (device/context). Both parties can independently compute this key without any key exchange protocol, because they both have access to the Handle's private key.
|
|
260
|
+
### `SubHandle` (leaf, MAX_DEPTH = 2)
|
|
273
261
|
|
|
274
262
|
```typescript
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
//
|
|
278
|
-
|
|
279
|
-
//
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
//
|
|
283
|
-
|
|
284
|
-
|
|
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.
|
|
287
|
-
|
|
288
|
-
**Returns:** 32-byte `Uint8Array` suitable for AES-256-GCM encryption.
|
|
289
|
-
|
|
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.
|
|
291
|
-
|
|
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.
|
|
293
|
-
|
|
294
|
-
---
|
|
295
|
-
|
|
296
|
-
## π― Use Cases
|
|
297
|
-
|
|
298
|
-
### 1. Deterministic Password Manager (Access Key Keeper)
|
|
299
|
-
|
|
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.
|
|
301
|
-
|
|
302
|
-
```typescript
|
|
303
|
-
// 1. User restores Identity from Seed (e.g., after entering a PIN)
|
|
304
|
-
const identity = await Identity.fromSeed(userSeed);
|
|
305
|
-
|
|
306
|
-
// 2. Derive the specific service Handle
|
|
307
|
-
const googleHandle = await identity.deriveHandle('google', {
|
|
308
|
-
displayName: 'Alice Personal'
|
|
309
|
-
});
|
|
310
|
-
|
|
311
|
-
// 3. Deterministically generate the password on the fly
|
|
312
|
-
const password = googleHandle.derivePassword('google');
|
|
313
|
-
|
|
314
|
-
// 4. Auto-fill the login form
|
|
315
|
-
console.log('Login:', 'alice@example.com');
|
|
316
|
-
console.log('Password:', password); // Always the same for this seed + handle + context
|
|
263
|
+
class SubHandle extends Handle {
|
|
264
|
+
getPath(): string[]; // ['station-001', 'connector-ccs']
|
|
265
|
+
getPathString(): string; // 'station-001/connector-ccs'
|
|
266
|
+
getDepth(): number; // always 2
|
|
267
|
+
isLeaf(): boolean; // always true
|
|
268
|
+
getSubMetadata(): SubHandleMetadata;
|
|
269
|
+
validateSessionOptions(options: { audience: string; scopes: string[]; ttl: number }): void;
|
|
270
|
+
// deriveSubHandle is overridden and ALWAYS throws (leaf node)
|
|
271
|
+
}
|
|
317
272
|
```
|
|
318
273
|
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
|
|
323
|
-
### 2. IoT Fleet with Encrypted Channels
|
|
324
|
-
|
|
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.
|
|
274
|
+
### `Session`
|
|
326
275
|
|
|
327
276
|
```typescript
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
throw new Error('Unknown device');
|
|
339
|
-
}
|
|
340
|
-
|
|
341
|
-
// 2. Derive the Handle (deterministic, no DB lookup)
|
|
342
|
-
const deviceHandle = await centerIdentity.deriveHandle(message.name);
|
|
343
|
-
|
|
344
|
-
// 3. Verify signature (proves device owns the private key)
|
|
345
|
-
const dataToVerify = concatBytes(
|
|
346
|
-
new TextEncoder().encode(message.name),
|
|
347
|
-
message.encrypted
|
|
348
|
-
);
|
|
349
|
-
const isValid = await Handle.verify(message.signature, dataToVerify, deviceHandle.getPublicKey());
|
|
350
|
-
if (!isValid) throw new Error('Invalid signature');
|
|
351
|
-
|
|
352
|
-
// 4. Derive the SAME channel key the device used for encryption
|
|
353
|
-
const channelKey = deviceHandle.deriveChannelKey('telemetry-v1');
|
|
354
|
-
|
|
355
|
-
// 5. Decrypt the message
|
|
356
|
-
const telemetry = await decryptAESGCM(message.encrypted, channelKey);
|
|
357
|
-
return telemetry;
|
|
277
|
+
class Session {
|
|
278
|
+
static create(handle: Handle | SubHandle, options: SessionOptions): Promise<Session>;
|
|
279
|
+
static verifyStateless(token: string, companyIdentity: Identity,
|
|
280
|
+
expectedAudience: string,
|
|
281
|
+
revocationChecker?: RevocationChecker): Promise<Session>;
|
|
282
|
+
static verifyAttested(token: string, rootPublicKey: Uint8Array,
|
|
283
|
+
attestationChain: string[], expectedAudience: string,
|
|
284
|
+
revocationChecker?: RevocationChecker): Promise<Session>;
|
|
285
|
+
isExpired(): boolean;
|
|
286
|
+
readonly handleId, handleName, audience, scopes, expiresAt, token, path, sessionId;
|
|
358
287
|
}
|
|
359
288
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
async function sendTelemetry(telemetry: object) {
|
|
363
|
-
const name = 'drone-001';
|
|
364
|
-
const privateKey = /* loaded from secure enclave */;
|
|
365
|
-
const droneHandle = new Handle(privateKey, name);
|
|
366
|
-
|
|
367
|
-
// 1. Derive the SAME channel key the center will use for decryption
|
|
368
|
-
const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
369
|
-
|
|
370
|
-
// 2. Encrypt telemetry
|
|
371
|
-
const telemetryBytes = new TextEncoder().encode(JSON.stringify(telemetry));
|
|
372
|
-
const encrypted = await encryptAESGCM(telemetryBytes, channelKey);
|
|
373
|
-
|
|
374
|
-
// 3. Sign (name + encrypted data)
|
|
375
|
-
const dataToSign = concatBytes(new TextEncoder().encode(name), encrypted);
|
|
376
|
-
const signature = await droneHandle.sign(dataToSign);
|
|
377
|
-
|
|
378
|
-
return { name, signature, encrypted };
|
|
289
|
+
interface SessionOptions {
|
|
290
|
+
audience: string; scopes: string[]; ttl: number; sessionId?: string;
|
|
379
291
|
}
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
β
**Benefits**:
|
|
383
|
-
- **Minimal registry**: Control center stores only device names (strings), not public keys
|
|
384
|
-
- **No key exchange**: Both parties derive the same key independently
|
|
385
|
-
- **Stateless verification**: Signature check proves device authenticity
|
|
386
|
-
- **Isolation**: Compromise of one device doesn't affect others (different Handles β different channel keys)
|
|
387
292
|
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
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.
|
|
293
|
+
interface SessionPayload { // signed token contents
|
|
294
|
+
hId: string; hNm: string; hPath?: string[];
|
|
295
|
+
aud: string; scp: string[]; exp: number; iat: number; jti: string;
|
|
296
|
+
}
|
|
393
297
|
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
const messengerHandle = await identity.deriveHandle('messenger-main');
|
|
398
|
-
const handleId = messengerHandle.getId();
|
|
399
|
-
// Send handleId to server for registration
|
|
400
|
-
|
|
401
|
-
// On the laptop (later, no sync needed):
|
|
402
|
-
const identity = await Identity.fromSeed(userSeed); // Same seed
|
|
403
|
-
const messengerHandle = await identity.deriveHandle('messenger-main'); // Same name
|
|
404
|
-
const handleId = messengerHandle.getId(); // Identical handleId!
|
|
405
|
-
// Server recognizes the same user automatically
|
|
298
|
+
interface RevocationChecker {
|
|
299
|
+
isRevoked(jti: string): Promise<boolean>;
|
|
300
|
+
}
|
|
406
301
|
```
|
|
407
302
|
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
---
|
|
411
|
-
|
|
412
|
-
### 4. Break-Glass Recovery and Inheritance
|
|
413
|
-
|
|
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.
|
|
303
|
+
### `Attestation`
|
|
415
304
|
|
|
416
305
|
```typescript
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
306
|
+
class Attestation {
|
|
307
|
+
static issue(signerPrivateKey: Uint8Array, subjectPublicKey: Uint8Array,
|
|
308
|
+
subjectName: string, grant: AttestationGrant,
|
|
309
|
+
opts?: { ttlSeconds?, expiresAt?, jti?, now? }): Promise<Attestation>;
|
|
310
|
+
static decode(token: string): AttestationPayload; // structure only β no sig, no time
|
|
311
|
+
static verifySignature(token: string, signerPublicKey: Uint8Array): Promise<boolean>;
|
|
312
|
+
static matchNamePattern(name: string, patterns: string[]): boolean;
|
|
313
|
+
get payload(): AttestationPayload;
|
|
314
|
+
get token(): string;
|
|
315
|
+
get jti(): string;
|
|
316
|
+
}
|
|
426
317
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
318
|
+
interface AttestationGrant {
|
|
319
|
+
audiences?: string[]; // undefined = unrestricted; [] = deny all
|
|
320
|
+
scopes: string[]; // exact strings, no wildcards
|
|
321
|
+
maxSessionTtl: number; // seconds, > 0
|
|
322
|
+
subNamePatterns?: string[]; // rootβhandle only; trailing '*' only
|
|
323
|
+
}
|
|
430
324
|
|
|
431
|
-
|
|
432
|
-
|
|
325
|
+
class AttestationError extends Error {
|
|
326
|
+
readonly code: AttestationErrorCode;
|
|
327
|
+
readonly level: AttestationLevel;
|
|
328
|
+
}
|
|
433
329
|
```
|
|
434
330
|
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
---
|
|
438
|
-
|
|
439
|
-
### 5. Ephemeral Delegated Access
|
|
440
|
-
|
|
441
|
-
Grant time-limited access to a contractor or temporary service by deriving a Handle with a time-bound name.
|
|
331
|
+
### Name normalization
|
|
442
332
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
role: 'auditor',
|
|
448
|
-
expiresAt: '2026-12-31T23:59:59Z'
|
|
449
|
-
});
|
|
333
|
+
All derivation inputs are canonicalized: `NFKC β lowercase β trim`,
|
|
334
|
+
then validated against `/^[a-z0-9][a-z0-9._@-]{0,62}$/`. Names with `/`,
|
|
335
|
+
non-ASCII letters, or > 64 chars **throw**. Identical inputs always
|
|
336
|
+
produce identical keys across platforms and entry points.
|
|
450
337
|
|
|
451
|
-
|
|
452
|
-
// Contractor uses this Handle for authenticated access
|
|
338
|
+
## π― Core Use Cases
|
|
453
339
|
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
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.
|
|
459
345
|
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
346
|
+
π **[USE_CASES.md](./USE_CASES.md)** β EV charging stations, drone fleet
|
|
347
|
+
access marketplace, corporate messenger, and a production Redis
|
|
348
|
+
`RevocationChecker`.
|
|
463
349
|
|
|
464
350
|
## π Cryptographic Details
|
|
465
351
|
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
inputKeyMaterial = IdentityPrivateKey,
|
|
473
|
-
salt = empty,
|
|
474
|
-
info = "me2em/handle/v1/" + lowercase(name),
|
|
475
|
-
length = 32
|
|
476
|
-
)
|
|
477
|
-
HandlePublicKey = Ed25519.PublicKey(HandlePrivateKey)
|
|
478
|
-
HandleId = Base64Url(HandlePublicKey)
|
|
479
|
-
```
|
|
480
|
-
|
|
481
|
-
**Properties:**
|
|
482
|
-
- π **Deterministic**: Same inputs β same output across all implementations
|
|
483
|
-
- π **One-way**: Cannot derive Identity key from Handle key
|
|
484
|
-
- π§© **Isolated**: Each Handle uses independent Ed25519 keypair
|
|
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
|
-
|
|
505
|
-
### Channel Key Derivation
|
|
506
|
-
|
|
507
|
-
Channel keys are derived using **HKDF-SHA256** with the Handle's private key as input key material:
|
|
508
|
-
|
|
509
|
-
```
|
|
510
|
-
ChannelKey = HKDF-SHA256(
|
|
511
|
-
inputKeyMaterial = HandlePrivateKey,
|
|
512
|
-
salt = "me2em/channel/" + lowercase(context),
|
|
513
|
-
info = "me2em/channel/v1",
|
|
514
|
-
length = 32
|
|
515
|
-
)
|
|
516
|
-
```
|
|
517
|
-
|
|
518
|
-
**Properties:**
|
|
519
|
-
- π **Deterministic**: Same Handle + same context β same 32-byte key
|
|
520
|
-
- π **Encapsulated**: Private key never leaves the Handle instance
|
|
521
|
-
- π§© **Domain-separated**: Different contexts produce different keys (e.g., `'telemetry-v1'` vs `'command-v1'`)
|
|
522
|
-
- β‘ **No key exchange**: Both parties derive the key independently, no ECDH needed
|
|
523
|
-
|
|
524
|
-
### Signature Scheme
|
|
525
|
-
|
|
526
|
-
- **Algorithm**: Ed25519 (RFC 8032)
|
|
527
|
-
- **Hash**: SHA-512 (via `@noble/ed25519`)
|
|
528
|
-
- **Encoding**: Raw bytes β base64url for transport
|
|
529
|
-
|
|
530
|
-
---
|
|
352
|
+
- **Identity:** `Ed25519 key = HKDF-SHA256(seed, salt="", info="me2em/identity/v1/root", 32)`
|
|
353
|
+
- **Handle:** `HKDF-SHA256(identityKey, salt="", info="me2em/handle/v1/{name}", 32)`
|
|
354
|
+
- **SubHandle:** `HKDF-SHA256(handleKey, salt="", info="me2em/subhandle/v1/{handle}/{sub}", 32)`
|
|
355
|
+
- **Signatures:** Ed25519 (RFC 8032); tokens are `base64url(payload).base64url(signature)`
|
|
356
|
+
- **Attestation payload limit:** 2048 bytes; **session payload limit:** 4096 bytes
|
|
357
|
+
- **Clock skew tolerance:** Β±30 seconds on all time checks
|
|
531
358
|
|
|
532
359
|
## π‘οΈ Security Best Practices
|
|
533
360
|
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
-
|
|
538
|
-
-
|
|
539
|
-
|
|
540
|
-
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
-
|
|
547
|
-
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
```
|
|
552
|
-
[User enters seed]
|
|
553
|
-
β
|
|
554
|
-
βΌ
|
|
555
|
-
[Derive Identity in RAM]
|
|
556
|
-
β
|
|
557
|
-
βΌ
|
|
558
|
-
[Derive Handle(s) as needed]
|
|
559
|
-
β
|
|
560
|
-
βΌ
|
|
561
|
-
[Sign challenge / data / derive password / derive channel key]
|
|
562
|
-
β
|
|
563
|
-
βΌ
|
|
564
|
-
[Zero out private key buffers] β Critical!
|
|
565
|
-
β
|
|
566
|
-
βΌ
|
|
567
|
-
[Keep only public HandleId for future use]
|
|
568
|
-
```
|
|
569
|
-
|
|
570
|
-
---
|
|
361
|
+
β
**Do**:
|
|
362
|
+
- Store seeds encrypted (PIN/biometric + AES-GCM); keep the root offline
|
|
363
|
+
except for issuance ceremonies.
|
|
364
|
+
- Use short session TTLs (β€ 1 hour recommended).
|
|
365
|
+
- Implement a `RevocationChecker` (e.g., Redis SET) β it is consulted for
|
|
366
|
+
attestation **and** session `jti` in `verifyAttested`.
|
|
367
|
+
- Prefer `verifyAttested` for any external audience; reserve
|
|
368
|
+
`verifyStateless` for infrastructure you fully control.
|
|
369
|
+
- Scope `subNamePatterns` as narrowly as possible β a holder can do
|
|
370
|
+
everything *inside* its wildcard.
|
|
371
|
+
|
|
372
|
+
β **Don't**:
|
|
373
|
+
- Never transmit seeds; keep derivation client-side.
|
|
374
|
+
- Don't reuse Handles across unrelated contexts.
|
|
375
|
+
- Don't log private keys or seed phrases.
|
|
376
|
+
- Don't rely on zeroing buffers as a hard guarantee β GC/JIT may retain
|
|
377
|
+
copies (tracked in [BACKLOG](./BACKLOG.md) BL-07).
|
|
571
378
|
|
|
572
379
|
## π§ͺ Testing
|
|
573
380
|
|
|
574
|
-
### Unit Tests
|
|
575
|
-
|
|
576
381
|
```bash
|
|
577
|
-
cd packages/core
|
|
578
|
-
pnpm test
|
|
579
|
-
```
|
|
580
|
-
|
|
581
|
-
Tests cover:
|
|
582
|
-
- β
Deterministic derivation (same seed + name β same HandleId)
|
|
583
|
-
- β
Signature generation and verification
|
|
584
|
-
- β
Password derivation (same Handle + context β same password)
|
|
585
|
-
- β
Channel key derivation (same Handle + context β same key)
|
|
586
|
-
- β
Edge cases (empty metadata, long names, unicode)
|
|
587
|
-
|
|
588
|
-
### Integration Test Example
|
|
589
|
-
|
|
590
|
-
```typescript
|
|
591
|
-
import { Identity } from '@me2em/core';
|
|
592
|
-
|
|
593
|
-
test('full auth flow', async () => {
|
|
594
|
-
// Client side
|
|
595
|
-
const identity = await Identity.fromSeed(testSeed);
|
|
596
|
-
const handle = await identity.deriveHandle('test');
|
|
597
|
-
const challenge = new TextEncoder().encode('nonce-123');
|
|
598
|
-
const signature = await handle.sign(challenge);
|
|
599
|
-
|
|
600
|
-
// Server side
|
|
601
|
-
const isValid = await Handle.verify(
|
|
602
|
-
signature,
|
|
603
|
-
challenge,
|
|
604
|
-
handle.getPublicKey()
|
|
605
|
-
);
|
|
606
|
-
expect(isValid).toBe(true);
|
|
607
|
-
expect(handle.getId()).toMatch(/^[A-Za-z0-9_-]{43}$/);
|
|
608
|
-
});
|
|
609
|
-
```
|
|
610
|
-
|
|
611
|
-
---
|
|
612
|
-
|
|
613
|
-
## π¦ Package Info
|
|
614
|
-
|
|
615
|
-
```json
|
|
616
|
-
{
|
|
617
|
-
"name": "@me2em/core",
|
|
618
|
-
"version": "0.4.2-alpha.1",
|
|
619
|
-
"type": "module",
|
|
620
|
-
"main": "./dist/index.js",
|
|
621
|
-
"types": "./dist/index.d.ts",
|
|
622
|
-
"exports": {
|
|
623
|
-
".": {
|
|
624
|
-
"types": "./dist/index.d.ts",
|
|
625
|
-
"import": "./dist/index.js",
|
|
626
|
-
"require": "./dist/index.cjs"
|
|
627
|
-
}
|
|
628
|
-
},
|
|
629
|
-
"dependencies": {
|
|
630
|
-
"@noble/ed25519": "^3.1.0",
|
|
631
|
-
"@noble/hashes": "^2.2.0",
|
|
632
|
-
"@scure/bip39": "^1.3.0"
|
|
633
|
-
},
|
|
634
|
-
"engines": {
|
|
635
|
-
"node": ">=18.0.0"
|
|
636
|
-
}
|
|
637
|
-
}
|
|
382
|
+
cd packages/core && pnpm test
|
|
638
383
|
```
|
|
639
384
|
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
385
|
+
166 tests cover: deterministic derivation and cross-entry-point key
|
|
386
|
+
consistency, name canonicalization, session lifecycle (create, verify,
|
|
387
|
+
tamper, expiry, iat), revocation, SubHandle constraint enforcement,
|
|
388
|
+
MAX_DEPTH leaf enforcement, attestation issue/decode/signature
|
|
389
|
+
determinism and validation, and the full `verifyAttested` chain
|
|
390
|
+
(20+ cases including nesting, wildcard permitting, revocation at every
|
|
391
|
+
level, and signature robustness).
|
|
645
392
|
|
|
646
|
-
|
|
647
|
-
- π³οΈ [GOVERNANCE.md](../../GOVERNANCE.md) β Project decision-making process
|
|
648
|
-
- π [SECURITY.md](../../SECURITY.md) β Responsible disclosure policy
|
|
393
|
+
## πΊοΈ Roadmap
|
|
649
394
|
|
|
650
|
-
|
|
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.
|
|
651
399
|
|
|
652
400
|
## π License
|
|
653
401
|
|
|
654
|
-
Apache License 2.0 β see [LICENSE](../../LICENSE)
|
|
402
|
+
Apache License 2.0 β see [LICENSE](../../LICENSE).
|
|
655
403
|
|
|
656
|
-
Β© 2026 Me2em Organization. Built for privacy, openness, and user sovereignty.
|
|
404
|
+
Β© 2026 Me2em Organization. Built for privacy, openness, and user sovereignty.
|