@me2em/core 0.4.4-alpha.2 → 0.7.0-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +294 -546
- package/dist/attestation.d.ts +151 -0
- package/dist/attestation.d.ts.map +1 -0
- package/dist/attestation.js +279 -0
- package/dist/attestation.js.map +1 -0
- package/dist/canonical-name.d.ts +3 -0
- package/dist/canonical-name.d.ts.map +1 -0
- package/dist/canonical-name.js +12 -0
- package/dist/canonical-name.js.map +1 -0
- package/dist/crypto/derivation-paths.d.ts +41 -0
- package/dist/crypto/derivation-paths.d.ts.map +1 -0
- package/dist/crypto/derivation-paths.js +50 -0
- package/dist/crypto/derivation-paths.js.map +1 -0
- package/dist/crypto/ed25519.d.ts +48 -8
- package/dist/crypto/ed25519.d.ts.map +1 -1
- package/dist/crypto/ed25519.js +63 -8
- package/dist/crypto/ed25519.js.map +1 -1
- package/dist/crypto/hkdf.d.ts.map +1 -1
- package/dist/crypto/hkdf.js +1 -0
- package/dist/crypto/hkdf.js.map +1 -1
- package/dist/crypto/index.d.ts +1 -0
- package/dist/crypto/index.d.ts.map +1 -1
- package/dist/crypto/index.js +2 -0
- package/dist/crypto/index.js.map +1 -1
- package/dist/crypto/init.d.ts.map +1 -1
- package/dist/crypto/init.js +1 -0
- package/dist/crypto/init.js.map +1 -1
- package/dist/handle.d.ts +149 -35
- package/dist/handle.d.ts.map +1 -1
- package/dist/handle.js +180 -40
- package/dist/handle.js.map +1 -1
- package/dist/identity.d.ts +99 -19
- package/dist/identity.d.ts.map +1 -1
- package/dist/identity.js +128 -32
- package/dist/identity.js.map +1 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -1
- package/dist/seed.d.ts +38 -39
- package/dist/seed.d.ts.map +1 -1
- package/dist/seed.js +36 -41
- package/dist/seed.js.map +1 -1
- package/dist/session.d.ts +207 -17
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +428 -11
- package/dist/session.js.map +1 -1
- package/dist/subhandle.d.ts +126 -0
- package/dist/subhandle.d.ts.map +1 -0
- package/dist/subhandle.js +182 -0
- package/dist/subhandle.js.map +1 -0
- package/dist/util.d.ts +9 -0
- package/dist/util.d.ts.map +1 -0
- package/dist/util.js +34 -0
- package/dist/util.js.map +1 -0
- package/package.json +3 -3
- package/src/attestation.ts +364 -0
- package/src/canonical-name.ts +12 -0
- package/src/crypto/derivation-paths.ts +56 -0
- package/src/crypto/ed25519.ts +82 -8
- package/src/crypto/hkdf.ts +2 -0
- package/src/crypto/index.ts +3 -1
- package/src/crypto/init.ts +1 -0
- package/src/handle.ts +227 -42
- package/src/identity.ts +164 -35
- package/src/index.ts +5 -1
- package/src/seed.ts +59 -59
- package/src/session.ts +637 -24
- package/src/subhandle.ts +254 -0
- package/src/util.ts +35 -0
package/dist/identity.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,
|
|
1
|
+
{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAA0B,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAC;AAEtE,SAAS,YAAY,CAAC,GAAW;IAC/B,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;GAeG;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;IAC/C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAyB;QAC7C,MAAM,SAAS,GAAG,OAAO,IAAI,KAAK,QAAQ;YACxC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC;YACpB,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,EACjB,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EACnD,EAAE,CACH,CAAC;QACF,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,YAAY,CAAC,IAAY,EAAE,QAAyB;QACxD,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACrE,MAAM,SAAS,GAAG,IAAI,CACpB,MAAM,EACN,IAAI,CAAC,UAAU,EACf,IAAI,UAAU,CAAC,CAAC,CAAC,EACjB,IAAI,EACJ,EAAE,CACH,CAAC;QACF,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,eAAe,CACnB,UAAkB,EAClB,OAAe,EACf,QAA4B;QAE5B,UAAU,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QAE3C,6DAA6D;QAC7D,MAAM,UAAU,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACjF,MAAM,SAAS,GAAG,IAAI,CACpB,MAAM,EACN,IAAI,CAAC,UAAU,EACf,IAAI,UAAU,CAAC,CAAC,CAAC,EACjB,UAAU,EACV,EAAE,CACH,CAAC;QAEF,uDAAuD;QACvD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CACtC,gBAAgB,CAAC,SAAS,CAAC,UAAU,EAAE,WAAW,CAAC,CACpD,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CACjB,MAAM,EACN,SAAS,EACT,IAAI,UAAU,CAAC,CAAC,CAAC,EACjB,OAAO,EACP,EAAE,CACH,CAAC;QAEF,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QACvC,OAAO,IAAI,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,YAAY,CAChB,IAAY,EACZ,KAAuB,EACvB,IAA8E;QAE9E,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QACnD,OAAO,WAAW,CAAC,KAAK,CACtB,IAAI,CAAC,UAAU,EACf,MAAM,CAAC,YAAY,EAAE,EACrB,UAAU,EACV,KAAK,EACL,IAAI,IAAI,EAAE,CACX,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
export { Identity } from './identity.js';
|
|
2
2
|
export { Handle, type HandleMetadata } from './handle.js';
|
|
3
|
-
export {
|
|
3
|
+
export { SubHandle, type SubHandleMetadata } from './subhandle.js';
|
|
4
|
+
export { Session, type SessionOptions, type SessionPayload, type RevocationChecker } from './session.js';
|
|
5
|
+
export { Attestation, AttestationError, ATTESTATION_TYPE, ATTESTATION_MAX_PAYLOAD, type AttestationGrant, type AttestationPayload, type AttestationErrorCode, type AttestationLevel } from './attestation.js';
|
|
4
6
|
export * as crypto from './crypto/index.js';
|
|
5
7
|
/**
|
|
6
8
|
* @module @me2em/core
|
|
@@ -13,8 +15,10 @@ export * as crypto from './crypto/index.js';
|
|
|
13
15
|
*
|
|
14
16
|
* ## Key Features
|
|
15
17
|
* - **Hierarchical Identities**: Derive multiple isolated {@link Handle}s from a single seed.
|
|
18
|
+
* - **SubHandle Leaf Nodes**: Hierarchical access control with MAX_DEPTH = 2.
|
|
16
19
|
* - **Stateless Auth**: Cryptographic proof without server-side session storage via {@link Session}.
|
|
17
20
|
* - **Zero-Knowledge Secrets**: Deterministic password derivation without storage.
|
|
21
|
+
* - **Revocation Support**: Optional {@link RevocationChecker} interface for session invalidation.
|
|
18
22
|
*
|
|
19
23
|
* @example Basic usage
|
|
20
24
|
* ```typescript
|
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,
|
|
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,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC9M,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
export { Identity } from './identity.js';
|
|
2
2
|
export { Handle } from './handle.js';
|
|
3
|
+
export { SubHandle } from './subhandle.js';
|
|
3
4
|
export { Session } from './session.js';
|
|
5
|
+
export { Attestation, AttestationError, ATTESTATION_TYPE, ATTESTATION_MAX_PAYLOAD } from './attestation.js';
|
|
4
6
|
export * as crypto from './crypto/index.js';
|
|
5
7
|
/**
|
|
6
8
|
* @module @me2em/core
|
|
@@ -13,8 +15,10 @@ export * as crypto from './crypto/index.js';
|
|
|
13
15
|
*
|
|
14
16
|
* ## Key Features
|
|
15
17
|
* - **Hierarchical Identities**: Derive multiple isolated {@link Handle}s from a single seed.
|
|
18
|
+
* - **SubHandle Leaf Nodes**: Hierarchical access control with MAX_DEPTH = 2.
|
|
16
19
|
* - **Stateless Auth**: Cryptographic proof without server-side session storage via {@link Session}.
|
|
17
20
|
* - **Zero-Knowledge Secrets**: Deterministic password derivation without storage.
|
|
21
|
+
* - **Revocation Support**: Optional {@link RevocationChecker} interface for session invalidation.
|
|
18
22
|
*
|
|
19
23
|
* @example Basic usage
|
|
20
24
|
* ```typescript
|
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,
|
|
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,SAAS,EAA0B,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,OAAO,EAAoE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,uBAAuB,EAAoG,MAAM,kBAAkB,CAAC;AAC9M,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EAE1B,MAAM,WAAW,CAAC"}
|
package/dist/seed.d.ts
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Seed strength in bits. 128 bits → 12 words, 256 bits → 24 words.
|
|
3
|
+
* Intermediate strengths (160/192/224 → 15/18/21 words) are valid
|
|
4
|
+
* BIP39 strengths but intentionally NOT exposed by this API; extend
|
|
5
|
+
* the union deliberately if ever needed (BREAKING for exhaustiveness
|
|
6
|
+
* checks).
|
|
7
|
+
*/
|
|
1
8
|
export type SeedStrength = 128 | 256;
|
|
2
9
|
/**
|
|
3
10
|
* Utilities for BIP39 mnemonic seed phrase generation and validation.
|
|
4
|
-
*
|
|
5
11
|
* These functions provide secure, deterministic seed phrase handling
|
|
6
12
|
* compatible with the BIP39 standard.
|
|
7
13
|
*
|
|
@@ -13,36 +19,29 @@ export type SeedStrength = 128 | 256;
|
|
|
13
19
|
*
|
|
14
20
|
* @param strength - The entropy strength in bits.
|
|
15
21
|
* - 128 bits = 12 words (standard security)
|
|
16
|
-
* - 160 bits = 15 words
|
|
17
|
-
* - 192 bits = 18 words
|
|
18
|
-
* - 224 bits = 21 words
|
|
19
22
|
* - 256 bits = 24 words (maximum security)
|
|
20
|
-
*
|
|
21
|
-
* @returns A Promise resolving to a space-separated mnemonic string.
|
|
23
|
+
* @returns A space-separated mnemonic string split into an array of words.
|
|
22
24
|
*
|
|
23
25
|
* @example
|
|
24
|
-
* ```
|
|
25
|
-
* const mnemonic12 =
|
|
26
|
-
* // "abandon abandon
|
|
26
|
+
* ```ts
|
|
27
|
+
* const mnemonic12 = generateSeedPhrase(128);
|
|
28
|
+
* // ["abandon", "abandon", ..., "art"]
|
|
27
29
|
*
|
|
28
|
-
* const mnemonic24 =
|
|
29
|
-
* // "abandon abandon
|
|
30
|
+
* const mnemonic24 = generateSeedPhrase(256);
|
|
31
|
+
* // ["abandon", "abandon", ..., "zoo"] (24 words)
|
|
30
32
|
* ```
|
|
31
33
|
*/
|
|
32
34
|
export declare function generateSeedPhrase(strength?: SeedStrength): string[];
|
|
33
35
|
/**
|
|
34
36
|
* Normalizes a mnemonic seed phrase by trimming whitespace and converting to lowercase.
|
|
35
37
|
*
|
|
36
|
-
* @param
|
|
37
|
-
* @returns A normalized
|
|
38
|
+
* @param seedPhrase - The mnemonic phrase to normalize (string or array of words).
|
|
39
|
+
* @returns A normalized array of lowercase words.
|
|
38
40
|
*
|
|
39
41
|
* @example
|
|
40
|
-
* ```
|
|
42
|
+
* ```ts
|
|
41
43
|
* const normalized = normalizeSeedPhrase(' ABANDON abandon ART ');
|
|
42
|
-
* // "abandon abandon art"
|
|
43
|
-
*
|
|
44
|
-
* const normalized2 = normalizeSeedPhrase(['abandon', ' ART ', 'zoo']);
|
|
45
|
-
* // "abandon art zoo"
|
|
44
|
+
* // ["abandon", "abandon", "art"]
|
|
46
45
|
* ```
|
|
47
46
|
*/
|
|
48
47
|
export declare function normalizeSeedPhrase(seedPhrase: string | string[]): string[];
|
|
@@ -50,20 +49,17 @@ export declare function normalizeSeedPhrase(seedPhrase: string | string[]): stri
|
|
|
50
49
|
* Validates a mnemonic seed phrase against the BIP39 standard.
|
|
51
50
|
*
|
|
52
51
|
* Checks:
|
|
53
|
-
* - Correct word count (12
|
|
52
|
+
* - Correct word count (12 or 24 words)
|
|
54
53
|
* - All words exist in the BIP39 wordlist
|
|
55
54
|
* - Valid checksum
|
|
56
55
|
*
|
|
57
|
-
* @param
|
|
58
|
-
* @returns `
|
|
56
|
+
* @param words - The mnemonic phrase to validate.
|
|
57
|
+
* @returns An object with `isValid` flag and optional `error` message.
|
|
59
58
|
*
|
|
60
59
|
* @example
|
|
61
|
-
* ```
|
|
62
|
-
* const
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
* const isInvalid = await validateSeedPhrase('invalid word list ...');
|
|
66
|
-
* // false
|
|
60
|
+
* ```ts
|
|
61
|
+
* const result = validateSeedPhrase(['abandon', 'abandon', ..., 'art']);
|
|
62
|
+
* if (!result.isValid) console.error(result.error);
|
|
67
63
|
* ```
|
|
68
64
|
*/
|
|
69
65
|
export declare function validateSeedPhrase(words: string[]): {
|
|
@@ -72,25 +68,28 @@ export declare function validateSeedPhrase(words: string[]): {
|
|
|
72
68
|
};
|
|
73
69
|
/**
|
|
74
70
|
* Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
|
|
75
|
-
*
|
|
76
71
|
* This is the standard BIP39 derivation function that converts a human-readable
|
|
77
|
-
* mnemonic into a binary seed suitable for key generation.
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
72
|
+
* mnemonic into a binary seed suitable for Ed25519 key generation.
|
|
73
|
+
*
|
|
74
|
+
* The resulting 64-byte BIP39 seed is hashed with SHA-256 to produce a
|
|
75
|
+
* deterministic 32-byte seed, as required by Ed25519.
|
|
76
|
+
*
|
|
77
|
+
* @param seedPhrase - The BIP39 mnemonic phrase (string or array of words).
|
|
78
|
+
* @param passphrase - Optional BIP39 passphrase ("25th word").
|
|
79
|
+
* Normalized via NFKC before use. An empty string (default)
|
|
80
|
+
* matches phrases without a passphrase. WARNING: the passphrase
|
|
81
|
+
* is NOT recoverable — a different passphrase silently derives a
|
|
82
|
+
* completely different seed with no error indication. Store it
|
|
83
|
+
* as carefully as the mnemonic itself.
|
|
81
84
|
* @returns A Promise resolving to a 32-byte Uint8Array seed.
|
|
82
85
|
*
|
|
83
86
|
* @example
|
|
84
|
-
* ```
|
|
87
|
+
* ```ts
|
|
85
88
|
* const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
|
|
86
89
|
* // Uint8Array(32) [123, 45, 67, ...]
|
|
87
90
|
*
|
|
88
|
-
* const seedWithPassphrase = await get32ByteSeedFromMnemonic(
|
|
89
|
-
* 'abandon abandon ... art',
|
|
90
|
-
* 'mySecretPassphrase'
|
|
91
|
-
* );
|
|
92
|
-
* // Different seed even with same mnemonic
|
|
91
|
+
* const seedWithPassphrase = await get32ByteSeedFromMnemonic(words, 'my secret 25th word');
|
|
93
92
|
* ```
|
|
94
93
|
*/
|
|
95
|
-
export declare function get32ByteSeedFromMnemonic(seedPhrase: string | string[]): Promise<Uint8Array>;
|
|
94
|
+
export declare function get32ByteSeedFromMnemonic(seedPhrase: string | string[], passphrase?: string): Promise<Uint8Array>;
|
|
96
95
|
//# 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":"
|
|
1
|
+
{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,CAAC;AAErC;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,YAAkB,GAAG,MAAM,EAAE,CAMzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAK3E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAaxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,EAC7B,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,UAAU,CAAC,CAUrB"}
|
package/dist/seed.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
+
// seed.ts
|
|
1
2
|
import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39';
|
|
2
3
|
import { wordlist } from '@scure/bip39/wordlists/english';
|
|
3
4
|
import { sha256 } from './crypto/hkdf.js';
|
|
4
5
|
/**
|
|
5
6
|
* Utilities for BIP39 mnemonic seed phrase generation and validation.
|
|
6
|
-
*
|
|
7
7
|
* These functions provide secure, deterministic seed phrase handling
|
|
8
8
|
* compatible with the BIP39 standard.
|
|
9
9
|
*
|
|
@@ -15,20 +15,16 @@ import { sha256 } from './crypto/hkdf.js';
|
|
|
15
15
|
*
|
|
16
16
|
* @param strength - The entropy strength in bits.
|
|
17
17
|
* - 128 bits = 12 words (standard security)
|
|
18
|
-
* - 160 bits = 15 words
|
|
19
|
-
* - 192 bits = 18 words
|
|
20
|
-
* - 224 bits = 21 words
|
|
21
18
|
* - 256 bits = 24 words (maximum security)
|
|
22
|
-
*
|
|
23
|
-
* @returns A Promise resolving to a space-separated mnemonic string.
|
|
19
|
+
* @returns A space-separated mnemonic string split into an array of words.
|
|
24
20
|
*
|
|
25
21
|
* @example
|
|
26
|
-
* ```
|
|
27
|
-
* const mnemonic12 =
|
|
28
|
-
* // "abandon abandon
|
|
22
|
+
* ```ts
|
|
23
|
+
* const mnemonic12 = generateSeedPhrase(128);
|
|
24
|
+
* // ["abandon", "abandon", ..., "art"]
|
|
29
25
|
*
|
|
30
|
-
* const mnemonic24 =
|
|
31
|
-
* // "abandon abandon
|
|
26
|
+
* const mnemonic24 = generateSeedPhrase(256);
|
|
27
|
+
* // ["abandon", "abandon", ..., "zoo"] (24 words)
|
|
32
28
|
* ```
|
|
33
29
|
*/
|
|
34
30
|
export function generateSeedPhrase(strength = 128) {
|
|
@@ -41,40 +37,36 @@ export function generateSeedPhrase(strength = 128) {
|
|
|
41
37
|
/**
|
|
42
38
|
* Normalizes a mnemonic seed phrase by trimming whitespace and converting to lowercase.
|
|
43
39
|
*
|
|
44
|
-
* @param
|
|
45
|
-
* @returns A normalized
|
|
40
|
+
* @param seedPhrase - The mnemonic phrase to normalize (string or array of words).
|
|
41
|
+
* @returns A normalized array of lowercase words.
|
|
46
42
|
*
|
|
47
43
|
* @example
|
|
48
|
-
* ```
|
|
44
|
+
* ```ts
|
|
49
45
|
* const normalized = normalizeSeedPhrase(' ABANDON abandon ART ');
|
|
50
|
-
* // "abandon abandon art"
|
|
51
|
-
*
|
|
52
|
-
* const normalized2 = normalizeSeedPhrase(['abandon', ' ART ', 'zoo']);
|
|
53
|
-
* // "abandon art zoo"
|
|
46
|
+
* // ["abandon", "abandon", "art"]
|
|
54
47
|
* ```
|
|
55
48
|
*/
|
|
56
49
|
export function normalizeSeedPhrase(seedPhrase) {
|
|
57
|
-
const words = Array.isArray(seedPhrase)
|
|
50
|
+
const words = Array.isArray(seedPhrase)
|
|
51
|
+
? seedPhrase
|
|
52
|
+
: seedPhrase.trim().split(/\s+/);
|
|
58
53
|
return words.map(word => word.toLowerCase().trim()).filter(word => word.length > 0);
|
|
59
54
|
}
|
|
60
55
|
/**
|
|
61
56
|
* Validates a mnemonic seed phrase against the BIP39 standard.
|
|
62
57
|
*
|
|
63
58
|
* Checks:
|
|
64
|
-
* - Correct word count (12
|
|
59
|
+
* - Correct word count (12 or 24 words)
|
|
65
60
|
* - All words exist in the BIP39 wordlist
|
|
66
61
|
* - Valid checksum
|
|
67
62
|
*
|
|
68
|
-
* @param
|
|
69
|
-
* @returns `
|
|
63
|
+
* @param words - The mnemonic phrase to validate.
|
|
64
|
+
* @returns An object with `isValid` flag and optional `error` message.
|
|
70
65
|
*
|
|
71
66
|
* @example
|
|
72
|
-
* ```
|
|
73
|
-
* const
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
* const isInvalid = await validateSeedPhrase('invalid word list ...');
|
|
77
|
-
* // false
|
|
67
|
+
* ```ts
|
|
68
|
+
* const result = validateSeedPhrase(['abandon', 'abandon', ..., 'art']);
|
|
69
|
+
* if (!result.isValid) console.error(result.error);
|
|
78
70
|
* ```
|
|
79
71
|
*/
|
|
80
72
|
export function validateSeedPhrase(words) {
|
|
@@ -93,34 +85,37 @@ export function validateSeedPhrase(words) {
|
|
|
93
85
|
}
|
|
94
86
|
/**
|
|
95
87
|
* Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
|
|
96
|
-
*
|
|
97
88
|
* This is the standard BIP39 derivation function that converts a human-readable
|
|
98
|
-
* mnemonic into a binary seed suitable for key generation.
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
89
|
+
* mnemonic into a binary seed suitable for Ed25519 key generation.
|
|
90
|
+
*
|
|
91
|
+
* The resulting 64-byte BIP39 seed is hashed with SHA-256 to produce a
|
|
92
|
+
* deterministic 32-byte seed, as required by Ed25519.
|
|
93
|
+
*
|
|
94
|
+
* @param seedPhrase - The BIP39 mnemonic phrase (string or array of words).
|
|
95
|
+
* @param passphrase - Optional BIP39 passphrase ("25th word").
|
|
96
|
+
* Normalized via NFKC before use. An empty string (default)
|
|
97
|
+
* matches phrases without a passphrase. WARNING: the passphrase
|
|
98
|
+
* is NOT recoverable — a different passphrase silently derives a
|
|
99
|
+
* completely different seed with no error indication. Store it
|
|
100
|
+
* as carefully as the mnemonic itself.
|
|
102
101
|
* @returns A Promise resolving to a 32-byte Uint8Array seed.
|
|
103
102
|
*
|
|
104
103
|
* @example
|
|
105
|
-
* ```
|
|
104
|
+
* ```ts
|
|
106
105
|
* const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
|
|
107
106
|
* // Uint8Array(32) [123, 45, 67, ...]
|
|
108
107
|
*
|
|
109
|
-
* const seedWithPassphrase = await get32ByteSeedFromMnemonic(
|
|
110
|
-
* 'abandon abandon ... art',
|
|
111
|
-
* 'mySecretPassphrase'
|
|
112
|
-
* );
|
|
113
|
-
* // Different seed even with same mnemonic
|
|
108
|
+
* const seedWithPassphrase = await get32ByteSeedFromMnemonic(words, 'my secret 25th word');
|
|
114
109
|
* ```
|
|
115
110
|
*/
|
|
116
|
-
export async function get32ByteSeedFromMnemonic(seedPhrase) {
|
|
111
|
+
export async function get32ByteSeedFromMnemonic(seedPhrase, passphrase = '') {
|
|
117
112
|
const words = normalizeSeedPhrase(seedPhrase);
|
|
118
113
|
const validation = validateSeedPhrase(words);
|
|
119
114
|
if (!validation.isValid) {
|
|
120
115
|
throw new Error(`Invalid seed phrase: ${validation.error}`);
|
|
121
116
|
}
|
|
122
117
|
const mnemonic = words.join(' ');
|
|
123
|
-
const seed64 = await mnemonicToSeed(mnemonic);
|
|
118
|
+
const seed64 = await mnemonicToSeed(mnemonic, passphrase.normalize('NFKC'));
|
|
124
119
|
// Hash the 64-byte seed to get a deterministic 32-byte seed for Ed25519
|
|
125
120
|
return sha256(seed64);
|
|
126
121
|
}
|
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;
|
|
1
|
+
{"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,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;AAW1C;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;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;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAA6B;IAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACrC,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACnC,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;;;;;;;;;;;;;;;;GAgBG;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;IACD,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;IACD,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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,UAA6B,EAC7B,aAAqB,EAAE;IAEvB,MAAM,KAAK,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,wBAAwB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5E,wEAAwE;IACxE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}
|
package/dist/session.d.ts
CHANGED
|
@@ -1,41 +1,231 @@
|
|
|
1
|
+
import { Handle } from './handle.js';
|
|
2
|
+
import { SubHandle } from './subhandle.js';
|
|
3
|
+
import { Identity } from './identity.js';
|
|
4
|
+
/**
|
|
5
|
+
* Options for creating a new {@link Session}.
|
|
6
|
+
*
|
|
7
|
+
* @category Types
|
|
8
|
+
*/
|
|
1
9
|
export interface SessionOptions {
|
|
10
|
+
/** The intended audience (recipient) of this session. */
|
|
2
11
|
audience: string;
|
|
12
|
+
/** Permission scopes granted in this session (e.g., `['read', 'write']`). */
|
|
3
13
|
scopes: string[];
|
|
4
|
-
|
|
14
|
+
/** Time-to-live in seconds. */
|
|
15
|
+
ttl: number;
|
|
16
|
+
/**
|
|
17
|
+
* Optional unique session identifier, used for revocation.
|
|
18
|
+
* If not provided, a random UUID is generated.
|
|
19
|
+
*/
|
|
20
|
+
sessionId?: string;
|
|
5
21
|
}
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
22
|
+
/**
|
|
23
|
+
* The payload structure encoded inside a session token.
|
|
24
|
+
*
|
|
25
|
+
* @category Types
|
|
26
|
+
*/
|
|
27
|
+
export interface SessionPayload {
|
|
28
|
+
/** Handle / SubHandle ID (Base64URL of public key). */
|
|
29
|
+
hId: string;
|
|
30
|
+
/** Handle / SubHandle name. */
|
|
31
|
+
hNm: string;
|
|
32
|
+
/**
|
|
33
|
+
* Derivation path for SubHandle sessions.
|
|
34
|
+
* Present only when the session was created by a SubHandle.
|
|
35
|
+
* Format: `[handleName, subName]`.
|
|
36
|
+
*/
|
|
37
|
+
hPath?: string[];
|
|
38
|
+
/** Intended audience. */
|
|
39
|
+
aud: string;
|
|
40
|
+
/** Granted scopes. */
|
|
41
|
+
scp: string[];
|
|
42
|
+
/** Expiration timestamp (Unix seconds). */
|
|
43
|
+
exp: number;
|
|
44
|
+
/** Issued-at timestamp (Unix seconds). */
|
|
45
|
+
iat: number;
|
|
46
|
+
/**
|
|
47
|
+
* Unique session identifier, used for revocation.
|
|
48
|
+
* Always present (generated automatically if not provided).
|
|
49
|
+
*/
|
|
50
|
+
jti: string;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Interface for application-side revocation checking.
|
|
54
|
+
*
|
|
55
|
+
* The Me2em protocol does not prescribe a storage backend for revocation.
|
|
56
|
+
* Applications implement this interface using their preferred store
|
|
57
|
+
* (Redis, PostgreSQL, in-memory Set, etc.) and pass it to
|
|
58
|
+
* {@link Session.verifyStateless}.
|
|
59
|
+
*
|
|
60
|
+
* @category Extension Points
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* ```ts
|
|
64
|
+
* // In-memory implementation (for simple cases)
|
|
65
|
+
* class InMemoryRevocationChecker implements RevocationChecker {
|
|
66
|
+
* private revoked = new Set<string>();
|
|
67
|
+
* async isRevoked(sessionId: string): Promise<boolean> {
|
|
68
|
+
* return this.revoked.has(sessionId);
|
|
69
|
+
* }
|
|
70
|
+
* revoke(sessionId: string): void {
|
|
71
|
+
* this.revoked.add(sessionId);
|
|
72
|
+
* }
|
|
73
|
+
* }
|
|
74
|
+
*
|
|
75
|
+
* // Redis implementation (for production)
|
|
76
|
+
* class RedisRevocationChecker implements RevocationChecker {
|
|
77
|
+
* constructor(private redis: Redis) {}
|
|
78
|
+
* async isRevoked(sessionId: string): Promise<boolean> {
|
|
79
|
+
* return (await this.redis.sismember('me2em:revoked', sessionId)) === 1;
|
|
80
|
+
* }
|
|
81
|
+
* }
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
export interface RevocationChecker {
|
|
85
|
+
/**
|
|
86
|
+
* Checks whether a session has been revoked.
|
|
87
|
+
*
|
|
88
|
+
* @param sessionId - The `jti` field from the session payload.
|
|
89
|
+
* @returns A Promise resolving to `true` if revoked, `false` otherwise.
|
|
90
|
+
*/
|
|
91
|
+
isRevoked(sessionId: string): Promise<boolean>;
|
|
11
92
|
}
|
|
12
93
|
/**
|
|
13
94
|
* Represents a stateless, cryptographically verifiable session token.
|
|
14
95
|
*
|
|
15
96
|
* Instead of storing session state on the server, the Session object
|
|
16
|
-
* encapsulates all necessary authorization data (handle ID, scopes,
|
|
17
|
-
* into a self-contained structure that can
|
|
97
|
+
* encapsulates all necessary authorization data (handle ID, scopes,
|
|
98
|
+
* expiration, derivation path) into a self-contained structure that can
|
|
99
|
+
* be verified using the Handle's or SubHandle's public key.
|
|
100
|
+
*
|
|
101
|
+
* Sessions can be created from either a {@link Handle} or a {@link SubHandle}.
|
|
102
|
+
* When created from a SubHandle, the token carries the derivation path
|
|
103
|
+
* (`hPath`) for hierarchical auditing.
|
|
18
104
|
*
|
|
19
105
|
* @category Core Primitives
|
|
20
106
|
*/
|
|
21
107
|
export declare class Session {
|
|
22
108
|
readonly handleId: string;
|
|
109
|
+
readonly handleName: string;
|
|
110
|
+
readonly audience: string;
|
|
23
111
|
readonly scopes: string[];
|
|
24
112
|
readonly expiresAt: number;
|
|
25
113
|
readonly token: string;
|
|
114
|
+
/** Derivation path, present only for SubHandle sessions. */
|
|
115
|
+
readonly path?: string[];
|
|
116
|
+
/** Unique session identifier, used for revocation. */
|
|
117
|
+
readonly sessionId: string;
|
|
26
118
|
/**
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
*/
|
|
34
|
-
constructor(handleId: string, scopes: string[], expiresAt: number, token: string);
|
|
119
|
+
* Creates a new Session instance.
|
|
120
|
+
*
|
|
121
|
+
* @internal Typically created via {@link Session.create} or
|
|
122
|
+
* {@link Session.verifyStateless}. Direct construction is discouraged.
|
|
123
|
+
*/
|
|
124
|
+
constructor(handleId: string, handleName: string, audience: string, scopes: string[], expiresAt: number, token: string, path?: string[], sessionId?: string);
|
|
35
125
|
/**
|
|
36
126
|
* Checks if the session has expired based on the current time.
|
|
37
|
-
*
|
|
127
|
+
*
|
|
128
|
+
* @returns `true` if the current time is past the `expiresAt` timestamp.
|
|
38
129
|
*/
|
|
39
130
|
isExpired(): boolean;
|
|
131
|
+
/**
|
|
132
|
+
* Creates a new signed session token.
|
|
133
|
+
*
|
|
134
|
+
* If the handle is a {@link SubHandle}, its constraints are validated
|
|
135
|
+
* before signing (audience, scopes, TTL, expiration). The derivation
|
|
136
|
+
* path is included in the payload as `hPath`.
|
|
137
|
+
*
|
|
138
|
+
* @param handle - The Handle or SubHandle that will sign this session.
|
|
139
|
+
* @param options - Session configuration including audience, scopes, TTL, and optional sessionId.
|
|
140
|
+
* @returns A Promise resolving to a new Session instance.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```ts
|
|
144
|
+
* const session = await Session.create(handle, {
|
|
145
|
+
* audience: 'app.example.com',
|
|
146
|
+
* scopes: ['read', 'write'],
|
|
147
|
+
* ttl: 3600,
|
|
148
|
+
* sessionId: 'unique-session-id' // optional
|
|
149
|
+
* });
|
|
150
|
+
* ```
|
|
151
|
+
*/
|
|
152
|
+
static create(handle: Handle | SubHandle, options: SessionOptions): Promise<Session>;
|
|
153
|
+
private static parseSessionToken;
|
|
154
|
+
/**
|
|
155
|
+
* Verifies a session token statelessly without server-side storage.
|
|
156
|
+
*
|
|
157
|
+
* Validates:
|
|
158
|
+
* - Token format (two Base64URL parts)
|
|
159
|
+
* - Payload size limit
|
|
160
|
+
* - Required fields (`hId`, `hNm`, `aud`, `scp`, `exp`, `iat`, `jti`)
|
|
161
|
+
* - Audience match
|
|
162
|
+
* - Expiration (with clock skew tolerance)
|
|
163
|
+
* - Signature (against the reconstructed Handle or SubHandle public key)
|
|
164
|
+
* - Revocation status (if a {@link RevocationChecker} is provided)
|
|
165
|
+
*
|
|
166
|
+
* For SubHandle sessions (those with `hPath`), the Handle/SubHandle is
|
|
167
|
+
* reconstructed atomically via {@link Identity.deriveSubHandle}.
|
|
168
|
+
*
|
|
169
|
+
* @param token - The Base64URL-encoded session token string.
|
|
170
|
+
* @param companyIdentity - The Identity used to reconstruct Handle/SubHandle public keys.
|
|
171
|
+
* @param expectedAudience - The audience that this token must be intended for.
|
|
172
|
+
* @param revocationChecker - Optional checker for revocation list.
|
|
173
|
+
* @returns A Promise resolving to a verified Session instance.
|
|
174
|
+
* @throws {Error} If the token is invalid, expired, tampered, audience mismatch, or revoked.
|
|
175
|
+
*
|
|
176
|
+
* @example
|
|
177
|
+
* ```ts
|
|
178
|
+
* const session = await Session.verifyStateless(
|
|
179
|
+
* token,
|
|
180
|
+
* companyIdentity,
|
|
181
|
+
* 'app.example.com',
|
|
182
|
+
* redisRevocationChecker // optional
|
|
183
|
+
* );
|
|
184
|
+
* ```
|
|
185
|
+
*/
|
|
186
|
+
static verifyStateless(token: string, companyIdentity: Identity, expectedAudience: string, revocationChecker?: RevocationChecker): Promise<Session>;
|
|
187
|
+
/**
|
|
188
|
+
* Verifies a session token together with its attestation chain
|
|
189
|
+
* (Mode 2 - using an attestation chain) — for verifiers that hold only the root PUBLIC key.
|
|
190
|
+
*
|
|
191
|
+
* The chain contains serialized attestations, root first:
|
|
192
|
+
* - handle sessions: `[attestHandle_token]` (length 1)
|
|
193
|
+
* - subhandle sessions: `[attestHandle_token, attestSubHandle_token]`
|
|
194
|
+
* (length 2)
|
|
195
|
+
*
|
|
196
|
+
* Enforced, in order: token structure and required fields (including
|
|
197
|
+
* `iat`); audience; session time (±30 s skew); chain shape; parent
|
|
198
|
+
* signature against `rootPublicKey`; parent validity and revocation;
|
|
199
|
+
* for subhandle sessions — child signature against the parent's
|
|
200
|
+
* `subjectId`, child validity/revocation, name/path agreement,
|
|
201
|
+
* wildcard permitting, `hId == child.subjectId`, and grant nesting
|
|
202
|
+
* (child scopes ⊆ parent scopes, child maxTtl ≤ parent maxTtl);
|
|
203
|
+
* session vs the effective grant (scopes, audiences, TTL); session
|
|
204
|
+
* expiry against the earliest attestation expiry; session signature
|
|
205
|
+
* against `hId`; session revocation — last.
|
|
206
|
+
*
|
|
207
|
+
* @param attestationChain - Attestation tokens, root first; length
|
|
208
|
+
* must match the session kind (1 for Handle, 2 for SubHandle).
|
|
209
|
+
* @param revocationChecker - Optional; consulted for attestation
|
|
210
|
+
* `jti` values (each chain level) and the session `jti`.
|
|
211
|
+
* @returns The verified session.
|
|
212
|
+
* @throws {AttestationError} With `code` and `level` identifying the
|
|
213
|
+
* failed layer — integrate on these fields, not on message text.
|
|
214
|
+
*
|
|
215
|
+
* @example
|
|
216
|
+
* ```ts
|
|
217
|
+
* const A = await identity.attestHandle('station-001', grantA);
|
|
218
|
+
* const sub = await station.deriveSubHandle('connector-ccs');
|
|
219
|
+
* const B = await station.attestSubHandle('connector-ccs', grantB);
|
|
220
|
+
* const session = await Session.create(sub, {
|
|
221
|
+
* audience: 'ev-app.com', scopes: ['charge:start'], ttl: 1800,
|
|
222
|
+
* });
|
|
223
|
+
* const verified = await Session.verifyAttested(
|
|
224
|
+
* session.token, identity.getPublicKey(), [A.token, B.token],
|
|
225
|
+
* 'ev-app.com',
|
|
226
|
+
* );
|
|
227
|
+
* ```
|
|
228
|
+
*/
|
|
229
|
+
static verifyAttested(token: string, rootPublicKey: Uint8Array, attestationChain: string[], expectedAudience: string, revocationChecker?: RevocationChecker): Promise<Session>;
|
|
40
230
|
}
|
|
41
231
|
//# 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":"
|
|
1
|
+
{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAWzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,OAAO;IAClB,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,SAAgB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,sDAAsD;IACtD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC;;;;;OAKG;gBAED,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,SAAS,CAAC,EAAE,MAAM;IAYpB;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;;;;;;;;;;;;;;;;OAoBG;WACU,MAAM,CACjB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC;IAkDnB,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAqDhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;WACU,eAAe,CAC1B,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,QAAQ,EACzB,gBAAgB,EAAE,MAAM,EACxB,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,OAAO,CAAC,OAAO,CAAC;IAkEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;WACU,cAAc,CACzB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EACxB,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,OAAO,CAAC,OAAO,CAAC;CAsNpB"}
|