@me2em/core 0.7.0-alpha.1 → 1.0.0-rc.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 (92) hide show
  1. package/README.md +242 -47
  2. package/dist/attestation.d.ts +26 -17
  3. package/dist/attestation.d.ts.map +1 -1
  4. package/dist/attestation.js +76 -29
  5. package/dist/attestation.js.map +1 -1
  6. package/dist/canonical-name.d.ts +18 -0
  7. package/dist/canonical-name.d.ts.map +1 -1
  8. package/dist/canonical-name.js +28 -1
  9. package/dist/canonical-name.js.map +1 -1
  10. package/dist/crypto/derivation-paths.d.ts +33 -2
  11. package/dist/crypto/derivation-paths.d.ts.map +1 -1
  12. package/dist/crypto/derivation-paths.js +33 -2
  13. package/dist/crypto/derivation-paths.js.map +1 -1
  14. package/dist/crypto/derivation.d.ts +47 -0
  15. package/dist/crypto/derivation.d.ts.map +1 -0
  16. package/dist/crypto/derivation.js +68 -0
  17. package/dist/crypto/derivation.js.map +1 -0
  18. package/dist/crypto/ecdh.d.ts +19 -0
  19. package/dist/crypto/ecdh.d.ts.map +1 -0
  20. package/dist/crypto/ecdh.js +33 -0
  21. package/dist/crypto/ecdh.js.map +1 -0
  22. package/dist/crypto/ed25519.d.ts +24 -3
  23. package/dist/crypto/ed25519.d.ts.map +1 -1
  24. package/dist/crypto/ed25519.js +39 -6
  25. package/dist/crypto/ed25519.js.map +1 -1
  26. package/dist/crypto/hkdf.d.ts +11 -2
  27. package/dist/crypto/hkdf.d.ts.map +1 -1
  28. package/dist/crypto/hkdf.js +13 -1
  29. package/dist/crypto/hkdf.js.map +1 -1
  30. package/dist/crypto/index.d.ts +25 -0
  31. package/dist/crypto/index.d.ts.map +1 -1
  32. package/dist/crypto/index.js +25 -0
  33. package/dist/crypto/index.js.map +1 -1
  34. package/dist/disposed-error.d.ts +24 -0
  35. package/dist/disposed-error.d.ts.map +1 -0
  36. package/dist/disposed-error.js +39 -0
  37. package/dist/disposed-error.js.map +1 -0
  38. package/dist/errors.d.ts +67 -0
  39. package/dist/errors.d.ts.map +1 -0
  40. package/dist/errors.js +54 -0
  41. package/dist/errors.js.map +1 -0
  42. package/dist/handle.d.ts +300 -14
  43. package/dist/handle.d.ts.map +1 -1
  44. package/dist/handle.js +463 -54
  45. package/dist/handle.js.map +1 -1
  46. package/dist/identity.d.ts +55 -11
  47. package/dist/identity.d.ts.map +1 -1
  48. package/dist/identity.js +105 -35
  49. package/dist/identity.js.map +1 -1
  50. package/dist/index.d.ts +10 -5
  51. package/dist/index.d.ts.map +1 -1
  52. package/dist/index.js +8 -4
  53. package/dist/index.js.map +1 -1
  54. package/dist/seed.d.ts +33 -22
  55. package/dist/seed.d.ts.map +1 -1
  56. package/dist/seed.js +59 -31
  57. package/dist/seed.js.map +1 -1
  58. package/dist/session.d.ts +42 -5
  59. package/dist/session.d.ts.map +1 -1
  60. package/dist/session.js +248 -117
  61. package/dist/session.js.map +1 -1
  62. package/dist/subhandle.d.ts +1 -125
  63. package/dist/subhandle.d.ts.map +1 -1
  64. package/dist/subhandle.js +12 -179
  65. package/dist/subhandle.js.map +1 -1
  66. package/dist/types.d.ts +22 -0
  67. package/dist/types.d.ts.map +1 -0
  68. package/dist/types.js +6 -0
  69. package/dist/types.js.map +1 -0
  70. package/dist/util.d.ts +47 -0
  71. package/dist/util.d.ts.map +1 -1
  72. package/dist/util.js +72 -20
  73. package/dist/util.js.map +1 -1
  74. package/package.json +12 -5
  75. package/src/attestation.ts +88 -38
  76. package/src/canonical-name.ts +33 -1
  77. package/src/crypto/derivation-paths.ts +37 -2
  78. package/src/crypto/derivation.ts +90 -0
  79. package/src/crypto/ecdh.ts +37 -0
  80. package/src/crypto/ed25519.ts +39 -6
  81. package/src/crypto/hkdf.ts +13 -1
  82. package/src/crypto/index.ts +28 -1
  83. package/src/disposed-error.ts +45 -0
  84. package/src/errors.ts +88 -0
  85. package/src/handle.ts +630 -65
  86. package/src/identity.ts +111 -64
  87. package/src/index.ts +13 -7
  88. package/src/seed.ts +75 -32
  89. package/src/session.ts +336 -132
  90. package/src/subhandle.ts +12 -251
  91. package/src/types.ts +26 -0
  92. package/src/util.ts +78 -20
