@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.
Files changed (70) hide show
  1. package/README.md +294 -546
  2. package/dist/attestation.d.ts +151 -0
  3. package/dist/attestation.d.ts.map +1 -0
  4. package/dist/attestation.js +279 -0
  5. package/dist/attestation.js.map +1 -0
  6. package/dist/canonical-name.d.ts +3 -0
  7. package/dist/canonical-name.d.ts.map +1 -0
  8. package/dist/canonical-name.js +12 -0
  9. package/dist/canonical-name.js.map +1 -0
  10. package/dist/crypto/derivation-paths.d.ts +41 -0
  11. package/dist/crypto/derivation-paths.d.ts.map +1 -0
  12. package/dist/crypto/derivation-paths.js +50 -0
  13. package/dist/crypto/derivation-paths.js.map +1 -0
  14. package/dist/crypto/ed25519.d.ts +48 -8
  15. package/dist/crypto/ed25519.d.ts.map +1 -1
  16. package/dist/crypto/ed25519.js +63 -8
  17. package/dist/crypto/ed25519.js.map +1 -1
  18. package/dist/crypto/hkdf.d.ts.map +1 -1
  19. package/dist/crypto/hkdf.js +1 -0
  20. package/dist/crypto/hkdf.js.map +1 -1
  21. package/dist/crypto/index.d.ts +1 -0
  22. package/dist/crypto/index.d.ts.map +1 -1
  23. package/dist/crypto/index.js +2 -0
  24. package/dist/crypto/index.js.map +1 -1
  25. package/dist/crypto/init.d.ts.map +1 -1
  26. package/dist/crypto/init.js +1 -0
  27. package/dist/crypto/init.js.map +1 -1
  28. package/dist/handle.d.ts +149 -35
  29. package/dist/handle.d.ts.map +1 -1
  30. package/dist/handle.js +180 -40
  31. package/dist/handle.js.map +1 -1
  32. package/dist/identity.d.ts +99 -19
  33. package/dist/identity.d.ts.map +1 -1
  34. package/dist/identity.js +128 -32
  35. package/dist/identity.js.map +1 -1
  36. package/dist/index.d.ts +5 -1
  37. package/dist/index.d.ts.map +1 -1
  38. package/dist/index.js +4 -0
  39. package/dist/index.js.map +1 -1
  40. package/dist/seed.d.ts +38 -39
  41. package/dist/seed.d.ts.map +1 -1
  42. package/dist/seed.js +36 -41
  43. package/dist/seed.js.map +1 -1
  44. package/dist/session.d.ts +207 -17
  45. package/dist/session.d.ts.map +1 -1
  46. package/dist/session.js +428 -11
  47. package/dist/session.js.map +1 -1
  48. package/dist/subhandle.d.ts +126 -0
  49. package/dist/subhandle.d.ts.map +1 -0
  50. package/dist/subhandle.js +182 -0
  51. package/dist/subhandle.js.map +1 -0
  52. package/dist/util.d.ts +9 -0
  53. package/dist/util.d.ts.map +1 -0
  54. package/dist/util.js +34 -0
  55. package/dist/util.js.map +1 -0
  56. package/package.json +3 -3
  57. package/src/attestation.ts +364 -0
  58. package/src/canonical-name.ts +12 -0
  59. package/src/crypto/derivation-paths.ts +56 -0
  60. package/src/crypto/ed25519.ts +82 -8
  61. package/src/crypto/hkdf.ts +2 -0
  62. package/src/crypto/index.ts +3 -1
  63. package/src/crypto/init.ts +1 -0
  64. package/src/handle.ts +227 -42
  65. package/src/identity.ts +164 -35
  66. package/src/index.ts +5 -1
  67. package/src/seed.ts +59 -59
  68. package/src/session.ts +637 -24
  69. package/src/subhandle.ts +254 -0
  70. package/src/util.ts +35 -0
@@ -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;;;;;;;;;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"}
1
+ {"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}
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 { Session, type SessionOptions, type SessionToken } from './session.js';
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
@@ -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;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,YAAY,EAClB,MAAM,WAAW,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,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,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"}
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
- * ```typescript
25
- * const mnemonic12 = await generateSeedPhrase(128);
26
- * // "abandon abandon abandon ... art"
26
+ * ```ts
27
+ * const mnemonic12 = generateSeedPhrase(128);
28
+ * // ["abandon", "abandon", ..., "art"]
27
29
  *
28
- * const mnemonic24 = await generateSeedPhrase(256);
29
- * // "abandon abandon abandon ... zoo" (24 words)
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 phrase - The mnemonic phrase to normalize (string or array of words).
37
- * @returns A normalized string of lowercase words separated by single spaces.
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
- * ```typescript
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, 15, 18, 21, or 24 words)
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 phrase - The mnemonic phrase to validate.
58
- * @returns `true` if the phrase is valid, `false` otherwise.
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
- * ```typescript
62
- * const isValid = await validateSeedPhrase('abandon abandon ... art');
63
- * // true
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
- * @param phrase - The BIP39 mnemonic phrase (will be normalized automatically).
80
- * @param passphrase - Optional passphrase for additional security (BIP39 "25th word").
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
- * ```typescript
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
@@ -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;;;;;;;;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"}
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
- * ```typescript
27
- * const mnemonic12 = await generateSeedPhrase(128);
28
- * // "abandon abandon abandon ... art"
22
+ * ```ts
23
+ * const mnemonic12 = generateSeedPhrase(128);
24
+ * // ["abandon", "abandon", ..., "art"]
29
25
  *
30
- * const mnemonic24 = await generateSeedPhrase(256);
31
- * // "abandon abandon abandon ... zoo" (24 words)
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 phrase - The mnemonic phrase to normalize (string or array of words).
45
- * @returns A normalized string of lowercase words separated by single spaces.
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
- * ```typescript
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) ? seedPhrase : seedPhrase.trim().split(/\s+/);
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, 15, 18, 21, or 24 words)
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 phrase - The mnemonic phrase to validate.
69
- * @returns `true` if the phrase is valid, `false` otherwise.
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
- * ```typescript
73
- * const isValid = await validateSeedPhrase('abandon abandon ... art');
74
- * // true
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
- * @param phrase - The BIP39 mnemonic phrase (will be normalized automatically).
101
- * @param passphrase - Optional passphrase for additional security (BIP39 "25th word").
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
- * ```typescript
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;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"}
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
- ttl?: number;
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
- export interface SessionToken {
7
- handleId: string;
8
- scopes: string[];
9
- expiresAt: number;
10
- token: string;
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, expiration)
17
- * into a self-contained structure that can be verified using the Handle's public key.
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
- * 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
- */
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
- * @returns `true` if the current time is past the `expiresAt` timestamp, `false` otherwise.
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
@@ -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;;;;;;;;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"}
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"}