@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.
@@ -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"}
@@ -1,4 +1,8 @@
1
1
  import { ed } from './init.js';
2
+ /**
3
+ * @internal
4
+ * Low-level Ed25519 implementation wrapper.
5
+ */
2
6
  export const getPublicKey = ed.getPublicKey;
3
7
  export const sign = ed.sign;
4
8
  export const verify = ed.verify;
@@ -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
- * - The Handle possesses its own private key directly
33
- * - The Identity can derive the same private key via `identity.deriveHandle(name)`
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
- * Both parties MUST use the same context to derive the same key.
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
  }
@@ -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;gBAEhC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc;IAO3E,KAAK,IAAI,MAAM;IAOT,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;WAIpC,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrG,OAAO,IAAI,MAAM;IACjB,WAAW,IAAI,cAAc,GAAG,SAAS;IACzC,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"}
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
- * - The Handle possesses its own private key directly
55
- * - The Identity can derive the same private key via `identity.deriveHandle(name)`
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
- * Both parties MUST use the same context to derive the same key.
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()}`);
@@ -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;IAE5C,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,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;IAED,KAAK,CAAC,IAAI,CAAC,IAAgB;QACzB,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED,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,OAAO,KAAa,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACxC,WAAW,KAAiC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,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"}
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"}
@@ -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
@@ -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;WAKM,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAoB7D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB5E,YAAY,IAAI,UAAU;CAG3B"}
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
  }
@@ -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;IAED,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;IAED,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,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}
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
@@ -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;AAG5C,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,gBAAgB,kBAAkB,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
- // Seed utilities for human-friendly key generation
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,mDAAmD;AACnD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EAE1B,MAAM,WAAW,CAAC;AAEnB,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAAC"}
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
- * Generates a BIP39 mnemonic phrase.
4
- * @param strength - 128 for 12 words (default), 256 for 24 words.
5
- * @returns Array of words.
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 (lowercase, trimmed, removes extra spaces).
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 BIP39 seed phrase.
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
- * Converts a BIP39 mnemonic phrase into a 32-byte Uint8Array suitable for Ed25519.
21
- * BIP39 produces a 64-byte seed. We hash it with SHA-256 to get exactly 32 bytes deterministically.
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
@@ -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;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,YAAkB,GAAG,MAAM,EAAE,CAMzE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAG3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAexF;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAalG"}
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
- * Generates a BIP39 mnemonic phrase.
6
- * @param strength - 128 for 12 words (default), 256 for 24 words.
7
- * @returns Array of words.
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 (lowercase, trimmed, removes extra spaces).
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 BIP39 seed phrase.
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
- * Converts a BIP39 mnemonic phrase into a 32-byte Uint8Array suitable for Ed25519.
42
- * BIP39 produces a 64-byte seed. We hash it with SHA-256 to get exactly 32 bytes deterministically.
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;;;;GAIG;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;;GAEG;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;;GAEG;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;;;GAGG;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"}
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
@@ -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;aAEA,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM,EAAE;aAChB,SAAS,EAAE,MAAM;aACjB,KAAK,EAAE,MAAM;gBAHb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM;IAG/B,SAAS,IAAI,OAAO;CAGrB"}
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
  }
@@ -1 +1 @@
1
- {"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAaA,MAAM,OAAO,OAAO;IAEA;IACA;IACA;IACA;IAJlB,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,SAAS;QACP,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IAC7C,CAAC;CACF"}
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@me2em/core",
3
- "version": "0.4.3-alpha.1",
3
+ "version": "0.4.4-alpha.2",
4
4
  "description": "Core primitives for the Me2em authorization protocol: Identity, Handle, and Session",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -1,5 +1,9 @@
1
1
  import { ed } from './init.js';
2
2
 
3
+ /**
4
+ * @internal
5
+ * Low-level Ed25519 implementation wrapper.
6
+ */
3
7
  export const getPublicKey = ed.getPublicKey;
4
8
  export const sign = ed.sign;
5
9
  export const verify = ed.verify;
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
- * - The Handle possesses its own private key directly
71
- * - The Identity can derive the same private key via `identity.deriveHandle(name)`
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
- * Both parties MUST use the same context to derive the same key.
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
- // Seed utilities for human-friendly key generation
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
- * Generates a BIP39 mnemonic phrase.
9
- * @param strength - 128 for 12 words (default), 256 for 24 words.
10
- * @returns Array of words.
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 (lowercase, trimmed, removes extra spaces).
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 BIP39 seed phrase.
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
- * Converts a BIP39 mnemonic phrase into a 32-byte Uint8Array suitable for Ed25519.
50
- * BIP39 produces a 64-byte seed. We hash it with SHA-256 to get exactly 32 bytes deterministically.
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
  }