hpke 1.1.2 → 1.1.4

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/index.ts CHANGED
@@ -5,7 +5,7 @@
5
5
  * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
6
6
  * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
7
7
  * being republished as a Standards Track document of the IETF as
8
- * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03).
8
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
9
9
  *
10
10
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
11
11
  * public key.
@@ -42,11 +42,11 @@
42
42
  // HPKE Context Classes - Sender and Recipient Contexts
43
43
  // ============================================================================
44
44
 
45
- /** @see [ComputeNonce](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2) */
45
+ /** @see [ComputeNonce](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2) */
46
46
  function ComputeNonce(base_nonce: Uint8Array, seq: number, Nn: number): Uint8Array {
47
47
  // Equivalent to xor(base_nonce, I2OSP(seq, Nn)) but avoids allocating the
48
48
  // intermediate seq_bytes array and fuses the two byte-wise passes into one.
49
- // seq is a safe integer (≥0, ≤2^53-1) guaranteed by IncrementSeq.
49
+ // seq stays exact because IncrementSeq caps it at Number.MAX_SAFE_INTEGER.
50
50
  const nonce = new Uint8Array(Nn)
51
51
  nonce.set(base_nonce)
52
52
  let s = seq
@@ -57,18 +57,21 @@ function ComputeNonce(base_nonce: Uint8Array, seq: number, Nn: number): Uint8Arr
57
57
  return nonce
58
58
  }
59
59
 
