hpke 1.0.4 → 1.0.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-02).
8
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03).
9
9
  *
10
10
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
11
11
  * public key.
@@ -42,11 +42,13 @@
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
46
  function ComputeNonce(base_nonce: Uint8Array, seq: number, Nn: number): Uint8Array {
46
47
  const seq_bytes = I2OSP(seq, Nn)
47
48
  return xor(base_nonce, seq_bytes)
48
49
  }
49
50
 
51
+ /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2) */
50
52
  function IncrementSeq(seq: number): number {
51
53
  // seq is guaranteed to be a safe integer due to:
52
54
  // 1. Initial value is 0
@@ -57,6 +59,7 @@ function IncrementSeq(seq: number): number {
57
59
  return ++seq
58
60
  }
59
61
 
62
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3) */
60
63
  async function ContextExport(
61
64
  suite: Triple,
62
65
  exporterSecret: Uint8Array,
@@ -68,7 +71,7 @@ async function ContextExport(
68
71
  if (!Number.isInteger(L) || L <= 0 || L > 0xffff) {
69
72
  throw new TypeError('"L" must be a positive integer not exceeding 65535')
70
73
  }
71
- const Export = stages === 1 ? ExportOneStage : ExportTwoStage
74
+ const Export = stages === 1 ? Export_OneStage : Export_TwoStage
72
75
  return await Export(suite.KDF, suite.id, exporterSecret, exporterContext, L)
73
76
  }
74
77
 
@@ -171,6 +174,7 @@ class SenderContext {
171
174
  *
172
175
  * @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
173
176
  * than the plaintext.
177
+ * @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2)
174
178
  */
175
179
  async Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
176
180
  checkUint8Array(plaintext, 'plaintext')
@@ -218,6 +222,7 @@ class SenderContext {
218
222
  * @param length - Desired length of exported secret in bytes
219
223
  *
220
224
  * @returns A Promise that resolves to the exported secret.
225
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3)
221
226
  */
222
227
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
223
228
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -318,6 +323,7 @@ class RecipientContext {
318
323
  * @param aad - Additional authenticated data
319
324
  *
320
325
  * @returns A Promise that resolves to the decrypted plaintext.
326
+ * @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2)
321
327
  */
322
328
  async Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
323
329
  checkUint8Array(ciphertext, 'ciphertext')
@@ -374,6 +380,7 @@ class RecipientContext {
374
380
  * @param length - Desired length of exported secret in bytes
375
381
  *
376
382
  * @returns A Promise that resolves to the exported secret.
383
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3)
377
384
  */
378
385
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
379
386
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -404,7 +411,7 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
404
411
  * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
405
412
  * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
406
413
  * being republished as a Standards Track document of the IETF as
407
- * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-02).
414
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03).
408
415
  *
409
416
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
410
417
  * public key. It supports two modes:
@@ -797,6 +804,7 @@ export class CipherSuite {
797
804
  * @returns A Promise that resolves to an object containing the encapsulated secret and
798
805
  * ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
799
806
  * encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
807
+ * @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.1)
800
808
  */
