hpke 1.1.3 → 1.1.5

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,7 +42,7 @@
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.
@@ -63,7 +63,7 @@ function MaxSeq(Nn: number): number {
63
63
  return Math.min(2 ** (8 * Nn) - 1, Number.MAX_SAFE_INTEGER)
64
64
  }
65
65
 
66
- /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2) */
66
+ /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2) */
67
67
  function IncrementSeq(seq: number, maxSeq: number): number {
68
68
  if (seq >= maxSeq) {
69
69
  throw new MessageLimitReachedError('Sequence number overflow')
@@ -71,7 +71,7 @@ function IncrementSeq(seq: number, maxSeq: number): number {
71
71
  return ++seq
72
72
  }
73
73
 
74
- /** @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) */
75
75
  async function ContextExport(
76
76
  suite: Triple,
77
77
  exporterSecret: Uint8Array,
@@ -129,14 +129,14 @@ class SenderContext {
129
129
  #key: Uint8Array
130
130
  #base_nonce: Uint8Array
131
131
  #exporter_secret: Uint8Array
132
- #mode: typeof MODE_BASE | typeof MODE_PSK
132
+ #mode: Mode
133
133
  #seq: number = 0
134
134
  #max_seq: number
135
135
  #mutex?: Mutex
136
136
 
137
137
  constructor(
138
138
  suite: Triple,
139
- mode: typeof MODE_BASE | typeof MODE_PSK,
139
+ mode: Mode,
140
140
  key: Uint8Array,
141
141
  base_nonce: Uint8Array,
142
142
  exporter_secret: Uint8Array,
@@ -154,7 +154,7 @@ class SenderContext {
154
154
  * @see {@link MODE_BASE}
155
155
  * @see {@link MODE_PSK}
156
156
  */
157
- get mode(): number {
157
+ get mode(): Mode {
158
158
  return this.#mode
159
159
  }
160
160
 
@@ -192,7 +192,7 @@ class SenderContext {
192
192
  *
193
193
  * @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
194
194
  * than the plaintext.
195
- * @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)
196
196
  */
197
197
  async Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
198
198
  checkUint8Array(plaintext, 'plaintext')
@@ -240,7 +240,7 @@ class SenderContext {
240
240
  * @param length - Desired length of exported secret in bytes
241
241
  *
242
242
  * @returns A Promise that resolves to the exported secret.
243
- * @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)
244
244
  */
245
245
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
246
246
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -280,14 +280,14 @@ class RecipientContext {
280
280
  #key: Uint8Array
281
281
  #base_nonce: Uint8Array
282
282
  #exporter_secret: Uint8Array
283
- #mode: typeof MODE_BASE | typeof MODE_PSK
283
+ #mode: Mode
284
284
  #seq: number = 0
285
285
  #max_seq: number
286
286
  #mutex?: Mutex
287
287
 
288
288
  constructor(
289
289
  suite: Triple,
290
- mode: typeof MODE_BASE | typeof MODE_PSK,
290
+ mode: Mode,
291
291
  key: Uint8Array,
292
292
  base_nonce: Uint8Array,
293
293
  exporter_secret: Uint8Array,
@@ -305,7 +305,7 @@ class RecipientContext {
305
305
  * @see {@link MODE_BASE}
306
306
  * @see {@link MODE_PSK}
307
307
  */
308
- get mode(): number {
308
+ get mode(): Mode {
309
309
  return this.#mode
310
310
  }
311
311
 
@@ -344,7 +344,7 @@ class RecipientContext {
344
344
  * @param aad - Additional authenticated data
345
345
  *
346
346
  * @returns A Promise that resolves to the decrypted plaintext.
347
- * @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)
348
348
  */
349
349
  async Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
350
350
  checkUint8Array(ciphertext, 'ciphertext')
@@ -401,7 +401,7 @@ class RecipientContext {
401
401
  * @param length - Desired length of exported secret in bytes
402
402
  *
403
403
  * @returns A Promise that resolves to the exported secret.
404
- * @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)
405
405
  */
406
406
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
407
407
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -432,7 +432,7 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
432
432
  * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
433
433
  * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
434
434
  * being republished as a Standards Track document of the IETF as
435
- * [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).
436
436
  *
437
437
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
438
438
  * public key. It supports two modes:
@@ -446,10 +446,11 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
446
446
  * - KDF: Key Derivation Function for deriving symmetric keys
447
447
  * - AEAD: Authenticated Encryption with Additional Data for encryption
448
448
  *
449
+ * @typeParam K - Key representation produced and consumed by the suite's KEM
449
450
  * @group Core
450
451
  */
451
- export class CipherSuite {
452
- #suite: Triple
452
+ export class CipherSuite<K extends Key = Key> {
453
+ #suite: Triple<K>
453
454
 
454
455
  /**
455
456
  * Creates a new HPKE cipher suite by combining a Key Encapsulation Mechanism (KEM), Key
@@ -512,7 +513,7 @@ export class CipherSuite {
512
513
  * @see {@link KDFFactory Available KDFs}
513
514
  * @see {@link AEADFactory Available AEADs}
514
515
  */
515
- constructor(KEM: KEMFactory, KDF: KDFFactory, AEAD: AEADFactory) {
516
+ constructor(KEM: KEMFactory<K>, KDF: KDFFactory, AEAD: AEADFactory) {
516
517
  const kem = validate(KEM, 'KEM')
517
518
  const kdf = validate(KDF, 'KDF')
518
519
  const aead = validate(AEAD, 'AEAD')
@@ -532,17 +533,17 @@ export class CipherSuite {
532
533
  */
533
534
  get KEM(): {
534
535
  /** The identifier of this suite's KEM */
535
- id: number
536
+ readonly id: number
536
537
  /** The name of this suite's KEM */
537
- name: string
538
+ readonly name: string
538
539
  /** The length in bytes of this suite's KEM produced shared secret */
539
- Nsecret: number
540
+ readonly Nsecret: number
540
541
  /** The length in bytes of this suite's KEM produced encapsulated secret */
541
- Nenc: number
542
+ readonly Nenc: number
542
543
  /** The length in bytes of this suite's KEM public key */
543
- Npk: number
544
+ readonly Npk: number
544
545
  /** The length in bytes of this suite's KEM private key */
545
- Nsk: number
546
+ readonly Nsk: number
546
547
  } {
547
548
  return {
548
549
  id: this.#suite.KEM.id,
@@ -561,21 +562,21 @@ export class CipherSuite {
561
562
  */
562
563
  get KDF(): {
563
564
  /** The identifier of this suite's KDF */
564
- id: number
565
+ readonly id: number
565
566
  /** The name of this suite's KDF */
566
- name: string
567
+ readonly name: string
567
568
  /**
568
569
  * When 1, this suite's KDF is a one-stage (Derive) KDF.
569
570
  *
570
571
  * When 2, this suite's KDF is a two-stage (Extract and Expand) KDF.
571
572
  */
572
- stages: 1 | 2
573
+ readonly stages: 1 | 2
573
574
  /**
574
575
  * For one-stage KDF: The security strength of this suite's KDF, in bytes.
575
576
  *
576
577
  * For two-stage KDF: The output size of this suite's KDF Extract() function in bytes.
577
578
  */
578
- Nh: number
579
+ readonly Nh: number
579
580
  } {
580
581
  return {
581
582
  id: this.#suite.KDF.id,
@@ -593,15 +594,15 @@ export class CipherSuite {
593
594
  */
594
595
  get AEAD(): {
595
596
  /** The identifier of this suite's AEAD */
596
- id: number
597
+ readonly id: number
597
598
  /** The name of this suite's AEAD */
598
- name: string
599
+ readonly name: string
599
600
  /** The length in bytes of a key for this suite's AEAD */
600
- Nk: number
601
+ readonly Nk: number
601
602
  /** The length in bytes of a nonce for this suite's AEAD */
602
- Nn: number
603
+ readonly Nn: number
603
604
  /** The length in bytes of an authentication tag for this suite's AEAD */
604
- Nt: number
605
+ readonly Nt: number
605
606
  } {
606
607
  return {
607
608
  id: this.#suite.AEAD.id,
@@ -629,7 +630,7 @@ export class CipherSuite {
629
630
  *
630
631
  * @returns A Promise that resolves to a generated key pair.
631
632
  */
632
- async GenerateKeyPair(extractable?: boolean): Promise<KeyPair> {
633
+ async GenerateKeyPair(extractable?: boolean): Promise<KeyPair<K>> {
633
634
  extractable ??= false
634
635
  checkExtractable(extractable)
635
636
  return await this.#suite.KEM.GenerateKeyPair(extractable)
@@ -662,7 +663,7 @@ export class CipherSuite {
662
663
  *
663
664
  * @returns A Promise that resolves to the derived key pair.
664
665
  */
665
- async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair> {
666
+ async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair<K>> {
666
667
  extractable ??= false
667
668
  checkExtractable(extractable)
668
669
  checkUint8Array(ikm, 'ikm')
@@ -695,7 +696,7 @@ export class CipherSuite {
695
696
  *
696
697
  * @returns A Promise that resolves to the serialized private key.
697
698
  */
698
- async SerializePrivateKey(privateKey: Key): Promise<Uint8Array> {
699
+ async SerializePrivateKey(privateKey: K): Promise<Uint8Array> {
699
700
  isKey(privateKey, 'private', true)
700
701
 
701
702
  return await this.#suite.KEM.SerializePrivateKey(privateKey)
@@ -717,7 +718,7 @@ export class CipherSuite {
717
718
  *
718
719
  * @returns A Promise that resolves to the serialized public key.
719
720
  */
720
- async SerializePublicKey(publicKey: Key): Promise<Uint8Array> {
721
+ async SerializePublicKey(publicKey: K): Promise<Uint8Array> {
721
722
  isKey(publicKey, 'public', true)
722
723
 
723
724
  return await this.#suite.KEM.SerializePublicKey(publicKey)
@@ -742,7 +743,7 @@ export class CipherSuite {
742
743
  *
743
744
  * @returns A Promise that resolves to the deserialized private key.
744
745
  */
745
- async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<Key> {
746
+ async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<K> {
746
747
  extractable ??= false
747
748
  checkExtractable(extractable)
748
749
  checkUint8Array(privateKey, 'privateKey')
@@ -777,7 +778,7 @@ export class CipherSuite {
777
778
  *
778
779
  * @returns A Promise that resolves to the deserialized public key.
779
780
  */
780
- async DeserializePublicKey(publicKey: Uint8Array): Promise<Key> {
781
+ async DeserializePublicKey(publicKey: Uint8Array): Promise<K> {
781
782
  checkUint8Array(publicKey, 'publicKey')
782
783
 
783
784
  try {
@@ -825,10 +826,10 @@ export class CipherSuite {
825
826
  * @returns A Promise that resolves to an object containing the encapsulated secret and
826
827
  * ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
827
828
  * encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
828
- * @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)
829
830
  */
830
831
  async Seal(
831
- publicKey: Key,
832
+ publicKey: K,
832
833
  plaintext: Uint8Array,
833
834
  options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
834
835
  ): Promise<{ encapsulatedSecret: Uint8Array; ciphertext: Uint8Array }> {
@@ -874,10 +875,10 @@ export class CipherSuite {
874
875
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
875
876
  *
876
877
  * @returns A Promise that resolves to the decrypted plaintext.
877
- * @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)
878
879
  */
879
880
  async Open(
880
- privateKey: Key | KeyPair,
881
+ privateKey: K | KeyPair<K>,
881
882
  encapsulatedSecret: Uint8Array,
882
883
  ciphertext: Uint8Array,
883
884
  options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
@@ -922,10 +923,10 @@ export class CipherSuite {
922
923
  *
923
924
  * @returns A Promise that resolves to an object containing the encapsulated secret and the
924
925
  * exported secret.
925
- * @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)
926
927
  */
927
928
  async SendExport(
928
- publicKey: Key,
929
+ publicKey: K,
929
930
  exporterContext: Uint8Array,
930
931
  length: number,
931
932
  options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
@@ -970,10 +971,10 @@ export class CipherSuite {
970
971
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
971
972
  *
972
973
  * @returns A Promise that resolves to the exported secret.
973
- * @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)
974
975
  */
975
976
  async ReceiveExport(
976
- privateKey: Key | KeyPair,
977
+ privateKey: K | KeyPair<K>,
977
978
  encapsulatedSecret: Uint8Array,
978
979
  exporterContext: Uint8Array,
979
980
  length: number,
@@ -1024,10 +1025,10 @@ export class CipherSuite {
1024
1025
  *
1025
1026
  * @returns A Promise that resolves to an object containing the encapsulated secret and the sender
1026
1027
  * context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
1027
- * @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)
1028
1029
  */
1029
1030
  async SetupSender(
1030
- publicKey: Key,
1031
+ publicKey: K,
1031
1032
  options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
1032
1033
  ): Promise<{ encapsulatedSecret: Uint8Array; ctx: SenderContext }> {
1033
1034
  isKey(publicKey, 'public')
@@ -1105,10 +1106,10 @@ export class CipherSuite {
1105
1106
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
1106
1107
  *
1107
1108
  * @returns A Promise that resolves to the recipient context.
1108
- * @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)
1109
1110
  */
1110
1111
  async SetupRecipient(
1111
- privateKey: Key | KeyPair,
1112
+ privateKey: K | KeyPair<K>,
1112
1113
  encapsulatedSecret: Uint8Array,
1113
1114
  options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
1114
1115
  ): Promise<RecipientContext> {
@@ -1141,7 +1142,7 @@ export class CipherSuite {
1141
1142
  return new RecipientContext(this.#suite, mode, key, base_nonce, exporter_secret)
1142
1143
  }
1143
1144
 
1144
- #extractRecipientKeys(skR: Key | KeyPair): { skR: Key; pkR: Key | undefined } {
1145
+ #extractRecipientKeys(skR: K | KeyPair<K>): { skR: K; pkR: K | undefined } {
1145
1146
  if (isKeyPair(skR)) {
1146
1147
  return { skR: skR.privateKey, pkR: skR.publicKey }
1147
1148
  }
@@ -1279,9 +1280,9 @@ export class NotSupportedError extends Error {
1279
1280
  // Type Definitions and Interfaces
1280
1281
  // ============================================================================
1281
1282
 
1282
- interface Triple {
1283
+ interface Triple<K extends Key = Key> {
1283
1284
  readonly id: Uint8Array
1284
- readonly KEM: Readonly<KEM>
1285
+ readonly KEM: Readonly<KEM<K>>
1285
1286
  readonly KDF: Readonly<KDF>
1286
1287
  readonly AEAD: Readonly<AEAD>
1287
1288
  }
@@ -1292,7 +1293,7 @@ interface Triple {
1292
1293
  * Base mode provides encryption to a public key without sender authentication. The recipient cannot
1293
1294
  * verify who encrypted the message, only that someone with access to their public key did.
1294
1295
  *
1295
- * @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)
1296
1297
  */
1297
1298
  export const MODE_BASE = 0x00
1298
1299
 
@@ -1303,10 +1304,13 @@ export const MODE_BASE = 0x00
1303
1304
  * sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
1304
1305
  * authentication.
1305
1306
  *
1306
- * @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)
1307
1308
  */
1308
1309
  export const MODE_PSK = 0x01
1309
1310
 
1311
+ /** Mode supported by this implementation. */
1312
+ export type Mode = typeof MODE_BASE | typeof MODE_PSK
1313
+
1310
1314
  /**
1311
1315
  * Factory function that returns a KEM implementation.
1312
1316
  *
@@ -1338,8 +1342,10 @@ export const MODE_PSK = 0x01
1338
1342
  * > returning an object conforming to the {@link KEM} interface can be used. Such implementations not
1339
1343
  * > reliant on Web Cryptography are exported by
1340
1344
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1345
+ *
1346
+ * @typeParam K - Key representation produced and consumed by the KEM
1341
1347
  */
1342
- export type KEMFactory = () => Readonly<KEM>
1348
+ export type KEMFactory<K extends Key = Key> = () => Readonly<KEM<K>>
1343
1349
 
1344
1350
  /**
1345
1351
  * Factory function that returns a KDF implementation.
@@ -1396,12 +1402,14 @@ export type AEADFactory = () => Readonly<AEAD>
1396
1402
  * - Private Key: Used by recipients for decryption operations (passed to
1397
1403
  * {@link CipherSuite.SetupRecipient} or {@link CipherSuite.Open}). These are not distributed and
1398
1404
  * kept private.
1405
+ *
1406
+ * @typeParam K - Key representation contained in the pair
1399
1407
  */
1400
- export interface KeyPair {
1408
+ export interface KeyPair<K extends Key = Key> {
1401
1409
  /** The public key, used for encryption operations. */
1402
- readonly publicKey: Readonly<Key>
1410
+ readonly publicKey: Readonly<K>
1403
1411
  /** The private key, used for decryption operations. */
1404
- readonly privateKey: Readonly<Key>
1412
+ readonly privateKey: Readonly<K>
1405
1413
  }
1406
1414
 
1407
1415
  /**
@@ -1428,6 +1436,34 @@ export interface Key {
1428
1436
  readonly type: 'private' | 'public' | (string & {})
1429
1437
  }
1430
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
+
1431
1467
  // ============================================================================
1432
1468
  // Utility Functions
1433
1469
  // ============================================================================
@@ -1525,7 +1561,7 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
1525
1561
  * ensures domain separation between different uses of the KDF in HPKE.
1526
1562
  *
1527
1563
  * @group Utilities
1528
- * @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)
1529
1565
  */
1530
1566
  export async function LabeledDerive(
1531
1567
  KDF: Pick<KDF, 'Derive'>,
@@ -1539,7 +1575,7 @@ export async function LabeledDerive(
1539
1575
  return await KDF.Derive(labeled_ikm, L)
1540
1576
  }
1541
1577
 
1542
- /** @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) */
1543
1579
  async function Export_OneStage(
1544
1580
  KDF: KDF,
1545
1581
  suite_id: Uint8Array,
@@ -1551,7 +1587,7 @@ async function Export_OneStage(
1551
1587
  return await LabeledDerive(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
1552
1588
  }
1553
1589
 
1554
- /** @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) */
1555
1591
  async function CombineSecrets_OneStage(
1556
1592
  suite: Triple,
1557
1593
  mode: number,
@@ -1608,7 +1644,7 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
1608
1644
  }
1609
1645
  }
1610
1646
 
1611
- /** @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) */
1612
1648
  async function CombineSecrets_TwoStage(
1613
1649
  suite: Triple,
1614
1650
  mode: number,
@@ -1651,7 +1687,7 @@ async function CombineSecrets_TwoStage(
1651
1687
  return { key, base_nonce, exporter_secret }
1652
1688
  }
1653
1689
 
1654
- /** @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) */
1655
1691
  async function Export_TwoStage(
1656
1692
  KDF: KDF,
1657
1693
  suite_id: Uint8Array,
@@ -1728,7 +1764,7 @@ async function Export_TwoStage(
1728
1764
  * )
1729
1765
  * ```
1730
1766
  *
1731
- * @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)
1732
1768
  */
1733
1769
  export interface KDF {
1734
1770
  /** KDF algorithm identifier */
@@ -1801,7 +1837,7 @@ export interface KDF {
1801
1837
  * pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
1802
1838
  *
1803
1839
  * @group Utilities
1804
- * @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)
1805
1841
  */
1806
1842
  export async function LabeledExtract(
1807
1843
  KDF: Pick<KDF, 'Extract'>,
@@ -1831,7 +1867,7 @@ export async function LabeledExtract(
1831
1867
  * of the KDF in HPKE.
1832
1868
  *
1833
1869
  * @group Utilities
1834
- * @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)
1835
1871
  */
1836
1872
  export async function LabeledExpand(
1837
1873
  KDF: Pick<KDF, 'Expand'>,
@@ -1940,9 +1976,10 @@ export async function LabeledExpand(
1940
1976
  * )
1941
1977
  * ```
1942
1978
  *
1943
- * @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)
1944
1981
  */
1945
- export interface KEM {
1982
+ export interface KEM<K extends Key = Key> {
1946
1983
  /** KEM algorithm identifier */
1947
1984
  readonly id: number
1948
1985
 
@@ -1972,7 +2009,7 @@ export interface KEM {
1972
2009
  *
1973
2010
  * @returns A promise resolving to a {@link KeyPair}
1974
2011
  */
1975
- DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair>
2012
+ DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair<K>>
1976
2013
 
1977
2014
  /**
1978
2015
  * Generates a random key pair.
@@ -1981,7 +2018,7 @@ export interface KEM {
1981
2018
  *
1982
2019
  * @returns A promise resolving to a {@link KeyPair}
1983
2020
  */
1984
- GenerateKeyPair(extractable: boolean): Promise<KeyPair>
2021
+ GenerateKeyPair(extractable: boolean): Promise<KeyPair<K>>
1985
2022
 
1986
2023
  /**
1987
2024
  * Serializes a public key to bytes.
@@ -1990,7 +2027,7 @@ export interface KEM {
1990
2027
  *
1991
2028
  * @returns A promise resolving to the serialized public key
1992
2029
  */
1993
- SerializePublicKey(key: Key): Promise<Uint8Array>
2030
+ SerializePublicKey(key: K): Promise<Uint8Array>
1994
2031
 
1995
2032
  /**
1996
2033
  * Deserializes a public key from bytes.
@@ -1999,7 +2036,7 @@ export interface KEM {
1999
2036
  *
2000
2037
  * @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
2001
2038
  */
2002
- DeserializePublicKey(key: Uint8Array): Promise<Key>
2039
+ DeserializePublicKey(key: Uint8Array): Promise<K>
2003
2040
 
2004
2041
  /**
2005
2042
  * Serializes a private key to bytes.
@@ -2008,7 +2045,7 @@ export interface KEM {
2008
2045
  *
2009
2046
  * @returns A promise resolving to the serialized private key
2010
2047
  */
2011
- SerializePrivateKey(key: Key): Promise<Uint8Array>
2048
+ SerializePrivateKey(key: K): Promise<Uint8Array>
2012
2049
 
2013
2050
  /**
2014
2051
  * Deserializes a private key from bytes.
@@ -2018,7 +2055,7 @@ export interface KEM {
2018
2055
  *
2019
2056
  * @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
2020
2057
  */
2021
- DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<Key>
2058
+ DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<K>
2022
2059
 
2023
2060
  /**
2024
2061
  * Encapsulates a shared secret to a recipient's public key.
@@ -2031,7 +2068,7 @@ export interface KEM {
2031
2068
  *
2032
2069
  * @returns A promise resolving to an object containing the shared secret and encapsulated secret
2033
2070
  */
2034
- Encap(pkR: Key): Promise<{ shared_secret: Uint8Array; enc: Uint8Array }>
2071
+ Encap(pkR: K): Promise<{ shared_secret: Uint8Array; enc: Uint8Array }>
2035
2072
 
2036
2073
  /**
2037
2074
  * Decapsulates a shared secret using a recipient's private key.
@@ -2046,10 +2083,10 @@ export interface KEM {
2046
2083
  *
2047
2084
  * @returns A promise resolving to the shared secret
2048
2085
  */
2049
- Decap(enc: Uint8Array, skR: Key, pkR: Key | undefined): Promise<Uint8Array>
2086
+ Decap(enc: Uint8Array, skR: K, pkR: K | undefined): Promise<Uint8Array>
2050
2087
  }
2051
2088
 
2052
- function isKeyPair(skR: unknown): skR is KeyPair {
2089
+ function isKeyPair<K extends Key>(skR: K | KeyPair<K>): skR is KeyPair<K> {
2053
2090
  if (!skR || typeof skR !== 'object') return false
2054
2091
  if ('publicKey' in skR && 'privateKey' in skR) {
2055
2092
  const pkR = skR.publicKey
@@ -2142,7 +2179,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
2142
2179
  * )
2143
2180
  * ```
2144
2181
  *
2145
- * @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)
2146
2183
  */
2147
2184
  export interface AEAD {
2148
2185
  /** AEAD algorithm identifier */
@@ -2177,7 +2214,7 @@ export interface AEAD {
2177
2214
  * @param pt - Plaintext to encrypt
2178
2215
  *
2179
2216
  * @returns A promise resolving to the ciphertext with authentication tag appended
2180
- * @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2)
2217
+ * @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
2181
2218
  */
2182
2219
  Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>
2183
2220
 
@@ -2238,7 +2275,7 @@ function KDFStages(KDF: KDF): 1 | 2 {
2238
2275
  throw new Error('unreachable')
2239
2276
  }
2240
2277
 
2241
- /** @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) */
2242
2279
  async function KeySchedule(
2243
2280
  suite: Triple,
2244
2281
  mode: number,
@@ -2261,7 +2298,7 @@ async function KeySchedule(
2261
2298
  return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
2262
2299
  }
2263
2300
 
2264
- /** @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) */
2265
2302
  function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
2266
2303
  if (psk.byteLength && psk_id.byteLength) {
2267
2304
  if (psk.byteLength < 32) {
@@ -2293,7 +2330,7 @@ const CHACHA20_POLY1305_P_MAX = 2 ** 38 - 64
2293
2330
  * This is a factory function that must be passed to the {@link CipherSuite} constructor.
2294
2331
  *
2295
2332
  * @group AEAD Algorithms
2296
- * @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)
2297
2334
  */
2298
2335
  export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
2299
2336
  return {
@@ -2419,7 +2456,7 @@ function HKDF_SHARED(): KDF_BASE {
2419
2456
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2420
2457
  *
2421
2458
  * @group KDF Algorithms
2422
- * @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)
2423
2460
  */
2424
2461
  export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2425
2462
  return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
@@ -2442,7 +2479,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2442
2479
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2443
2480
  *
2444
2481
  * @group KDF Algorithms
2445
- * @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)
2446
2483
  */
2447
2484
  export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2448
2485
  return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
@@ -2465,7 +2502,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2465
2502
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2466
2503
  *
2467
2504
  * @group KDF Algorithms
2468
- * @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)
2469
2506
  */
2470
2507
  export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
2471
2508
  return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
@@ -2513,7 +2550,7 @@ function SHAKE_SHARED(): KDF_BASE {
2513
2550
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2514
2551
  *
2515
2552
  * @group KDF Algorithms
2516
- * @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)
2517
2554
  */
2518
2555
  export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2519
2556
  return {
@@ -2543,7 +2580,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2543
2580
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2544
2581
  *
2545
2582
  * @group KDF Algorithms
2546
- * @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)
2547
2584
  */
2548
2585
  export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2549
2586
  return {
@@ -2573,7 +2610,7 @@ export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2573
2610
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2574
2611
  *
2575
2612
  * @group KDF Algorithms
2576
- * @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)
2577
2614
  */
2578
2615
  export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2579
2616
  return {
@@ -2603,7 +2640,7 @@ export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2603
2640
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2604
2641
  *
2605
2642
  * @group KDF Algorithms
2606
- * @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)
2607
2644
  */
2608
2645
  export const KDF_TurboSHAKE256: KDFFactory = function (): SHAKE {
2609
2646
  return {
@@ -2658,8 +2695,8 @@ function checkNotAllZeros(buffer: Uint8Array): void {
2658
2695
  }
2659
2696
  }
2660
2697
 
2661
- type KEM_BASE = Pick<
2662
- KEM,
2698
+ type KEM_BASE<K extends Key = Key> = Pick<
2699
+ KEM<K>,
2663
2700
  | 'GenerateKeyPair'
2664
2701
  | 'DeriveKeyPair'
2665
2702
  | 'SerializePublicKey'
@@ -2670,7 +2707,7 @@ type KEM_BASE = Pick<
2670
2707
  | 'Decap'
2671
2708
  >
2672
2709
 
2673
- interface DHKEM extends KEM {
2710
+ interface DHKEM extends KEM<CryptoKey> {
2674
2711
  readonly suite_id: Uint8Array
2675
2712
  readonly Ndh: number
2676
2713
  readonly kdf: KDF
@@ -2709,7 +2746,7 @@ function b64u(input: string): Uint8Array {
2709
2746
  // KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
2710
2747
  // ============================================================================
2711
2748
 
2712
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
2749
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
2713
2750
  async function DeriveKeyPairBytes(
2714
2751
  DHKEM: DHKEM,
2715
2752
  ikm: Uint8Array,
@@ -2766,7 +2803,7 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
2766
2803
  }
2767
2804
  }
2768
2805
 
2769
- /** @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) */
2770
2807
  async function ExtractAndExpand_OneStage(
2771
2808
  DHKEM: DHKEM,
2772
2809
  dh: Uint8Array,
@@ -2782,7 +2819,7 @@ async function ExtractAndExpand_OneStage(
2782
2819
  )
2783
2820
  }
2784
2821
 
2785
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.5) */
2822
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2786
2823
  async function ExtractAndExpand_TwoStage(
2787
2824
  DHKEM: DHKEM,
2788
2825
  dh: Uint8Array,
@@ -2799,7 +2836,7 @@ async function ExtractAndExpand_TwoStage(
2799
2836
  )
2800
2837
  }
2801
2838
 
2802
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.5) */
2839
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2803
2840
  async function ExtractAndExpand(
2804
2841
  DHKEM: DHKEM,
2805
2842
  dh: Uint8Array,
@@ -2813,7 +2850,9 @@ async function ExtractAndExpand(
2813
2850
  // KEM (Key Encapsulation Mechanism) - DHKEM Shared Implementation
2814
2851
  // ============================================================================
2815
2852
 
2816
- function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializePrivateKey'>> {
2853
+ function DHKEM_SHARED(): Required<
2854
+ Omit<KEM_BASE<CryptoKey>, 'DeriveKeyPair' | 'DeserializePrivateKey'>
2855
+ > {
2817
2856
  return {
2818
2857
  async GenerateKeyPair(this: DHKEM, extractable) {
2819
2858
  return (await subtle(
@@ -3097,7 +3136,7 @@ async function DeserializePrivateKeyNist(
3097
3136
  return privateKey
3098
3137
  }
3099
3138
 
3100
- /** @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) */
3101
3140
  async function DeriveKeyPairNist(
3102
3141
  this: DHKEM & NistCurveConfig,
3103
3142
  ikm: Uint8Array,
@@ -3145,7 +3184,7 @@ async function GetKeyPairNist(
3145
3184
  // KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
3146
3185
  // ============================================================================
3147
3186
 
3148
- /** @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) */
3149
3188
  async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
3150
3189
  const sk = await DeriveKeyPairBytes(this, ikm, L_sk, new Uint8Array())
3151
3190
  return await createKeyPairFromPrivateKey(this, sk, extractable)
@@ -3184,9 +3223,10 @@ const P256: NistCurveConfig = {
3184
3223
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3185
3224
  *
3186
3225
  * @group KEM Algorithms
3187
- * @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)
3188
3227
  */
3189
- 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 {
3190
3230
  const id = 0x0010
3191
3231
  const name = 'DHKEM(P-256, HKDF-SHA256)'
3192
3232
  const kdf = KDF_HKDF_SHA256()
@@ -3239,9 +3279,10 @@ const P384: NistCurveConfig = {
3239
3279
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3240
3280
  *
3241
3281
  * @group KEM Algorithms
3242
- * @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)
3243
3283
  */
3244
- 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 {
3245
3286
  const id = 0x0011
3246
3287
  const name = 'DHKEM(P-384, HKDF-SHA384)'
3247
3288
  const kdf = KDF_HKDF_SHA384()
@@ -3294,9 +3335,10 @@ const P521: NistCurveConfig = {
3294
3335
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3295
3336
  *
3296
3337
  * @group KEM Algorithms
3297
- * @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)
3298
3339
  */
3299
- 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 {
3300
3342
  const id = 0x0012
3301
3343
  const name = 'DHKEM(P-521, HKDF-SHA512)'
3302
3344
  const kdf = KDF_HKDF_SHA512()
@@ -3340,9 +3382,11 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistC
3340
3382
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3341
3383
  *
3342
3384
  * @group KEM Algorithms
3343
- * @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)
3344
3386
  */
3345
- 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
+ } {
3346
3390
  const id = 0x0020
3347
3391
  const name = 'DHKEM(X25519, HKDF-SHA256)'
3348
3392
  const kdf = KDF_HKDF_SHA256()
@@ -3387,9 +3431,11 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { p
3387
3431
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3388
3432
  *
3389
3433
  * @group KEM Algorithms
3390
- * @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)
3391
3435
  */
3392
- 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
+ } {
3393
3439
  const id = 0x0021
3394
3440
  const name = 'DHKEM(X448, HKDF-SHA512)'
3395
3441
  const kdf = KDF_HKDF_SHA512()
@@ -3417,18 +3463,20 @@ export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkc
3417
3463
  }
3418
3464
 
3419
3465
  // ============================================================================
3420
- // KEM (Key Encapsulation Mechanism) - ML-KEM Types and Implementation
3466
+ // KEM (Key Encapsulation Mechanism) - Direct KEM Types and Implementation
3421
3467
  // ============================================================================
3422
3468
 
3423
- interface MLKEM extends KEM {
3469
+ type KEMParams = Pick<KEM, 'id' | 'name' | 'Nsecret' | 'Nenc' | 'Npk' | 'Nsk'>
3470
+
3471
+ interface DirectKEM extends KEM<CryptoKey> {
3424
3472
  readonly suite_id: Uint8Array
3425
3473
  readonly algorithm: Readonly<KeyAlgorithm>
3426
3474
  readonly kdf: KDF
3427
3475
  }
3428
3476
 
3429
- function MLKEM_SHARED(): KEM_BASE {
3477
+ function DIRECT_KEM_SHARED(): KEM_BASE<CryptoKey> {
3430
3478
  return {
3431
- async DeriveKeyPair(this: MLKEM, ikm, extractable) {
3479
+ async DeriveKeyPair(this: DirectKEM, ikm, extractable) {
3432
3480
  const dk = await LabeledDerive(
3433
3481
  this.kdf,
3434
3482
  this.suite_id,
@@ -3445,7 +3493,7 @@ function MLKEM_SHARED(): KEM_BASE {
3445
3493
 
3446
3494
  return { privateKey, publicKey }
3447
3495
  },
3448
- async GenerateKeyPair(this: MLKEM, extractable) {
3496
+ async GenerateKeyPair(this: DirectKEM, extractable) {
3449
3497
  // @ts-expect-error
3450
3498
  const usages: KeyUsage[] = ['encapsulateBits', 'decapsulateBits']
3451
3499
  return (await subtle(
@@ -3453,14 +3501,14 @@ function MLKEM_SHARED(): KEM_BASE {
3453
3501
  this.name,
3454
3502
  )) as CryptoKeyPair
3455
3503
  },
3456
- async SerializePublicKey(this: MLKEM, key) {
3504
+ async SerializePublicKey(this: DirectKEM, key) {
3457
3505
  assertKeyAlgorithm(key, this.algorithm)
3458
3506
  assertCryptoKey(key)
3459
3507
  // @ts-expect-error
3460
3508
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
3461
3509
  return new Uint8Array(await subtle((c) => c.exportKey(format, key), this.name))
3462
3510
  },
3463
- async DeserializePublicKey(this: MLKEM, key) {
3511
+ async DeserializePublicKey(this: DirectKEM, key) {
3464
3512
  // @ts-expect-error
3465
3513
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
3466
3514
  // @ts-expect-error
@@ -3470,14 +3518,14 @@ function MLKEM_SHARED(): KEM_BASE {
3470
3518
  this.name,
3471
3519
  )
3472
3520
  },
3473
- async SerializePrivateKey(this: MLKEM, key) {
3521
+ async SerializePrivateKey(this: DirectKEM, key) {
3474
3522
  assertKeyAlgorithm(key, this.algorithm)
3475
3523
  assertCryptoKey(key)
3476
3524
  // @ts-expect-error
3477
3525
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
3478
3526
  return new Uint8Array(await subtle((c) => c.exportKey(format, key), this.name))
3479
3527
  },
3480
- async DeserializePrivateKey(this: MLKEM, key, extractable) {
3528
+ async DeserializePrivateKey(this: DirectKEM, key, extractable) {
3481
3529
  // @ts-expect-error
3482
3530
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
3483
3531
  // @ts-expect-error
@@ -3487,7 +3535,7 @@ function MLKEM_SHARED(): KEM_BASE {
3487
3535
  this.name,
3488
3536
  )
3489
3537
  },
3490
- async Encap(this: MLKEM, pkR) {
3538
+ async Encap(this: DirectKEM, pkR) {
3491
3539
  assertKeyAlgorithm(pkR, this.algorithm)
3492
3540
 
3493
3541
  const { sharedKey, ciphertext } = (await subtle(
@@ -3498,7 +3546,7 @@ function MLKEM_SHARED(): KEM_BASE {
3498
3546
 
3499
3547
  return { shared_secret: new Uint8Array(sharedKey), enc: new Uint8Array(ciphertext) }
3500
3548
  },
3501
- async Decap(this: MLKEM, enc, skR, _pkR) {
3549
+ async Decap(this: DirectKEM, enc, skR, _pkR) {
3502
3550
  assertKeyAlgorithm(skR, this.algorithm)
3503
3551
  return new Uint8Array(
3504
3552
  await subtle(
@@ -3511,6 +3559,25 @@ function MLKEM_SHARED(): KEM_BASE {
3511
3559
  }
3512
3560
  }
3513
3561
 
3562
+ function createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk }: KEMParams): DirectKEM {
3563
+ const kdf = KDF_SHAKE256()
3564
+ // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3565
+ kdf.name = name
3566
+ return {
3567
+ id,
3568
+ suite_id: concat(L_KEM, I2OSP(id, 2)),
3569
+ type: 'KEM',
3570
+ name,
3571
+ Nsecret,
3572
+ Nenc,
3573
+ Npk,
3574
+ Nsk,
3575
+ algorithm: { name },
3576
+ kdf,
3577
+ ...DIRECT_KEM_SHARED(),
3578
+ }
3579
+ }
3580
+
3514
3581
  // ============================================================================
3515
3582
  // KEM (Key Encapsulation Mechanism) - ML-KEM Suite Exports
3516
3583
  // ============================================================================
@@ -3536,27 +3603,16 @@ function MLKEM_SHARED(): KEM_BASE {
3536
3603
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3537
3604
  *
3538
3605
  * @group KEM Algorithms
3539
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3606
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3540
3607
  */
3541
- export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3608
+ export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): DirectKEM {
3542
3609
  const id = 0x0040
3543
3610
  const name = 'ML-KEM-512'
3544
- const kdf = KDF_SHAKE256()
3545
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3546
- kdf.name = name
3547
- return {
3548
- id,
3549
- suite_id: concat(L_KEM, I2OSP(id, 2)),
3550
- type: 'KEM',
3551
- name,
3552
- Nsecret: 32,
3553
- Nenc: 768,
3554
- Npk: 800,
3555
- Nsk: 64,
3556
- algorithm: { name: 'ML-KEM-512' },
3557
- kdf,
3558
- ...MLKEM_SHARED(),
3559
- }
3611
+ const Nsecret = 32
3612
+ const Nenc = 768
3613
+ const Npk = 800
3614
+ const Nsk = 64
3615
+ return createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk })
3560
3616
  }
3561
3617
 
3562
3618
  /**
@@ -3576,27 +3632,16 @@ export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3576
3632
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3577
3633
  *
3578
3634
  * @group KEM Algorithms
3579
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3635
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3580
3636
  */
3581
- export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3637
+ export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): DirectKEM {
3582
3638
  const id = 0x0041
3583
3639
  const name = 'ML-KEM-768'
3584
- const kdf = KDF_SHAKE256()
3585
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3586
- kdf.name = name
3587
- return {
3588
- id,
3589
- suite_id: concat(L_KEM, I2OSP(id, 2)),
3590
- type: 'KEM',
3591
- name,
3592
- Nsecret: 32,
3593
- Nenc: 1088,
3594
- Npk: 1184,
3595
- Nsk: 64,
3596
- algorithm: { name: 'ML-KEM-768' },
3597
- kdf,
3598
- ...MLKEM_SHARED(),
3599
- }
3640
+ const Nsecret = 32
3641
+ const Nenc = 1088
3642
+ const Npk = 1184
3643
+ const Nsk = 64
3644
+ return createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk })
3600
3645
  }
3601
3646
 
3602
3647
  /**
@@ -3616,27 +3661,16 @@ export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3616
3661
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3617
3662
  *
3618
3663
  * @group KEM Algorithms
3619
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3664
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3620
3665
  */
3621
- export const KEM_ML_KEM_1024: KEMFactory = function (): MLKEM {
3666
+ export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): DirectKEM {
3622
3667
  const id = 0x0042
3623
3668
  const name = 'ML-KEM-1024'
3624
- const kdf = KDF_SHAKE256()
3625
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3626
- kdf.name = name
3627
- return {
3628
- id,
3629
- suite_id: concat(L_KEM, I2OSP(id, 2)),
3630
- type: 'KEM',
3631
- name,
3632
- Nsecret: 32,
3633
- Nenc: 1568,
3634
- Npk: 1568,
3635
- Nsk: 64,
3636
- algorithm: { name: 'ML-KEM-1024' },
3637
- kdf,
3638
- ...MLKEM_SHARED(),
3639
- }
3669
+ const Nsecret = 32
3670
+ const Nenc = 1568
3671
+ const Npk = 1568
3672
+ const Nsk = 64
3673
+ return createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk })
3640
3674
  }
3641
3675
 
3642
3676
  interface WebCryptoAEAD extends AEAD {
@@ -3728,7 +3762,7 @@ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3728
3762
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3729
3763
  *
3730
3764
  * @group AEAD Algorithms
3731
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3765
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3732
3766
  */
3733
3767
  export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3734
3768
  return {
@@ -3760,7 +3794,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3760
3794
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3761
3795
  *
3762
3796
  * @group AEAD Algorithms
3763
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3797
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3764
3798
  */
3765
3799
  export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3766
3800
  return {
@@ -3792,7 +3826,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3792
3826
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3793
3827
  *
3794
3828
  * @group AEAD Algorithms
3795
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3829
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3796
3830
  */
3797
3831
  export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
3798
3832
  return {
@@ -3810,7 +3844,7 @@ export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305
3810
3844
  }
3811
3845
 
3812
3846
  // ============================================================================
3813
- // KEM (Key Encapsulation Mechanism) - Hybrid KEM Types and Implementation
3847
+ // KEM (Key Encapsulation Mechanism) - Composite Hybrid KEM Types and Implementation
3814
3848
  // ============================================================================
3815
3849
 
3816
3850
  /* c8 ignore next 5 */
@@ -3910,7 +3944,7 @@ function split(N1: number, N2: number, x: Uint8Array): [Uint8Array, Uint8Array]
3910
3944
  return [x1, x2]
3911
3945
  }
3912
3946
 
3913
- function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3947
+ function RandomScalarNist(t: CompositeHybridKEM['t'], seed: Uint8Array): Uint8Array {
3914
3948
  let sk_bigint = 0n
3915
3949
  let start = 0
3916
3950
  let end = t.Nscalar!
@@ -3927,70 +3961,70 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3927
3961
  return bigIntToUint8Array(sk_bigint, t.Nscalar!)
3928
3962
  }
3929
3963
 
3930
- /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3931
- async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
3932
- const Nout = PQTKEM.pq.Nseed + PQTKEM.t.Nseed
3964
+ /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3965
+ async function expandDecapsKeyG(kem: CompositeHybridKEM, seed: Uint8Array) {
3966
+ const Nout = kem.pq.Nseed + kem.t.Nseed
3933
3967
  const bits = Nout << 3
3934
3968
  // @ts-expect-error
3935
3969
  const algorithm: CShakeParams = { name: 'cSHAKE256', length: bits, outputLength: bits }
3936
- const seed_full = await subtle((c) => c.digest(algorithm, seed as BufferSource), PQTKEM.name)
3970
+ const seed_full = await subtle((c) => c.digest(algorithm, seed as BufferSource), kem.name)
3937
3971
 
3938
- const [seed_PQ, seed_T] = split(PQTKEM.pq.Nseed, PQTKEM.t.Nseed, new Uint8Array(seed_full))
3972
+ const [seed_PQ, seed_T] = split(kem.pq.Nseed, kem.t.Nseed, new Uint8Array(seed_full))
3939
3973
 
3940
3974
  // @ts-expect-error
3941
3975
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
3942
3976
  // @ts-expect-error
3943
3977
  const usages: [KeyUsage, KeyUsage] = ['decapsulateBits', 'encapsulateBits']
3944
3978
  const dk_PQ = await subtle(
3945
- (c) => c.importKey(format, seed_PQ as BufferSource, PQTKEM.pq.algorithm, true, [usages[0]]),
3946
- PQTKEM.name,
3979
+ (c) => c.importKey(format, seed_PQ as BufferSource, kem.pq.algorithm, true, [usages[0]]),
3980
+ kem.name,
3947
3981
  )
3948
- const ek_PQ = await getPublicKey(PQTKEM.name, dk_PQ, [usages[1]])
3982
+ const ek_PQ = await getPublicKey(kem.name, dk_PQ, [usages[1]])
3949
3983
 
3950
- const sk = PQTKEM.t.RandomScalar?.(seed_T) ?? seed_T
3951
- const { privateKey: dk_T, publicKey: ek_T } = await PQTKEM.t.GetKeyPair(sk)
3984
+ const sk = kem.t.RandomScalar?.(seed_T) ?? seed_T
3985
+ const { privateKey: dk_T, publicKey: ek_T } = await kem.t.GetKeyPair(sk)
3952
3986
 
3953
3987
  return { ek_PQ, ek_T, dk_PQ, dk_T }
3954
3988
  }
3955
3989
 
3956
- /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.3) */
3990
+ /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.3) */
3957
3991
  async function C2PRICombiner(
3958
- PQTKEM: HybridKEM,
3992
+ kem: CompositeHybridKEM,
3959
3993
  ss_PQ: Uint8Array,
3960
3994
  ss_T: Uint8Array,
3961
3995
  ct_T: Uint8Array,
3962
3996
  _ek_T: CryptoKey,
3963
3997
  label: Uint8Array,
3964
3998
  ): Promise<Uint8Array> {
3965
- const ek_T = new Uint8Array(await subtle((c) => c.exportKey('raw', _ek_T), PQTKEM.name))
3999
+ const ek_T = new Uint8Array(await subtle((c) => c.exportKey('raw', _ek_T), kem.name))
3966
4000
  const data = concat(ss_PQ, ss_T, ct_T, ek_T, label) as BufferSource
3967
- return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), PQTKEM.name))
4001
+ return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), kem.name))
3968
4002
  }
3969
4003
 
3970
- /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
4004
+ /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3971
4005
  async function prepareEncapsG(
3972
- PQTKEM: HybridKEM,
4006
+ kem: CompositeHybridKEM,
3973
4007
  ek_PQ: CryptoKey,
3974
4008
  ek_T: CryptoKey,
3975
4009
  ): Promise<[Uint8Array, Uint8Array, Uint8Array, Uint8Array]> {
3976
4010
  const res = (await subtle(
3977
4011
  // @ts-expect-error
3978
- (c) => c.encapsulateBits(PQTKEM.pq.algorithm, ek_PQ),
3979
- PQTKEM.name,
4012
+ (c) => c.encapsulateBits(kem.pq.algorithm, ek_PQ),
4013
+ kem.name,
3980
4014
  )) as { sharedKey: ArrayBuffer; ciphertext: ArrayBuffer }
3981
4015
  const ss_PQ = new Uint8Array(res.sharedKey)
3982
4016
  const ct_PQ = new Uint8Array(res.ciphertext)
3983
4017
 
3984
4018
  const { privateKey: sk_E, publicKey } = (await subtle(
3985
- (c) => c.generateKey(PQTKEM.t.algorithm, false, ['deriveBits']),
3986
- PQTKEM.name,
4019
+ (c) => c.generateKey(kem.t.algorithm, true, ['deriveBits']),
4020
+ kem.name,
3987
4021
  )) as CryptoKeyPair
3988
- const ct_T = new Uint8Array(await subtle((c) => c.exportKey('raw', publicKey), PQTKEM.name))
4022
+ const ct_T = new Uint8Array(await subtle((c) => c.exportKey('raw', publicKey), kem.name))
3989
4023
 
3990
4024
  const ss_T = new Uint8Array(
3991
4025
  await subtle(
3992
- (c) => c.deriveBits({ name: PQTKEM.t.algorithm.name, public: ek_T }, sk_E, PQTKEM.t.Nss << 3),
3993
- PQTKEM.name,
4026
+ (c) => c.deriveBits({ name: kem.t.algorithm.name, public: ek_T }, sk_E, kem.t.Nss << 3),
4027
+ kem.name,
3994
4028
  ),
3995
4029
  )
3996
4030
  checkNotAllZeros(ss_T)
@@ -3998,9 +4032,9 @@ async function prepareEncapsG(
3998
4032
  return [ss_PQ, ss_T, ct_PQ, ct_T]
3999
4033
  }
4000
4034
 
4001
- /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
4035
+ /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
4002
4036
  async function prepareDecapsG(
4003
- PQTKEM: HybridKEM,
4037
+ kem: CompositeHybridKEM,
4004
4038
  dk_PQ: CryptoKey,
4005
4039
  dk_T: CryptoKey,
4006
4040
  ct_PQ: Uint8Array,
@@ -4009,20 +4043,20 @@ async function prepareDecapsG(
4009
4043
  const ss_PQ = new Uint8Array(
4010
4044
  await subtle(
4011
4045
  // @ts-expect-error
4012
- (c) => c.decapsulateBits(PQTKEM.pq.algorithm, dk_PQ, ct_PQ),
4013
- PQTKEM.name,
4046
+ (c) => c.decapsulateBits(kem.pq.algorithm, dk_PQ, ct_PQ),
4047
+ kem.name,
4014
4048
  ),
4015
4049
  )
4016
4050
 
4017
4051
  const pub = await subtle(
4018
- (c) => c.importKey('raw', ct_T as BufferSource, PQTKEM.t.algorithm, true, []),
4019
- PQTKEM.name,
4052
+ (c) => c.importKey('raw', ct_T as BufferSource, kem.t.algorithm, true, []),
4053
+ kem.name,
4020
4054
  )
4021
4055
 
4022
4056
  const ss_T = new Uint8Array(
4023
4057
  await subtle(
4024
- (c) => c.deriveBits({ name: PQTKEM.t.algorithm.name, public: pub }, dk_T, PQTKEM.t.Nss << 3),
4025
- PQTKEM.name,
4058
+ (c) => c.deriveBits({ name: kem.t.algorithm.name, public: pub }, dk_T, kem.t.Nss << 3),
4059
+ kem.name,
4026
4060
  ),
4027
4061
  )
4028
4062
  checkNotAllZeros(ss_T)
@@ -4030,7 +4064,7 @@ async function prepareDecapsG(
4030
4064
  return [ss_PQ, ss_T]
4031
4065
  }
4032
4066
 
4033
- interface HybridKEM extends KEM {
4067
+ interface CompositeHybridKEM extends KEM<HybridKey> {
4034
4068
  readonly suite_id: Uint8Array
4035
4069
  readonly kdf: KDF
4036
4070
  readonly algorithm: KeyAlgorithm
@@ -4050,18 +4084,20 @@ interface HybridKEM extends KEM {
4050
4084
  readonly Nsk: number
4051
4085
  readonly Nscalar?: number
4052
4086
  readonly GetKeyPair: (
4053
- this: HybridKEM['t'],
4087
+ this: CompositeHybridKEM['t'],
4054
4088
  sk: Uint8Array,
4055
4089
  ) => Promise<{ privateKey: CryptoKey; publicKey: CryptoKey }>
4056
4090
  readonly order?: bigint
4057
- readonly RandomScalar?: (this: HybridKEM['t'], seed: Uint8Array) => Uint8Array
4091
+ readonly RandomScalar?: (this: CompositeHybridKEM['t'], seed: Uint8Array) => Uint8Array
4058
4092
  }
4059
4093
  }
4060
4094
 
4061
- function PQTKEM_SHARED(): KEM_BASE {
4095
+ type CompositeHybridKEMParams = KEMParams & Pick<CompositeHybridKEM, 'pq' | 't' | 'label'>
4096
+
4097
+ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4062
4098
  Object.freeze(HybridKey.prototype)
4063
4099
  return {
4064
- async DeriveKeyPair(this: HybridKEM, ikm: Uint8Array, extractable) {
4100
+ async DeriveKeyPair(this: CompositeHybridKEM, ikm: Uint8Array, extractable) {
4065
4101
  const seed = await LabeledDerive(
4066
4102
  this.kdf,
4067
4103
  this.suite_id,
@@ -4087,10 +4123,10 @@ function PQTKEM_SHARED(): KEM_BASE {
4087
4123
 
4088
4124
  return { privateKey, publicKey }
4089
4125
  },
4090
- async GenerateKeyPair(this: HybridKEM, extractable) {
4126
+ async GenerateKeyPair(this: CompositeHybridKEM, extractable) {
4091
4127
  return await this.DeriveKeyPair(crypto.getRandomValues(new Uint8Array(32)), extractable)
4092
4128
  },
4093
- async SerializePublicKey(this: HybridKEM, key) {
4129
+ async SerializePublicKey(this: CompositeHybridKEM, key) {
4094
4130
  assertKeyAlgorithm(key, this.algorithm)
4095
4131
  HybridKey.validate(key, true)
4096
4132
  // @ts-expect-error
@@ -4104,7 +4140,7 @@ function PQTKEM_SHARED(): KEM_BASE {
4104
4140
 
4105
4141
  return concat(ek_PQ, ek_T)
4106
4142
  },
4107
- async DeserializePublicKey(this: HybridKEM, key) {
4143
+ async DeserializePublicKey(this: CompositeHybridKEM, key) {
4108
4144
  // @ts-expect-error
4109
4145
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
4110
4146
  // @ts-expect-error
@@ -4118,13 +4154,13 @@ function PQTKEM_SHARED(): KEM_BASE {
4118
4154
 
4119
4155
  return new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4120
4156
  },
4121
- async SerializePrivateKey(this: HybridKEM, key) {
4157
+ async SerializePrivateKey(this: CompositeHybridKEM, key) {
4122
4158
  assertKeyAlgorithm(key, this.algorithm)
4123
4159
  HybridKey.validate(key, true)
4124
4160
 
4125
4161
  return key.getSeed(priv)
4126
4162
  },
4127
- async DeserializePrivateKey(this: HybridKEM, key, extractable) {
4163
+ async DeserializePrivateKey(this: CompositeHybridKEM, key, extractable) {
4128
4164
  const { ek_PQ, ek_T, dk_PQ, dk_T } = await expandDecapsKeyG(this, key)
4129
4165
  const publicKey = new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4130
4166
  const privateKey = new HybridKey(
@@ -4140,7 +4176,7 @@ function PQTKEM_SHARED(): KEM_BASE {
4140
4176
 
4141
4177
  return privateKey
4142
4178
  },
4143
- async Encap(this: HybridKEM, pkR) {
4179
+ async Encap(this: CompositeHybridKEM, pkR) {
4144
4180
  assertKeyAlgorithm(pkR, this.algorithm)
4145
4181
  HybridKey.validate(pkR)
4146
4182
 
@@ -4152,7 +4188,7 @@ function PQTKEM_SHARED(): KEM_BASE {
4152
4188
 
4153
4189
  return { shared_secret: ss_H, enc: ct_H }
4154
4190
  },
4155
- async Decap(this: HybridKEM, enc, skR, pkR) {
4191
+ async Decap(this: CompositeHybridKEM, enc, skR, pkR) {
4156
4192
  assertKeyAlgorithm(skR, this.algorithm)
4157
4193
  HybridKey.validate(skR)
4158
4194
 
@@ -4174,6 +4210,20 @@ function PQTKEM_SHARED(): KEM_BASE {
4174
4210
  }
4175
4211
  }
4176
4212
 
4213
+ function createCompositeHybridKEM(parameters: CompositeHybridKEMParams): CompositeHybridKEM {
4214
+ const kdf = KDF_SHAKE256()
4215
+ // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4216
+ kdf.name = parameters.name
4217
+ return {
4218
+ ...parameters,
4219
+ suite_id: concat(L_KEM, I2OSP(parameters.id, 2)),
4220
+ type: 'KEM',
4221
+ algorithm: { name: parameters.name },
4222
+ kdf,
4223
+ ...COMPOSITE_HYBRID_KEM_SHARED(),
4224
+ }
4225
+ }
4226
+
4177
4227
  // ============================================================================
4178
4228
  // KEM (Key Encapsulation Mechanism) - Hybrid KEM Suite Exports
4179
4229
  // ============================================================================
@@ -4181,7 +4231,12 @@ function PQTKEM_SHARED(): KEM_BASE {
4181
4231
  /**
4182
4232
  * Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519).
4183
4233
  *
4184
- * Depends on the following Web Cryptography algorithms being supported in the runtime:
4234
+ * Depends on one of the following Web Cryptography algorithm sets being supported in the runtime:
4235
+ *
4236
+ * - MLKEM768-X25519 key encapsulation
4237
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
4238
+ *
4239
+ * Or:
4185
4240
  *
4186
4241
  * - ML-KEM-768 key encapsulation
4187
4242
  * - X25519 key agreement
@@ -4195,26 +4250,24 @@ function PQTKEM_SHARED(): KEM_BASE {
4195
4250
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4196
4251
  *
4197
4252
  * @group KEM Algorithms
4198
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4253
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4199
4254
  */
4200
- export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4255
+ export const KEM_MLKEM768_X25519: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4201
4256
  const id = 0x647a
4202
4257
  const name = 'MLKEM768-X25519'
4203
- const kdf = KDF_SHAKE256()
4204
- const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20); // prettier-ignore
4205
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4206
- kdf.name = name
4207
- return {
4208
- id,
4209
- kdf,
4210
- suite_id: concat(L_KEM, I2OSP(id, 2)),
4211
- type: 'KEM',
4212
- name,
4213
- Nsecret: 32,
4214
- Nenc: 1120,
4215
- Npk: 1216,
4216
- Nsk: 32,
4217
- algorithm: { name: 'MLKEM768-X25519' },
4258
+ const Nsecret = 32
4259
+ const Nenc = 1120
4260
+ const Npk = 1216
4261
+ const Nsk = 32
4262
+ const kem = { id, name, Nsecret, Nenc, Npk, Nsk }
4263
+ // @ts-expect-error
4264
+ if (SubtleCrypto.supports?.('generateKey', name) ?? false) {
4265
+ return createDirectKEM(kem)
4266
+ }
4267
+
4268
+ const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20) // prettier-ignore
4269
+ return createCompositeHybridKEM({
4270
+ ...kem,
4218
4271
  pq: { algorithm: { name: 'ML-KEM-768' }, Nseed: 64, Npk: 1184, Nct: 1088 },
4219
4272
  t: {
4220
4273
  algorithm: { name: 'X25519' },
@@ -4231,14 +4284,18 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4231
4284
  },
4232
4285
  },
4233
4286
  label: Uint8Array.of(0x5c, 0x2e, 0x2f, 0x2f, 0x5e, 0x5c), // prettier-ignore
4234
- ...PQTKEM_SHARED(),
4235
- }
4287
+ })
4236
4288
  }
4237
4289
 
4238
4290
  /**
4239
4291
  * Hybrid KEM combining ML-KEM-768 with P-256 (MLKEM768-P256).
4240
4292
  *
4241
- * Depends on the following Web Cryptography algorithms being supported in the runtime:
4293
+ * Depends on one of the following Web Cryptography algorithm sets being supported in the runtime:
4294
+ *
4295
+ * - MLKEM768-P256 key encapsulation
4296
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
4297
+ *
4298
+ * Or:
4242
4299
  *
4243
4300
  * - ML-KEM-768 key encapsulation
4244
4301
  * - ECDH with P-256 curve
@@ -4252,25 +4309,23 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4252
4309
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4253
4310
  *
4254
4311
  * @group KEM Algorithms
4255
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4312
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4256
4313
  */
4257
- export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4314
+ export const KEM_MLKEM768_P256: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4258
4315
  const id = 0x0050
4259
4316
  const name = 'MLKEM768-P256'
4260
- const kdf = KDF_SHAKE256()
4261
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4262
- kdf.name = name
4263
- return {
4264
- id,
4265
- kdf,
4266
- suite_id: concat(L_KEM, I2OSP(id, 2)),
4267
- type: 'KEM',
4268
- name,
4269
- Nsecret: 32,
4270
- Nenc: 1153,
4271
- Npk: 1249,
4272
- Nsk: 32,
4273
- algorithm: { name: 'MLKEM768-P256' },
4317
+ const Nsecret = 32
4318
+ const Nenc = 1153
4319
+ const Npk = 1249
4320
+ const Nsk = 32
4321
+ const kem = { id, name, Nsecret, Nenc, Npk, Nsk }
4322
+ // @ts-expect-error
4323
+ if (SubtleCrypto.supports?.('generateKey', name) ?? false) {
4324
+ return createDirectKEM(kem)
4325
+ }
4326
+
4327
+ return createCompositeHybridKEM({
4328
+ ...kem,
4274
4329
  pq: { algorithm: { name: 'ML-KEM-768' }, Nseed: 64, Npk: 1184, Nct: 1088 },
4275
4330
  t: {
4276
4331
  ...P256,
@@ -4287,14 +4342,18 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4287
4342
  },
4288
4343
  },
4289
4344
  label: Uint8Array.of(0x4d, 0x4c, 0x4b, 0x45, 0x4d, 0x37, 0x36, 0x38, 0x2d, 0x50, 0x32, 0x35, 0x36), // prettier-ignore
4290
- ...PQTKEM_SHARED(),
4291
- }
4345
+ })
4292
4346
  }
4293
4347
 
4294
4348
  /**
4295
4349
  * Hybrid KEM combining ML-KEM-1024 with P-384 (MLKEM1024-P384).
4296
4350
  *
4297
- * Depends on the following Web Cryptography algorithms being supported in the runtime:
4351
+ * Depends on one of the following Web Cryptography algorithm sets being supported in the runtime:
4352
+ *
4353
+ * - MLKEM1024-P384 key encapsulation
4354
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
4355
+ *
4356
+ * Or:
4298
4357
  *
4299
4358
  * - ML-KEM-1024 key encapsulation
4300
4359
  * - ECDH with P-384 curve
@@ -4308,25 +4367,23 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4308
4367
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4309
4368
  *
4310
4369
  * @group KEM Algorithms
4311
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4370
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4312
4371
  */
4313
- export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4372
+ export const KEM_MLKEM1024_P384: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4314
4373
  const id = 0x0051
4315
4374
  const name = 'MLKEM1024-P384'
4316
- const kdf = KDF_SHAKE256()
4317
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4318
- kdf.name = name
4319
- return {
4320
- id,
4321
- kdf,
4322
- suite_id: concat(L_KEM, I2OSP(id, 2)),
4323
- type: 'KEM',
4324
- name,
4325
- Nsecret: 32,
4326
- Nenc: 1665,
4327
- Npk: 1665,
4328
- Nsk: 32,
4329
- algorithm: { name: 'MLKEM1024-P384' },
4375
+ const Nsecret = 32
4376
+ const Nenc = 1665
4377
+ const Npk = 1665
4378
+ const Nsk = 32
4379
+ const kem = { id, name, Nsecret, Nenc, Npk, Nsk }
4380
+ // @ts-expect-error
4381
+ if (SubtleCrypto.supports?.('generateKey', name) ?? false) {
4382
+ return createDirectKEM(kem)
4383
+ }
4384
+
4385
+ return createCompositeHybridKEM({
4386
+ ...kem,
4330
4387
  pq: { algorithm: { name: 'ML-KEM-1024' }, Nseed: 64, Npk: 1568, Nct: 1568 },
4331
4388
  t: {
4332
4389
  ...P384,
@@ -4344,6 +4401,5 @@ export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4344
4401
  },
4345
4402
  },
4346
4403
  label: Uint8Array.of(0x4d, 0x4c, 0x4b, 0x45, 0x4d, 0x31, 0x30, 0x32, 0x34, 0x2d, 0x50, 0x33, 0x38, 0x34), // prettier-ignore
4347
- ...PQTKEM_SHARED(),
4348
- }
4404
+ })
4349
4405
  }