60
- /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2) */
61
- function IncrementSeq(seq: number): number {
62
- // seq is guaranteed to be a safe integer due to:
63
- // 1. Initial value is 0
64
- // 2. This function throws at MAX_SAFE_INTEGER
65
- if (seq >= Number.MAX_SAFE_INTEGER) {
60
+ function MaxSeq(Nn: number): number {
61
+ // HPKE limits seq to the largest integer encodable in Nn bytes. This
62
+ // implementation stores seq as a JS number, so it uses the stricter limit.
63
+ return Math.min(2 ** (8 * Nn) - 1, Number.MAX_SAFE_INTEGER)
64
+ }
65
+
66
+ /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2) */
67
+ function IncrementSeq(seq: number, maxSeq: number): number {
68
+ if (seq >= maxSeq) {
66
69
  throw new MessageLimitReachedError('Sequence number overflow')
67
70
  }
68
71
  return ++seq
69
72
  }
70
73
 
71
- /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3) */
74
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
72
75
  async function ContextExport(
73
76
  suite: Triple,
74
77
  exporterSecret: Uint8Array,
@@ -126,13 +129,14 @@ class SenderContext {
126
129
  #key: Uint8Array
127
130
  #base_nonce: Uint8Array
128
131
  #exporter_secret: Uint8Array
129
- #mode: typeof MODE_BASE | typeof MODE_PSK
132
+ #mode: Mode
130
133
  #seq: number = 0
134
+ #max_seq: number
131
135
  #mutex?: Mutex
132
136
 
133
137
  constructor(
134
138
  suite: Triple,
135
- mode: typeof MODE_BASE | typeof MODE_PSK,
139
+ mode: Mode,
136
140
  key: Uint8Array,
137
141
  base_nonce: Uint8Array,
138
142
  exporter_secret: Uint8Array,
@@ -142,6 +146,7 @@ class SenderContext {
142
146
  this.#key = key
143
147
  this.#base_nonce = base_nonce
144
148
  this.#exporter_secret = exporter_secret
149
+ this.#max_seq = MaxSeq(suite.AEAD.Nn)
145
150
  }
146
151
 
147
152
  /**
@@ -149,14 +154,15 @@ class SenderContext {
149
154
  * @see {@link MODE_BASE}
150
155
  * @see {@link MODE_PSK}
151
156
  */
152
- get mode(): number {
157
+ get mode(): Mode {
153
158
  return this.#mode
154
159
  }
155
160
 
156
161
  /**
157
162
  * @returns The sequence number for this context's next {@link Seal}, initially zero, increments
158
163
  * automatically with each successful {@link Seal}. The sequence number provides AEAD nonce
159
- * uniqueness. The maximum supported sequence number in this implementation is `2^53-1`.
164
+ * uniqueness. The maximum supported sequence number is the lower of the AEAD nonce-size limit
165
+ * and `2^53-1`.
160
166
  */
161
167
  get seq(): number {
162
168
  return this.#seq
@@ -186,7 +192,7 @@ class SenderContext {
186
192
  *
187
193
  * @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
188
194
  * than the plaintext.
189
- * @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2)
195
+ * @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
190
196
  */
191
197
  async Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
192
198
  checkUint8Array(plaintext, 'plaintext')
@@ -206,7 +212,7 @@ class SenderContext {
206
212
  aad,
207
213
  plaintext,
208
214
  )
209
- this.#seq = IncrementSeq(this.#seq)
215
+ this.#seq = IncrementSeq(this.#seq, this.#max_seq)
210
216
  return ct
211
217
  } finally {
212
218
  release()
@@ -234,7 +240,7 @@ class SenderContext {
234
240
  * @param length - Desired length of exported secret in bytes
235
241
  *
236
242
  * @returns A Promise that resolves to the exported secret.
237
- * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3)
243
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
238
244
  */
239
245
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
240
246
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -274,13 +280,14 @@ class RecipientContext {
274
280
  #key: Uint8Array
275
281
  #base_nonce: Uint8Array
276
282
  #exporter_secret: Uint8Array
277
- #mode: typeof MODE_BASE | typeof MODE_PSK
283
+ #mode: Mode
278
284
  #seq: number = 0
285
+ #max_seq: number
279
286
  #mutex?: Mutex
280
287
 
281
288
  constructor(
282
289
  suite: Triple,
283
- mode: typeof MODE_BASE | typeof MODE_PSK,
290
+ mode: Mode,
284
291
  key: Uint8Array,
285
292
  base_nonce: Uint8Array,
286
293
  exporter_secret: Uint8Array,
@@ -290,6 +297,7 @@ class RecipientContext {
290
297
  this.#key = key
291
298
  this.#base_nonce = base_nonce
292
299
  this.#exporter_secret = exporter_secret
300
+ this.#max_seq = MaxSeq(suite.AEAD.Nn)
293
301
  }
294
302
 
295
303
  /**
@@ -297,14 +305,15 @@ class RecipientContext {
297
305
  * @see {@link MODE_BASE}
298
306
  * @see {@link MODE_PSK}
299
307
  */
300
- get mode(): number {
308
+ get mode(): Mode {
301
309
  return this.#mode
302
310
  }
303
311
 
304
312
  /**
305
313
  * @returns The sequence number for this context's next {@link Open}, initially zero, increments
306
314
  * automatically with each successful {@link Open}. The sequence number provides AEAD nonce
307
- * uniqueness. The maximum supported sequence number in this implementation is `2^53-1`.
315
+ * uniqueness. The maximum supported sequence number is the lower of the AEAD nonce-size limit
316
+ * and `2^53-1`.
308
317
  */
309
318
  get seq(): number {
310
319
  return this.#seq
@@ -335,7 +344,7 @@ class RecipientContext {
335
344
  * @param aad - Additional authenticated data
336
345
  *
337
346
  * @returns A Promise that resolves to the decrypted plaintext.
338
- * @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2)
347
+ * @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
339
348
  */
340
349
  async Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
341
350
  checkUint8Array(ciphertext, 'ciphertext')
@@ -364,7 +373,7 @@ class RecipientContext {
364
373
 
365
374
  throw new OpenError('AEAD decryption failed', { cause })
366
375
  }
367
- this.#seq = IncrementSeq(this.#seq)
376
+ this.#seq = IncrementSeq(this.#seq, this.#max_seq)
368
377
  return pt
369
378
  } finally {
370
379
  release()
@@ -392,7 +401,7 @@ class RecipientContext {
392
401
  * @param length - Desired length of exported secret in bytes
393
402
  *
394
403
  * @returns A Promise that resolves to the exported secret.
395
- * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3)
404
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
396
405
  */
397
406
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
398
407
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -423,7 +432,7 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
423
432
  * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
424
433
  * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
425
434
  * being republished as a Standards Track document of the IETF as
426
- * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03).
435
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
427
436
  *
428
437
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
429
438
  * public key. It supports two modes:
@@ -437,10 +446,11 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
437
446
  * - KDF: Key Derivation Function for deriving symmetric keys
438
447
  * - AEAD: Authenticated Encryption with Additional Data for encryption
439
448
  *
449
+ * @typeParam K - Key representation produced and consumed by the suite's KEM
440
450
  * @group Core
441
451
  */
442
- export class CipherSuite {
443
- #suite: Triple
452
+ export class CipherSuite<K extends Key = Key> {
453
+ #suite: Triple<K>
444
454
 
445
455
  /**
446
456
  * Creates a new HPKE cipher suite by combining a Key Encapsulation Mechanism (KEM), Key
@@ -503,7 +513,7 @@ export class CipherSuite {
503
513
  * @see {@link KDFFactory Available KDFs}
504
514
  * @see {@link AEADFactory Available AEADs}
505
515
  */
506
- constructor(KEM: KEMFactory, KDF: KDFFactory, AEAD: AEADFactory) {
516
+ constructor(KEM: KEMFactory<K>, KDF: KDFFactory, AEAD: AEADFactory) {
507
517
  const kem = validate(KEM, 'KEM')
508
518
  const kdf = validate(KDF, 'KDF')
509
519
  const aead = validate(AEAD, 'AEAD')
@@ -523,17 +533,17 @@ export class CipherSuite {
523
533
  */
524
534
  get KEM(): {
525
535
  /** The identifier of this suite's KEM */
526
- id: number
536
+ readonly id: number
527
537
  /** The name of this suite's KEM */
528
- name: string
538
+ readonly name: string
529
539
  /** The length in bytes of this suite's KEM produced shared secret */
530
- Nsecret: number
540
+ readonly Nsecret: number
531
541
  /** The length in bytes of this suite's KEM produced encapsulated secret */
532
- Nenc: number
542
+ readonly Nenc: number
533
543
  /** The length in bytes of this suite's KEM public key */
534
- Npk: number
544
+ readonly Npk: number
535
545
  /** The length in bytes of this suite's KEM private key */
536
- Nsk: number
546
+ readonly Nsk: number
537
547
  } {
538
548
  return {
539
549
  id: this.#suite.KEM.id,
@@ -552,21 +562,21 @@ export class CipherSuite {
552
562
  */
553
563
  get KDF(): {
554
564
  /** The identifier of this suite's KDF */
555
- id: number
565
+ readonly id: number
556
566
  /** The name of this suite's KDF */
557
- name: string
567
+ readonly name: string
558
568
  /**
559
569
  * When 1, this suite's KDF is a one-stage (Derive) KDF.
560
570
  *
561
571
  * When 2, this suite's KDF is a two-stage (Extract and Expand) KDF.
562
572
  */
563
- stages: 1 | 2
573
+ readonly stages: 1 | 2
564
574
  /**
565
575
  * For one-stage KDF: The security strength of this suite's KDF, in bytes.
566
576
  *
567
577
  * For two-stage KDF: The output size of this suite's KDF Extract() function in bytes.
568
578
  */
569
- Nh: number
579
+ readonly Nh: number
570
580
  } {
571
581
  return {
572
582
  id: this.#suite.KDF.id,
@@ -584,15 +594,15 @@ export class CipherSuite {
584
594
  */
585
595
  get AEAD(): {
586
596
  /** The identifier of this suite's AEAD */
587
- id: number
597
+ readonly id: number
588
598
  /** The name of this suite's AEAD */
589
- name: string
599
+ readonly name: string
590
600
  /** The length in bytes of a key for this suite's AEAD */
591
- Nk: number
601
+ readonly Nk: number
592
602
  /** The length in bytes of a nonce for this suite's AEAD */
593
- Nn: number
603
+ readonly Nn: number
594
604
  /** The length in bytes of an authentication tag for this suite's AEAD */
595
- Nt: number
605
+ readonly Nt: number
596
606
  } {
597
607
  return {
598
608
  id: this.#suite.AEAD.id,
@@ -620,7 +630,7 @@ export class CipherSuite {
620
630
  *
621
631
  * @returns A Promise that resolves to a generated key pair.
622
632
  */
623
- async GenerateKeyPair(extractable?: boolean): Promise<KeyPair> {
633
+ async GenerateKeyPair(extractable?: boolean): Promise<KeyPair<K>> {
624
634
  extractable ??= false
625
635
  checkExtractable(extractable)
626
636
  return await this.#suite.KEM.GenerateKeyPair(extractable)
@@ -653,7 +663,7 @@ export class CipherSuite {
653
663
  *
654
664
  * @returns A Promise that resolves to the derived key pair.
655
665
  */
656
- async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair> {
666
+ async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair<K>> {
657
667
  extractable ??= false
658
668
  checkExtractable(extractable)
659
669
  checkUint8Array(ikm, 'ikm')
@@ -686,7 +696,7 @@ export class CipherSuite {
686
696
  *
687
697
  * @returns A Promise that resolves to the serialized private key.
688
698
  */
689
- async SerializePrivateKey(privateKey: Key): Promise<Uint8Array> {
699
+ async SerializePrivateKey(privateKey: K): Promise<Uint8Array> {
690
700
  isKey(privateKey, 'private', true)
691
701
 
692
702
  return await this.#suite.KEM.SerializePrivateKey(privateKey)
@@ -708,7 +718,7 @@ export class CipherSuite {
708
718
  *
709
719
  * @returns A Promise that resolves to the serialized public key.
710
720
  */
711
- async SerializePublicKey(publicKey: Key): Promise<Uint8Array> {
721
+ async SerializePublicKey(publicKey: K): Promise<Uint8Array> {
712
722
  isKey(publicKey, 'public', true)
713
723
 
714
724
  return await this.#suite.KEM.SerializePublicKey(publicKey)
@@ -733,7 +743,7 @@ export class CipherSuite {
733
743
  *
734
744
  * @returns A Promise that resolves to the deserialized private key.
735
745
  */
736
- async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<Key> {
746
+ async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<K> {
737
747
  extractable ??= false
738
748
  checkExtractable(extractable)
739
749
  checkUint8Array(privateKey, 'privateKey')
@@ -768,7 +778,7 @@ export class CipherSuite {
768
778
  *
769
779
  * @returns A Promise that resolves to the deserialized public key.
770
780
  */
771
- async DeserializePublicKey(publicKey: Uint8Array): Promise<Key> {
781
+ async DeserializePublicKey(publicKey: Uint8Array): Promise<K> {
772
782
  checkUint8Array(publicKey, 'publicKey')
773
783
 
774
784
  try {
@@ -816,10 +826,10 @@ export class CipherSuite {
816
826
  * @returns A Promise that resolves to an object containing the encapsulated secret and
817
827
  * ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
818
828
  * encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
819
- * @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.1)
829
+ * @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
820
830
  */
821
831
  async Seal(
822
- publicKey: Key,
832
+ publicKey: K,
823
833
  plaintext: Uint8Array,
824
834
  options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
825
835
  ): Promise<{ encapsulatedSecret: Uint8Array; ciphertext: Uint8Array }> {
@@ -865,10 +875,10 @@ export class CipherSuite {
865
875
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
866
876
  *
867
877
  * @returns A Promise that resolves to the decrypted plaintext.
868
- * @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.1)
878
+ * @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
869
879
  */
870
880
  async Open(
871
- privateKey: Key | KeyPair,
881
+ privateKey: K | KeyPair<K>,
872
882
  encapsulatedSecret: Uint8Array,
873
883
  ciphertext: Uint8Array,
874
884
  options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
@@ -913,10 +923,10 @@ export class CipherSuite {
913
923
  *
914
924
  * @returns A Promise that resolves to an object containing the encapsulated secret and the
915
925
  * exported secret.
916
- * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.2)
926
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
917
927
  */
918
928
  async SendExport(
919
- publicKey: Key,
929
+ publicKey: K,
920
930
  exporterContext: Uint8Array,
921
931
  length: number,
922
932
  options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
@@ -961,10 +971,10 @@ export class CipherSuite {
961
971
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
962
972
  *
963
973
  * @returns A Promise that resolves to the exported secret.
964
- * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.2)
974
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
965
975
  */
966
976
  async ReceiveExport(
967
- privateKey: Key | KeyPair,
977
+ privateKey: K | KeyPair<K>,
968
978
  encapsulatedSecret: Uint8Array,
969
979
  exporterContext: Uint8Array,
970
980
  length: number,
@@ -1015,10 +1025,10 @@ export class CipherSuite {
1015
1025
  *
1016
1026
  * @returns A Promise that resolves to an object containing the encapsulated secret and the sender
1017
1027
  * context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
1018
- * @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1.1)
1028
+ * @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
1019
1029
  */
1020
1030
  async SetupSender(
1021
- publicKey: Key,
1031
+ publicKey: K,
1022
1032
  options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
1023
1033
  ): Promise<{ encapsulatedSecret: Uint8Array; ctx: SenderContext }> {
1024
1034
  isKey(publicKey, 'public')
@@ -1096,10 +1106,10 @@ export class CipherSuite {
1096
1106
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
1097
1107
  *
1098
1108
  * @returns A Promise that resolves to the recipient context.
1099
- * @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1.1)
1109
+ * @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
1100
1110
  */
1101
1111
  async SetupRecipient(
1102
- privateKey: Key | KeyPair,
1112
+ privateKey: K | KeyPair<K>,
1103
1113
  encapsulatedSecret: Uint8Array,
1104
1114
  options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
1105
1115
  ): Promise<RecipientContext> {
@@ -1132,7 +1142,7 @@ export class CipherSuite {
1132
1142
  return new RecipientContext(this.#suite, mode, key, base_nonce, exporter_secret)
1133
1143
  }
1134
1144
 
1135
- #extractRecipientKeys(skR: Key | KeyPair): { skR: Key; pkR: Key | undefined } {
1145
+ #extractRecipientKeys(skR: K | KeyPair<K>): { skR: K; pkR: K | undefined } {
1136
1146
  if (isKeyPair(skR)) {
1137
1147
  return { skR: skR.privateKey, pkR: skR.publicKey }
1138
1148
  }
@@ -1270,9 +1280,9 @@ export class NotSupportedError extends Error {
1270
1280
  // Type Definitions and Interfaces
1271
1281
  // ============================================================================
1272
1282
 
1273
- interface Triple {
1283
+ interface Triple<K extends Key = Key> {
1274
1284
  readonly id: Uint8Array
1275
- readonly KEM: Readonly<KEM>
1285
+ readonly KEM: Readonly<KEM<K>>
1276
1286
  readonly KDF: Readonly<KDF>
1277
1287
  readonly AEAD: Readonly<AEAD>
1278
1288
  }
@@ -1283,7 +1293,7 @@ interface Triple {
1283
1293
  * Base mode provides encryption to a public key without sender authentication. The recipient cannot
1284
1294
  * verify who encrypted the message, only that someone with access to their public key did.
1285
1295
  *
1286
- * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5)
1296
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
1287
1297
  */
1288
1298
  export const MODE_BASE = 0x00
1289
1299
 
@@ -1294,10 +1304,13 @@ export const MODE_BASE = 0x00
1294
1304
  * sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
1295
1305
  * authentication.
1296
1306
  *
1297
- * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5)
1307
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
1298
1308
  */
1299
1309
  export const MODE_PSK = 0x01
1300
1310
 
1311
+ /** Mode supported by this implementation. */
1312
+ export type Mode = typeof MODE_BASE | typeof MODE_PSK
1313
+
1301
1314
  /**
1302
1315
  * Factory function that returns a KEM implementation.
1303
1316
  *
@@ -1329,8 +1342,10 @@ export const MODE_PSK = 0x01
1329
1342
  * > returning an object conforming to the {@link KEM} interface can be used. Such implementations not
1330
1343
  * > reliant on Web Cryptography are exported by
1331
1344
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1345
+ *
1346
+ * @typeParam K - Key representation produced and consumed by the KEM
1332
1347
  */
1333
- export type KEMFactory = () => Readonly<KEM>
1348
+ export type KEMFactory<K extends Key = Key> = () => Readonly<KEM<K>>
1334
1349
 
1335
1350
  /**
1336
1351
  * Factory function that returns a KDF implementation.
@@ -1387,12 +1402,14 @@ export type AEADFactory = () => Readonly<AEAD>
1387
1402
  * - Private Key: Used by recipients for decryption operations (passed to
1388
1403
  * {@link CipherSuite.SetupRecipient} or {@link CipherSuite.Open}). These are not distributed and
1389
1404
  * kept private.
1405
+ *
1406
+ * @typeParam K - Key representation contained in the pair
1390
1407
  */
1391
- export interface KeyPair {
1408
+ export interface KeyPair<K extends Key = Key> {
1392
1409
  /** The public key, used for encryption operations. */
1393
- readonly publicKey: Readonly<Key>
1410
+ readonly publicKey: Readonly<K>
1394
1411
  /** The private key, used for decryption operations. */
1395
- readonly privateKey: Readonly<Key>
1412
+ readonly privateKey: Readonly<K>
1396
1413
  }
1397
1414
 
1398
1415
  /**
@@ -1419,6 +1436,34 @@ export interface Key {
1419
1436
  readonly type: 'private' | 'public' | (string & {})
1420
1437
  }
1421
1438
 
1439
+ /**
1440
+ * A Web Cryptography key as declared by the host runtime.
1441
+ *
1442
+ * This aliases the key type returned by the host's `SubtleCrypto.generateKey()` API when it is
1443
+ * exposed on `globalThis`. A structural fallback is used otherwise, keeping the package portable to
1444
+ * runtimes and TypeScript projects that do not include DOM or Node.js ambient types.
1445
+ */
1446
+ export type CryptoKey = typeof globalThis extends {
1447
+ crypto: { subtle: { generateKey(...args: any[]): Promise<infer R> } }
1448
+ }
1449
+ ? Extract<R, { type: string }>
1450
+ : CryptoKeyStructuralFallback
1451
+
1452
+ /**
1453
+ * Used as {@link CryptoKey} when the host runtime's `crypto` global is not exposed on `typeof
1454
+ * globalThis`, including when it is absent from ambient types or declared with `const` or `let`. It
1455
+ * remains structurally compatible with host {@link !CryptoKey} declarations so values flow freely to
1456
+ * and from {@link !SubtleCrypto} APIs.
1457
+ *
1458
+ * @internal
1459
+ */
1460
+ interface CryptoKeyStructuralFallback {
1461
+ readonly algorithm: { name: string }
1462
+ readonly extractable: boolean
1463
+ readonly type: string
1464
+ readonly usages: string[]
1465
+ }
1466
+
1422
1467
  // ============================================================================
1423
1468
  // Utility Functions
1424
1469
  // ============================================================================
@@ -1516,7 +1561,7 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
1516
1561
  * ensures domain separation between different uses of the KDF in HPKE.
1517
1562
  *
1518
1563
  * @group Utilities
1519
- * @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
1564
+ * @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
1520
1565
  */
1521
1566
  export async function LabeledDerive(
1522
1567
  KDF: Pick<KDF, 'Derive'>,
@@ -1530,7 +1575,7 @@ export async function LabeledDerive(
1530
1575
  return await KDF.Derive(labeled_ikm, L)
1531
1576
  }
1532
1577
 
1533
- /** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5) */
1578
+ /** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
1534
1579
  async function Export_OneStage(
1535
1580
  KDF: KDF,
1536
1581
  suite_id: Uint8Array,
@@ -1542,7 +1587,7 @@ async function Export_OneStage(
1542
1587
  return await LabeledDerive(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
1543
1588
  }
1544
1589
 
1545
- /** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5) */
1590
+ /** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
1546
1591
  async function CombineSecrets_OneStage(
1547
1592
  suite: Triple,
1548
1593
  mode: number,
@@ -1599,7 +1644,7 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
1599
1644
  }
1600
1645
  }
1601
1646
 
1602
- /** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
1647
+ /** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
1603
1648
  async function CombineSecrets_TwoStage(
1604
1649
  suite: Triple,
1605
1650
  mode: number,
@@ -1642,7 +1687,7 @@ async function CombineSecrets_TwoStage(
1642
1687
  return { key, base_nonce, exporter_secret }
1643
1688
  }
1644
1689
 
1645
- /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3) */
1690
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
1646
1691
  async function Export_TwoStage(
1647
1692
  KDF: KDF,
1648
1693
  suite_id: Uint8Array,
@@ -1719,7 +1764,7 @@ async function Export_TwoStage(
1719
1764
  * )
1720
1765
  * ```
1721
1766
  *
1722
- * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.2)
1767
+ * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.2)
1723
1768
  */
1724
1769
  export interface KDF {
1725
1770
  /** KDF algorithm identifier */
@@ -1792,7 +1837,7 @@ export interface KDF {
1792
1837
  * pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
1793
1838
  *
1794
1839
  * @group Utilities
1795
- * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.4)
1840
+ * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
1796
1841
  */
1797
1842
  export async function LabeledExtract(
1798
1843
  KDF: Pick<KDF, 'Extract'>,
@@ -1822,7 +1867,7 @@ export async function LabeledExtract(
1822
1867
  * of the KDF in HPKE.
1823
1868
  *
1824
1869
  * @group Utilities
1825
- * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.4)
1870
+ * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
1826
1871
  */
1827
1872
  export async function LabeledExpand(
1828
1873
  KDF: Pick<KDF, 'Expand'>,
@@ -1931,9 +1976,10 @@ export async function LabeledExpand(
1931
1976
  * )
1932
1977
  * ```
1933
1978
  *
1934
- * @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.1)
1979
+ * @typeParam K - Key representation produced and consumed by the KEM
1980
+ * @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.1)
1935
1981
  */
1936
- export interface KEM {
1982
+ export interface KEM<K extends Key = Key> {
1937
1983
  /** KEM algorithm identifier */
1938
1984
  readonly id: number
1939
1985
 
@@ -1963,7 +2009,7 @@ export interface KEM {
1963
2009
  *
1964
2010
  * @returns A promise resolving to a {@link KeyPair}
1965
2011
  */
1966
- DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair>
2012
+ DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair<K>>
1967
2013
 
1968
2014
  /**
1969
2015
  * Generates a random key pair.
@@ -1972,7 +2018,7 @@ export interface KEM {
1972
2018
  *
1973
2019
  * @returns A promise resolving to a {@link KeyPair}
1974
2020
  */
1975
- GenerateKeyPair(extractable: boolean): Promise<KeyPair>
2021
+ GenerateKeyPair(extractable: boolean): Promise<KeyPair<K>>
1976
2022
 
1977
2023
  /**
1978
2024
  * Serializes a public key to bytes.
@@ -1981,7 +2027,7 @@ export interface KEM {
1981
2027
  *
1982
2028
  * @returns A promise resolving to the serialized public key
1983
2029
  */
1984
- SerializePublicKey(key: Key): Promise<Uint8Array>
2030
+ SerializePublicKey(key: K): Promise<Uint8Array>
1985
2031
 
1986
2032
  /**
1987
2033
  * Deserializes a public key from bytes.
@@ -1990,7 +2036,7 @@ export interface KEM {
1990
2036
  *
1991
2037
  * @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
1992
2038
  */
1993
- DeserializePublicKey(key: Uint8Array): Promise<Key>
2039
+ DeserializePublicKey(key: Uint8Array): Promise<K>
1994
2040
 
1995
2041
  /**
1996
2042
  * Serializes a private key to bytes.
@@ -1999,7 +2045,7 @@ export interface KEM {
1999
2045
  *
2000
2046
  * @returns A promise resolving to the serialized private key
2001
2047
  */
2002
- SerializePrivateKey(key: Key): Promise<Uint8Array>
2048
+ SerializePrivateKey(key: K): Promise<Uint8Array>
2003
2049
 
2004
2050
  /**
2005
2051
  * Deserializes a private key from bytes.
@@ -2009,7 +2055,7 @@ export interface KEM {
2009
2055
  *
2010
2056
  * @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
2011
2057
  */
2012
- DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<Key>
2058
+ DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<K>
2013
2059
 
2014
2060
  /**
2015
2061
  * Encapsulates a shared secret to a recipient's public key.
@@ -2022,7 +2068,7 @@ export interface KEM {
2022
2068
  *
2023
2069
  * @returns A promise resolving to an object containing the shared secret and encapsulated secret
2024
2070
  */
2025
- Encap(pkR: Key): Promise<{ shared_secret: Uint8Array; enc: Uint8Array }>
2071
+ Encap(pkR: K): Promise<{ shared_secret: Uint8Array; enc: Uint8Array }>
2026
2072
 
2027
2073
  /**
2028
2074
  * Decapsulates a shared secret using a recipient's private key.
@@ -2037,10 +2083,10 @@ export interface KEM {
2037
2083
  *
2038
2084
  * @returns A promise resolving to the shared secret
2039
2085
  */
2040
- Decap(enc: Uint8Array, skR: Key, pkR: Key | undefined): Promise<Uint8Array>
2086
+ Decap(enc: Uint8Array, skR: K, pkR: K | undefined): Promise<Uint8Array>
2041
2087
  }
2042
2088
 
2043
- function isKeyPair(skR: unknown): skR is KeyPair {
2089
+ function isKeyPair<K extends Key>(skR: K | KeyPair<K>): skR is KeyPair<K> {
2044
2090
  if (!skR || typeof skR !== 'object') return false
2045
2091
  if ('publicKey' in skR && 'privateKey' in skR) {
2046
2092
  const pkR = skR.publicKey
@@ -2133,7 +2179,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
2133
2179
  * )
2134
2180
  * ```
2135
2181
  *
2136
- * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.3)
2182
+ * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.3)
2137
2183
  */
2138
2184
  export interface AEAD {
2139
2185
  /** AEAD algorithm identifier */
@@ -2157,12 +2203,18 @@ export interface AEAD {
2157
2203
  /**
2158
2204
  * Encrypts and authenticates plaintext with associated data.
2159
2205
  *
2206
+ * Implementations must enforce the AEAD algorithm's per-invocation plaintext length limit (P_MAX)
2207
+ * before encryption. HPKE's explicit error list maps `MessageLimitReachedError` to context
2208
+ * sequence number overflow; it does not prescribe a specific error for P_MAX violations. Report
2209
+ * them as ordinary input range errors, such as `RangeError`.
2210
+ *
2160
2211
  * @param key - The encryption key of {@link Nk} bytes
2161
2212
  * @param nonce - The nonce of {@link Nn} bytes
2162
2213
  * @param aad - Additional authenticated data
2163
2214
  * @param pt - Plaintext to encrypt
2164
2215
  *
2165
2216
  * @returns A promise resolving to the ciphertext with authentication tag appended
2217
+ * @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
2166
2218
  */
2167
2219
  Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>
2168
2220
 
@@ -2223,7 +2275,7 @@ function KDFStages(KDF: KDF): 1 | 2 {
2223
2275
  throw new Error('unreachable')
2224
2276
  }
2225
2277
 
2226
- /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
2278
+ /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
2227
2279
  async function KeySchedule(
2228
2280
  suite: Triple,
2229
2281
  mode: number,
@@ -2246,7 +2298,7 @@ async function KeySchedule(
2246
2298
  return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
2247
2299
  }
2248
2300
 
2249
- /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
2301
+ /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
2250
2302
  function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
2251
2303
  if (psk.byteLength && psk_id.byteLength) {
2252
2304
  if (psk.byteLength < 32) {
@@ -2266,6 +2318,8 @@ const NotApplicable = () => {
2266
2318
  }
2267
2319
 
2268
2320
  const EXPORT_ONLY = 0xffff
2321
+ const AES_GCM_P_MAX = 2 ** 36 - 31
2322
+ const CHACHA20_POLY1305_P_MAX = 2 ** 38 - 64
2269
2323
  /**
2270
2324
  * Export-only AEAD mode.
2271
2325
  *
@@ -2276,7 +2330,7 @@ const EXPORT_ONLY = 0xffff
2276
2330
  * This is a factory function that must be passed to the {@link CipherSuite} constructor.
2277
2331
  *
2278
2332
  * @group AEAD Algorithms
2279
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
2333
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
2280
2334
  */
2281
2335
  export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
2282
2336
  return {
@@ -2402,7 +2456,7 @@ function HKDF_SHARED(): KDF_BASE {
2402
2456
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2403
2457
  *
2404
2458
  * @group KDF Algorithms
2405
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2459
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2406
2460
  */
2407
2461
  export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2408
2462
  return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
@@ -2425,7 +2479,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2425
2479
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2426
2480
  *
2427
2481
  * @group KDF Algorithms
2428
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2482
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2429
2483
  */
2430
2484
  export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2431
2485
  return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
@@ -2448,7 +2502,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2448
2502
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2449
2503
  *
2450
2504
  * @group KDF Algorithms
2451
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2505
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2452
2506
  */
2453
2507
  export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
2454
2508
  return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
@@ -2496,7 +2550,7 @@ function SHAKE_SHARED(): KDF_BASE {
2496
2550
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2497
2551
  *
2498
2552
  * @group KDF Algorithms
2499
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2553
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2500
2554
  */
2501
2555
  export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2502
2556
  return {
@@ -2526,7 +2580,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2526
2580
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2527
2581
  *
2528
2582
  * @group KDF Algorithms
2529
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2583
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2530
2584
  */
2531
2585
  export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2532
2586
  return {
@@ -2556,7 +2610,7 @@ export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2556
2610
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2557
2611
  *
2558
2612
  * @group KDF Algorithms
2559
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2613
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2560
2614
  */
2561
2615
  export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2562
2616
  return {
@@ -2586,7 +2640,7 @@ export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2586
2640
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2587
2641
  *
2588
2642
  * @group KDF Algorithms
2589
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2643
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2590
2644
  */
2591
2645
  export const KDF_TurboSHAKE256: KDFFactory = function (): SHAKE {
2592
2646
  return {
@@ -2641,8 +2695,8 @@ function checkNotAllZeros(buffer: Uint8Array): void {
2641
2695
  }
2642
2696
  }
2643
2697
 
2644
- type KEM_BASE = Pick<
2645
- KEM,
2698
+ type KEM_BASE<K extends Key = Key> = Pick<
2699
+ KEM<K>,
2646
2700
  | 'GenerateKeyPair'
2647
2701
  | 'DeriveKeyPair'
2648
2702
  | 'SerializePublicKey'
@@ -2653,7 +2707,7 @@ type KEM_BASE = Pick<
2653
2707
  | 'Decap'
2654
2708
  >
2655
2709
 
2656
- interface DHKEM extends KEM {
2710
+ interface DHKEM extends KEM<CryptoKey> {
2657
2711
  readonly suite_id: Uint8Array
2658
2712
  readonly Ndh: number
2659
2713
  readonly kdf: KDF
@@ -2692,22 +2746,19 @@ function b64u(input: string): Uint8Array {
2692
2746
  // KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
2693
2747
  // ============================================================================
2694
2748
 
2695
- /** @see [DeriveKeyPair (DeriveCandidate)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
2696
- async function DeriveCandidate_TwoStage(
2749
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
2750
+ async function DeriveKeyPairBytes(
2697
2751
  DHKEM: DHKEM,
2698
- suite_id: Uint8Array,
2699
2752
  ikm: Uint8Array,
2700
- counter: number,
2753
+ label: Uint8Array,
2754
+ context: Uint8Array,
2701
2755
  ) {
2702
- const dkp_prk = await LabeledExtract(DHKEM.kdf, suite_id, new Uint8Array(), L_dkp_prk, ikm)
2703
- return await LabeledExpand(
2704
- DHKEM.kdf,
2705
- suite_id,
2706
- dkp_prk,
2707
- L_candidate,
2708
- I2OSP(counter, 1),
2709
- DHKEM.Nsk,
2710
- )
2756
+ if (KDFStages(DHKEM.kdf) === 1) {
2757
+ return await LabeledDerive(DHKEM.kdf, DHKEM.suite_id, ikm, label, context, DHKEM.Nsk)
2758
+ }
2759
+
2760
+ const dkp_prk = await LabeledExtract(DHKEM.kdf, DHKEM.suite_id, new Uint8Array(), L_dkp_prk, ikm)
2761
+ return await LabeledExpand(DHKEM.kdf, DHKEM.suite_id, dkp_prk, label, context, DHKEM.Nsk)
2711
2762
  }
2712
2763
 
2713
2764
  function OS2IP(x: Uint8Array): bigint {
@@ -2752,7 +2803,23 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
2752
2803
  }
2753
2804
  }
2754
2805
 
2755
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.5) */
2806
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2807
+ async function ExtractAndExpand_OneStage(
2808
+ DHKEM: DHKEM,
2809
+ dh: Uint8Array,
2810
+ kem_context: Uint8Array,
2811
+ ): Promise<Uint8Array> {
2812
+ return await LabeledDerive(
2813
+ DHKEM.kdf,
2814
+ DHKEM.suite_id,
2815
+ dh,
2816
+ L_shared_secret,
2817
+ kem_context,
2818
+ DHKEM.Nsecret,
2819
+ )
2820
+ }
2821
+
2822
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2756
2823
  async function ExtractAndExpand_TwoStage(
2757
2824
  DHKEM: DHKEM,
2758
2825
  dh: Uint8Array,
@@ -2769,11 +2836,23 @@ async function ExtractAndExpand_TwoStage(
2769
2836
  )
2770
2837
  }
2771
2838
 
2839
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2840
+ async function ExtractAndExpand(
2841
+ DHKEM: DHKEM,
2842
+ dh: Uint8Array,
2843
+ kem_context: Uint8Array,
2844
+ ): Promise<Uint8Array> {
2845
+ const Fn = KDFStages(DHKEM.kdf) === 1 ? ExtractAndExpand_OneStage : ExtractAndExpand_TwoStage
2846
+ return await Fn(DHKEM, dh, kem_context)
2847
+ }
2848
+
2772
2849
  // ============================================================================
2773
2850
  // KEM (Key Encapsulation Mechanism) - DHKEM Shared Implementation
2774
2851
  // ============================================================================
2775
2852
 
2776
- function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializePrivateKey'>> {
2853
+ function DHKEM_SHARED(): Required<
2854
+ Omit<KEM_BASE<CryptoKey>, 'DeriveKeyPair' | 'DeserializePrivateKey'>
2855
+ > {
2777
2856
  return {
2778
2857
  async GenerateKeyPair(this: DHKEM, extractable) {
2779
2858
  return (await subtle(
@@ -2819,7 +2898,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
2819
2898
  const enc = await this.SerializePublicKey(pkE)
2820
2899
  const pkRm = await this.SerializePublicKey(pkR)
2821
2900
  const kem_context = concat(enc, pkRm)
2822
- const shared_secret = await ExtractAndExpand_TwoStage(this, dh, kem_context)
2901
+ const shared_secret = await ExtractAndExpand(this, dh, kem_context)
2823
2902
  return { shared_secret, enc }
2824
2903
  },
2825
2904
  async Decap(this: DHKEM, enc, skR, pkR) {
@@ -2846,7 +2925,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
2846
2925
 
2847
2926
  const pkRm = await this.SerializePublicKey(pkR)
2848
2927
  const kem_context = concat(enc, pkRm)
2849
- const shared_secret = await ExtractAndExpand_TwoStage(this, dh, kem_context)
2928
+ const shared_secret = await ExtractAndExpand(this, dh, kem_context)
2850
2929
  return shared_secret
2851
2930
  },
2852
2931
  }
@@ -3057,7 +3136,7 @@ async function DeserializePrivateKeyNist(
3057
3136
  return privateKey
3058
3137
  }
3059
3138
 
3060
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
3139
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
3061
3140
  async function DeriveKeyPairNist(
3062
3141
  this: DHKEM & NistCurveConfig,
3063
3142
  ikm: Uint8Array,
@@ -3070,7 +3149,7 @@ async function DeriveKeyPairNist(
3070
3149
  if (counter > 255) {
3071
3150
  throw new DeriveKeyPairError('Key derivation exceeded maximum iterations')
3072
3151
  }
3073
- candidate = await DeriveCandidate_TwoStage(this, this.suite_id, ikm, counter)
3152
+ candidate = await DeriveKeyPairBytes(this, ikm, L_candidate, I2OSP(counter, 1))
3074
3153
  candidate[0] = candidate[0]! & this.bitmask
3075
3154
  sk = OS2IP(candidate)
3076
3155
  counter = counter + 1
@@ -3105,10 +3184,9 @@ async function GetKeyPairNist(
3105
3184
  // KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
3106
3185
  // ============================================================================
3107
3186
 
3108
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
3187
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
3109
3188
  async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
3110
- const dkp_prk = await LabeledExtract(this.kdf, this.suite_id, new Uint8Array(), L_dkp_prk, ikm)
3111
- const sk = await LabeledExpand(this.kdf, this.suite_id, dkp_prk, L_sk, new Uint8Array(), this.Nsk)
3189
+ const sk = await DeriveKeyPairBytes(this, ikm, L_sk, new Uint8Array())
3112
3190
  return await createKeyPairFromPrivateKey(this, sk, extractable)
3113
3191
  }
3114
3192
 
@@ -3145,9 +3223,10 @@ const P256: NistCurveConfig = {
3145
3223
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3146
3224
  *
3147
3225
  * @group KEM Algorithms
3148
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3226
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3149
3227
  */
3150
- export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory = function (): DHKEM & NistCurveConfig {
3228
+ export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM &
3229
+ NistCurveConfig {
3151
3230
  const id = 0x0010
3152
3231
  const name = 'DHKEM(P-256, HKDF-SHA256)'
3153
3232
  const kdf = KDF_HKDF_SHA256()
@@ -3200,9 +3279,10 @@ const P384: NistCurveConfig = {
3200
3279
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3201
3280
  *
3202
3281
  * @group KEM Algorithms
3203
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3282
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3204
3283
  */
3205
- export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory = function (): DHKEM & NistCurveConfig {
3284
+ export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory<CryptoKey> = function (): DHKEM &
3285
+ NistCurveConfig {
3206
3286
  const id = 0x0011
3207
3287
  const name = 'DHKEM(P-384, HKDF-SHA384)'
3208
3288
  const kdf = KDF_HKDF_SHA384()
@@ -3255,9 +3335,10 @@ const P521: NistCurveConfig = {
3255
3335
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3256
3336
  *
3257
3337
  * @group KEM Algorithms
3258
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3338
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3259
3339
  */
3260
- export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistCurveConfig {
3340
+ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM &
3341
+ NistCurveConfig {
3261
3342
  const id = 0x0012
3262
3343
  const name = 'DHKEM(P-521, HKDF-SHA512)'
3263
3344
  const kdf = KDF_HKDF_SHA512()
@@ -3301,9 +3382,11 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistC
3301
3382
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3302
3383
  *
3303
3384
  * @group KEM Algorithms
3304
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3385
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3305
3386
  */
3306
- export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { pkcs8: Uint8Array } {
3387
+ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM & {
3388
+ pkcs8: Uint8Array
3389
+ } {
3307
3390
  const id = 0x0020
3308
3391
  const name = 'DHKEM(X25519, HKDF-SHA256)'
3309
3392
  const kdf = KDF_HKDF_SHA256()
@@ -3348,9 +3431,11 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { p
3348
3431
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3349
3432
  *
3350
3433
  * @group KEM Algorithms
3351
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3434
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3352
3435
  */
3353
- export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkcs8: Uint8Array } {
3436
+ export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM & {
3437
+ pkcs8: Uint8Array
3438
+ } {
3354
3439
  const id = 0x0021
3355
3440
  const name = 'DHKEM(X448, HKDF-SHA512)'
3356
3441
  const kdf = KDF_HKDF_SHA512()
@@ -3381,13 +3466,13 @@ export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkc
3381
3466
  // KEM (Key Encapsulation Mechanism) - ML-KEM Types and Implementation
3382
3467
  // ============================================================================
3383
3468
 
3384
- interface MLKEM extends KEM {
3469
+ interface MLKEM extends KEM<CryptoKey> {
3385
3470
  readonly suite_id: Uint8Array
3386
3471
  readonly algorithm: Readonly<KeyAlgorithm>
3387
3472
  readonly kdf: KDF
3388
3473
  }
3389
3474
 
3390
- function MLKEM_SHARED(): KEM_BASE {
3475
+ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3391
3476
  return {
3392
3477
  async DeriveKeyPair(this: MLKEM, ikm, extractable) {
3393
3478
  const dk = await LabeledDerive(
@@ -3497,9 +3582,9 @@ function MLKEM_SHARED(): KEM_BASE {
3497
3582
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3498
3583
  *
3499
3584
  * @group KEM Algorithms
3500
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3585
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3501
3586
  */
3502
- export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3587
+ export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): MLKEM {
3503
3588
  const id = 0x0040
3504
3589
  const name = 'ML-KEM-512'
3505
3590
  const kdf = KDF_SHAKE256()
@@ -3537,9 +3622,9 @@ export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3537
3622
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3538
3623
  *
3539
3624
  * @group KEM Algorithms
3540
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3625
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3541
3626
  */
3542
- export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3627
+ export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): MLKEM {
3543
3628
  const id = 0x0041
3544
3629
  const name = 'ML-KEM-768'
3545
3630
  const kdf = KDF_SHAKE256()
@@ -3577,9 +3662,9 @@ export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3577
3662
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3578
3663
  *
3579
3664
  * @group KEM Algorithms
3580
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3665
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3581
3666
  */
3582
- export const KEM_ML_KEM_1024: KEMFactory = function (): MLKEM {
3667
+ export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): MLKEM {
3583
3668
  const id = 0x0042
3584
3669
  const name = 'ML-KEM-1024'
3585
3670
  const kdf = KDF_SHAKE256()
@@ -3607,11 +3692,7 @@ interface WebCryptoAEAD extends AEAD {
3607
3692
 
3608
3693
  type AEAD_BASE = Pick<AEAD, 'Seal' | 'Open'>
3609
3694
 
3610
- function AEAD_SHARED(): AEAD_BASE {
3611
- // Note: The per-invocation plaintext limits (P_MAX, e.g. 2^36 - 31 bytes for
3612
- // AES-GCM and 2^38 - 64 bytes for ChaCha20-Poly1305) are not explicitly
3613
- // enforced here as they exceed the maximum ArrayBuffer/Uint8Array sizes
3614
- // attainable in JavaScript runtimes.
3695
+ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3615
3696
  // Cache the WebCrypto CryptoKey derived from a given key-bytes Uint8Array.
3616
3697
  // Across the lifetime of a SenderContext/RecipientContext, `this.#key` is a
3617
3698
  // stable Uint8Array, so crypto.subtle.importKey() would otherwise be called
@@ -3630,6 +3711,9 @@ function AEAD_SHARED(): AEAD_BASE {
3630
3711
  }
3631
3712
  return {
3632
3713
  async Seal(this: WebCryptoAEAD, key, nonce, aad, pt) {
3714
+ if (pt.byteLength > P_MAX) {
3715
+ throw new RangeError('"pt" exceeds P_MAX')
3716
+ }
3633
3717
  const cryptoKey =
3634
3718
  cache.get(key) ?? (await cacheValue(cache, key, () => importKey.call(this, key)))
3635
3719
  return new Uint8Array(
@@ -3690,7 +3774,7 @@ function AEAD_SHARED(): AEAD_BASE {
3690
3774
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3691
3775
  *
3692
3776
  * @group AEAD Algorithms
3693
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3777
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3694
3778
  */
3695
3779
  export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3696
3780
  return {
@@ -3702,7 +3786,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3702
3786
  Nt: 16,
3703
3787
  algorithm: 'AES-GCM',
3704
3788
  keyFormat: 'raw',
3705
- ...AEAD_SHARED(),
3789
+ ...AEAD_SHARED(AES_GCM_P_MAX),
3706
3790
  }
3707
3791
  }
3708
3792
 
@@ -3722,7 +3806,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3722
3806
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3723
3807
  *
3724
3808
  * @group AEAD Algorithms
3725
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3809
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3726
3810
  */
3727
3811
  export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3728
3812
  return {
@@ -3734,7 +3818,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3734
3818
  Nt: 16,
3735
3819
  algorithm: 'AES-GCM',
3736
3820
  keyFormat: 'raw',
3737
- ...AEAD_SHARED(),
3821
+ ...AEAD_SHARED(AES_GCM_P_MAX),
3738
3822
  }
3739
3823
  }
3740
3824
 
@@ -3754,7 +3838,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3754
3838
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3755
3839
  *
3756
3840
  * @group AEAD Algorithms
3757
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3841
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3758
3842
  */
3759
3843
  export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
3760
3844
  return {
@@ -3767,7 +3851,7 @@ export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305
3767
3851
  algorithm: 'ChaCha20-Poly1305',
3768
3852
  // @ts-expect-error
3769
3853
  keyFormat: 'raw-secret',
3770
- ...AEAD_SHARED(),
3854
+ ...AEAD_SHARED(CHACHA20_POLY1305_P_MAX),
3771
3855
  }
3772
3856
  }
3773
3857
 
@@ -3889,7 +3973,7 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3889
3973
  return bigIntToUint8Array(sk_bigint, t.Nscalar!)
3890
3974
  }
3891
3975
 
3892
- /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3976
+ /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3893
3977
  async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
3894
3978
  const Nout = PQTKEM.pq.Nseed + PQTKEM.t.Nseed
3895
3979
  const bits = Nout << 3
@@ -3915,7 +3999,7 @@ async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
3915
3999
  return { ek_PQ, ek_T, dk_PQ, dk_T }
3916
4000
  }
3917
4001
 
3918
- /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.3) */
4002
+ /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.3) */
3919
4003
  async function C2PRICombiner(
3920
4004
  PQTKEM: HybridKEM,
3921
4005
  ss_PQ: Uint8Array,
@@ -3929,7 +4013,7 @@ async function C2PRICombiner(
3929
4013
  return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), PQTKEM.name))
3930
4014
  }
3931
4015
 
3932
- /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
4016
+ /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3933
4017
  async function prepareEncapsG(
3934
4018
  PQTKEM: HybridKEM,
3935
4019
  ek_PQ: CryptoKey,
@@ -3960,7 +4044,7 @@ async function prepareEncapsG(
3960
4044
  return [ss_PQ, ss_T, ct_PQ, ct_T]
3961
4045
  }
3962
4046
 
3963
- /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
4047
+ /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3964
4048
  async function prepareDecapsG(
3965
4049
  PQTKEM: HybridKEM,
3966
4050
  dk_PQ: CryptoKey,
@@ -3992,7 +4076,7 @@ async function prepareDecapsG(
3992
4076
  return [ss_PQ, ss_T]
3993
4077
  }
3994
4078
 
3995
- interface HybridKEM extends KEM {
4079
+ interface HybridKEM extends KEM<HybridKey> {
3996
4080
  readonly suite_id: Uint8Array
3997
4081
  readonly kdf: KDF
3998
4082
  readonly algorithm: KeyAlgorithm
@@ -4020,7 +4104,7 @@ interface HybridKEM extends KEM {
4020
4104
  }
4021
4105
  }
4022
4106
 
4023
- function PQTKEM_SHARED(): KEM_BASE {
4107
+ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4024
4108
  Object.freeze(HybridKey.prototype)
4025
4109
  return {
4026
4110
  async DeriveKeyPair(this: HybridKEM, ikm: Uint8Array, extractable) {
@@ -4157,13 +4241,13 @@ function PQTKEM_SHARED(): KEM_BASE {
4157
4241
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4158
4242
  *
4159
4243
  * @group KEM Algorithms
4160
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4244
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4161
4245
  */
4162
4246
  export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4163
4247
  const id = 0x647a
4164
4248
  const name = 'MLKEM768-X25519'
4165
4249
  const kdf = KDF_SHAKE256()
4166
- const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20); // prettier-ignore
4250
+ const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20) // prettier-ignore
4167
4251
  // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4168
4252
  kdf.name = name
4169
4253
  return {
@@ -4214,7 +4298,7 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4214
4298
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4215
4299
  *
4216
4300
  * @group KEM Algorithms
4217
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4301
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4218
4302
  */
4219
4303
  export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4220
4304
  const id = 0x0050
@@ -4270,7 +4354,7 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4270
4354
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4271
4355
  *
4272
4356
  * @group KEM Algorithms
4273
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4357
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4274
4358
  */
4275
4359
  export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4276
4360
  const id = 0x0051