hpke 1.1.3 → 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,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()
@@ -3420,13 +3466,13 @@ export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkc
3420
3466
  // KEM (Key Encapsulation Mechanism) - ML-KEM Types and Implementation
3421
3467
  // ============================================================================
3422
3468
 
3423
- interface MLKEM extends KEM {
3469
+ interface MLKEM extends KEM<CryptoKey> {
3424
3470
  readonly suite_id: Uint8Array
3425
3471
  readonly algorithm: Readonly<KeyAlgorithm>
3426
3472
  readonly kdf: KDF
3427
3473
  }
3428
3474
 
3429
- function MLKEM_SHARED(): KEM_BASE {
3475
+ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3430
3476
  return {
3431
3477
  async DeriveKeyPair(this: MLKEM, ikm, extractable) {
3432
3478
  const dk = await LabeledDerive(
@@ -3536,9 +3582,9 @@ function MLKEM_SHARED(): KEM_BASE {
3536
3582
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3537
3583
  *
3538
3584
  * @group KEM Algorithms
3539
- * @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)
3540
3586
  */
3541
- export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3587
+ export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): MLKEM {
3542
3588
  const id = 0x0040
3543
3589
  const name = 'ML-KEM-512'
3544
3590
  const kdf = KDF_SHAKE256()
@@ -3576,9 +3622,9 @@ export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3576
3622
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3577
3623
  *
3578
3624
  * @group KEM Algorithms
3579
- * @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)
3580
3626
  */
3581
- export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3627
+ export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): MLKEM {
3582
3628
  const id = 0x0041
3583
3629
  const name = 'ML-KEM-768'
3584
3630
  const kdf = KDF_SHAKE256()
@@ -3616,9 +3662,9 @@ export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3616
3662
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3617
3663
  *
3618
3664
  * @group KEM Algorithms
3619
- * @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)
3620
3666
  */
3621
- export const KEM_ML_KEM_1024: KEMFactory = function (): MLKEM {
3667
+ export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): MLKEM {
3622
3668
  const id = 0x0042
3623
3669
  const name = 'ML-KEM-1024'
3624
3670
  const kdf = KDF_SHAKE256()
@@ -3728,7 +3774,7 @@ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3728
3774
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3729
3775
  *
3730
3776
  * @group AEAD Algorithms
3731
- * @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)
3732
3778
  */
3733
3779
  export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3734
3780
  return {
@@ -3760,7 +3806,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3760
3806
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3761
3807
  *
3762
3808
  * @group AEAD Algorithms
3763
- * @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)
3764
3810
  */
3765
3811
  export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3766
3812
  return {
@@ -3792,7 +3838,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3792
3838
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3793
3839
  *
3794
3840
  * @group AEAD Algorithms
3795
- * @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)
3796
3842
  */
3797
3843
  export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
3798
3844
  return {
@@ -3927,7 +3973,7 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3927
3973
  return bigIntToUint8Array(sk_bigint, t.Nscalar!)
3928
3974
  }
3929
3975
 
3930
- /** @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) */
3931
3977
  async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
3932
3978
  const Nout = PQTKEM.pq.Nseed + PQTKEM.t.Nseed
3933
3979
  const bits = Nout << 3
@@ -3953,7 +3999,7 @@ async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
3953
3999
  return { ek_PQ, ek_T, dk_PQ, dk_T }
3954
4000
  }
3955
4001
 
3956
- /** @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) */
3957
4003
  async function C2PRICombiner(
3958
4004
  PQTKEM: HybridKEM,
3959
4005
  ss_PQ: Uint8Array,
@@ -3967,7 +4013,7 @@ async function C2PRICombiner(
3967
4013
  return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), PQTKEM.name))
3968
4014
  }
3969
4015
 
3970
- /** @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) */
3971
4017
  async function prepareEncapsG(
3972
4018
  PQTKEM: HybridKEM,
3973
4019
  ek_PQ: CryptoKey,
@@ -3998,7 +4044,7 @@ async function prepareEncapsG(
3998
4044
  return [ss_PQ, ss_T, ct_PQ, ct_T]
3999
4045
  }
4000
4046
 
4001
- /** @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) */
4002
4048
  async function prepareDecapsG(
4003
4049
  PQTKEM: HybridKEM,
4004
4050
  dk_PQ: CryptoKey,
@@ -4030,7 +4076,7 @@ async function prepareDecapsG(
4030
4076
  return [ss_PQ, ss_T]
4031
4077
  }
4032
4078
 
4033
- interface HybridKEM extends KEM {
4079
+ interface HybridKEM extends KEM<HybridKey> {
4034
4080
  readonly suite_id: Uint8Array
4035
4081
  readonly kdf: KDF
4036
4082
  readonly algorithm: KeyAlgorithm
@@ -4058,7 +4104,7 @@ interface HybridKEM extends KEM {
4058
4104
  }
4059
4105
  }
4060
4106
 
4061
- function PQTKEM_SHARED(): KEM_BASE {
4107
+ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4062
4108
  Object.freeze(HybridKey.prototype)
4063
4109
  return {
4064
4110
  async DeriveKeyPair(this: HybridKEM, ikm: Uint8Array, extractable) {
@@ -4195,13 +4241,13 @@ function PQTKEM_SHARED(): KEM_BASE {
4195
4241
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4196
4242
  *
4197
4243
  * @group KEM Algorithms
4198
- * @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)
4199
4245
  */
4200
4246
  export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4201
4247
  const id = 0x647a
4202
4248
  const name = 'MLKEM768-X25519'
4203
4249
  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
4250
+ const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20) // prettier-ignore
4205
4251
  // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4206
4252
  kdf.name = name
4207
4253
  return {
@@ -4252,7 +4298,7 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4252
4298
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4253
4299
  *
4254
4300
  * @group KEM Algorithms
4255
- * @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)
4256
4302
  */
4257
4303
  export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4258
4304
  const id = 0x0050
@@ -4308,7 +4354,7 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4308
4354
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4309
4355
  *
4310
4356
  * @group KEM Algorithms
4311
- * @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)
4312
4358
  */
4313
4359
  export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4314
4360
  const id = 0x0051