801
809
  async Seal(
802
810
  publicKey: Key,
@@ -845,6 +853,7 @@ export class CipherSuite {
845
853
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
846
854
  *
847
855
  * @returns A Promise that resolves to the decrypted plaintext.
856
+ * @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.1)
848
857
  */
849
858
  async Open(
850
859
  privateKey: Key | KeyPair,
@@ -892,6 +901,7 @@ export class CipherSuite {
892
901
  *
893
902
  * @returns A Promise that resolves to an object containing the encapsulated secret and the
894
903
  * exported secret.
904
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.2)
895
905
  */
896
906
  async SendExport(
897
907
  publicKey: Key,
@@ -939,6 +949,7 @@ export class CipherSuite {
939
949
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
940
950
  *
941
951
  * @returns A Promise that resolves to the exported secret.
952
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.2)
942
953
  */
943
954
  async ReceiveExport(
944
955
  privateKey: Key | KeyPair,
@@ -992,6 +1003,7 @@ export class CipherSuite {
992
1003
  *
993
1004
  * @returns A Promise that resolves to an object containing the encapsulated secret and the sender
994
1005
  * context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
1006
+ * @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1.1)
995
1007
  */
996
1008
  async SetupSender(
997
1009
  publicKey: Key,
@@ -1072,6 +1084,7 @@ export class CipherSuite {
1072
1084
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
1073
1085
  *
1074
1086
  * @returns A Promise that resolves to the recipient context.
1087
+ * @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1.1)
1075
1088
  */
1076
1089
  async SetupRecipient(
1077
1090
  privateKey: Key | KeyPair,
@@ -1257,6 +1270,8 @@ interface Triple {
1257
1270
  *
1258
1271
  * Base mode provides encryption to a public key without sender authentication. The recipient cannot
1259
1272
  * verify who encrypted the message, only that someone with access to their public key did.
1273
+ *
1274
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5)
1260
1275
  */
1261
1276
  export const MODE_BASE = 0x00
1262
1277
 
@@ -1266,6 +1281,8 @@ export const MODE_BASE = 0x00
1266
1281
  * PSK (Pre-Shared Key) mode provides encryption with authentication using a pre-shared secret. Both
1267
1282
  * sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
1268
1283
  * authentication.
1284
+ *
1285
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5)
1269
1286
  */
1270
1287
  export const MODE_PSK = 0x01
1271
1288
 
@@ -1286,7 +1303,7 @@ export const MODE_PSK = 0x01
1286
1303
  * Post-quantum/Traditional (PQ/T Hybrid):
1287
1304
  *
1288
1305
  * - {@link KEM_MLKEM768_P256 | MLKEM768-P256}
1289
- * - {@link KEM_MLKEM768_X25519 | MLKEM768-X25519 (aka X-Wing)}
1306
+ * - {@link KEM_MLKEM768_X25519 | MLKEM768-X25519}
1290
1307
  * - {@link KEM_MLKEM1024_P384 | MLKEM1024-P384}
1291
1308
  *
1292
1309
  * Post-quantum (PQ):
@@ -1475,6 +1492,7 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
1475
1492
  * ensures domain separation between different uses of the KDF in HPKE.
1476
1493
  *
1477
1494
  * @group Utilities
1495
+ * @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
1478
1496
  */
1479
1497
  export async function LabeledDerive(
1480
1498
  KDF: Pick<KDF, 'Derive'>,
@@ -1495,7 +1513,8 @@ export async function LabeledDerive(
1495
1513
  return await KDF.Derive(labeled_ikm, L)
1496
1514
  }
1497
1515
 
1498
- async function ExportOneStage(
1516
+ /** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5) */
1517
+ async function Export_OneStage(
1499
1518
  KDF: KDF,
1500
1519
  suite_id: Uint8Array,
1501
1520
  exporter_secret: Uint8Array,
@@ -1506,7 +1525,8 @@ async function ExportOneStage(
1506
1525
  return await LabeledDerive(KDF, suite_id, exporter_secret, encode('sec'), exporter_context, L)
1507
1526
  }
1508
1527
 
1509
- async function CombineSecretsOneStage(
1528
+ /** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5) */
1529
+ async function CombineSecrets_OneStage(
1510
1530
  suite: Triple,
1511
1531
  mode: number,
1512
1532
  shared_secret: Uint8Array,
@@ -1559,7 +1579,8 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
1559
1579
  }
1560
1580
  }
1561
1581
 
1562
- async function CombineSecretsTwoStage(
1582
+ /** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
1583
+ async function CombineSecrets_TwoStage(
1563
1584
  suite: Triple,
1564
1585
  mode: number,
1565
1586
  shared_secret: Uint8Array,
@@ -1608,7 +1629,8 @@ async function CombineSecretsTwoStage(
1608
1629
  return { key, base_nonce, exporter_secret }
1609
1630
  }
1610
1631
 
1611
- async function ExportTwoStage(
1632
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3) */
1633
+ async function Export_TwoStage(
1612
1634
  KDF: KDF,
1613
1635
  suite_id: Uint8Array,
1614
1636
  exporter_secret: Uint8Array,
@@ -1684,7 +1706,7 @@ async function ExportTwoStage(
1684
1706
  * )
1685
1707
  * ```
1686
1708
  *
1687
- * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
1709
+ * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.2)
1688
1710
  */
1689
1711
  export interface KDF {
1690
1712
  /** KDF algorithm identifier */
@@ -1757,6 +1779,7 @@ export interface KDF {
1757
1779
  * pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
1758
1780
  *
1759
1781
  * @group Utilities
1782
+ * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.4)
1760
1783
  */
1761
1784
  export async function LabeledExtract(
1762
1785
  KDF: Pick<KDF, 'Extract'>,
@@ -1786,6 +1809,7 @@ export async function LabeledExtract(
1786
1809
  * of the KDF in HPKE.
1787
1810
  *
1788
1811
  * @group Utilities
1812
+ * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.4)
1789
1813
  */
1790
1814
  export async function LabeledExpand(
1791
1815
  KDF: Pick<KDF, 'Expand'>,
@@ -1894,7 +1918,7 @@ export async function LabeledExpand(
1894
1918
  * )
1895
1919
  * ```
1896
1920
  *
1897
- * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
1921
+ * @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.1)
1898
1922
  */
1899
1923
  export interface KEM {
1900
1924
  /** KEM algorithm identifier */
@@ -2096,7 +2120,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
2096
2120
  * )
2097
2121
  * ```
2098
2122
  *
2099
- * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
2123
+ * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.3)
2100
2124
  */
2101
2125
  export interface AEAD {
2102
2126
  /** AEAD algorithm identifier */
@@ -2156,6 +2180,7 @@ export interface AEAD {
2156
2180
  *
2157
2181
  * @returns A Uint8Array of length w containing the big-endian representation of n
2158
2182
  * @group Utilities
2183
+ * @see [I2OSP](https://www.rfc-editor.org/rfc/rfc8017#section-4.1)
2159
2184
  */
2160
2185
  export function I2OSP(n: number, w: number): Uint8Array {
2161
2186
  if (!Number.isSafeInteger(w) || w <= 0) {
@@ -2185,6 +2210,7 @@ function KDFStages(KDF: KDF): 1 | 2 {
2185
2210
  throw new Error('unreachable')
2186
2211
  }
2187
2212
 
2213
+ /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
2188
2214
  async function KeySchedule(
2189
2215
  suite: Triple,
2190
2216
  mode: number,
@@ -2201,12 +2227,13 @@ async function KeySchedule(
2201
2227
  checkUint8Array(pskId, 'pskId')
2202
2228
 
2203
2229
  const stages = KDFStages(suite.KDF)
2204
- const CombineSecrets = stages === 1 ? CombineSecretsOneStage : CombineSecretsTwoStage
2230
+ const CombineSecrets = stages === 1 ? CombineSecrets_OneStage : CombineSecrets_TwoStage
2205
2231
 
2206
2232
  VerifyPSKInputs(psk, pskId)
2207
2233
  return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
2208
2234
  }
2209
2235
 
2236
+ /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
2210
2237
  function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
2211
2238
  if (psk.byteLength && psk_id.byteLength) {
2212
2239
  if (psk.byteLength < 32) {
@@ -2236,6 +2263,7 @@ const EXPORT_ONLY = 0xffff
2236
2263
  * This is a factory function that must be passed to the {@link CipherSuite} constructor.
2237
2264
  *
2238
2265
  * @group AEAD Algorithms
2266
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
2239
2267
  */
2240
2268
  export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
2241
2269
  return {
@@ -2367,6 +2395,7 @@ function HKDF_SHARED(): KDF_BASE {
2367
2395
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2368
2396
  *
2369
2397
  * @group KDF Algorithms
2398
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2370
2399
  */
2371
2400
  export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2372
2401
  return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
@@ -2389,6 +2418,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2389
2418
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2390
2419
  *
2391
2420
  * @group KDF Algorithms
2421
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2392
2422
  */
2393
2423
  export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2394
2424
  return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
@@ -2411,6 +2441,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2411
2441
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2412
2442
  *
2413
2443
  * @group KDF Algorithms
2444
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2414
2445
  */
2415
2446
  export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
2416
2447
  return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
@@ -2458,6 +2489,7 @@ function SHAKE_SHARED(): KDF_BASE {
2458
2489
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2459
2490
  *
2460
2491
  * @group KDF Algorithms
2492
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2461
2493
  */
2462
2494
  export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2463
2495
  return {
@@ -2487,6 +2519,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2487
2519
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2488
2520
  *
2489
2521
  * @group KDF Algorithms
2522
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2490
2523
  */
2491
2524
  export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2492
2525
  return {
@@ -2592,7 +2625,8 @@ function b64u(input: string): Uint8Array {
2592
2625
  // KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
2593
2626
  // ============================================================================
2594
2627
 
2595
- async function DeriveCandidate(
2628
+ /** @see [DeriveKeyPair (DeriveCandidate)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
2629
+ async function DeriveCandidate_TwoStage(
2596
2630
  DHKEM: DHKEM,
2597
2631
  suite_id: Uint8Array,
2598
2632
  ikm: Uint8Array,
@@ -2657,6 +2691,29 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
2657
2691
  }
2658
2692
  }
2659
2693
 
2694
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.5) */
2695
+ async function ExtractAndExpand_TwoStage(
2696
+ DHKEM: DHKEM,
2697
+ dh: Uint8Array,
2698
+ kem_context: Uint8Array,
2699
+ ): Promise<Uint8Array> {
2700
+ const eae_prk = await LabeledExtract(
2701
+ DHKEM.kdf,
2702
+ DHKEM.suite_id,
2703
+ new Uint8Array(),
2704
+ encode('eae_prk'),
2705
+ dh,
2706
+ )
2707
+ return await LabeledExpand(
2708
+ DHKEM.kdf,
2709
+ DHKEM.suite_id,
2710
+ eae_prk,
2711
+ encode('shared_secret'),
2712
+ kem_context,
2713
+ DHKEM.Nsecret,
2714
+ )
2715
+ }
2716
+
2660
2717
  // ============================================================================
2661
2718
  // KEM (Key Encapsulation Mechanism) - DHKEM Shared Implementation
2662
2719
  // ============================================================================
@@ -2705,21 +2762,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
2705
2762
  const enc = await this.SerializePublicKey(pkE)
2706
2763
  const pkRm = await this.SerializePublicKey(pkR)
2707
2764
  const kem_context = concat(enc, pkRm)
2708
- const eae_prk = await LabeledExtract(
2709
- this.kdf,
2710
- this.suite_id,
2711
- new Uint8Array(),
2712
- encode('eae_prk'),
2713
- dh,
2714
- )
2715
- const shared_secret = await LabeledExpand(
2716
- this.kdf,
2717
- this.suite_id,
2718
- eae_prk,
2719
- encode('shared_secret'),
2720
- kem_context,
2721
- this.Nsecret,
2722
- )
2765
+ const shared_secret = await ExtractAndExpand_TwoStage(this, dh, kem_context)
2723
2766
  return { shared_secret, enc }
2724
2767
  },
2725
2768
  async Decap(this: DHKEM, enc, skR, pkR) {
@@ -2746,21 +2789,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
2746
2789
 
2747
2790
  const pkRm = await this.SerializePublicKey(pkR)
2748
2791
  const kem_context = concat(enc, pkRm)
2749
- const eae_prk = await LabeledExtract(
2750
- this.kdf,
2751
- this.suite_id,
2752
- new Uint8Array(),
2753
- encode('eae_prk'),
2754
- dh,
2755
- )
2756
- const shared_secret = await LabeledExpand(
2757
- this.kdf,
2758
- this.suite_id,
2759
- eae_prk,
2760
- encode('shared_secret'),
2761
- kem_context,
2762
- this.Nsecret,
2763
- )
2792
+ const shared_secret = await ExtractAndExpand_TwoStage(this, dh, kem_context)
2764
2793
  return shared_secret
2765
2794
  },
2766
2795
  }
@@ -2950,6 +2979,7 @@ async function DeserializePrivateKeyNist(
2950
2979
  return privateKey
2951
2980
  }
2952
2981
 
2982
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
2953
2983
  async function DeriveKeyPairNist(
2954
2984
  this: DHKEM & NistCurveConfig,
2955
2985
  ikm: Uint8Array,
@@ -2957,18 +2987,18 @@ async function DeriveKeyPairNist(
2957
2987
  ) {
2958
2988
  let sk = 0n
2959
2989
  let counter = 0
2960
- let bytes: Uint8Array
2990
+ let candidate: Uint8Array
2961
2991
  while (sk === 0n || sk >= this.order) {
2962
2992
  if (counter > 255) {
2963
2993
  throw new DeriveKeyPairError('Key derivation exceeded maximum iterations')
2964
2994
  }
2965
- bytes = await DeriveCandidate(this, this.suite_id, ikm, counter)
2966
- bytes[0] = bytes[0]! & this.bitmask
2967
- sk = OS2IP(bytes)
2995
+ candidate = await DeriveCandidate_TwoStage(this, this.suite_id, ikm, counter)
2996
+ candidate[0] = candidate[0]! & this.bitmask
2997
+ sk = OS2IP(candidate)
2968
2998
  counter = counter + 1
2969
2999
  }
2970
3000
 
2971
- return GetKeyPairNist(this, bytes!, extractable, this.name)
3001
+ return GetKeyPairNist(this, candidate!, extractable, this.name)
2972
3002
  }
2973
3003
 
2974
3004
  async function GetKeyPairNist(
@@ -2997,6 +3027,7 @@ async function GetKeyPairNist(
2997
3027
  // KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
2998
3028
  // ============================================================================
2999
3029
 
3030
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
3000
3031
  async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
3001
3032
  const dkp_prk = await LabeledExtract(
3002
3033
  this.kdf,
@@ -3049,6 +3080,7 @@ const P256: NistCurveConfig = {
3049
3080
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3050
3081
  *
3051
3082
  * @group KEM Algorithms
3083
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3052
3084
  */
3053
3085
  export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory = function (): DHKEM & NistCurveConfig {
3054
3086
  const id = 0x0010
@@ -3103,6 +3135,7 @@ const P384: NistCurveConfig = {
3103
3135
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3104
3136
  *
3105
3137
  * @group KEM Algorithms
3138
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3106
3139
  */
3107
3140
  export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory = function (): DHKEM & NistCurveConfig {
3108
3141
  const id = 0x0011
@@ -3157,6 +3190,7 @@ const P521: NistCurveConfig = {
3157
3190
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3158
3191
  *
3159
3192
  * @group KEM Algorithms
3193
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3160
3194
  */
3161
3195
  export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistCurveConfig {
3162
3196
  const id = 0x0012
@@ -3202,6 +3236,7 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistC
3202
3236
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3203
3237
  *
3204
3238
  * @group KEM Algorithms
3239
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3205
3240
  */
3206
3241
  export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { pkcs8: Uint8Array } {
3207
3242
  const id = 0x0020
@@ -3248,6 +3283,7 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { p
3248
3283
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3249
3284
  *
3250
3285
  * @group KEM Algorithms
3286
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3251
3287
  */
3252
3288
  export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkcs8: Uint8Array } {
3253
3289
  const id = 0x0021
@@ -3392,6 +3428,7 @@ function MLKEM_SHARED(): KEM_BASE {
3392
3428
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3393
3429
  *
3394
3430
  * @group KEM Algorithms
3431
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3395
3432
  */
3396
3433
  export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3397
3434
  const id = 0x0040
@@ -3431,6 +3468,7 @@ export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3431
3468
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3432
3469
  *
3433
3470
  * @group KEM Algorithms
3471
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3434
3472
  */
3435
3473
  export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3436
3474
  const id = 0x0041
@@ -3470,6 +3508,7 @@ export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3470
3508
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3471
3509
  *
3472
3510
  * @group KEM Algorithms
3511
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3473
3512
  */
3474
3513
  export const KEM_ML_KEM_1024: KEMFactory = function (): MLKEM {
3475
3514
  const id = 0x0042
@@ -3558,6 +3597,7 @@ function AEAD_SHARED(): AEAD_BASE {
3558
3597
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3559
3598
  *
3560
3599
  * @group AEAD Algorithms
3600
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3561
3601
  */
3562
3602
  export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3563
3603
  return {
@@ -3589,6 +3629,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3589
3629
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3590
3630
  *
3591
3631
  * @group AEAD Algorithms
3632
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3592
3633
  */
3593
3634
  export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3594
3635
  return {
@@ -3620,6 +3661,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3620
3661
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3621
3662
  *
3622
3663
  * @group AEAD Algorithms
3664
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3623
3665
  */
3624
3666
  export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
3625
3667
  return {
@@ -3754,6 +3796,7 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3754
3796
  return bigIntToUint8Array(sk_bigint, t.Nscalar!)
3755
3797
  }
3756
3798
 
3799
+ /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3757
3800
  async function expandDecapsKeyG(PQTKEM: HybridKEM, _seed: Uint8Array) {
3758
3801
  const Nout = PQTKEM.pq.Nseed + PQTKEM.t.Nseed
3759
3802
  const bits = Nout << 3
@@ -3781,6 +3824,7 @@ async function expandDecapsKeyG(PQTKEM: HybridKEM, _seed: Uint8Array) {
3781
3824
  return { ek_PQ, ek_T, dk_PQ, dk_T }
3782
3825
  }
3783
3826
 
3827
+ /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.3) */
3784
3828
  async function C2PRICombiner(
3785
3829
  PQTKEM: HybridKEM,
3786
3830
  ss_PQ: Uint8Array,
@@ -3794,6 +3838,7 @@ async function C2PRICombiner(
3794
3838
  return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), PQTKEM.name))
3795
3839
  }
3796
3840
 
3841
+ /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3797
3842
  async function prepareEncapsG(
3798
3843
  PQTKEM: HybridKEM,
3799
3844
  ek_PQ: CryptoKey,
@@ -3824,6 +3869,7 @@ async function prepareEncapsG(
3824
3869
  return [ss_PQ, ss_T, ct_PQ, ct_T]
3825
3870
  }
3826
3871
 
3872
+ /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3827
3873
  async function prepareDecapsG(
3828
3874
  PQTKEM: HybridKEM,
3829
3875
  dk_PQ: CryptoKey,
@@ -4005,7 +4051,7 @@ function PQTKEM_SHARED(): KEM_BASE {
4005
4051
  // ============================================================================
4006
4052
 
4007
4053
  /**
4008
- * Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519 aka X-Wing).
4054
+ * Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519).
4009
4055
  *
4010
4056
  * Depends on the following Web Cryptography algorithms being supported in the runtime:
4011
4057
  *
@@ -4021,6 +4067,7 @@ function PQTKEM_SHARED(): KEM_BASE {
4021
4067
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4022
4068
  *
4023
4069
  * @group KEM Algorithms
4070
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4024
4071
  */
4025
4072
  export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4026
4073
  const id = 0x647a
@@ -4077,6 +4124,7 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4077
4124
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4078
4125
  *
4079
4126
  * @group KEM Algorithms
4127
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4080
4128
  */
4081
4129
  export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4082
4130
  const id = 0x0050
@@ -4132,6 +4180,7 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4132
4180
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4133
4181
  *
4134
4182
  * @group KEM Algorithms
4183
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4135
4184
  */
4136
4185
  export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4137
4186
  const id = 0x0051
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hpke",
3
- "version": "1.0.4",
3
+ "version": "1.0.5",
4
4
  "description": "Hybrid Public Key Encryption (HPKE) for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes",
5
5
  "keywords": [
6
6
  "browser",
@@ -43,12 +43,13 @@
43
43
  "build": "node build.cjs",
44
44
  "build:other": "npx tsc -p tsconfig.test.json && npx tsc -p tsconfig.examples.json",
45
45
  "docs": "npx typedoc",
46
- "format": "prettier --log-level silent --cache --write '**/*.{ts,mjs,cjs,json,yml}' '**/README.md'",
46
+ "format": "prettier --log-level silent --cache --write '**/*.{ts,js,mjs,cjs,json,yml}' '**/README.md'",
47
47
  "test": "node --test --no-warnings test/*.ts",
48
48
  "test:browsers": "node test/browser.mjs",
49
49
  "test:bun": "bun test ./test/*.ts",
50
50
  "test:deno": "deno test --no-check --allow-read test/*.ts",
51
- "test:docs": "./check-examples.sh"
51
+ "test:docs": "./check-examples.sh",
52
+ "test:workerd": "./test/.workerd.sh"
52
53
  },
53
54
  "devDependencies": {
54
55
  "@noble/ciphers": "^2.1.1",
@@ -58,6 +59,7 @@
58
59
  "@types/node": "^24.10.11",
59
60
  "@types/web": "^0.0.327",
60
61
  "amaro": "^1.1.7",
62
+ "esbuild": "^0.27.0",
61
63
  "playwright": "^1.58.2",
62
64
  "prettier": "^3.8.1",
63
65
  "prettier-plugin-jsdoc": "^1.8.0",