@me2em/core 0.4.3-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/dist/crypto/ed25519.d.ts +4 -0
- package/dist/crypto/ed25519.d.ts.map +1 -1
- package/dist/crypto/ed25519.js +4 -0
- package/dist/crypto/ed25519.js.map +1 -1
- package/dist/handle.d.ts +40 -6
- package/dist/handle.d.ts.map +1 -1
- package/dist/handle.js +40 -6
- package/dist/handle.js.map +1 -1
- package/dist/identity.d.ts +33 -0
- package/dist/identity.d.ts.map +1 -1
- package/dist/identity.js +33 -0
- package/dist/identity.js.map +1 -1
- package/dist/index.d.ts +23 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +23 -2
- package/dist/index.js.map +1 -1
- package/dist/seed.d.ts +79 -7
- package/dist/seed.d.ts.map +1 -1
- package/dist/seed.js +79 -7
- package/dist/seed.js.map +1 -1
- package/dist/session.d.ts +21 -0
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +21 -0
- package/dist/session.js.map +1 -1
- package/package.json +1 -1
- package/src/crypto/ed25519.ts +4 -0
- package/src/handle.ts +42 -6
- package/src/identity.ts +33 -0
- package/src/index.ts +23 -3
- package/src/seed.ts +80 -7
- package/src/session.ts +22 -0
package/dist/crypto/ed25519.d.ts
CHANGED
|
@@ -1,4 +1,8 @@
|
|
|
1
1
|
import { ed } from './init.js';
|
|
2
|
+
/**
|
|
3
|
+
* @internal
|
|
4
|
+
* Low-level Ed25519 implementation wrapper.
|
|
5
|
+
*/
|
|
2
6
|
export declare const getPublicKey: (secretKey: ed.TArg<Uint8Array>) => ed.TRet<Uint8Array>;
|
|
3
7
|
export declare const sign: (message: ed.TArg<Uint8Array>, secretKey: ed.TArg<Uint8Array>) => ed.TRet<Uint8Array>;
|
|
4
8
|
export declare const verify: (signature: ed.TArg<Uint8Array>, message: ed.TArg<Uint8Array>, publicKey: ed.TArg<Uint8Array>, opts?: ed.TArg<ed.EdDSAVerifyOpts>) => boolean;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ed25519.d.ts","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAE/B,eAAO,MAAM,YAAY,yDAAkB,CAAC;AAC5C,eAAO,MAAM,IAAI,uFAAU,CAAC;AAC5B,eAAO,MAAM,MAAM,+IAAY,CAAC;AAChC,eAAO,MAAM,iBAAiB,kEAAuB,CAAC;AACtD,eAAO,MAAM,SAAS,gGAAe,CAAC;AACtC,eAAO,MAAM,WAAW,wJAAiB,CAAC"}
|
|
1
|
+
{"version":3,"file":"ed25519.d.ts","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,YAAY,yDAAkB,CAAC;AAC5C,eAAO,MAAM,IAAI,uFAAU,CAAC;AAC5B,eAAO,MAAM,MAAM,+IAAY,CAAC;AAChC,eAAO,MAAM,iBAAiB,kEAAuB,CAAC;AACtD,eAAO,MAAM,SAAS,gGAAe,CAAC;AACtC,eAAO,MAAM,WAAW,wJAAiB,CAAC"}
|
package/dist/crypto/ed25519.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ed25519.js","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAE/B,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC,YAAY,CAAC;AAC5C,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;AAC5B,MAAM,CAAC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;AAChC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,iBAAiB,CAAC;AACtD,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC;AACtC,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC"}
|
|
1
|
+
{"version":3,"file":"ed25519.js","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAE/B;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC,YAAY,CAAC;AAC5C,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;AAC5B,MAAM,CAAC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;AAChC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,iBAAiB,CAAC;AACtD,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC;AACtC,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC"}
|
package/dist/handle.d.ts
CHANGED
|
@@ -3,17 +3,51 @@ export interface HandleMetadata {
|
|
|
3
3
|
avatar?: string;
|
|
4
4
|
[key: string]: unknown;
|
|
5
5
|
}
|
|
6
|
+
/**
|
|
7
|
+
* Represents a context-specific cryptographic handle derived from an {@link Identity}.
|
|
8
|
+
*
|
|
9
|
+
* A Handle encapsulates a private key tied to a specific name (context).
|
|
10
|
+
* It provides methods for signing data, verifying signatures, and deriving
|
|
11
|
+
* secondary secrets (like passwords or channel keys) without ever exposing
|
|
12
|
+
* the underlying private key.
|
|
13
|
+
*
|
|
14
|
+
* @category Core Primitives
|
|
15
|
+
*/
|
|
6
16
|
export declare class Handle {
|
|
7
17
|
private readonly privateKey;
|
|
8
18
|
private readonly publicKey;
|
|
9
19
|
private readonly _name;
|
|
10
20
|
private readonly _metadata?;
|
|
21
|
+
/**
|
|
22
|
+
* Creates a new Handle instance.
|
|
23
|
+
* @internal Typically created via {@link Identity.deriveHandle}.
|
|
24
|
+
*
|
|
25
|
+
* @param privateKey - The 32-byte Ed25519 private key for this handle.
|
|
26
|
+
* @param name - The context name this handle represents.
|
|
27
|
+
* @param metadata - Optional metadata associated with this handle.
|
|
28
|
+
*/
|
|
11
29
|
constructor(privateKey: Uint8Array, name: string, metadata?: HandleMetadata);
|
|
30
|
+
/** @returns The unique context identifier for this Handle. */
|
|
12
31
|
getId(): string;
|
|
32
|
+
/**
|
|
33
|
+
* Cryptographically signs arbitrary data using the Handle's private key.
|
|
34
|
+
* @param data - The data to be signed, as a Uint8Array.
|
|
35
|
+
* @returns A Promise resolving to the Ed25519 signature as a Uint8Array.
|
|
36
|
+
*/
|
|
13
37
|
sign(data: Uint8Array): Promise<Uint8Array>;
|
|
38
|
+
/**
|
|
39
|
+
* Verifies an Ed25519 signature against the provided data and public key.
|
|
40
|
+
* @param signature - The signature to verify (Uint8Array).
|
|
41
|
+
* @param data - The original data that was signed (Uint8Array).
|
|
42
|
+
* @param publicKey - The public key to verify against (Uint8Array).
|
|
43
|
+
* @returns A Promise resolving to true if the signature is valid, false otherwise.
|
|
44
|
+
*/
|
|
14
45
|
static verify(signature: Uint8Array, data: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
|
|
46
|
+
/** @returns The context name associated with this Handle. */
|
|
15
47
|
getName(): string;
|
|
48
|
+
/** @returns The metadata object associated with this Handle. */
|
|
16
49
|
getMetadata(): HandleMetadata | undefined;
|
|
50
|
+
/** @returns A Uint8Array containing the 32-byte Ed25519 public key. */
|
|
17
51
|
getPublicKey(): Uint8Array;
|
|
18
52
|
/**
|
|
19
53
|
* Deterministically derives a secret (e.g., a password or API key) for a specific service context.
|
|
@@ -29,16 +63,15 @@ export declare class Handle {
|
|
|
29
63
|
* the Identity (controller) and this Handle (device/context).
|
|
30
64
|
*
|
|
31
65
|
* Both parties can independently compute this key because:
|
|
32
|
-
*
|
|
33
|
-
*
|
|
66
|
+
* 1. The Handle possesses its own private key directly.
|
|
67
|
+
* 2. The Identity can derive the same private key via `identity.deriveHandle(name)`.
|
|
34
68
|
*
|
|
35
69
|
* This enables zero-knowledge encrypted channels without key exchange protocols.
|
|
36
70
|
*
|
|
37
|
-
* @param context - Channel identifier for domain separation (e.g., 'drone-001', 'session-abc').
|
|
38
|
-
*
|
|
39
|
-
* @returns 32-byte Uint8Array suitable for AES-256-GCM encryption.
|
|
40
|
-
*
|
|
71
|
+
* @param context - Channel identifier for domain separation (e.g., 'drone-001', 'session-abc'). Both parties MUST use the same context.
|
|
72
|
+
* @returns A 32-byte Uint8Array suitable for AES-256-GCM encryption.
|
|
41
73
|
* @example
|
|
74
|
+
* ```typescript
|
|
42
75
|
* // On the drone (Handle side):
|
|
43
76
|
* const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
44
77
|
* const encrypted = await encryptAESGCM(telemetry, channelKey);
|
|
@@ -47,6 +80,7 @@ export declare class Handle {
|
|
|
47
80
|
* const droneHandle = await centerIdentity.deriveHandle('drone-001');
|
|
48
81
|
* const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
49
82
|
* const decrypted = await decryptAESGCM(encrypted, channelKey);
|
|
83
|
+
* ```
|
|
50
84
|
*/
|
|
51
85
|
deriveChannelKey(context: string): Uint8Array;
|
|
52
86
|
}
|
package/dist/handle.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAiB;
|
|
1
|
+
{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAiB;IAE1C;;;;;;;KAOC;gBACS,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc;IAO3E,8DAA8D;IAC9D,KAAK,IAAI,MAAM;IAOb;;;;KAIC;IACG,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAI/C;;;;;;KAMC;WACU,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrG,6DAA6D;IAC7D,OAAO,IAAI,MAAM;IAEjB,gEAAgE;IAChE,WAAW,IAAI,cAAc,GAAG,SAAS;IAExC,uEAAuE;IACxE,YAAY,IAAI,UAAU;IAE1B;;;;;;;OAOG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,MAAM;IAc5D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;CAK9C"}
|
package/dist/handle.js
CHANGED
|
@@ -1,31 +1,65 @@
|
|
|
1
1
|
import { ed } from './crypto/init.js';
|
|
2
2
|
import { hkdf } from '@noble/hashes/hkdf.js';
|
|
3
3
|
import { sha256 } from '@noble/hashes/sha2.js';
|
|
4
|
+
/**
|
|
5
|
+
* Represents a context-specific cryptographic handle derived from an {@link Identity}.
|
|
6
|
+
*
|
|
7
|
+
* A Handle encapsulates a private key tied to a specific name (context).
|
|
8
|
+
* It provides methods for signing data, verifying signatures, and deriving
|
|
9
|
+
* secondary secrets (like passwords or channel keys) without ever exposing
|
|
10
|
+
* the underlying private key.
|
|
11
|
+
*
|
|
12
|
+
* @category Core Primitives
|
|
13
|
+
*/
|
|
4
14
|
export class Handle {
|
|
5
15
|
privateKey;
|
|
6
16
|
publicKey;
|
|
7
17
|
_name;
|
|
8
18
|
_metadata;
|
|
19
|
+
/**
|
|
20
|
+
* Creates a new Handle instance.
|
|
21
|
+
* @internal Typically created via {@link Identity.deriveHandle}.
|
|
22
|
+
*
|
|
23
|
+
* @param privateKey - The 32-byte Ed25519 private key for this handle.
|
|
24
|
+
* @param name - The context name this handle represents.
|
|
25
|
+
* @param metadata - Optional metadata associated with this handle.
|
|
26
|
+
*/
|
|
9
27
|
constructor(privateKey, name, metadata) {
|
|
10
28
|
this.privateKey = privateKey;
|
|
11
29
|
this.publicKey = ed.getPublicKey(privateKey);
|
|
12
30
|
this._name = name;
|
|
13
31
|
this._metadata = metadata;
|
|
14
32
|
}
|
|
33
|
+
/** @returns The unique context identifier for this Handle. */
|
|
15
34
|
getId() {
|
|
16
35
|
return btoa(String.fromCharCode(...this.publicKey))
|
|
17
36
|
.replace(/\+/g, '-')
|
|
18
37
|
.replace(/\//g, '_')
|
|
19
38
|
.replace(/=+$/, '');
|
|
20
39
|
}
|
|
40
|
+
/**
|
|
41
|
+
* Cryptographically signs arbitrary data using the Handle's private key.
|
|
42
|
+
* @param data - The data to be signed, as a Uint8Array.
|
|
43
|
+
* @returns A Promise resolving to the Ed25519 signature as a Uint8Array.
|
|
44
|
+
*/
|
|
21
45
|
async sign(data) {
|
|
22
46
|
return ed.sign(data, this.privateKey);
|
|
23
47
|
}
|
|
48
|
+
/**
|
|
49
|
+
* Verifies an Ed25519 signature against the provided data and public key.
|
|
50
|
+
* @param signature - The signature to verify (Uint8Array).
|
|
51
|
+
* @param data - The original data that was signed (Uint8Array).
|
|
52
|
+
* @param publicKey - The public key to verify against (Uint8Array).
|
|
53
|
+
* @returns A Promise resolving to true if the signature is valid, false otherwise.
|
|
54
|
+
*/
|
|
24
55
|
static async verify(signature, data, publicKey) {
|
|
25
56
|
return ed.verify(signature, data, publicKey);
|
|
26
57
|
}
|
|
58
|
+
/** @returns The context name associated with this Handle. */
|
|
27
59
|
getName() { return this._name; }
|
|
60
|
+
/** @returns The metadata object associated with this Handle. */
|
|
28
61
|
getMetadata() { return this._metadata; }
|
|
62
|
+
/** @returns A Uint8Array containing the 32-byte Ed25519 public key. */
|
|
29
63
|
getPublicKey() { return this.publicKey; }
|
|
30
64
|
/**
|
|
31
65
|
* Deterministically derives a secret (e.g., a password or API key) for a specific service context.
|
|
@@ -51,16 +85,15 @@ export class Handle {
|
|
|
51
85
|
* the Identity (controller) and this Handle (device/context).
|
|
52
86
|
*
|
|
53
87
|
* Both parties can independently compute this key because:
|
|
54
|
-
*
|
|
55
|
-
*
|
|
88
|
+
* 1. The Handle possesses its own private key directly.
|
|
89
|
+
* 2. The Identity can derive the same private key via `identity.deriveHandle(name)`.
|
|
56
90
|
*
|
|
57
91
|
* This enables zero-knowledge encrypted channels without key exchange protocols.
|
|
58
92
|
*
|
|
59
|
-
* @param context - Channel identifier for domain separation (e.g., 'drone-001', 'session-abc').
|
|
60
|
-
*
|
|
61
|
-
* @returns 32-byte Uint8Array suitable for AES-256-GCM encryption.
|
|
62
|
-
*
|
|
93
|
+
* @param context - Channel identifier for domain separation (e.g., 'drone-001', 'session-abc'). Both parties MUST use the same context.
|
|
94
|
+
* @returns A 32-byte Uint8Array suitable for AES-256-GCM encryption.
|
|
63
95
|
* @example
|
|
96
|
+
* ```typescript
|
|
64
97
|
* // On the drone (Handle side):
|
|
65
98
|
* const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
66
99
|
* const encrypted = await encryptAESGCM(telemetry, channelKey);
|
|
@@ -69,6 +102,7 @@ export class Handle {
|
|
|
69
102
|
* const droneHandle = await centerIdentity.deriveHandle('drone-001');
|
|
70
103
|
* const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
71
104
|
* const decrypted = await decryptAESGCM(encrypted, channelKey);
|
|
105
|
+
* ```
|
|
72
106
|
*/
|
|
73
107
|
deriveChannelKey(context) {
|
|
74
108
|
const salt = new TextEncoder().encode(`me2em/channel/${context.toLowerCase().trim()}`);
|
package/dist/handle.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"handle.js","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAQ/C,MAAM,OAAO,MAAM;IACA,UAAU,CAAa;IACvB,SAAS,CAAa;IACtB,KAAK,CAAS;IACd,SAAS,CAAkB;
|
|
1
|
+
{"version":3,"file":"handle.js","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAQ/C;;;;;;;;;GASG;AACH,MAAM,OAAO,MAAM;IACA,UAAU,CAAa;IACvB,SAAS,CAAa;IACtB,KAAK,CAAS;IACd,SAAS,CAAkB;IAE1C;;;;;;;KAOC;IACH,YAAY,UAAsB,EAAE,IAAY,EAAE,QAAyB;QACzE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,8DAA8D;IAC9D,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;aAChD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;IAEC;;;;KAIC;IACH,KAAK,CAAC,IAAI,CAAC,IAAgB;QACzB,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAEC;;;;;;KAMC;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAqB,EAAE,IAAgB,EAAE,SAAqB;QAChF,OAAO,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED,6DAA6D;IAC7D,OAAO,KAAa,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAExC,gEAAgE;IAChE,WAAW,KAAiC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAEnE,uEAAuE;IACxE,YAAY,KAAiB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAErD;;;;;;;OAOG;IACH,cAAc,CAAC,OAAe,EAAE,SAAiB,EAAE;QACjD,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gBAAgB,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtF,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAEzD,+DAA+D;QAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAEtE,mDAAmD;QACnD,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,WAAW,CAAC,CAAC;aAC7C,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gBAAgB,CAAC,OAAe;QAC9B,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,iBAAiB,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvF,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IACvD,CAAC;CACF"}
|
package/dist/identity.d.ts
CHANGED
|
@@ -1,10 +1,43 @@
|
|
|
1
1
|
import { Handle, type HandleMetadata } from './handle.js';
|
|
2
|
+
/**
|
|
3
|
+
* Represents the root cryptographic identity derived from a seed phrase.
|
|
4
|
+
*
|
|
5
|
+
* An Identity is the foundation of the Me2em protocol. It allows for the
|
|
6
|
+
* hierarchical derivation of isolated {@link Handle}s for different contexts
|
|
7
|
+
* (e.g., email, social, specific devices) from a single master seed,
|
|
8
|
+
* ensuring zero cross-contamination of cryptographic material.
|
|
9
|
+
*
|
|
10
|
+
* @category Core Primitives
|
|
11
|
+
*/
|
|
2
12
|
export declare class Identity {
|
|
3
13
|
private readonly privateKey;
|
|
4
14
|
private readonly publicKey;
|
|
5
15
|
private constructor();
|
|
16
|
+
/**
|
|
17
|
+
* Initializes a new Identity from a BIP39 mnemonic seed phrase or raw seed bytes.
|
|
18
|
+
*
|
|
19
|
+
* @param seed - A 12 or 24-word BIP39 mnemonic string, or a raw Uint8Array seed.
|
|
20
|
+
* @returns A Promise resolving to a new Identity instance.
|
|
21
|
+
* @throws {Error} If the provided seed is invalid or cannot be processed.
|
|
22
|
+
*/
|
|
6
23
|
static fromSeed(seed: Uint8Array | string): Promise<Identity>;
|
|
24
|
+
/**
|
|
25
|
+
* Derives a new, cryptographically isolated {@link Handle} for a specific context.
|
|
26
|
+
*
|
|
27
|
+
* Each Handle is derived deterministically. The same name and metadata will
|
|
28
|
+
* always produce the same Handle from the same Identity, but different names
|
|
29
|
+
* produce completely unrelated keys.
|
|
30
|
+
*
|
|
31
|
+
* @param name - The context identifier (e.g., 'alice@example.com', 'device-1').
|
|
32
|
+
* @param metadata - Optional metadata to associate with this Handle.
|
|
33
|
+
* @returns A Promise resolving to the derived Handle.
|
|
34
|
+
*/
|
|
7
35
|
deriveHandle(name: string, metadata?: HandleMetadata): Promise<Handle>;
|
|
36
|
+
/**
|
|
37
|
+
* Retrieves the public key of the root Identity.
|
|
38
|
+
*
|
|
39
|
+
* @returns A Uint8Array containing the 32-byte Ed25519 public key.
|
|
40
|
+
*/
|
|
8
41
|
getPublicKey(): Uint8Array;
|
|
9
42
|
}
|
|
10
43
|
//# sourceMappingURL=identity.d.ts.map
|
package/dist/identity.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAI1D,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IAEvC,OAAO;
|
|
1
|
+
{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAI1D;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IAEvC,OAAO;IAKL;;;;;;KAMC;WACU,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAoBjE;;;;;;;;;;KAUC;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB5E;;;;OAIG;IACH,YAAY,IAAI,UAAU;CAG3B"}
|
package/dist/identity.js
CHANGED
|
@@ -3,6 +3,16 @@ import { hkdf } from '@noble/hashes/hkdf.js';
|
|
|
3
3
|
import { sha256 } from '@noble/hashes/sha2.js';
|
|
4
4
|
import { Handle } from './handle.js';
|
|
5
5
|
const ME2EM_HKDF_INFO_PREFIX = 'me2em/handle/v1/';
|
|
6
|
+
/**
|
|
7
|
+
* Represents the root cryptographic identity derived from a seed phrase.
|
|
8
|
+
*
|
|
9
|
+
* An Identity is the foundation of the Me2em protocol. It allows for the
|
|
10
|
+
* hierarchical derivation of isolated {@link Handle}s for different contexts
|
|
11
|
+
* (e.g., email, social, specific devices) from a single master seed,
|
|
12
|
+
* ensuring zero cross-contamination of cryptographic material.
|
|
13
|
+
*
|
|
14
|
+
* @category Core Primitives
|
|
15
|
+
*/
|
|
6
16
|
export class Identity {
|
|
7
17
|
privateKey;
|
|
8
18
|
publicKey;
|
|
@@ -10,6 +20,13 @@ export class Identity {
|
|
|
10
20
|
this.privateKey = privateKey;
|
|
11
21
|
this.publicKey = ed.getPublicKey(privateKey); // Теперь работает синхронно
|
|
12
22
|
}
|
|
23
|
+
/**
|
|
24
|
+
* Initializes a new Identity from a BIP39 mnemonic seed phrase or raw seed bytes.
|
|
25
|
+
*
|
|
26
|
+
* @param seed - A 12 or 24-word BIP39 mnemonic string, or a raw Uint8Array seed.
|
|
27
|
+
* @returns A Promise resolving to a new Identity instance.
|
|
28
|
+
* @throws {Error} If the provided seed is invalid or cannot be processed.
|
|
29
|
+
*/
|
|
13
30
|
static async fromSeed(seed) {
|
|
14
31
|
const seedBytes = typeof seed === 'string'
|
|
15
32
|
? Uint8Array.from(Buffer.from(seed, 'hex'))
|
|
@@ -23,6 +40,17 @@ export class Identity {
|
|
|
23
40
|
);
|
|
24
41
|
return new Identity(key);
|
|
25
42
|
}
|
|
43
|
+
/**
|
|
44
|
+
* Derives a new, cryptographically isolated {@link Handle} for a specific context.
|
|
45
|
+
*
|
|
46
|
+
* Each Handle is derived deterministically. The same name and metadata will
|
|
47
|
+
* always produce the same Handle from the same Identity, but different names
|
|
48
|
+
* produce completely unrelated keys.
|
|
49
|
+
*
|
|
50
|
+
* @param name - The context identifier (e.g., 'alice@example.com', 'device-1').
|
|
51
|
+
* @param metadata - Optional metadata to associate with this Handle.
|
|
52
|
+
* @returns A Promise resolving to the derived Handle.
|
|
53
|
+
*/
|
|
26
54
|
async deriveHandle(name, metadata) {
|
|
27
55
|
const info = new TextEncoder().encode(ME2EM_HKDF_INFO_PREFIX + name.toLowerCase().trim());
|
|
28
56
|
// Используем sha256 для единообразия (или sha512, если нужно)
|
|
@@ -31,6 +59,11 @@ export class Identity {
|
|
|
31
59
|
this.privateKey, new Uint8Array(0), info, 32);
|
|
32
60
|
return new Handle(handleKey, name, metadata);
|
|
33
61
|
}
|
|
62
|
+
/**
|
|
63
|
+
* Retrieves the public key of the root Identity.
|
|
64
|
+
*
|
|
65
|
+
* @returns A Uint8Array containing the 32-byte Ed25519 public key.
|
|
66
|
+
*/
|
|
34
67
|
getPublicKey() {
|
|
35
68
|
return this.publicKey;
|
|
36
69
|
}
|
package/dist/identity.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAU,MAAM,kBAAkB,CAAC,CAAE,wCAAwC;AACxF,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAE1D,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAElD,MAAM,OAAO,QAAQ;IACF,UAAU,CAAa;IACvB,SAAS,CAAa;IAEvC,YAAoB,UAAsB;QACxC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAE,4BAA4B;IAC7E,CAAC;
|
|
1
|
+
{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAU,MAAM,kBAAkB,CAAC,CAAE,wCAAwC;AACxF,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAE1D,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,OAAO,QAAQ;IACF,UAAU,CAAa;IACvB,SAAS,CAAa;IAEvC,YAAoB,UAAsB;QACxC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAE,4BAA4B;IAC7E,CAAC;IAEC;;;;;;KAMC;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAyB;QAC7C,MAAM,SAAS,GAAG,OAAO,IAAI,KAAK,QAAQ;YACxC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC3C,CAAC,CAAC,IAAI,CAAC;QAET,IAAI,SAAS,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CACd,MAAM,EACN,SAAS,EACT,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO;QAC1B,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,wBAAwB,CAAC,EAAE,OAAO;QAC3D,EAAE,CAAC,SAAS;SACb,CAAC;QAEF,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAEC;;;;;;;;;;KAUC;IACH,KAAK,CAAC,YAAY,CAAC,IAAY,EAAE,QAAyB;QACxD,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,sBAAsB,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAE1F,8DAA8D;QAC9D,qDAAqD;QACrD,MAAM,SAAS,GAAG,IAAI,CACpB,MAAM,EAAG,8DAA8D;QACvE,IAAI,CAAC,UAAU,EACf,IAAI,UAAU,CAAC,CAAC,CAAC,EACjB,IAAI,EACJ,EAAE,CACH,CAAC;QAEF,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}
|
package/dist/index.d.ts
CHANGED
|
@@ -2,6 +2,28 @@ export { Identity } from './identity.js';
|
|
|
2
2
|
export { Handle, type HandleMetadata } from './handle.js';
|
|
3
3
|
export { Session, type SessionOptions, type SessionToken } from './session.js';
|
|
4
4
|
export * as crypto from './crypto/index.js';
|
|
5
|
+
/**
|
|
6
|
+
* @module @me2em/core
|
|
7
|
+
* @packageDocumentation
|
|
8
|
+
*
|
|
9
|
+
* Core cryptographic primitives for the Me2em authorization protocol.
|
|
10
|
+
*
|
|
11
|
+
* This package provides the foundation for decentralized, multi-context
|
|
12
|
+
* identity management and secure, stateless authentication.
|
|
13
|
+
*
|
|
14
|
+
* ## Key Features
|
|
15
|
+
* - **Hierarchical Identities**: Derive multiple isolated {@link Handle}s from a single seed.
|
|
16
|
+
* - **Stateless Auth**: Cryptographic proof without server-side session storage via {@link Session}.
|
|
17
|
+
* - **Zero-Knowledge Secrets**: Deterministic password derivation without storage.
|
|
18
|
+
*
|
|
19
|
+
* @example Basic usage
|
|
20
|
+
* ```typescript
|
|
21
|
+
* import { Identity } from '@me2em/core';
|
|
22
|
+
*
|
|
23
|
+
* const identity = await Identity.fromSeed('your twelve word mnemonic phrase here...');
|
|
24
|
+
* const handle = await identity.deriveHandle('user@example.com');
|
|
25
|
+
* const signature = await handle.sign(new TextEncoder().encode('data'));
|
|
26
|
+
* ```
|
|
27
|
+
*/
|
|
5
28
|
export { generateSeedPhrase, normalizeSeedPhrase, validateSeedPhrase, get32ByteSeedFromMnemonic, type SeedStrength } from './seed.js';
|
|
6
|
-
export declare const PROTOCOL_VERSION = "0.4.1-alpha.1";
|
|
7
29
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,28 @@ export { Identity } from './identity.js';
|
|
|
2
2
|
export { Handle } from './handle.js';
|
|
3
3
|
export { Session } from './session.js';
|
|
4
4
|
export * as crypto from './crypto/index.js';
|
|
5
|
-
|
|
5
|
+
/**
|
|
6
|
+
* @module @me2em/core
|
|
7
|
+
* @packageDocumentation
|
|
8
|
+
*
|
|
9
|
+
* Core cryptographic primitives for the Me2em authorization protocol.
|
|
10
|
+
*
|
|
11
|
+
* This package provides the foundation for decentralized, multi-context
|
|
12
|
+
* identity management and secure, stateless authentication.
|
|
13
|
+
*
|
|
14
|
+
* ## Key Features
|
|
15
|
+
* - **Hierarchical Identities**: Derive multiple isolated {@link Handle}s from a single seed.
|
|
16
|
+
* - **Stateless Auth**: Cryptographic proof without server-side session storage via {@link Session}.
|
|
17
|
+
* - **Zero-Knowledge Secrets**: Deterministic password derivation without storage.
|
|
18
|
+
*
|
|
19
|
+
* @example Basic usage
|
|
20
|
+
* ```typescript
|
|
21
|
+
* import { Identity } from '@me2em/core';
|
|
22
|
+
*
|
|
23
|
+
* const identity = await Identity.fromSeed('your twelve word mnemonic phrase here...');
|
|
24
|
+
* const handle = await identity.deriveHandle('user@example.com');
|
|
25
|
+
* const signature = await handle.sign(new TextEncoder().encode('data'));
|
|
26
|
+
* ```
|
|
27
|
+
*/
|
|
6
28
|
export { generateSeedPhrase, normalizeSeedPhrase, validateSeedPhrase, get32ByteSeedFromMnemonic } from './seed.js';
|
|
7
|
-
export const PROTOCOL_VERSION = '0.4.1-alpha.1';
|
|
8
29
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,OAAO,EAA0C,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,OAAO,EAA0C,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EAE1B,MAAM,WAAW,CAAC"}
|
package/dist/seed.d.ts
CHANGED
|
@@ -1,24 +1,96 @@
|
|
|
1
1
|
export type SeedStrength = 128 | 256;
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
3
|
+
* Utilities for BIP39 mnemonic seed phrase generation and validation.
|
|
4
|
+
*
|
|
5
|
+
* These functions provide secure, deterministic seed phrase handling
|
|
6
|
+
* compatible with the BIP39 standard.
|
|
7
|
+
*
|
|
8
|
+
* @category Seed Utilities
|
|
9
|
+
* @packageDocumentation
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Generates a cryptographically secure random mnemonic seed phrase.
|
|
13
|
+
*
|
|
14
|
+
* @param strength - The entropy strength in bits.
|
|
15
|
+
* - 128 bits = 12 words (standard security)
|
|
16
|
+
* - 160 bits = 15 words
|
|
17
|
+
* - 192 bits = 18 words
|
|
18
|
+
* - 224 bits = 21 words
|
|
19
|
+
* - 256 bits = 24 words (maximum security)
|
|
20
|
+
*
|
|
21
|
+
* @returns A Promise resolving to a space-separated mnemonic string.
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```typescript
|
|
25
|
+
* const mnemonic12 = await generateSeedPhrase(128);
|
|
26
|
+
* // "abandon abandon abandon ... art"
|
|
27
|
+
*
|
|
28
|
+
* const mnemonic24 = await generateSeedPhrase(256);
|
|
29
|
+
* // "abandon abandon abandon ... zoo" (24 words)
|
|
30
|
+
* ```
|
|
6
31
|
*/
|
|
7
32
|
export declare function generateSeedPhrase(strength?: SeedStrength): string[];
|
|
8
33
|
/**
|
|
9
|
-
* Normalizes a seed phrase
|
|
34
|
+
* Normalizes a mnemonic seed phrase by trimming whitespace and converting to lowercase.
|
|
35
|
+
*
|
|
36
|
+
* @param phrase - The mnemonic phrase to normalize (string or array of words).
|
|
37
|
+
* @returns A normalized string of lowercase words separated by single spaces.
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* ```typescript
|
|
41
|
+
* const normalized = normalizeSeedPhrase(' ABANDON abandon ART ');
|
|
42
|
+
* // "abandon abandon art"
|
|
43
|
+
*
|
|
44
|
+
* const normalized2 = normalizeSeedPhrase(['abandon', ' ART ', 'zoo']);
|
|
45
|
+
* // "abandon art zoo"
|
|
46
|
+
* ```
|
|
10
47
|
*/
|
|
11
48
|
export declare function normalizeSeedPhrase(seedPhrase: string | string[]): string[];
|
|
12
49
|
/**
|
|
13
|
-
* Validates a
|
|
50
|
+
* Validates a mnemonic seed phrase against the BIP39 standard.
|
|
51
|
+
*
|
|
52
|
+
* Checks:
|
|
53
|
+
* - Correct word count (12, 15, 18, 21, or 24 words)
|
|
54
|
+
* - All words exist in the BIP39 wordlist
|
|
55
|
+
* - Valid checksum
|
|
56
|
+
*
|
|
57
|
+
* @param phrase - The mnemonic phrase to validate.
|
|
58
|
+
* @returns `true` if the phrase is valid, `false` otherwise.
|
|
59
|
+
*
|
|
60
|
+
* @example
|
|
61
|
+
* ```typescript
|
|
62
|
+
* const isValid = await validateSeedPhrase('abandon abandon ... art');
|
|
63
|
+
* // true
|
|
64
|
+
*
|
|
65
|
+
* const isInvalid = await validateSeedPhrase('invalid word list ...');
|
|
66
|
+
* // false
|
|
67
|
+
* ```
|
|
14
68
|
*/
|
|
15
69
|
export declare function validateSeedPhrase(words: string[]): {
|
|
16
70
|
isValid: boolean;
|
|
17
71
|
error?: string;
|
|
18
72
|
};
|
|
19
73
|
/**
|
|
20
|
-
*
|
|
21
|
-
*
|
|
74
|
+
* Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
|
|
75
|
+
*
|
|
76
|
+
* This is the standard BIP39 derivation function that converts a human-readable
|
|
77
|
+
* mnemonic into a binary seed suitable for key generation.
|
|
78
|
+
*
|
|
79
|
+
* @param phrase - The BIP39 mnemonic phrase (will be normalized automatically).
|
|
80
|
+
* @param passphrase - Optional passphrase for additional security (BIP39 "25th word").
|
|
81
|
+
* @returns A Promise resolving to a 32-byte Uint8Array seed.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```typescript
|
|
85
|
+
* const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
|
|
86
|
+
* // Uint8Array(32) [123, 45, 67, ...]
|
|
87
|
+
*
|
|
88
|
+
* const seedWithPassphrase = await get32ByteSeedFromMnemonic(
|
|
89
|
+
* 'abandon abandon ... art',
|
|
90
|
+
* 'mySecretPassphrase'
|
|
91
|
+
* );
|
|
92
|
+
* // Different seed even with same mnemonic
|
|
93
|
+
* ```
|
|
22
94
|
*/
|
|
23
95
|
export declare function get32ByteSeedFromMnemonic(seedPhrase: string | string[]): Promise<Uint8Array>;
|
|
24
96
|
//# sourceMappingURL=seed.d.ts.map
|
package/dist/seed.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,CAAC;AAErC
|
|
1
|
+
{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,CAAC;AAErC;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,YAAkB,GAAG,MAAM,EAAE,CAMzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAG3E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAexF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAalG"}
|
package/dist/seed.js
CHANGED
|
@@ -2,9 +2,34 @@ import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39
|
|
|
2
2
|
import { wordlist } from '@scure/bip39/wordlists/english';
|
|
3
3
|
import { sha256 } from './crypto/hkdf.js';
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* Utilities for BIP39 mnemonic seed phrase generation and validation.
|
|
6
|
+
*
|
|
7
|
+
* These functions provide secure, deterministic seed phrase handling
|
|
8
|
+
* compatible with the BIP39 standard.
|
|
9
|
+
*
|
|
10
|
+
* @category Seed Utilities
|
|
11
|
+
* @packageDocumentation
|
|
12
|
+
*/
|
|
13
|
+
/**
|
|
14
|
+
* Generates a cryptographically secure random mnemonic seed phrase.
|
|
15
|
+
*
|
|
16
|
+
* @param strength - The entropy strength in bits.
|
|
17
|
+
* - 128 bits = 12 words (standard security)
|
|
18
|
+
* - 160 bits = 15 words
|
|
19
|
+
* - 192 bits = 18 words
|
|
20
|
+
* - 224 bits = 21 words
|
|
21
|
+
* - 256 bits = 24 words (maximum security)
|
|
22
|
+
*
|
|
23
|
+
* @returns A Promise resolving to a space-separated mnemonic string.
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* ```typescript
|
|
27
|
+
* const mnemonic12 = await generateSeedPhrase(128);
|
|
28
|
+
* // "abandon abandon abandon ... art"
|
|
29
|
+
*
|
|
30
|
+
* const mnemonic24 = await generateSeedPhrase(256);
|
|
31
|
+
* // "abandon abandon abandon ... zoo" (24 words)
|
|
32
|
+
* ```
|
|
8
33
|
*/
|
|
9
34
|
export function generateSeedPhrase(strength = 128) {
|
|
10
35
|
if (strength !== 128 && strength !== 256) {
|
|
@@ -14,14 +39,43 @@ export function generateSeedPhrase(strength = 128) {
|
|
|
14
39
|
return mnemonic.split(' ');
|
|
15
40
|
}
|
|
16
41
|
/**
|
|
17
|
-
* Normalizes a seed phrase
|
|
42
|
+
* Normalizes a mnemonic seed phrase by trimming whitespace and converting to lowercase.
|
|
43
|
+
*
|
|
44
|
+
* @param phrase - The mnemonic phrase to normalize (string or array of words).
|
|
45
|
+
* @returns A normalized string of lowercase words separated by single spaces.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* ```typescript
|
|
49
|
+
* const normalized = normalizeSeedPhrase(' ABANDON abandon ART ');
|
|
50
|
+
* // "abandon abandon art"
|
|
51
|
+
*
|
|
52
|
+
* const normalized2 = normalizeSeedPhrase(['abandon', ' ART ', 'zoo']);
|
|
53
|
+
* // "abandon art zoo"
|
|
54
|
+
* ```
|
|
18
55
|
*/
|
|
19
56
|
export function normalizeSeedPhrase(seedPhrase) {
|
|
20
57
|
const words = Array.isArray(seedPhrase) ? seedPhrase : seedPhrase.trim().split(/\s+/);
|
|
21
58
|
return words.map(word => word.toLowerCase().trim()).filter(word => word.length > 0);
|
|
22
59
|
}
|
|
23
60
|
/**
|
|
24
|
-
* Validates a
|
|
61
|
+
* Validates a mnemonic seed phrase against the BIP39 standard.
|
|
62
|
+
*
|
|
63
|
+
* Checks:
|
|
64
|
+
* - Correct word count (12, 15, 18, 21, or 24 words)
|
|
65
|
+
* - All words exist in the BIP39 wordlist
|
|
66
|
+
* - Valid checksum
|
|
67
|
+
*
|
|
68
|
+
* @param phrase - The mnemonic phrase to validate.
|
|
69
|
+
* @returns `true` if the phrase is valid, `false` otherwise.
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* ```typescript
|
|
73
|
+
* const isValid = await validateSeedPhrase('abandon abandon ... art');
|
|
74
|
+
* // true
|
|
75
|
+
*
|
|
76
|
+
* const isInvalid = await validateSeedPhrase('invalid word list ...');
|
|
77
|
+
* // false
|
|
78
|
+
* ```
|
|
25
79
|
*/
|
|
26
80
|
export function validateSeedPhrase(words) {
|
|
27
81
|
const wordCount = words.length;
|
|
@@ -38,8 +92,26 @@ export function validateSeedPhrase(words) {
|
|
|
38
92
|
return { isValid, error: isValid ? undefined : 'Invalid seed phrase checksum' };
|
|
39
93
|
}
|
|
40
94
|
/**
|
|
41
|
-
*
|
|
42
|
-
*
|
|
95
|
+
* Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
|
|
96
|
+
*
|
|
97
|
+
* This is the standard BIP39 derivation function that converts a human-readable
|
|
98
|
+
* mnemonic into a binary seed suitable for key generation.
|
|
99
|
+
*
|
|
100
|
+
* @param phrase - The BIP39 mnemonic phrase (will be normalized automatically).
|
|
101
|
+
* @param passphrase - Optional passphrase for additional security (BIP39 "25th word").
|
|
102
|
+
* @returns A Promise resolving to a 32-byte Uint8Array seed.
|
|
103
|
+
*
|
|
104
|
+
* @example
|
|
105
|
+
* ```typescript
|
|
106
|
+
* const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
|
|
107
|
+
* // Uint8Array(32) [123, 45, 67, ...]
|
|
108
|
+
*
|
|
109
|
+
* const seedWithPassphrase = await get32ByteSeedFromMnemonic(
|
|
110
|
+
* 'abandon abandon ... art',
|
|
111
|
+
* 'mySecretPassphrase'
|
|
112
|
+
* );
|
|
113
|
+
* // Different seed even with same mnemonic
|
|
114
|
+
* ```
|
|
43
115
|
*/
|
|
44
116
|
export async function get32ByteSeedFromMnemonic(seedPhrase) {
|
|
45
117
|
const words = normalizeSeedPhrase(seedPhrase);
|
package/dist/seed.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI1C
|
|
1
|
+
{"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI1C;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAyB,GAAG;IAC7D,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACtD,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAA6B;IAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAe;IAChD,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;IAC/B,IAAI,SAAS,KAAK,EAAE,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,2CAA2C,SAAS,EAAE,EAAE,CAAC;IAC3F,CAAC;IAED,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;IACjE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,8BAA8B,EAAE,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,UAA6B;IAC3E,MAAM,KAAK,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAE7C,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,wBAAwB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE9C,wEAAwE;IACxE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}
|
package/dist/session.d.ts
CHANGED
|
@@ -9,12 +9,33 @@ export interface SessionToken {
|
|
|
9
9
|
expiresAt: number;
|
|
10
10
|
token: string;
|
|
11
11
|
}
|
|
12
|
+
/**
|
|
13
|
+
* Represents a stateless, cryptographically verifiable session token.
|
|
14
|
+
*
|
|
15
|
+
* Instead of storing session state on the server, the Session object
|
|
16
|
+
* encapsulates all necessary authorization data (handle ID, scopes, expiration)
|
|
17
|
+
* into a self-contained structure that can be verified using the Handle's public key.
|
|
18
|
+
*
|
|
19
|
+
* @category Core Primitives
|
|
20
|
+
*/
|
|
12
21
|
export declare class Session {
|
|
13
22
|
readonly handleId: string;
|
|
14
23
|
readonly scopes: string[];
|
|
15
24
|
readonly expiresAt: number;
|
|
16
25
|
readonly token: string;
|
|
26
|
+
/**
|
|
27
|
+
* Creates a new Session instance.
|
|
28
|
+
*
|
|
29
|
+
* @param handleId - The ID of the Handle that authorized this session.
|
|
30
|
+
* @param scopes - An array of permission scopes granted in this session (e.g., ['read', 'write']).
|
|
31
|
+
* @param expiresAt - Unix timestamp (in milliseconds) when this session expires.
|
|
32
|
+
* @param token - The cryptographic token string (e.g., JWT or custom signature format).
|
|
33
|
+
*/
|
|
17
34
|
constructor(handleId: string, scopes: string[], expiresAt: number, token: string);
|
|
35
|
+
/**
|
|
36
|
+
* Checks if the session has expired based on the current time.
|
|
37
|
+
* @returns `true` if the current time is past the `expiresAt` timestamp, `false` otherwise.
|
|
38
|
+
*/
|
|
18
39
|
isExpired(): boolean;
|
|
19
40
|
}
|
|
20
41
|
//# sourceMappingURL=session.d.ts.map
|
package/dist/session.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,OAAO;
|
|
1
|
+
{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,qBAAa,OAAO;aAWA,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM,EAAE;aAChB,SAAS,EAAE,MAAM;aACjB,KAAK,EAAE,MAAM;IAZ7B;;;;;;;KAOC;gBAEe,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM;IAG/B;;;OAGG;IACH,SAAS,IAAI,OAAO;CAGrB"}
|
package/dist/session.js
CHANGED
|
@@ -1,14 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Represents a stateless, cryptographically verifiable session token.
|
|
3
|
+
*
|
|
4
|
+
* Instead of storing session state on the server, the Session object
|
|
5
|
+
* encapsulates all necessary authorization data (handle ID, scopes, expiration)
|
|
6
|
+
* into a self-contained structure that can be verified using the Handle's public key.
|
|
7
|
+
*
|
|
8
|
+
* @category Core Primitives
|
|
9
|
+
*/
|
|
1
10
|
export class Session {
|
|
2
11
|
handleId;
|
|
3
12
|
scopes;
|
|
4
13
|
expiresAt;
|
|
5
14
|
token;
|
|
15
|
+
/**
|
|
16
|
+
* Creates a new Session instance.
|
|
17
|
+
*
|
|
18
|
+
* @param handleId - The ID of the Handle that authorized this session.
|
|
19
|
+
* @param scopes - An array of permission scopes granted in this session (e.g., ['read', 'write']).
|
|
20
|
+
* @param expiresAt - Unix timestamp (in milliseconds) when this session expires.
|
|
21
|
+
* @param token - The cryptographic token string (e.g., JWT or custom signature format).
|
|
22
|
+
*/
|
|
6
23
|
constructor(handleId, scopes, expiresAt, token) {
|
|
7
24
|
this.handleId = handleId;
|
|
8
25
|
this.scopes = scopes;
|
|
9
26
|
this.expiresAt = expiresAt;
|
|
10
27
|
this.token = token;
|
|
11
28
|
}
|
|
29
|
+
/**
|
|
30
|
+
* Checks if the session has expired based on the current time.
|
|
31
|
+
* @returns `true` if the current time is past the `expiresAt` timestamp, `false` otherwise.
|
|
32
|
+
*/
|
|
12
33
|
isExpired() {
|
|
13
34
|
return Date.now() >= this.expiresAt * 1000;
|
|
14
35
|
}
|
package/dist/session.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAaA,MAAM,OAAO,OAAO;
|
|
1
|
+
{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH,MAAM,OAAO,OAAO;IAWA;IACA;IACA;IACA;IAZhB;;;;;;;KAOC;IACH,YACkB,QAAgB,EAChB,MAAgB,EAChB,SAAiB,EACjB,KAAa;QAHb,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAU;QAChB,cAAS,GAAT,SAAS,CAAQ;QACjB,UAAK,GAAL,KAAK,CAAQ;IAC5B,CAAC;IAEJ;;;OAGG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IAC7C,CAAC;CACF"}
|
package/package.json
CHANGED
package/src/crypto/ed25519.ts
CHANGED
package/src/handle.ts
CHANGED
|
@@ -8,12 +8,30 @@ export interface HandleMetadata {
|
|
|
8
8
|
[key: string]: unknown;
|
|
9
9
|
}
|
|
10
10
|
|
|
11
|
+
/**
|
|
12
|
+
* Represents a context-specific cryptographic handle derived from an {@link Identity}.
|
|
13
|
+
*
|
|
14
|
+
* A Handle encapsulates a private key tied to a specific name (context).
|
|
15
|
+
* It provides methods for signing data, verifying signatures, and deriving
|
|
16
|
+
* secondary secrets (like passwords or channel keys) without ever exposing
|
|
17
|
+
* the underlying private key.
|
|
18
|
+
*
|
|
19
|
+
* @category Core Primitives
|
|
20
|
+
*/
|
|
11
21
|
export class Handle {
|
|
12
22
|
private readonly privateKey: Uint8Array;
|
|
13
23
|
private readonly publicKey: Uint8Array;
|
|
14
24
|
private readonly _name: string;
|
|
15
25
|
private readonly _metadata?: HandleMetadata;
|
|
16
26
|
|
|
27
|
+
/**
|
|
28
|
+
* Creates a new Handle instance.
|
|
29
|
+
* @internal Typically created via {@link Identity.deriveHandle}.
|
|
30
|
+
*
|
|
31
|
+
* @param privateKey - The 32-byte Ed25519 private key for this handle.
|
|
32
|
+
* @param name - The context name this handle represents.
|
|
33
|
+
* @param metadata - Optional metadata associated with this handle.
|
|
34
|
+
*/
|
|
17
35
|
constructor(privateKey: Uint8Array, name: string, metadata?: HandleMetadata) {
|
|
18
36
|
this.privateKey = privateKey;
|
|
19
37
|
this.publicKey = ed.getPublicKey(privateKey);
|
|
@@ -21,6 +39,7 @@ export class Handle {
|
|
|
21
39
|
this._metadata = metadata;
|
|
22
40
|
}
|
|
23
41
|
|
|
42
|
+
/** @returns The unique context identifier for this Handle. */
|
|
24
43
|
getId(): string {
|
|
25
44
|
return btoa(String.fromCharCode(...this.publicKey))
|
|
26
45
|
.replace(/\+/g, '-')
|
|
@@ -28,16 +47,33 @@ export class Handle {
|
|
|
28
47
|
.replace(/=+$/, '');
|
|
29
48
|
}
|
|
30
49
|
|
|
50
|
+
/**
|
|
51
|
+
* Cryptographically signs arbitrary data using the Handle's private key.
|
|
52
|
+
* @param data - The data to be signed, as a Uint8Array.
|
|
53
|
+
* @returns A Promise resolving to the Ed25519 signature as a Uint8Array.
|
|
54
|
+
*/
|
|
31
55
|
async sign(data: Uint8Array): Promise<Uint8Array> {
|
|
32
56
|
return ed.sign(data, this.privateKey);
|
|
33
57
|
}
|
|
34
58
|
|
|
59
|
+
/**
|
|
60
|
+
* Verifies an Ed25519 signature against the provided data and public key.
|
|
61
|
+
* @param signature - The signature to verify (Uint8Array).
|
|
62
|
+
* @param data - The original data that was signed (Uint8Array).
|
|
63
|
+
* @param publicKey - The public key to verify against (Uint8Array).
|
|
64
|
+
* @returns A Promise resolving to true if the signature is valid, false otherwise.
|
|
65
|
+
*/
|
|
35
66
|
static async verify(signature: Uint8Array, data: Uint8Array, publicKey: Uint8Array): Promise<boolean> {
|
|
36
67
|
return ed.verify(signature, data, publicKey);
|
|
37
68
|
}
|
|
38
69
|
|
|
70
|
+
/** @returns The context name associated with this Handle. */
|
|
39
71
|
getName(): string { return this._name; }
|
|
72
|
+
|
|
73
|
+
/** @returns The metadata object associated with this Handle. */
|
|
40
74
|
getMetadata(): HandleMetadata | undefined { return this._metadata; }
|
|
75
|
+
|
|
76
|
+
/** @returns A Uint8Array containing the 32-byte Ed25519 public key. */
|
|
41
77
|
getPublicKey(): Uint8Array { return this.publicKey; }
|
|
42
78
|
|
|
43
79
|
/**
|
|
@@ -67,16 +103,15 @@ export class Handle {
|
|
|
67
103
|
* the Identity (controller) and this Handle (device/context).
|
|
68
104
|
*
|
|
69
105
|
* Both parties can independently compute this key because:
|
|
70
|
-
*
|
|
71
|
-
*
|
|
106
|
+
* 1. The Handle possesses its own private key directly.
|
|
107
|
+
* 2. The Identity can derive the same private key via `identity.deriveHandle(name)`.
|
|
72
108
|
*
|
|
73
109
|
* This enables zero-knowledge encrypted channels without key exchange protocols.
|
|
74
110
|
*
|
|
75
|
-
* @param context - Channel identifier for domain separation (e.g., 'drone-001', 'session-abc').
|
|
76
|
-
*
|
|
77
|
-
* @returns 32-byte Uint8Array suitable for AES-256-GCM encryption.
|
|
78
|
-
*
|
|
111
|
+
* @param context - Channel identifier for domain separation (e.g., 'drone-001', 'session-abc'). Both parties MUST use the same context.
|
|
112
|
+
* @returns A 32-byte Uint8Array suitable for AES-256-GCM encryption.
|
|
79
113
|
* @example
|
|
114
|
+
* ```typescript
|
|
80
115
|
* // On the drone (Handle side):
|
|
81
116
|
* const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
82
117
|
* const encrypted = await encryptAESGCM(telemetry, channelKey);
|
|
@@ -85,6 +120,7 @@ export class Handle {
|
|
|
85
120
|
* const droneHandle = await centerIdentity.deriveHandle('drone-001');
|
|
86
121
|
* const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
87
122
|
* const decrypted = await decryptAESGCM(encrypted, channelKey);
|
|
123
|
+
* ```
|
|
88
124
|
*/
|
|
89
125
|
deriveChannelKey(context: string): Uint8Array {
|
|
90
126
|
const salt = new TextEncoder().encode(`me2em/channel/${context.toLowerCase().trim()}`);
|
package/src/identity.ts
CHANGED
|
@@ -5,6 +5,16 @@ import { Handle, type HandleMetadata } from './handle.js';
|
|
|
5
5
|
|
|
6
6
|
const ME2EM_HKDF_INFO_PREFIX = 'me2em/handle/v1/';
|
|
7
7
|
|
|
8
|
+
/**
|
|
9
|
+
* Represents the root cryptographic identity derived from a seed phrase.
|
|
10
|
+
*
|
|
11
|
+
* An Identity is the foundation of the Me2em protocol. It allows for the
|
|
12
|
+
* hierarchical derivation of isolated {@link Handle}s for different contexts
|
|
13
|
+
* (e.g., email, social, specific devices) from a single master seed,
|
|
14
|
+
* ensuring zero cross-contamination of cryptographic material.
|
|
15
|
+
*
|
|
16
|
+
* @category Core Primitives
|
|
17
|
+
*/
|
|
8
18
|
export class Identity {
|
|
9
19
|
private readonly privateKey: Uint8Array;
|
|
10
20
|
private readonly publicKey: Uint8Array;
|
|
@@ -14,6 +24,13 @@ export class Identity {
|
|
|
14
24
|
this.publicKey = ed.getPublicKey(privateKey); // Теперь работает синхронно
|
|
15
25
|
}
|
|
16
26
|
|
|
27
|
+
/**
|
|
28
|
+
* Initializes a new Identity from a BIP39 mnemonic seed phrase or raw seed bytes.
|
|
29
|
+
*
|
|
30
|
+
* @param seed - A 12 or 24-word BIP39 mnemonic string, or a raw Uint8Array seed.
|
|
31
|
+
* @returns A Promise resolving to a new Identity instance.
|
|
32
|
+
* @throws {Error} If the provided seed is invalid or cannot be processed.
|
|
33
|
+
*/
|
|
17
34
|
static async fromSeed(seed: Uint8Array | string): Promise<Identity> {
|
|
18
35
|
const seedBytes = typeof seed === 'string'
|
|
19
36
|
? Uint8Array.from(Buffer.from(seed, 'hex'))
|
|
@@ -34,6 +51,17 @@ export class Identity {
|
|
|
34
51
|
return new Identity(key);
|
|
35
52
|
}
|
|
36
53
|
|
|
54
|
+
/**
|
|
55
|
+
* Derives a new, cryptographically isolated {@link Handle} for a specific context.
|
|
56
|
+
*
|
|
57
|
+
* Each Handle is derived deterministically. The same name and metadata will
|
|
58
|
+
* always produce the same Handle from the same Identity, but different names
|
|
59
|
+
* produce completely unrelated keys.
|
|
60
|
+
*
|
|
61
|
+
* @param name - The context identifier (e.g., 'alice@example.com', 'device-1').
|
|
62
|
+
* @param metadata - Optional metadata to associate with this Handle.
|
|
63
|
+
* @returns A Promise resolving to the derived Handle.
|
|
64
|
+
*/
|
|
37
65
|
async deriveHandle(name: string, metadata?: HandleMetadata): Promise<Handle> {
|
|
38
66
|
const info = new TextEncoder().encode(ME2EM_HKDF_INFO_PREFIX + name.toLowerCase().trim());
|
|
39
67
|
|
|
@@ -50,6 +78,11 @@ export class Identity {
|
|
|
50
78
|
return new Handle(handleKey, name, metadata);
|
|
51
79
|
}
|
|
52
80
|
|
|
81
|
+
/**
|
|
82
|
+
* Retrieves the public key of the root Identity.
|
|
83
|
+
*
|
|
84
|
+
* @returns A Uint8Array containing the 32-byte Ed25519 public key.
|
|
85
|
+
*/
|
|
53
86
|
getPublicKey(): Uint8Array {
|
|
54
87
|
return this.publicKey;
|
|
55
88
|
}
|
package/src/index.ts
CHANGED
|
@@ -3,7 +3,29 @@ export { Handle, type HandleMetadata } from './handle.js';
|
|
|
3
3
|
export { Session, type SessionOptions, type SessionToken } from './session.js';
|
|
4
4
|
export * as crypto from './crypto/index.js';
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
/**
|
|
7
|
+
* @module @me2em/core
|
|
8
|
+
* @packageDocumentation
|
|
9
|
+
*
|
|
10
|
+
* Core cryptographic primitives for the Me2em authorization protocol.
|
|
11
|
+
*
|
|
12
|
+
* This package provides the foundation for decentralized, multi-context
|
|
13
|
+
* identity management and secure, stateless authentication.
|
|
14
|
+
*
|
|
15
|
+
* ## Key Features
|
|
16
|
+
* - **Hierarchical Identities**: Derive multiple isolated {@link Handle}s from a single seed.
|
|
17
|
+
* - **Stateless Auth**: Cryptographic proof without server-side session storage via {@link Session}.
|
|
18
|
+
* - **Zero-Knowledge Secrets**: Deterministic password derivation without storage.
|
|
19
|
+
*
|
|
20
|
+
* @example Basic usage
|
|
21
|
+
* ```typescript
|
|
22
|
+
* import { Identity } from '@me2em/core';
|
|
23
|
+
*
|
|
24
|
+
* const identity = await Identity.fromSeed('your twelve word mnemonic phrase here...');
|
|
25
|
+
* const handle = await identity.deriveHandle('user@example.com');
|
|
26
|
+
* const signature = await handle.sign(new TextEncoder().encode('data'));
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
7
29
|
export {
|
|
8
30
|
generateSeedPhrase,
|
|
9
31
|
normalizeSeedPhrase,
|
|
@@ -11,5 +33,3 @@ export {
|
|
|
11
33
|
get32ByteSeedFromMnemonic,
|
|
12
34
|
type SeedStrength
|
|
13
35
|
} from './seed.js';
|
|
14
|
-
|
|
15
|
-
export const PROTOCOL_VERSION = '0.4.1-alpha.1';
|
package/src/seed.ts
CHANGED
|
@@ -5,9 +5,35 @@ import { sha256 } from './crypto/hkdf.js';
|
|
|
5
5
|
export type SeedStrength = 128 | 256; // 128 bits = 12 words, 256 bits = 24 words
|
|
6
6
|
|
|
7
7
|
/**
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
8
|
+
* Utilities for BIP39 mnemonic seed phrase generation and validation.
|
|
9
|
+
*
|
|
10
|
+
* These functions provide secure, deterministic seed phrase handling
|
|
11
|
+
* compatible with the BIP39 standard.
|
|
12
|
+
*
|
|
13
|
+
* @category Seed Utilities
|
|
14
|
+
* @packageDocumentation
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Generates a cryptographically secure random mnemonic seed phrase.
|
|
19
|
+
*
|
|
20
|
+
* @param strength - The entropy strength in bits.
|
|
21
|
+
* - 128 bits = 12 words (standard security)
|
|
22
|
+
* - 160 bits = 15 words
|
|
23
|
+
* - 192 bits = 18 words
|
|
24
|
+
* - 224 bits = 21 words
|
|
25
|
+
* - 256 bits = 24 words (maximum security)
|
|
26
|
+
*
|
|
27
|
+
* @returns A Promise resolving to a space-separated mnemonic string.
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* ```typescript
|
|
31
|
+
* const mnemonic12 = await generateSeedPhrase(128);
|
|
32
|
+
* // "abandon abandon abandon ... art"
|
|
33
|
+
*
|
|
34
|
+
* const mnemonic24 = await generateSeedPhrase(256);
|
|
35
|
+
* // "abandon abandon abandon ... zoo" (24 words)
|
|
36
|
+
* ```
|
|
11
37
|
*/
|
|
12
38
|
export function generateSeedPhrase(strength: SeedStrength = 128): string[] {
|
|
13
39
|
if (strength !== 128 && strength !== 256) {
|
|
@@ -18,7 +44,19 @@ export function generateSeedPhrase(strength: SeedStrength = 128): string[] {
|
|
|
18
44
|
}
|
|
19
45
|
|
|
20
46
|
/**
|
|
21
|
-
* Normalizes a seed phrase
|
|
47
|
+
* Normalizes a mnemonic seed phrase by trimming whitespace and converting to lowercase.
|
|
48
|
+
*
|
|
49
|
+
* @param phrase - The mnemonic phrase to normalize (string or array of words).
|
|
50
|
+
* @returns A normalized string of lowercase words separated by single spaces.
|
|
51
|
+
*
|
|
52
|
+
* @example
|
|
53
|
+
* ```typescript
|
|
54
|
+
* const normalized = normalizeSeedPhrase(' ABANDON abandon ART ');
|
|
55
|
+
* // "abandon abandon art"
|
|
56
|
+
*
|
|
57
|
+
* const normalized2 = normalizeSeedPhrase(['abandon', ' ART ', 'zoo']);
|
|
58
|
+
* // "abandon art zoo"
|
|
59
|
+
* ```
|
|
22
60
|
*/
|
|
23
61
|
export function normalizeSeedPhrase(seedPhrase: string | string[]): string[] {
|
|
24
62
|
const words = Array.isArray(seedPhrase) ? seedPhrase : seedPhrase.trim().split(/\s+/);
|
|
@@ -26,7 +64,24 @@ export function normalizeSeedPhrase(seedPhrase: string | string[]): string[] {
|
|
|
26
64
|
}
|
|
27
65
|
|
|
28
66
|
/**
|
|
29
|
-
* Validates a
|
|
67
|
+
* Validates a mnemonic seed phrase against the BIP39 standard.
|
|
68
|
+
*
|
|
69
|
+
* Checks:
|
|
70
|
+
* - Correct word count (12, 15, 18, 21, or 24 words)
|
|
71
|
+
* - All words exist in the BIP39 wordlist
|
|
72
|
+
* - Valid checksum
|
|
73
|
+
*
|
|
74
|
+
* @param phrase - The mnemonic phrase to validate.
|
|
75
|
+
* @returns `true` if the phrase is valid, `false` otherwise.
|
|
76
|
+
*
|
|
77
|
+
* @example
|
|
78
|
+
* ```typescript
|
|
79
|
+
* const isValid = await validateSeedPhrase('abandon abandon ... art');
|
|
80
|
+
* // true
|
|
81
|
+
*
|
|
82
|
+
* const isInvalid = await validateSeedPhrase('invalid word list ...');
|
|
83
|
+
* // false
|
|
84
|
+
* ```
|
|
30
85
|
*/
|
|
31
86
|
export function validateSeedPhrase(words: string[]): { isValid: boolean; error?: string } {
|
|
32
87
|
const wordCount = words.length;
|
|
@@ -46,8 +101,26 @@ export function validateSeedPhrase(words: string[]): { isValid: boolean; error?:
|
|
|
46
101
|
}
|
|
47
102
|
|
|
48
103
|
/**
|
|
49
|
-
*
|
|
50
|
-
*
|
|
104
|
+
* Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
|
|
105
|
+
*
|
|
106
|
+
* This is the standard BIP39 derivation function that converts a human-readable
|
|
107
|
+
* mnemonic into a binary seed suitable for key generation.
|
|
108
|
+
*
|
|
109
|
+
* @param phrase - The BIP39 mnemonic phrase (will be normalized automatically).
|
|
110
|
+
* @param passphrase - Optional passphrase for additional security (BIP39 "25th word").
|
|
111
|
+
* @returns A Promise resolving to a 32-byte Uint8Array seed.
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* ```typescript
|
|
115
|
+
* const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
|
|
116
|
+
* // Uint8Array(32) [123, 45, 67, ...]
|
|
117
|
+
*
|
|
118
|
+
* const seedWithPassphrase = await get32ByteSeedFromMnemonic(
|
|
119
|
+
* 'abandon abandon ... art',
|
|
120
|
+
* 'mySecretPassphrase'
|
|
121
|
+
* );
|
|
122
|
+
* // Different seed even with same mnemonic
|
|
123
|
+
* ```
|
|
51
124
|
*/
|
|
52
125
|
export async function get32ByteSeedFromMnemonic(seedPhrase: string | string[]): Promise<Uint8Array> {
|
|
53
126
|
const words = normalizeSeedPhrase(seedPhrase);
|
package/src/session.ts
CHANGED
|
@@ -11,7 +11,25 @@ export interface SessionToken {
|
|
|
11
11
|
token: string;
|
|
12
12
|
}
|
|
13
13
|
|
|
14
|
+
/**
|
|
15
|
+
* Represents a stateless, cryptographically verifiable session token.
|
|
16
|
+
*
|
|
17
|
+
* Instead of storing session state on the server, the Session object
|
|
18
|
+
* encapsulates all necessary authorization data (handle ID, scopes, expiration)
|
|
19
|
+
* into a self-contained structure that can be verified using the Handle's public key.
|
|
20
|
+
*
|
|
21
|
+
* @category Core Primitives
|
|
22
|
+
*/
|
|
14
23
|
export class Session {
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Creates a new Session instance.
|
|
27
|
+
*
|
|
28
|
+
* @param handleId - The ID of the Handle that authorized this session.
|
|
29
|
+
* @param scopes - An array of permission scopes granted in this session (e.g., ['read', 'write']).
|
|
30
|
+
* @param expiresAt - Unix timestamp (in milliseconds) when this session expires.
|
|
31
|
+
* @param token - The cryptographic token string (e.g., JWT or custom signature format).
|
|
32
|
+
*/
|
|
15
33
|
constructor(
|
|
16
34
|
public readonly handleId: string,
|
|
17
35
|
public readonly scopes: string[],
|
|
@@ -19,6 +37,10 @@ export class Session {
|
|
|
19
37
|
public readonly token: string
|
|
20
38
|
) {}
|
|
21
39
|
|
|
40
|
+
/**
|
|
41
|
+
* Checks if the session has expired based on the current time.
|
|
42
|
+
* @returns `true` if the current time is past the `expiresAt` timestamp, `false` otherwise.
|
|
43
|
+
*/
|
|
22
44
|
isExpired(): boolean {
|
|
23
45
|
return Date.now() >= this.expiresAt * 1000;
|
|
24
46
|
}
|