@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
package/dist/session.js CHANGED
@@ -1,37 +1,454 @@
1
+ // session.ts
2
+ import { Handle } from './handle.js';
3
+ import { base64urlEncode, base64urlDecode } from './util.js';
4
+ import { Attestation, AttestationError, } from './attestation.js';
5
+ const MAX_PAYLOAD_SIZE = 4096;
6
+ const CLOCK_SKEW_SECONDS = 30;
1
7
  /**
2
8
  * Represents a stateless, cryptographically verifiable session token.
3
9
  *
4
10
  * Instead of storing session state on the server, the Session object
5
- * encapsulates all necessary authorization data (handle ID, scopes, expiration)
6
- * into a self-contained structure that can be verified using the Handle's public key.
11
+ * encapsulates all necessary authorization data (handle ID, scopes,
12
+ * expiration, derivation path) into a self-contained structure that can
13
+ * be verified using the Handle's or SubHandle's public key.
14
+ *
15
+ * Sessions can be created from either a {@link Handle} or a {@link SubHandle}.
16
+ * When created from a SubHandle, the token carries the derivation path
17
+ * (`hPath`) for hierarchical auditing.
7
18
  *
8
19
  * @category Core Primitives
9
20
  */
10
21
  export class Session {
11
22
  handleId;
23
+ handleName;
24
+ audience;
12
25
  scopes;
13
26
  expiresAt;
14
27
  token;
28
+ /** Derivation path, present only for SubHandle sessions. */
29
+ path;
30
+ /** Unique session identifier, used for revocation. */
31
+ sessionId;
15
32
  /**
16
- * Creates a new Session instance.
17
- *
18
- * @param handleId - The ID of the Handle that authorized this session.
19
- * @param scopes - An array of permission scopes granted in this session (e.g., ['read', 'write']).
20
- * @param expiresAt - Unix timestamp (in milliseconds) when this session expires.
21
- * @param token - The cryptographic token string (e.g., JWT or custom signature format).
22
- */
23
- constructor(handleId, scopes, expiresAt, token) {
33
+ * Creates a new Session instance.
34
+ *
35
+ * @internal Typically created via {@link Session.create} or
36
+ * {@link Session.verifyStateless}. Direct construction is discouraged.
37
+ */
38
+ constructor(handleId, handleName, audience, scopes, expiresAt, token, path, sessionId) {
24
39
  this.handleId = handleId;
40
+ this.handleName = handleName;
41
+ this.audience = audience;
25
42
  this.scopes = scopes;
26
43
  this.expiresAt = expiresAt;
27
44
  this.token = token;
45
+ this.path = path;
46
+ this.sessionId = sessionId ?? '';
28
47
  }
29
48
  /**
30
49
  * Checks if the session has expired based on the current time.
31
- * @returns `true` if the current time is past the `expiresAt` timestamp, `false` otherwise.
50
+ *
51
+ * @returns `true` if the current time is past the `expiresAt` timestamp.
32
52
  */
33
53
  isExpired() {
34
54
  return Date.now() >= this.expiresAt * 1000;
35
55
  }
56
+ /**
57
+ * Creates a new signed session token.
58
+ *
59
+ * If the handle is a {@link SubHandle}, its constraints are validated
60
+ * before signing (audience, scopes, TTL, expiration). The derivation
61
+ * path is included in the payload as `hPath`.
62
+ *
63
+ * @param handle - The Handle or SubHandle that will sign this session.
64
+ * @param options - Session configuration including audience, scopes, TTL, and optional sessionId.
65
+ * @returns A Promise resolving to a new Session instance.
66
+ *
67
+ * @example
68
+ * ```ts
69
+ * const session = await Session.create(handle, {
70
+ * audience: 'app.example.com',
71
+ * scopes: ['read', 'write'],
72
+ * ttl: 3600,
73
+ * sessionId: 'unique-session-id' // optional
74
+ * });
75
+ * ```
76
+ */
77
+ static async create(handle, options) {
78
+ if (typeof options.ttl !== 'number' ||
79
+ !Number.isInteger(options.ttl) ||
80
+ options.ttl <= 0) {
81
+ throw new Error(`ttl must be a positive integer (seconds), got: ${String(options.ttl)}`);
82
+ }
83
+ handle.validateSessionOptions(options);
84
+ const now = Math.floor(Date.now() / 1000);
85
+ const expiresAt = now + options.ttl;
86
+ const sessionId = options.sessionId ?? crypto.randomUUID();
87
+ const payload = {
88
+ hId: handle.getId(),
89
+ hNm: handle.getName(),
90
+ aud: options.audience,
91
+ scp: options.scopes,
92
+ exp: expiresAt,
93
+ iat: now,
94
+ jti: sessionId,
95
+ };
96
+ // Include derivation path for SubHandle sessions
97
+ const hPath = handle.getPath();
98
+ if (hPath) {
99
+ payload.hPath = hPath;
100
+ }
101
+ const payloadBytes = new TextEncoder().encode(JSON.stringify(payload));
102
+ const signature = await handle.sign(payloadBytes);
103
+ const payloadB64 = base64urlEncode(payloadBytes);
104
+ const signatureB64 = base64urlEncode(signature);
105
+ const token = `${payloadB64}.${signatureB64}`;
106
+ return new Session(payload.hId, payload.hNm, payload.aud, payload.scp, payload.exp, token, payload.hPath, sessionId);
107
+ }
108
+ static parseSessionToken(token) {
109
+ if (typeof token !== 'string') {
110
+ throw new Error('Token must be a string');
111
+ }
112
+ const parts = token.split('.');
113
+ if (parts.length !== 2) {
114
+ throw new Error('Invalid token format: expected two Base64URL parts separated by "."');
115
+ }
116
+ const [payloadB64, signatureB64] = parts;
117
+ const b64urlRegex = /^[A-Za-z0-9_-]+$/;
118
+ if (!b64urlRegex.test(payloadB64) || !b64urlRegex.test(signatureB64)) {
119
+ throw new Error('Invalid token format: payload and signature must be valid Base64URL');
120
+ }
121
+ const payloadBytes = base64urlDecode(payloadB64);
122
+ if (payloadBytes.length > MAX_PAYLOAD_SIZE) {
123
+ throw new Error(`Payload exceeds maximum size of ${MAX_PAYLOAD_SIZE} bytes`);
124
+ }
125
+ let payload;
126
+ try {
127
+ const jsonString = new TextDecoder().decode(payloadBytes);
128
+ payload = JSON.parse(jsonString);
129
+ }
130
+ catch {
131
+ throw new Error('Invalid token format: payload is not valid JSON');
132
+ }
133
+ // Required fields validation
134
+ if (!payload.hId ||
135
+ !payload.hNm ||
136
+ !payload.aud ||
137
+ !Array.isArray(payload.scp) ||
138
+ typeof payload.exp !== 'number' ||
139
+ typeof payload.iat !== 'number' ||
140
+ typeof payload.jti !== 'string') {
141
+ throw new Error('Invalid token format: missing required fields (hId, hNm, aud, scp, exp, iat, jti)');
142
+ }
143
+ const signatureBytes = base64urlDecode(signatureB64);
144
+ return { payload, payloadBytes, signatureBytes };
145
+ }
146
+ /**
147
+ * Verifies a session token statelessly without server-side storage.
148
+ *
149
+ * Validates:
150
+ * - Token format (two Base64URL parts)
151
+ * - Payload size limit
152
+ * - Required fields (`hId`, `hNm`, `aud`, `scp`, `exp`, `iat`, `jti`)
153
+ * - Audience match
154
+ * - Expiration (with clock skew tolerance)
155
+ * - Signature (against the reconstructed Handle or SubHandle public key)
156
+ * - Revocation status (if a {@link RevocationChecker} is provided)
157
+ *
158
+ * For SubHandle sessions (those with `hPath`), the Handle/SubHandle is
159
+ * reconstructed atomically via {@link Identity.deriveSubHandle}.
160
+ *
161
+ * @param token - The Base64URL-encoded session token string.
162
+ * @param companyIdentity - The Identity used to reconstruct Handle/SubHandle public keys.
163
+ * @param expectedAudience - The audience that this token must be intended for.
164
+ * @param revocationChecker - Optional checker for revocation list.
165
+ * @returns A Promise resolving to a verified Session instance.
166
+ * @throws {Error} If the token is invalid, expired, tampered, audience mismatch, or revoked.
167
+ *
168
+ * @example
169
+ * ```ts
170
+ * const session = await Session.verifyStateless(
171
+ * token,
172
+ * companyIdentity,
173
+ * 'app.example.com',
174
+ * redisRevocationChecker // optional
175
+ * );
176
+ * ```
177
+ */
178
+ static async verifyStateless(token, companyIdentity, expectedAudience, revocationChecker) {
179
+ const { payload, payloadBytes, signatureBytes } = Session.parseSessionToken(token);
180
+ // Audience check
181
+ if (payload.aud !== expectedAudience) {
182
+ throw new Error(`Audience mismatch: expected "${expectedAudience}", got "${payload.aud}"`);
183
+ }
184
+ // Time checks
185
+ const now = Math.floor(Date.now() / 1000);
186
+ if (now > payload.exp + CLOCK_SKEW_SECONDS) {
187
+ throw new Error('Token expired');
188
+ }
189
+ if (now < payload.iat - CLOCK_SKEW_SECONDS) {
190
+ throw new Error('Token is future-dated');
191
+ }
192
+ // Reconstruct Handle or SubHandle
193
+ let handle;
194
+ if (payload.hPath && payload.hPath.length === 2) {
195
+ handle = await companyIdentity.deriveSubHandle(payload.hPath[0], payload.hPath[1]);
196
+ }
197
+ else {
198
+ handle = await companyIdentity.deriveHandle(payload.hNm);
199
+ }
200
+ // Signature verification (wrapped to catch exceptions from the crypto lib)
201
+ const publicKey = handle.getPublicKey();
202
+ let isValid = false;
203
+ try {
204
+ isValid = await Handle.verify(signatureBytes, payloadBytes, publicKey);
205
+ }
206
+ catch {
207
+ isValid = false;
208
+ }
209
+ if (!isValid) {
210
+ throw new Error('Invalid signature: token payload has been tampered with or was not signed by the claimed Handle');
211
+ }
212
+ if (handle.getId() !== payload.hId) {
213
+ throw new Error('hId mismatch');
214
+ }
215
+ // Revocation check — last, after signature is verified
216
+ if (revocationChecker) {
217
+ const isRevoked = await revocationChecker.isRevoked(payload.jti);
218
+ if (isRevoked) {
219
+ throw new Error('Session has been revoked');
220
+ }
221
+ }
222
+ return new Session(payload.hId, payload.hNm, payload.aud, payload.scp, payload.exp, token, payload.hPath, payload.jti);
223
+ }
224
+ /**
225
+ * Verifies a session token together with its attestation chain
226
+ * (Mode 2 - using an attestation chain) — for verifiers that hold only the root PUBLIC key.
227
+ *
228
+ * The chain contains serialized attestations, root first:
229
+ * - handle sessions: `[attestHandle_token]` (length 1)
230
+ * - subhandle sessions: `[attestHandle_token, attestSubHandle_token]`
231
+ * (length 2)
232
+ *
233
+ * Enforced, in order: token structure and required fields (including
234
+ * `iat`); audience; session time (±30 s skew); chain shape; parent
235
+ * signature against `rootPublicKey`; parent validity and revocation;
236
+ * for subhandle sessions — child signature against the parent's
237
+ * `subjectId`, child validity/revocation, name/path agreement,
238
+ * wildcard permitting, `hId == child.subjectId`, and grant nesting
239
+ * (child scopes ⊆ parent scopes, child maxTtl ≤ parent maxTtl);
240
+ * session vs the effective grant (scopes, audiences, TTL); session
241
+ * expiry against the earliest attestation expiry; session signature
242
+ * against `hId`; session revocation — last.
243
+ *
244
+ * @param attestationChain - Attestation tokens, root first; length
245
+ * must match the session kind (1 for Handle, 2 for SubHandle).
246
+ * @param revocationChecker - Optional; consulted for attestation
247
+ * `jti` values (each chain level) and the session `jti`.
248
+ * @returns The verified session.
249
+ * @throws {AttestationError} With `code` and `level` identifying the
250
+ * failed layer — integrate on these fields, not on message text.
251
+ *
252
+ * @example
253
+ * ```ts
254
+ * const A = await identity.attestHandle('station-001', grantA);
255
+ * const sub = await station.deriveSubHandle('connector-ccs');
256
+ * const B = await station.attestSubHandle('connector-ccs', grantB);
257
+ * const session = await Session.create(sub, {
258
+ * audience: 'ev-app.com', scopes: ['charge:start'], ttl: 1800,
259
+ * });
260
+ * const verified = await Session.verifyAttested(
261
+ * session.token, identity.getPublicKey(), [A.token, B.token],
262
+ * 'ev-app.com',
263
+ * );
264
+ * ```
265
+ */
266
+ static async verifyAttested(token, rootPublicKey, attestationChain, expectedAudience, revocationChecker) {
267
+ const { payload, payloadBytes, signatureBytes } = Session.parseSessionToken(token);
268
+ // Step 2: Audience
269
+ if (payload.aud !== expectedAudience) {
270
+ throw new AttestationError('AUDIENCE_NOT_PERMITTED', 'SESSION', `Expected audience "${expectedAudience}", got "${payload.aud}"`);
271
+ }
272
+ // Step 3: Session time
273
+ const now = Math.floor(Date.now() / 1000);
274
+ if (now > payload.exp + CLOCK_SKEW_SECONDS) {
275
+ throw new AttestationError('EXPIRED', 'SESSION', 'Session has expired');
276
+ }
277
+ if (now < payload.iat - CLOCK_SKEW_SECONDS) {
278
+ throw new AttestationError('NOT_YET_VALID', 'SESSION', 'Session is not yet valid');
279
+ }
280
+ // Step 4: Chain structure
281
+ const isSubSession = payload.hPath !== undefined;
282
+ if (isSubSession) {
283
+ if (!payload.hPath || payload.hPath.length !== 2) {
284
+ throw new AttestationError('PATH_MISMATCH', 'SESSION', 'SubHandle session requires hPath of length 2');
285
+ }
286
+ if (attestationChain.length !== 2) {
287
+ throw new AttestationError('CHAIN_INCOMPLETE', 'FORMAT', 'SubHandle session requires exactly 2 attestations');
288
+ }
289
+ }
290
+ else {
291
+ if (attestationChain.length !== 1) {
292
+ throw new AttestationError('CHAIN_INCOMPLETE', 'FORMAT', 'Handle session requires exactly 1 attestation');
293
+ }
294
+ }
295
+ // Step 5: Decode A
296
+ const A = Attestation.decode(attestationChain[0]);
297
+ // Step 6: Verify A signature against root
298
+ let sigOkA = false;
299
+ try {
300
+ sigOkA = await Attestation.verifySignature(attestationChain[0], rootPublicKey);
301
+ }
302
+ catch {
303
+ sigOkA = false;
304
+ }
305
+ if (!sigOkA) {
306
+ throw new AttestationError('BAD_SIGNATURE', 'ROOT', 'Root attestation signature is invalid');
307
+ }
308
+ // Step 7: A time
309
+ if (now > A.exp + CLOCK_SKEW_SECONDS) {
310
+ throw new AttestationError('EXPIRED', 'ROOT', 'Root attestation has expired');
311
+ }
312
+ if (now < A.iat - CLOCK_SKEW_SECONDS) {
313
+ throw new AttestationError('NOT_YET_VALID', 'ROOT', 'Root attestation is not yet valid');
314
+ }
315
+ // Step 8: A revocation
316
+ if (revocationChecker) {
317
+ const isRevoked = await revocationChecker.isRevoked(A.jti);
318
+ if (isRevoked) {
319
+ throw new AttestationError('REVOKED', 'ROOT', 'Root attestation has been revoked');
320
+ }
321
+ }
322
+ let G;
323
+ let bPayload;
324
+ if (isSubSession) {
325
+ // Step 9: SubHandle chain
326
+ const B = Attestation.decode(attestationChain[1]);
327
+ bPayload = B;
328
+ const signerPubABytes = (() => {
329
+ try {
330
+ return base64urlDecode(A.subjectId);
331
+ }
332
+ catch {
333
+ return null;
334
+ }
335
+ })();
336
+ if (!signerPubABytes) {
337
+ throw new AttestationError('MALFORMED', 'FORMAT', 'Cannot decode root attestation subjectId');
338
+ }
339
+ let sigOkB = false;
340
+ try {
341
+ sigOkB = await Attestation.verifySignature(attestationChain[1], signerPubABytes);
342
+ }
343
+ catch {
344
+ sigOkB = false;
345
+ }
346
+ if (!sigOkB) {
347
+ throw new AttestationError('BAD_SIGNATURE', 'HANDLE_ATTESTATION', 'Handle attestation signature is invalid');
348
+ }
349
+ if (now > B.exp + CLOCK_SKEW_SECONDS) {
350
+ throw new AttestationError('EXPIRED', 'HANDLE_ATTESTATION', 'Handle attestation has expired');
351
+ }
352
+ if (now < B.iat - CLOCK_SKEW_SECONDS) {
353
+ throw new AttestationError('NOT_YET_VALID', 'HANDLE_ATTESTATION', 'Handle attestation is not yet valid');
354
+ }
355
+ if (revocationChecker) {
356
+ const isRevoked = await revocationChecker.isRevoked(B.jti);
357
+ if (isRevoked) {
358
+ throw new AttestationError('REVOKED', 'HANDLE_ATTESTATION', 'Handle attestation has been revoked');
359
+ }
360
+ }
361
+ if (B.subjectName !== payload.hPath[1]) {
362
+ throw new AttestationError('PATH_MISMATCH', 'HANDLE_ATTESTATION', `Handle attestation subject "${B.subjectName}" does not match session subName "${payload.hPath[1]}"`);
363
+ }
364
+ if (A.subjectName !== payload.hPath[0]) {
365
+ throw new AttestationError('PATH_MISMATCH', 'ROOT', `Root attestation subject "${A.subjectName}" does not match session handleName "${payload.hPath[0]}"`);
366
+ }
367
+ if (A.grant.subNamePatterns !== undefined) {
368
+ if (!Attestation.matchNamePattern(B.subjectName, A.grant.subNamePatterns)) {
369
+ throw new AttestationError('NAME_NOT_PERMITTED', 'ROOT', `SubHandle name "${B.subjectName}" not permitted by root patterns`);
370
+ }
371
+ }
372
+ if (payload.hId !== B.subjectId) {
373
+ throw new AttestationError('SUBJECT_MISMATCH', 'SUB_ATTESTATION', 'Session handleId does not match handle attestation subjectId');
374
+ }
375
+ // Nested grant check
376
+ const forbidden = B.grant.scopes.filter(s => !A.grant.scopes.includes(s));
377
+ if (forbidden.length > 0) {
378
+ throw new AttestationError('SCOPE_EXCEEDED', 'ROOT', `Handle attestation scopes not subset of root: ${forbidden.join(', ')}`);
379
+ }
380
+ if (B.grant.maxSessionTtl > A.grant.maxSessionTtl) {
381
+ throw new AttestationError('TTL_EXCEEDED', 'ROOT', 'Handle attestation maxSessionTtl exceeds root attestation');
382
+ }
383
+ G = B.grant;
384
+ }
385
+ else {
386
+ // Handle session
387
+ const subjectIdBytes = (() => {
388
+ try {
389
+ return base64urlDecode(A.subjectId);
390
+ }
391
+ catch {
392
+ return null;
393
+ }
394
+ })();
395
+ if (!subjectIdBytes) {
396
+ throw new AttestationError('MALFORMED', 'FORMAT', 'Cannot decode root attestation subjectId');
397
+ }
398
+ if (payload.hId !== A.subjectId) {
399
+ throw new AttestationError('SUBJECT_MISMATCH', 'ROOT', 'Session handleId does not match root attestation subjectId');
400
+ }
401
+ G = A.grant;
402
+ }
403
+ // Step 10: Session vs grant G
404
+ const sessionForbidden = payload.scp.filter(s => !G.scopes.includes(s));
405
+ if (sessionForbidden.length > 0) {
406
+ throw new AttestationError('SCOPE_EXCEEDED', 'SESSION', `Session scopes not permitted by grant: ${sessionForbidden.join(', ')}`);
407
+ }
408
+ if (G.audiences !== undefined && !G.audiences.includes(payload.aud)) {
409
+ throw new AttestationError('AUDIENCE_NOT_PERMITTED', 'SESSION', `Session audience "${payload.aud}" not in grant audiences`);
410
+ }
411
+ if ((payload.exp - payload.iat) > G.maxSessionTtl) {
412
+ throw new AttestationError('TTL_EXCEEDED', 'SESSION', `Session duration ${payload.exp - payload.iat}s exceeds grant maxSessionTtl ${G.maxSessionTtl}s`);
413
+ }
414
+ // Step 11: Session does not outlive attestation
415
+ const earliestAttestationExp = isSubSession
416
+ ? Math.min(A.exp, bPayload.exp)
417
+ : A.exp;
418
+ if (payload.exp > earliestAttestationExp + CLOCK_SKEW_SECONDS) {
419
+ throw new AttestationError('SESSION_OUTLIVES_ATTESTATION', 'SESSION', 'Session expires after the earliest attestation');
420
+ }
421
+ // Step 12: Session signature
422
+ const sessionPub = (() => {
423
+ try {
424
+ return base64urlDecode(payload.hId);
425
+ }
426
+ catch {
427
+ return null;
428
+ }
429
+ })();
430
+ if (!sessionPub) {
431
+ throw new AttestationError('BAD_SIGNATURE', 'SESSION', 'Cannot decode session hId');
432
+ }
433
+ let sigOk = false;
434
+ try {
435
+ sigOk = await Handle.verify(signatureBytes, payloadBytes, sessionPub);
436
+ }
437
+ catch {
438
+ sigOk = false;
439
+ }
440
+ if (!sigOk) {
441
+ throw new AttestationError('BAD_SIGNATURE', 'SESSION', 'Session signature is invalid');
442
+ }
443
+ // Step 13: Session revocation
444
+ if (revocationChecker) {
445
+ const isRevoked = await revocationChecker.isRevoked(payload.jti);
446
+ if (isRevoked) {
447
+ throw new AttestationError('REVOKED', 'SESSION', 'Session has been revoked');
448
+ }
449
+ }
450
+ // Step 14
451
+ return new Session(payload.hId, payload.hNm, payload.aud, payload.scp, payload.exp, token, payload.hPath, payload.jti);
452
+ }
36
453
  }
37
454
  //# sourceMappingURL=session.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH,MAAM,OAAO,OAAO;IAWA;IACA;IACA;IACA;IAZhB;;;;;;;KAOC;IACH,YACkB,QAAgB,EAChB,MAAgB,EAChB,SAAiB,EACjB,KAAa;QAHb,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAU;QAChB,cAAS,GAAT,SAAS,CAAQ;QACjB,UAAK,GAAL,KAAK,CAAQ;IAC5B,CAAC;IAEJ;;;OAGG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IAC7C,CAAC;CACF"}
1
+ {"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,126 @@
1
+ import { Handle, type HandleMetadata } from './handle.js';
2
+ /**
3
+ * Metadata for a {@link SubHandle}, extending {@link HandleMetadata} with
4
+ * constraints that govern session creation.
5
+ *
6
+ * All constraint fields are optional. When present, they are enforced by
7
+ * {@link SubHandle.validateSessionOptions} at session creation time.
8
+ *
9
+ * @category Types
10
+ */
11
+ export interface SubHandleMetadata extends HandleMetadata {
12
+ /**
13
+ * Restricts the set of audiences this SubHandle may create sessions for.
14
+ * `undefined` = unrestricted; `[]` = deny all.
15
+ */
16
+ allowedAudiences?: string[];
17
+ /**
18
+ * Restricts the set of scopes this SubHandle may request in sessions.
19
+ * `undefined` = unrestricted; `[]` = deny all.
20
+ */
21
+ allowedScopes?: string[];
22
+ /**
23
+ * Maximum allowed TTL (in seconds) for sessions created by this SubHandle.
24
+ * Attempts to create a session with a larger TTL will be rejected.
25
+ */
26
+ maxSessionTtl?: number;
27
+ /**
28
+ * Unix timestamp (in seconds) at which this SubHandle itself expires.
29
+ * After this time, any attempt to create a session will fail.
30
+ * Useful for temporary access grants (e.g., contractor access for 2 weeks).
31
+ */
32
+ expiresAt?: number;
33
+ }
34
+ /**
35
+ * Represents a context-isolated child Handle in the Me2em hierarchy.
36
+ *
37
+ * A SubHandle is always derived from a parent {@link Handle} and represents
38
+ * a leaf node in the derivation tree (MAX_DEPTH = 2). It inherits all
39
+ * cryptographic capabilities of Handle (signing, key derivation, etc.) but
40
+ * adds:
41
+ *
42
+ * - A **derivation path** (`[handleName, subName]`) carried in session tokens.
43
+ * - **Constraint enforcement** on audience, scopes, and TTL at session creation.
44
+ * - An optional **expiration timestamp** for temporary access grants.
45
+ *
46
+ * SubHandle is used for polymorphism in {@link Session}: both Handle and
47
+ * SubHandle can create and verify sessions, but SubHandle sessions carry
48
+ * the additional `hPath` field for hierarchical auditing.
49
+ *
50
+ * @category Core Primitives
51
+ */
52
+ export declare class SubHandle extends Handle {
53
+ private readonly _path;
54
+ private readonly _subMetadata;
55
+ /**
56
+ * Creates a new SubHandle instance.
57
+ *
58
+ * @internal Typically created via {@link Handle.deriveSubHandle} or
59
+ * {@link Identity.deriveSubHandle}. Direct construction is discouraged.
60
+ *
61
+ * @param privateKey - The 32-byte Ed25519 private key for this SubHandle.
62
+ * @param name - The SubHandle name.
63
+ * @param path - The derivation path, must have exactly 2 elements: `[handleName, subName]`.
64
+ * @param subMetadata - Optional constraints and metadata.
65
+ * @throws {Error} If the path does not have exactly 2 elements.
66
+ */
67
+ constructor(privateKey: Uint8Array, name: string, path: string[], subMetadata?: SubHandleMetadata);
68
+ /**
69
+ * Returns the full derivation path of this SubHandle.
70
+ *
71
+ * @returns A copy of the path array, e.g. `["station-001", "connector-1"]`.
72
+ */
73
+ getPath(): string[];
74
+ /**
75
+ * Returns the derivation path as a slash-separated string.
76
+ *
77
+ * @returns The path string, e.g. `"station-001/connector-1"`.
78
+ */
79
+ getPathString(): string;
80
+ /**
81
+ * Returns the depth of this SubHandle in the derivation hierarchy.
82
+ *
83
+ * With MAX_DEPTH = 2, this is always `2` (Identity = 0, Handle = 1, SubHandle = 2).
84
+ *
85
+ * @returns The depth, always `2`.
86
+ */
87
+ getDepth(): number;
88
+ /**
89
+ * Returns whether this SubHandle is a leaf node.
90
+ *
91
+ * With MAX_DEPTH = 2, a SubHandle is **always** a leaf and cannot derive children.
92
+ *
93
+ * @returns Always `true`.
94
+ */
95
+ isLeaf(): boolean;
96
+ /**
97
+ * SubHandle is a leaf node (depth = 2) and cannot derive children.
98
+ * Overrides the inherited `Handle.deriveSubHandle` to throw an error.
99
+ */
100
+ deriveSubHandle(): Promise<never>;
101
+ /**
102
+ * Returns the SubHandle-specific metadata (constraints).
103
+ *
104
+ * @returns The SubHandleMetadata object.
105
+ */
106
+ getSubMetadata(): SubHandleMetadata;
107
+ /**
108
+ * Validates session options against this SubHandle's constraints.
109
+ *
110
+ * Called internally by {@link Session.create} before signing. Throws if
111
+ * any constraint is violated:
112
+ * - `audience` not in `allowedAudiences`
113
+ * - any `scope` not in `allowedScopes`
114
+ * - `ttl` exceeds `maxSessionTtl`
115
+ * - current time is past `expiresAt`
116
+ *
117
+ * @param options - The session options to validate.
118
+ * @throws {Error} If any constraint is violated.
119
+ */
120
+ validateSessionOptions(options: {
121
+ audience: string;
122
+ scopes: string[];
123
+ ttl: number;
124
+ }): void;
125
+ }
126
+ //# sourceMappingURL=subhandle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"subhandle.d.ts","sourceRoot":"","sources":["../src/subhandle.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAG1D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD;;;QAGI;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE5B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0BD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAU,SAAQ,MAAM;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IAEjD;;;;;;;;;;;OAWG;gBAED,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,CAAC,EAAE,iBAAiB;IAmBjC;;;;OAIG;IACH,OAAO,IAAI,MAAM,EAAE;IAInB;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;OAMG;IACH,MAAM,IAAI,OAAO;IAIjB;;;OAGG;IACY,eAAe,IAAI,OAAO,CAAC,KAAK,CAAC;IAIhD;;;;OAIG;IACH,cAAc,IAAI,iBAAiB;IAYnC;;;;;;;;;;;;OAYG;IACH,sBAAsB,CAAC,OAAO,EAAE;QAC9B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;KACb,GAAG,IAAI;CA6CT"}