package/dist/seed.js CHANGED
@@ -1,7 +1,7 @@
1
- // seed.ts
1
+ // packages/core/src/seed.ts
2
2
  import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39';
3
3
  import { wordlist } from '@scure/bip39/wordlists/english';
4
- import { sha256 } from './crypto/hkdf.js';
4
+ import { AttestationError } from './errors.js';
5
5
  /**
6
6
  * Utilities for BIP39 mnemonic seed phrase generation and validation.
7
7
  * These functions provide secure, deterministic seed phrase handling
@@ -29,7 +29,7 @@ import { sha256 } from './crypto/hkdf.js';
29
29
  */
30
30
  export function generateSeedPhrase(strength = 128) {
31
31
  if (strength !== 128 && strength !== 256) {
32
- throw new Error('Seed strength must be 128 (12 words) or 256 (24 words)');
32
+ throw new AttestationError('MALFORMED', 'FORMAT', 'Seed strength must be 128 (12 words) or 256 (24 words)');
33
33
  }
34
34
  const mnemonic = generateMnemonic(wordlist, strength);
35
35
  return mnemonic.split(' ');
@@ -53,70 +53,98 @@ export function normalizeSeedPhrase(seedPhrase) {
53
53
  return words.map(word => word.toLowerCase().trim()).filter(word => word.length > 0);
54
54
  }
55
55
  /**
56
- * Validates a mnemonic seed phrase against the BIP39 standard.
56
+ * Validates a mnemonic seed phrase against the BIP39 standard with
57
+ * detailed feedback.
57
58
  *
58
- * Checks:
59
- * - Correct word count (12 or 24 words)
60
- * - All words exist in the BIP39 wordlist
61
- * - Valid checksum
59
+ * Checks (in order):
60
+ * 1. Word count must be 12 or 24.
61
+ * 2. Each word must exist in the BIP39 English wordlist.
62
+ * 3. Checksum must be valid.
62
63
  *
63
64
  * @param words - The mnemonic phrase to validate.
64
- * @returns An object with `isValid` flag and optional `error` message.
65
+ * @returns A result object with isValid, error, wordCount, and invalidWords.
65
66
  *
66
67
  * @example
67
68
  * ```ts
68
69
  * const result = validateSeedPhrase(['abandon', 'abandon', ..., 'art']);
69
- * if (!result.isValid) console.error(result.error);
70
+ * if (!result.isValid) {
71
+ * console.error(result.error);
72
+ * console.log('Invalid words:', result.invalidWords);
73
+ * }
70
74
  * ```
71
75
  */
72
76
  export function validateSeedPhrase(words) {
73
- const wordCount = words.length;
74
- if (wordCount !== 12 && wordCount !== 24) {
75
- return { isValid: false, error: `Seed phrase must be 12 or 24 words, got ${wordCount}` };
76
- }
77
77
  const normalized = normalizeSeedPhrase(words);
78
+ const invalidWords = [];
78
79
  for (const word of normalized) {
79
80
  if (!wordlist.includes(word)) {
80
- return { isValid: false, error: `Invalid word: ${word}` };
81
+ invalidWords.push(word);
81
82
  }
82
83
  }
84
+ if (normalized.length !== 12 && normalized.length !== 24) {
85
+ return {
86
+ isValid: false,
87
+ error: `Seed phrase must be 12 or 24 words, got ${normalized.length}`,
88
+ wordCount: normalized.length,
89
+ invalidWords,
90
+ };
91
+ }
92
+ if (invalidWords.length > 0) {
93
+ return {
94
+ isValid: false,
95
+ error: `Invalid words found: ${invalidWords.join(', ')}`,
96
+ wordCount: normalized.length,
97
+ invalidWords,
98
+ };
99
+ }
83
100
  const isValid = validateMnemonic(normalized.join(' '), wordlist);
84
- return { isValid, error: isValid ? undefined : 'Invalid seed phrase checksum' };
101
+ return {
102
+ isValid,
103
+ error: isValid ? undefined : 'Invalid seed phrase checksum',
104
+ wordCount: normalized.length,
105
+ invalidWords: [],
106
+ };
85
107
  }
86
108
  /**
87
- * Derives a 32-byte cryptographic seed from a BIP39 mnemonic phrase using PBKDF2.
88
- * This is the standard BIP39 derivation function that converts a human-readable
89
- * mnemonic into a binary seed suitable for Ed25519 key generation.
109
+ * Derives the 64-byte BIP39 seed from a mnemonic phrase using PBKDF2
110
+ * (PBKDF2-HMAC-SHA512, 2048 iterations, salt `"mnemonic" + passphrase`).
111
+ * This is the standard BIP39 derivation: the full 512-bit seed is returned
112
+ * unmodified and serves as the input key material for identity derivation
113
+ * ({@link Identity.fromSeed} applies HKDF-SHA256 on top).
90
114
  *
91
- * The resulting 64-byte BIP39 seed is hashed with SHA-256 to produce a
92
- * deterministic 32-byte seed, as required by Ed25519.
115
+ * Both 12-word (128-bit) and 24-word (256-bit) mnemonics produce the same
116
+ * 64-byte seed length, per the BIP39 standard.
93
117
  *
94
118
  * @param seedPhrase - The BIP39 mnemonic phrase (string or array of words).
95
119
  * @param passphrase - Optional BIP39 passphrase ("25th word").
96
- * Normalized via NFKC before use. An empty string (default)
120
+ * BIP39 NFKD normalization (mnemonic and passphrase) is performed by
121
+ * `@scure/bip39`; this function passes the passphrase through
122
+ * unchanged. An empty string (default)
97
123
  * matches phrases without a passphrase. WARNING: the passphrase
98
124
  * is NOT recoverable — a different passphrase silently derives a
99
125
  * completely different seed with no error indication. Store it
100
126
  * as carefully as the mnemonic itself.
101
- * @returns A Promise resolving to a 32-byte Uint8Array seed.
127
+ * @returns A Promise resolving to the 64-byte Uint8Array BIP39 seed.
102
128
  *
103
129
  * @example
104
130
  * ```ts
105
- * const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
106
- * // Uint8Array(32) [123, 45, 67, ...]
131
+ * const seed = await get64ByteSeedFromMnemonic('abandon abandon ... art');
132
+ * // Uint8Array(64) [94, 176, 187, ...]
107
133
  *
108
- * const seedWithPassphrase = await get32ByteSeedFromMnemonic(words, 'my secret 25th word');
134
+ * const seedWithPassphrase = await get64ByteSeedFromMnemonic(words, 'my secret 25th word');
109
135
  * ```
110
136
  */
111
- export async function get32ByteSeedFromMnemonic(seedPhrase, passphrase = '') {
137
+ export async function get64ByteSeedFromMnemonic(seedPhrase, passphrase = '') {
112
138
  const words = normalizeSeedPhrase(seedPhrase);
113
139
  const validation = validateSeedPhrase(words);
114
140
  if (!validation.isValid) {
115
- throw new Error(`Invalid seed phrase: ${validation.error}`);
141
+ throw new AttestationError('MALFORMED', 'FORMAT', `Invalid seed phrase: ${validation.error}`);
116
142
  }
117
143
  const mnemonic = words.join(' ');
118
- const seed64 = await mnemonicToSeed(mnemonic, passphrase.normalize('NFKC'));
119
- // Hash the 64-byte seed to get a deterministic 32-byte seed for Ed25519
120
- return sha256(seed64);
144
+ // Full 64-byte BIP39 seed (PBKDF2-HMAC-SHA512 output) — no post-hashing.
145
+ // Normalization (NFKD on mnemonic + passphrase salt) is the BIP39 layer's
146
+ // job — do not pre-normalize here (spec §2: implementations MUST NOT
147
+ // apply additional normalization on top).
148
+ return mnemonicToSeed(mnemonic, passphrase);
121
149
  }
122
150
  //# sourceMappingURL=seed.js.map
package/dist/seed.js.map CHANGED
@@ -1 +1 @@
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"}
1
+ {"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"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"}
package/dist/session.d.ts CHANGED
@@ -52,7 +52,7 @@ export interface SessionPayload {
52
52
  /**
53
53
  * Interface for application-side revocation checking.
54
54
  *
55
- * The Me2em protocol does not prescribe a storage backend for revocation.
55
+ * The Me2eM protocol does not prescribe a storage backend for revocation.
56
56
  * Applications implement this interface using their preferred store
57
57
  * (Redis, PostgreSQL, in-memory Set, etc.) and pass it to
58
58
  * {@link Session.verifyStateless}.
@@ -105,6 +105,7 @@ export interface RevocationChecker {
105
105
  * @category Core Primitives
106
106
  */
107
107
  export declare class Session {
108
+ #private;
108
109
  readonly handleId: string;
109
110
  readonly handleName: string;
110
111
  readonly audience: string;
@@ -118,10 +119,36 @@ export declare class Session {
118
119
  /**
119
120
  * Creates a new Session instance.
120
121
  *
121
- * @internal Typically created via {@link Session.create} or
122
- * {@link Session.verifyStateless}. Direct construction is discouraged.
122
+ * @internal Construction is a library-internal step (PR-11, D6): a
123
+ * Session is either freshly issued — {@link Session.create} — or the
124
+ * result of a verified token — {@link Session.verifyStateless} /
125
+ * {@link Session.verifyAttested}. External callers cannot fabricate a
126
+ * verified-looking session object; test/tooling reconstruction goes
127
+ * through the {@link Session.fromVerified} internal factory.
123
128
  */
124
- constructor(handleId: string, handleName: string, audience: string, scopes: string[], expiresAt: number, token: string, path?: string[], sessionId?: string);
129
+ private constructor();
130
+ /**
131
+ * Rebuilds a Session from parts whose validity has already been
132
+ * established — the single sanctioned bypass of the private
133
+ * constructor (PR-11, D6).
134
+ *
135
+ * @internal Not public API. Production code gets sessions from
136
+ * {@link Session.create} / {@link Session.verifyStateless} /
137
+ * {@link Session.verifyAttested}; only library tests (via test-utils)
138
+ * use this factory. It performs no verification of its own — the name
139
+ * says "verified" because the CALLER asserts the parts come from a
140
+ * verification step or a fresh issuance.
141
+ *
142
+ * @param handleId - Handle / SubHandle ID (Base64URL of public key).
143
+ * @param handleName - Handle / SubHandle name.
144
+ * @param audience - Intended audience.
145
+ * @param scopes - Granted scopes.
146
+ * @param expiresAt - Expiration timestamp (Unix seconds).
147
+ * @param token - The full session token.
148
+ * @param path - Derivation path (SubHandle sessions only).
149
+ * @param sessionId - Session `jti` (revocation id).
150
+ */
151
+ static fromVerified(handleId: string, handleName: string, audience: string, scopes: string[], expiresAt: number, token: string, path?: string[], sessionId?: string): Session;
125
152
  /**
126
153
  * Checks if the session has expired based on the current time.
127
154
  *
@@ -171,7 +198,10 @@ export declare class Session {
171
198
  * @param expectedAudience - The audience that this token must be intended for.
172
199
  * @param revocationChecker - Optional checker for revocation list.
173
200
  * @returns A Promise resolving to a verified Session instance.
174
- * @throws {Error} If the token is invalid, expired, tampered, audience mismatch, or revoked.
201
+ * @throws {AttestationError} With `code`/`level` — `MALFORMED`/`FORMAT`
202
+ * for structural failures, then `AUDIENCE_NOT_PERMITTED`,
203
+ * `EXPIRED`, `NOT_YET_VALID` (session), `BAD_SIGNATURE`,
204
+ * `SUBJECT_MISMATCH`, `REVOKED` at level `SESSION`.
175
205
  *
176
206
  * @example
177
207
  * ```ts
@@ -204,6 +234,13 @@ export declare class Session {
204
234
  * expiry against the earliest attestation expiry; session signature
205
235
  * against `hId`; session revocation — last.
206
236
  *
237
+ * Internally (PR-11, 3.4/3.6) the flow is split into five private
238
+ * stages — `#verifyChainStructure`, `#verifyRootAttestation`,
239
+ * `#verifyHandleAttestation`, `#verifySessionAgainstGrant`,
240
+ * `#verifySessionSignature` — with the check order, error codes and
241
+ * error levels byte-identical to the pre-split monolith (pinned by the
242
+ * untouched attested-session, error-table and fuzz suites).
243
+ *
207
244
  * @param attestationChain - Attestation tokens, root first; length
208
245
  * must match the session kind (1 for Handle, 2 for SubHandle).
209
246
  * @param revocationChecker - Optional; consulted for attestation
@@ -1 +1 @@
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"}
1
+ {"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}