hpke 0.5.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.ts ADDED
@@ -0,0 +1,1824 @@
1
+ /**
2
+ * Hybrid Public Key Encryption (HPKE) implementation for JavaScript runtimes.
3
+ *
4
+ * Implements an authenticated encryption encapsulation format that combines a semi-static
5
+ * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
6
+ * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
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).
9
+ *
10
+ * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
11
+ * public key.
12
+ *
13
+ * @module hpke
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+
50
+
51
+
52
+
53
+
54
+
55
+
56
+
57
+ * @group Core
58
+ */
59
+ declare class SenderContext {
60
+ #private;
61
+ constructor(suite: Triple, mode: typeof MODE_BASE | typeof MODE_PSK, key: Uint8Array, base_nonce: Uint8Array, exporter_secret: Uint8Array);
62
+ /**
63
+ * @returns The mode (0x00 = Base, 0x01 = PSK) for this context.
64
+ * @see {@link MODE_BASE}
65
+ * @see {@link MODE_PSK}
66
+ */
67
+ get mode(): number;
68
+ /**
69
+ * @returns The sequence number for this context's next {@link Seal}, initially zero, increments
70
+ * automatically with each successful {@link Seal}. The sequence number provides AEAD nonce
71
+ * uniqueness. The maximum supported sequence number in this implementation is `2^53-1`.
72
+ */
73
+ get seq(): number;
74
+ /**
75
+ * Encrypts plaintext with additional authenticated data. Each successful call automatically
76
+ * increments the sequence number to ensure nonce uniqueness.
77
+ *
78
+
79
+
80
+
81
+
82
+
83
+
84
+
85
+
86
+
87
+
88
+
89
+
90
+
91
+
92
+
93
+ * @param plaintext - Plaintext to encrypt
94
+ * @param aad - Additional authenticated data
95
+ *
96
+ * @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
97
+ * than the plaintext.
98
+ */
99
+ Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
100
+ /**
101
+ * Exports a secret using a variable-length pseudorandom function (PRF).
102
+ *
103
+ * The exported secret is indistinguishable from a uniformly random bitstring of equal length.
104
+ *
105
+
106
+
107
+
108
+
109
+
110
+
111
+
112
+
113
+
114
+
115
+
116
+
117
+ * @param exporterContext - Context for domain separation
118
+ * @param length - Desired length of exported secret in bytes
119
+ *
120
+ * @returns A Promise that resolves to the exported secret.
121
+ */
122
+ Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array>;
123
+ /**
124
+ * @returns The length in bytes of an authentication tag for the AEAD algorithm used by this
125
+ * context.
126
+ */
127
+ get Nt(): number;
128
+ }
129
+ export type { SenderContext };
130
+ /**
131
+ * Context for decrypting multiple messages and exporting secrets on the recipient side.
132
+ *
133
+ * `RecipientContext` instance is obtained from {@link CipherSuite.SetupRecipient}.
134
+ *
135
+
136
+
137
+
138
+
139
+
140
+
141
+
142
+
143
+
144
+
145
+
146
+
147
+ * @group Core
148
+ */
149
+ declare class RecipientContext {
150
+ #private;
151
+ constructor(suite: Triple, mode: typeof MODE_BASE | typeof MODE_PSK, key: Uint8Array, base_nonce: Uint8Array, exporter_secret: Uint8Array);
152
+ /**
153
+ * @returns The mode (0x00 = Base, 0x01 = PSK) for this context.
154
+ * @see {@link MODE_BASE}
155
+ * @see {@link MODE_PSK}
156
+ */
157
+ get mode(): number;
158
+ /**
159
+ * @returns The sequence number for this context's next {@link Open}, initially zero, increments
160
+ * automatically with each successful {@link Open}. The sequence number provides AEAD nonce
161
+ * uniqueness. The maximum supported sequence number in this implementation is `2^53-1`.
162
+ */
163
+ get seq(): number;
164
+ /**
165
+ * Decrypts ciphertext with additional authenticated data.
166
+ *
167
+ * Applications must ensure that ciphertexts are presented to `Open` in the exact order they were
168
+ * produced by the sender.
169
+ *
170
+
171
+
172
+
173
+
174
+
175
+
176
+
177
+
178
+
179
+
180
+
181
+
182
+
183
+
184
+
185
+ * @param ciphertext - Ciphertext to decrypt
186
+ * @param aad - Additional authenticated data
187
+ *
188
+ * @returns A Promise that resolves to the decrypted plaintext.
189
+ */
190
+ Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
191
+ /**
192
+ * Exports a secret using a variable-length pseudorandom function (PRF).
193
+ *
194
+ * The exported secret is indistinguishable from a uniformly random bitstring of equal length.
195
+ *
196
+
197
+
198
+
199
+
200
+
201
+
202
+
203
+
204
+
205
+
206
+
207
+
208
+ * @param exporterContext - Context for domain separation
209
+ * @param length - Desired length of exported secret in bytes
210
+ *
211
+ * @returns A Promise that resolves to the exported secret.
212
+ */
213
+ Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array>;
214
+ }
215
+ export type { RecipientContext };
216
+ /**
217
+ * Hybrid Public Key Encryption (HPKE) suite combining a KEM, KDF, and AEAD.
218
+ *
219
+ * Implements an authenticated encryption encapsulation format that combines a semi-static
220
+ * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
221
+ * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
222
+ * being republished as a Standards Track document of the IETF as
223
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-02).
224
+ *
225
+ * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
226
+ * public key. It supports two modes:
227
+ *
228
+ * - Base mode: Encryption to a public key without sender authentication
229
+ * - PSK mode: Encryption with pre-shared key authentication
230
+ *
231
+ * The cipher suite consists of:
232
+ *
233
+ * - KEM: Key Encapsulation Mechanism for establishing shared secrets
234
+ * - KDF: Key Derivation Function for deriving symmetric keys
235
+ * - AEAD: Authenticated Encryption with Additional Data for encryption
236
+ *
237
+ * @group Core
238
+ */
239
+ export declare class CipherSuite {
240
+ #private;
241
+ /**
242
+ * Creates a new HPKE cipher suite by combining a Key Encapsulation Mechanism (KEM), Key
243
+ * Derivation Function (KDF), and an Authenticated Encryption with Associated Data (AEAD)
244
+ * algorithm.
245
+ *
246
+ * A cipher suite defines the complete cryptographic configuration for HPKE operations. The choice
247
+ * of algorithms affects security properties, performance, and compatibility across different
248
+ * platforms and runtimes.
249
+ *
250
+
251
+
252
+
253
+
254
+
255
+
256
+
257
+
258
+
259
+
260
+
261
+
262
+
263
+
264
+
265
+
266
+
267
+
268
+
269
+
270
+
271
+
272
+
273
+
274
+
275
+
276
+
277
+
278
+
279
+
280
+
281
+
282
+
283
+
284
+
285
+
286
+
287
+
288
+
289
+
290
+
291
+
292
+ * @param KEM - KEM implementation factory. Must return an object conforming to the {@link KEM}
293
+ * interface.
294
+ * @param KDF - KDF implementation factory. Must return an object conforming to the {@link KDF}
295
+ * interface.
296
+ * @param AEAD - AEAD implementation factory. Must return an object conforming to the {@link AEAD}
297
+ * interface.
298
+ * @see {@link KEMFactory Available KEMs}
299
+ * @see {@link KDFFactory Available KDFs}
300
+ * @see {@link AEADFactory Available AEADs}
301
+ */
302
+ constructor(KEM: KEMFactory, KDF: KDFFactory, AEAD: AEADFactory);
303
+ /**
304
+ * Provides read-only access to this suite's KEM identifier, name, and other attributes.
305
+ *
306
+ * @returns An object with this suite's Key Encapsulation Mechanism (KEM) properties.
307
+ */
308
+ get KEM(): {
309
+ /** The identifier of this suite's KEM */
310
+ id: number;
311
+ /** The name of this suite's KEM */
312
+ name: string;
313
+ /** The length in bytes of this suite's KEM produced shared secret */
314
+ Nsecret: number;
315
+ /** The length in bytes of this suite's KEM produced encapsulated secret */
316
+ Nenc: number;
317
+ /** The length in bytes of this suite's KEM public key */
318
+ Npk: number;
319
+ /** The length in bytes of this suite's KEM private key */
320
+ Nsk: number;
321
+ };
322
+ /**
323
+ * Provides read-only access to this suite's KDF identifier, name, and other attributes.
324
+ *
325
+ * @returns An object with this suite's Key Derivation Function (KDF) properties.
326
+ */
327
+ get KDF(): {
328
+ /** The identifier of this suite's KDF */
329
+ id: number;
330
+ /** The name of this suite's KDF */
331
+ name: string;
332
+ /**
333
+ * When 1, this suite's KDF is a one-stage (Derive) KDF.
334
+ *
335
+ * When 2, this suite's KDF is a two-stage (Extract and Expand) KDF.
336
+ */
337
+ stages: 1 | 2;
338
+ /**
339
+ * For one-stage KDF: The security strength of this suite's KDF, in bytes.
340
+ *
341
+ * For two-stage KDF: The output size of this suite's KDF Extract() function in bytes.
342
+ */
343
+ Nh: number;
344
+ };
345
+ /**
346
+ * Provides read-only access to this suite's AEAD identifier, name, and other attributes.
347
+ *
348
+ * @returns An object with this suite's Authenticated Encryption with Associated Data (AEAD)
349
+ * cipher properties.
350
+ */
351
+ get AEAD(): {
352
+ /** The identifier of this suite's AEAD */
353
+ id: number;
354
+ /** The name of this suite's AEAD */
355
+ name: string;
356
+ /** The length in bytes of a key for this suite's AEAD */
357
+ Nk: number;
358
+ /** The length in bytes of a nonce for this suite's AEAD */
359
+ Nn: number;
360
+ /** The length in bytes of an authentication tag for this suite's AEAD */
361
+ Nt: number;
362
+ };
363
+ /**
364
+ * Generates a random key pair for this CipherSuite. By default, private keys are generated as
365
+ * non-extractable (their value cannot be exported).
366
+ *
367
+ * @category Key Management
368
+
369
+
370
+
371
+
372
+
373
+
374
+
375
+ * @param extractable - Whether the generated key pair's private key should be extractable (e.g.
376
+ * by {@link SerializePrivateKey}) (default: false)
377
+ *
378
+ * @returns A Promise that resolves to a generated key pair.
379
+ */
380
+ GenerateKeyPair(extractable?: boolean): Promise<KeyPair>;
381
+ /**
382
+ * Deterministically derives a key pair for this CipherSuite's KEM from input keying material. By
383
+ * default, private keys are derived as non-extractable (their value cannot be exported).
384
+ *
385
+ * > [!CAUTION]\
386
+ * > Input keying material must not be reused elsewhere, particularly not with `DeriveKeyPair()` of
387
+ * > a different KEM. Re-use across different KEMs could leak information about the private key.
388
+ *
389
+ * > [!CAUTION]\
390
+ * > Input keying material should be generated from a cryptographically secure random source or
391
+ * > derived from high-entropy secret material.
392
+ *
393
+ * @category Key Management
394
+
395
+
396
+
397
+
398
+
399
+
400
+
401
+
402
+ * @param ikm - Input keying material (must be at least {@link CipherSuite.KEM Nsk} bytes)
403
+ * @param extractable - Whether the derived key pair's private key should be extractable (e.g. by
404
+ * {@link SerializePrivateKey}) (default: false)
405
+ *
406
+ * @returns A Promise that resolves to the derived key pair.
407
+ */
408
+ DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair>;
409
+ /**
410
+ * Serializes an extractable private key to bytes.
411
+ *
412
+ * @category Key Management
413
+
414
+
415
+
416
+
417
+
418
+
419
+
420
+
421
+ * @param privateKey - Private key to serialize
422
+ *
423
+ * @returns A Promise that resolves to the serialized private key.
424
+ */
425
+ SerializePrivateKey(privateKey: Key): Promise<Uint8Array>;
426
+ /**
427
+ * Serializes a public key to bytes.
428
+ *
429
+ * @category Key Management
430
+
431
+
432
+
433
+
434
+
435
+
436
+
437
+
438
+ * @param publicKey - Public key to serialize
439
+ *
440
+ * @returns A Promise that resolves to the serialized public key.
441
+ */
442
+ SerializePublicKey(publicKey: Key): Promise<Uint8Array>;
443
+ /**
444
+ * Deserializes a private key from bytes. By default, private keys are deserialized as
445
+ * non-extractable (their value cannot be exported).
446
+ *
447
+ * @category Key Management
448
+
449
+
450
+
451
+
452
+
453
+
454
+
455
+
456
+ * @param privateKey - Serialized private key (must be exactly {@link CipherSuite.KEM Nsk} bytes)
457
+ * @param extractable - Whether the deserialized private key should be extractable (e.g. by
458
+ * {@link SerializePrivateKey}) (default: false)
459
+ *
460
+ * @returns A Promise that resolves to the deserialized private key.
461
+ */
462
+ DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<Key>;
463
+ /**
464
+ * Deserializes a public key from bytes. Public keys are always deserialized as extractable (their
465
+ * value can be exported, e.g. by {@link SerializePublicKey}).
466
+ *
467
+ * @category Key Management
468
+
469
+
470
+
471
+
472
+
473
+
474
+
475
+
476
+ * @param publicKey - Serialized public key (must be exactly {@link CipherSuite.KEM Npk} bytes)
477
+ *
478
+ * @returns A Promise that resolves to the deserialized public key.
479
+ */
480
+ DeserializePublicKey(publicKey: Uint8Array): Promise<Key>;
481
+ /**
482
+ * Single-shot API for encrypting a single message. It combines context setup and encryption in
483
+ * one call.
484
+ *
485
+ * Mode selection:
486
+ *
487
+ * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
488
+ * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
489
+ *
490
+ * @category Single-Shot APIs
491
+
492
+
493
+
494
+
495
+
496
+
497
+
498
+
499
+
500
+
501
+
502
+ * @param publicKey - Recipient's public key
503
+ * @param plaintext - Plaintext to encrypt
504
+ * @param options - Options
505
+ * @param options.aad - Additional authenticated data passed to the AEAD
506
+ * @param options.info - Application-supplied information
507
+ * @param options.psk - Pre-shared key (for PSK modes)
508
+ * @param options.pskId - Pre-shared key identifier (for PSK modes)
509
+ *
510
+ * @returns A Promise that resolves to an object containing the encapsulated secret and
511
+ * ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
512
+ * encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
513
+ */
514
+ Seal(publicKey: Key, plaintext: Uint8Array, options?: {
515
+ aad?: Uint8Array;
516
+ info?: Uint8Array;
517
+ psk?: Uint8Array;
518
+ pskId?: Uint8Array;
519
+ }): Promise<{
520
+ encapsulatedSecret: Uint8Array;
521
+ ciphertext: Uint8Array;
522
+ }>;
523
+ /**
524
+ * Single-shot API for decrypting a single message.
525
+ *
526
+ * It combines context setup and decryption in one call.
527
+ *
528
+ * Mode selection:
529
+ *
530
+ * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
531
+ * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
532
+ *
533
+ * @category Single-Shot APIs
534
+
535
+
536
+
537
+
538
+
539
+
540
+
541
+
542
+
543
+
544
+
545
+
546
+
547
+ * @param privateKey - Recipient's private key or key pair
548
+ * @param encapsulatedSecret - Encapsulated secret from the sender
549
+ * @param ciphertext - Ciphertext to decrypt
550
+ * @param options - Options
551
+ * @param options.aad - Additional authenticated data
552
+ * @param options.info - Application-supplied information
553
+ * @param options.psk - Pre-shared key (for PSK mode)
554
+ * @param options.pskId - Pre-shared key identifier (for PSK mode)
555
+ *
556
+ * @returns A Promise that resolves to the decrypted plaintext.
557
+ */
558
+ Open(privateKey: Key | KeyPair, encapsulatedSecret: Uint8Array, ciphertext: Uint8Array, options?: {
559
+ aad?: Uint8Array;
560
+ info?: Uint8Array;
561
+ psk?: Uint8Array;
562
+ pskId?: Uint8Array;
563
+ }): Promise<Uint8Array>;
564
+ /**
565
+ * Single-shot API for deriving a secret known only to sender and recipient.
566
+ *
567
+ * It combines context setup and secret export in one call.
568
+ *
569
+ * The exported secret is indistinguishable from a uniformly random bitstring of equal length.
570
+ *
571
+ * @category Single-Shot APIs
572
+
573
+
574
+
575
+
576
+
577
+
578
+
579
+
580
+
581
+
582
+
583
+
584
+
585
+
586
+
587
+ * @param publicKey - Recipient's public key
588
+ * @param exporterContext - Context of the export operation
589
+ * @param length - Desired length of exported secret in bytes
590
+ * @param options - Options
591
+ * @param options.info - Application-supplied information
592
+ * @param options.psk - Pre-shared key (for PSK modes)
593
+ * @param options.pskId - Pre-shared key identifier (for PSK modes)
594
+ *
595
+ * @returns A Promise that resolves to an object containing the encapsulated secret and the
596
+ * exported secret.
597
+ */
598
+ SendExport(publicKey: Key, exporterContext: Uint8Array, length: number, options?: {
599
+ info?: Uint8Array;
600
+ psk?: Uint8Array;
601
+ pskId?: Uint8Array;
602
+ }): Promise<{
603
+ encapsulatedSecret: Uint8Array;
604
+ exportedSecret: Uint8Array;
605
+ }>;
606
+ /**
607
+ * Single-shot API for receiving an exported secret.
608
+ *
609
+ * It combines context setup and secret export in one call.
610
+ *
611
+ * @category Single-Shot APIs
612
+
613
+
614
+
615
+
616
+
617
+
618
+
619
+
620
+
621
+
622
+
623
+
624
+
625
+
626
+
627
+
628
+
629
+
630
+
631
+ * @param privateKey - Recipient's private key or key pair
632
+ * @param encapsulatedSecret - Encapsulated secret from the sender
633
+ * @param exporterContext - Context of the export operation
634
+ * @param length - Desired length of exported secret in bytes
635
+ * @param options - Options
636
+ * @param options.info - Application-supplied information
637
+ * @param options.psk - Pre-shared key (for PSK mode)
638
+ * @param options.pskId - Pre-shared key identifier (for PSK mode)
639
+ *
640
+ * @returns A Promise that resolves to the exported secret.
641
+ */
642
+ ReceiveExport(privateKey: Key | KeyPair, encapsulatedSecret: Uint8Array, exporterContext: Uint8Array, length: number, options?: {
643
+ info?: Uint8Array;
644
+ psk?: Uint8Array;
645
+ pskId?: Uint8Array;
646
+ }): Promise<Uint8Array>;
647
+ /**
648
+ * Establishes a sender encryption context.
649
+ *
650
+ * Creates a context that can be used to encrypt multiple messages to the same recipient,
651
+ * amortizing the cost of the public key operations.
652
+ *
653
+ * Mode selection:
654
+ *
655
+ * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
656
+ * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
657
+ *
658
+ * The returned context maintains a sequence number that increments with each encryption, ensuring
659
+ * nonce uniqueness.
660
+ *
661
+ * @category Encryption Context
662
+
663
+
664
+
665
+
666
+
667
+
668
+
669
+
670
+
671
+
672
+
673
+
674
+
675
+
676
+
677
+
678
+
679
+
680
+ * @param publicKey - Recipient's public key
681
+ * @param options - Options
682
+ * @param options.info - Application-supplied information
683
+ * @param options.psk - Pre-shared key (for PSK modes)
684
+ * @param options.pskId - Pre-shared key identifier (for PSK modes)
685
+ *
686
+ * @returns A Promise that resolves to an object containing the encapsulated secret and the sender
687
+ * context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
688
+ */
689
+ SetupSender(publicKey: Key, options?: {
690
+ info?: Uint8Array;
691
+ psk?: Uint8Array;
692
+ pskId?: Uint8Array;
693
+ }): Promise<{
694
+ encapsulatedSecret: Uint8Array;
695
+ ctx: SenderContext;
696
+ }>;
697
+ /**
698
+ * Establishes a recipient decryption context.
699
+ *
700
+ * Creates a context that can be used to decrypt multiple messages from the same sender.
701
+ *
702
+ * Mode selection:
703
+ *
704
+ * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
705
+ * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
706
+ *
707
+ * @category Encryption Context
708
+
709
+
710
+
711
+
712
+
713
+
714
+
715
+
716
+
717
+
718
+
719
+
720
+
721
+
722
+
723
+
724
+
725
+
726
+
727
+
728
+
729
+
730
+
731
+
732
+
733
+
734
+
735
+ * @param privateKey - Recipient's private key or key pair
736
+ * @param encapsulatedSecret - Encapsulated secret from the sender
737
+ * @param options - Options
738
+ * @param options.info - Application-supplied information
739
+ * @param options.psk - Pre-shared key (for PSK mode)
740
+ * @param options.pskId - Pre-shared key identifier (for PSK mode)
741
+ *
742
+ * @returns A Promise that resolves to the recipient context.
743
+ */
744
+ SetupRecipient(privateKey: Key | KeyPair, encapsulatedSecret: Uint8Array, options?: {
745
+ info?: Uint8Array;
746
+ psk?: Uint8Array;
747
+ pskId?: Uint8Array;
748
+ }): Promise<RecipientContext>;
749
+ }
750
+ /**
751
+ * Error thrown when input validation fails.
752
+ *
753
+ * @ignore
754
+ * @group Errors
755
+ */
756
+ export declare class ValidationError extends Error {
757
+ constructor(message?: string, options?: {
758
+ cause?: unknown;
759
+ });
760
+ }
761
+ /**
762
+ * Error thrown when key deserialization fails.
763
+ *
764
+ * @ignore
765
+ * @group Errors
766
+ */
767
+ export declare class DeserializeError extends Error {
768
+ constructor(message?: string, options?: {
769
+ cause?: unknown;
770
+ });
771
+ }
772
+ /**
773
+ * Error thrown when encapsulation operation fails.
774
+ *
775
+ * @ignore
776
+ * @group Errors
777
+ */
778
+ export declare class EncapError extends Error {
779
+ constructor(message?: string, options?: {
780
+ cause?: unknown;
781
+ });
782
+ }
783
+ /**
784
+ * Error thrown when decapsulation operation fails.
785
+ *
786
+ * @ignore
787
+ * @group Errors
788
+ */
789
+ export declare class DecapError extends Error {
790
+ constructor(message?: string, options?: {
791
+ cause?: unknown;
792
+ });
793
+ }
794
+ /**
795
+ * Error thrown when AEAD decryption (open) operation fails.
796
+ *
797
+ * @ignore
798
+ * @group Errors
799
+ */
800
+ export declare class OpenError extends Error {
801
+ constructor(message?: string, options?: {
802
+ cause?: unknown;
803
+ });
804
+ }
805
+ /**
806
+ * Error thrown when the message sequence number limit is reached.
807
+ *
808
+ * @ignore
809
+ * @group Errors
810
+ */
811
+ export declare class MessageLimitReachedError extends Error {
812
+ constructor(message?: string, options?: {
813
+ cause?: unknown;
814
+ });
815
+ }
816
+ /**
817
+ * Error thrown when key pair derivation fails.
818
+ *
819
+ * @ignore
820
+ * @group Errors
821
+ */
822
+ export declare class DeriveKeyPairError extends Error {
823
+ constructor(message?: string, options?: {
824
+ cause?: unknown;
825
+ });
826
+ }
827
+ /**
828
+ * Error thrown when the runtime doesn't support an algorithm.
829
+ *
830
+ * @ignore
831
+ * @group Errors
832
+ */
833
+ export declare class NotSupportedError extends Error {
834
+ constructor(message?: string, options?: {
835
+ cause?: unknown;
836
+ });
837
+ }
838
+ interface Triple {
839
+ readonly id: Uint8Array;
840
+ readonly KEM: Readonly<KEM>;
841
+ readonly KDF: Readonly<KDF>;
842
+ readonly AEAD: Readonly<AEAD>;
843
+ }
844
+ /**
845
+ * Mode identifier for Base mode (0x00).
846
+ *
847
+ * Base mode provides encryption to a public key without sender authentication. The recipient cannot
848
+ * verify who encrypted the message, only that someone with access to their public key did.
849
+ */
850
+ export declare const MODE_BASE = 0;
851
+ /**
852
+ * Mode identifier for PSK mode (0x01).
853
+ *
854
+ * PSK (Pre-Shared Key) mode provides encryption with authentication using a pre-shared secret. Both
855
+ * sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
856
+ * authentication.
857
+ */
858
+ export declare const MODE_PSK = 1;
859
+ /**
860
+ * Factory function that returns a KEM implementation.
861
+ *
862
+ * The following [Web Cryptography](https://www.w3.org/TR/webcrypto-2/)-based implementations are
863
+ * exported by this module:
864
+ *
865
+ * Traditional:
866
+ *
867
+ * - {@link KEM_DHKEM_P256_HKDF_SHA256 | DHKEM(P-256, HKDF-SHA256)}
868
+ * - {@link KEM_DHKEM_P384_HKDF_SHA384 | DHKEM(P-384, HKDF-SHA384)}
869
+ * - {@link KEM_DHKEM_P521_HKDF_SHA512 | DHKEM(P-521, HKDF-SHA512)}
870
+ * - {@link KEM_DHKEM_X25519_HKDF_SHA256 | DHKEM(X25519, HKDF-SHA256)}
871
+ * - {@link KEM_DHKEM_X448_HKDF_SHA512 | DHKEM(X448, HKDF-SHA512)}
872
+ *
873
+ * Post-quantum/Traditional (PQ/T Hybrid):
874
+ *
875
+ * - {@link KEM_MLKEM768_P256 | MLKEM768-P256}
876
+ * - {@link KEM_MLKEM768_X25519 | MLKEM768-X25519 (aka X-Wing)}
877
+ * - {@link KEM_MLKEM1024_P384 | MLKEM1024-P384}
878
+ *
879
+ * Post-quantum (PQ):
880
+ *
881
+ * - {@link KEM_ML_KEM_512 | ML-KEM-512}
882
+ * - {@link KEM_ML_KEM_768 | ML-KEM-768}
883
+ * - {@link KEM_ML_KEM_1024 | ML-KEM-1024}
884
+ *
885
+ * > [!TIP]\
886
+ * > {@link CipherSuite} is not limited to using only these exported KEM implementations. Any function
887
+ * > returning an object conforming to the {@link KEM} interface can be used. Such implementations not
888
+ * > reliant on Web Cryptography are exported by
889
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
890
+ */
891
+ export type KEMFactory = () => Readonly<KEM>;
892
+ /**
893
+ * Factory function that returns a KDF implementation.
894
+ *
895
+ * The following [Web Cryptography](https://www.w3.org/TR/webcrypto-2/)-based implementations are
896
+ * exported by this module:
897
+ *
898
+ * - {@link KDF_HKDF_SHA256 | HKDF-SHA256}
899
+ * - {@link KDF_HKDF_SHA384 | HKDF-SHA384}
900
+ * - {@link KDF_HKDF_SHA512 | HKDF-SHA512}
901
+ * - {@link KDF_SHAKE128 | SHAKE128}
902
+ * - {@link KDF_SHAKE256 | SHAKE256}
903
+ *
904
+ * > [!TIP]\
905
+ * > {@link CipherSuite} is not limited to using only these exported KDF implementations. Any function
906
+ * > returning an object conforming to the {@link KDF} interface can be used. Such implementations not
907
+ * > reliant on Web Cryptography are exported by
908
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
909
+ */
910
+ export type KDFFactory = () => Readonly<KDF>;
911
+ /**
912
+ * Factory function that returns an AEAD implementation.
913
+ *
914
+ * The following [Web Cryptography](https://www.w3.org/TR/webcrypto-2/)-based implementations are
915
+ * exported by this module:
916
+ *
917
+ * - {@link AEAD_AES_128_GCM | AES-128-GCM}
918
+ * - {@link AEAD_AES_256_GCM | AES-256-GCM}
919
+ * - {@link AEAD_ChaCha20Poly1305 | ChaCha20Poly1305}
920
+ * - {@link AEAD_EXPORT_ONLY | Export-only}
921
+ *
922
+ * > [!TIP]\
923
+ * > {@link CipherSuite} is not limited to using only these exported AEAD implementations. Any function
924
+ * > returning an object conforming to the {@link AEAD} interface can be used. Such implementations not
925
+ * > reliant on Web Cryptography are exported by
926
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
927
+ */
928
+ export type AEADFactory = () => Readonly<AEAD>;
929
+ /**
930
+ * Represents a cryptographic key pair consisting of a public key and private key.
931
+ *
932
+ * These keys are used throughout HPKE for key encapsulation mechanisms (KEM). Key pairs are
933
+ * randomly generated using {@link CipherSuite.GenerateKeyPair} or deterministically derived from a
934
+ * seed using {@link CipherSuite.DeriveKeyPair}.
935
+ *
936
+ * Key Usage:
937
+ *
938
+ * - Public Key: Used by senders for encryption operations (passed to {@link CipherSuite.SetupSender}
939
+ * or {@link CipherSuite.Seal}). These keys are distributed by recipients.
940
+ * - Private Key: Used by recipients for decryption operations (passed to
941
+ * {@link CipherSuite.SetupRecipient} or {@link CipherSuite.Open}). These are not distributed and
942
+ * kept private.
943
+ */
944
+ export interface KeyPair {
945
+ /** The public key, used for encryption operations. */
946
+ readonly publicKey: Readonly<Key>;
947
+ /** The private key, used for decryption operations. */
948
+ readonly privateKey: Readonly<Key>;
949
+ }
950
+ /**
951
+ * A minimal key representation interface.
952
+ *
953
+ * This interface is designed to be compatible with Web Cryptography's CryptoKey objects while
954
+ * allowing for custom key implementations that may not have all CryptoKey properties. It includes
955
+ * only the essential properties needed for HPKE operations and validations.
956
+ *
957
+ * Keys are created through {@link CipherSuite.GenerateKeyPair}, {@link CipherSuite.DeriveKeyPair},
958
+ * {@link CipherSuite.DeserializePrivateKey}, or {@link CipherSuite.DeserializePublicKey}.
959
+ */
960
+ export interface Key {
961
+ /** The key algorithm properties */
962
+ readonly algorithm: {
963
+ /** The algorithm identifier for the key. */
964
+ name: string;
965
+ };
966
+ /** Whether the key material can be extracted. */
967
+ readonly extractable: boolean;
968
+ /** The type of key: 'private' or 'public' */
969
+ readonly type: 'private' | 'public' | (string & {});
970
+ }
971
+ /**
972
+ * Concatenates multiple Uint8Array buffers into a single Uint8Array. It's exported for use in
973
+ * custom KEM, KDF, or AEAD implementations.
974
+ *
975
+ * @param buffers - Variable number of Uint8Array buffers to concatenate
976
+ *
977
+ * @returns A new Uint8Array containing all input buffers concatenated in order
978
+ * @group Utilities
979
+ */
980
+ export declare function concat(...buffers: Uint8Array[]): Uint8Array;
981
+ /**
982
+ * Encodes an ASCII string into a Uint8Array.
983
+ *
984
+ * This utility function converts ASCII strings to byte arrays. It's exported for use in custom KEM,
985
+ * KDF, or AEAD implementations to encode identifiers or HPKE suite_id values.
986
+ *
987
+ * @param string - ASCII string to encode
988
+ *
989
+ * @returns A Uint8Array containing the ASCII byte values
990
+ * @group Utilities
991
+ */
992
+ export declare function encode(string: string): Uint8Array;
993
+ /**
994
+ * Performs labeled key derivation for one-stage KDFs.
995
+ *
996
+ * This function implements the LabeledDerive operation as specified in the HPKE specification for
997
+ * use with one-stage KDFs. It constructs a labeled input by concatenating:
998
+ *
999
+ * - The input keying material (`ikm`)
1000
+ * - The version string "HPKE-v1"
1001
+ * - The suite identifier (`suite_id`)
1002
+ * - A length-prefixed label
1003
+ * - The desired output length as a 2-byte encoding
1004
+ * - Additional context
1005
+ *
1006
+ * The labeled input is then passed to the KDF's Derive function to produce L bytes of output. This
1007
+ * ensures domain separation between different uses of the KDF in HPKE.
1008
+ *
1009
+ * @group Utilities
1010
+ */
1011
+ export declare function LabeledDerive(KDF: Pick<KDF, 'Derive'>, suite_id: Uint8Array, ikm: Uint8Array, label: Uint8Array, context: Uint8Array, L: number): Promise<Uint8Array>;
1012
+ /**
1013
+ * Key Derivation Function (KDF) implementation interface.
1014
+ *
1015
+ * This implementation interface defines the contract for additional KDF implementations to be
1016
+ * usable with {@link CipherSuite}. While this module provides built-in KDF implementations based on
1017
+ * [Web Cryptography](https://www.w3.org/TR/webcrypto-2/), this interface is exported to allow
1018
+ * custom KDF implementations that may not rely on Web Cryptography (e.g., using native bindings,
1019
+ * alternative crypto libraries, or specialized hardware).
1020
+ *
1021
+ * Custom KDF implementations must conform to this interface to be compatible with
1022
+ * {@link CipherSuite} and its APIs.
1023
+ *
1024
+ * KDF implementations are either one-stage or two-stage:
1025
+ *
1026
+ * - One-stage KDFs only implement {@link Derive}. The {@link Extract} and {@link Expand} methods will
1027
+ * not be called and may be no-op implementations.
1028
+ * - Two-stage KDFs only implement {@link Extract} and {@link Expand}. The {@link Derive} method will not
1029
+ * be called and may be a no-op implementation.
1030
+ *
1031
+
1032
+
1033
+
1034
+
1035
+
1036
+
1037
+
1038
+
1039
+
1040
+
1041
+
1042
+
1043
+
1044
+
1045
+
1046
+
1047
+
1048
+
1049
+
1050
+
1051
+
1052
+
1053
+
1054
+
1055
+
1056
+
1057
+
1058
+
1059
+
1060
+
1061
+
1062
+
1063
+
1064
+
1065
+
1066
+
1067
+
1068
+
1069
+
1070
+
1071
+
1072
+
1073
+
1074
+
1075
+
1076
+
1077
+ * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
1078
+ */
1079
+ export interface KDF {
1080
+ /** KDF algorithm identifier */
1081
+ readonly id: number;
1082
+ /** Type discriminator, always 'KDF' */
1083
+ readonly type: 'KDF';
1084
+ /** Human-readable name of the KDF algorithm */
1085
+ readonly name: string;
1086
+ /**
1087
+ * For one-stage KDFs, the security strength of the KDF in bytes.
1088
+ *
1089
+ * For two-stage KDFs, the output size of the {@link Extract} function in bytes.
1090
+ */
1091
+ readonly Nh: number;
1092
+ /** Number of stages (1 or 2) indicating one-stage or two-stage KDF */
1093
+ readonly stages: 1 | 2;
1094
+ /**
1095
+ * Extracts a pseudorandom key from input keying material.
1096
+ *
1097
+ * @param salt - Salt value
1098
+ * @param ikm - Input keying material
1099
+ *
1100
+ * @returns A promise resolving to the pseudorandom key
1101
+ */
1102
+ Extract(salt: Uint8Array, ikm: Uint8Array): Promise<Uint8Array>;
1103
+ /**
1104
+ * Expands a pseudorandom key to the desired length.
1105
+ *
1106
+ * @param prk - Pseudorandom key
1107
+ * @param info - Context and application-specific information
1108
+ * @param L - Desired length of output keying material in bytes
1109
+ *
1110
+ * @returns A promise resolving to the output keying material
1111
+ */
1112
+ Expand(prk: Uint8Array, info: Uint8Array, L: number): Promise<Uint8Array>;
1113
+ /**
1114
+ * Derives output keying material directly from labeled input keying material.
1115
+ *
1116
+ * @param labeled_ikm - Labeled input keying material
1117
+ * @param L - Desired length of output keying material in bytes
1118
+ *
1119
+ * @returns A promise resolving to the output keying material
1120
+ */
1121
+ Derive(labeled_ikm: Uint8Array, L: number): Promise<Uint8Array>;
1122
+ }
1123
+ /**
1124
+ * Performs labeled extraction for two-stage KDFs.
1125
+ *
1126
+ * This function implements the LabeledExtract operation as specified in the HPKE specification for
1127
+ * use with two-stage KDFs. It constructs a labeled input by concatenating:
1128
+ *
1129
+ * - The version string "HPKE-v1"
1130
+ * - The suite identifier (`suite_id`)
1131
+ * - The label
1132
+ * - The input keying material (`ikm`)
1133
+ *
1134
+ * The labeled input is then passed to the KDF's Extract function along with the salt to produce a
1135
+ * pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
1136
+ *
1137
+ * @group Utilities
1138
+ */
1139
+ export declare function LabeledExtract(KDF: Pick<KDF, 'Extract'>, suite_id: Uint8Array, salt: Uint8Array, label: Uint8Array, ikm: Uint8Array): Promise<Uint8Array>;
1140
+ /**
1141
+ * Performs labeled expansion for two-stage KDFs.
1142
+ *
1143
+ * This function implements the LabeledExpand operation as specified in the HPKE specification for
1144
+ * use with two-stage KDFs. It constructs a labeled info string by concatenating:
1145
+ *
1146
+ * - The desired output length as a 2-byte encoding
1147
+ * - The version string "HPKE-v1"
1148
+ * - The suite identifier (`suite_id`)
1149
+ * - The label
1150
+ * - Additional info context
1151
+ *
1152
+ * The labeled info is then passed to the KDF's Expand function along with the pseudorandom key to
1153
+ * produce L bytes of output keying material. This ensures domain separation between different uses
1154
+ * of the KDF in HPKE.
1155
+ *
1156
+ * @group Utilities
1157
+ */
1158
+ export declare function LabeledExpand(KDF: Pick<KDF, 'Expand'>, suite_id: Uint8Array, prk: Uint8Array, label: Uint8Array, info: Uint8Array, L: number): Promise<Uint8Array>;
1159
+ /**
1160
+ * Key Encapsulation Mechanism (KEM) implementation interface.
1161
+ *
1162
+ * This implementation interface defines the contract for additional KEM implementations to be
1163
+ * usable with {@link CipherSuite}. While this module provides built-in KEM implementations based on
1164
+ * [Web Cryptography](https://www.w3.org/TR/webcrypto-2/), this interface is exported to allow
1165
+ * custom KEM implementations that may not rely on Web Cryptography (e.g., using native bindings,
1166
+ * alternative crypto libraries, or specialized hardware).
1167
+ *
1168
+ * Custom KEM implementations must conform to this interface to be compatible with
1169
+ * {@link CipherSuite} and its APIs.
1170
+ *
1171
+
1172
+
1173
+
1174
+
1175
+
1176
+
1177
+
1178
+
1179
+
1180
+
1181
+
1182
+
1183
+
1184
+
1185
+
1186
+
1187
+
1188
+
1189
+
1190
+
1191
+
1192
+
1193
+
1194
+
1195
+
1196
+
1197
+
1198
+
1199
+
1200
+
1201
+
1202
+
1203
+
1204
+
1205
+
1206
+
1207
+
1208
+
1209
+
1210
+
1211
+
1212
+
1213
+
1214
+
1215
+
1216
+
1217
+
1218
+
1219
+
1220
+
1221
+
1222
+
1223
+
1224
+
1225
+
1226
+
1227
+
1228
+
1229
+
1230
+
1231
+
1232
+
1233
+
1234
+
1235
+
1236
+
1237
+
1238
+
1239
+
1240
+
1241
+
1242
+
1243
+
1244
+
1245
+
1246
+
1247
+
1248
+
1249
+
1250
+ * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
1251
+ */
1252
+ export interface KEM {
1253
+ /** KEM algorithm identifier */
1254
+ readonly id: number;
1255
+ /** Type discriminator, always 'KEM' */
1256
+ readonly type: 'KEM';
1257
+ /** Human-readable name of the KEM algorithm */
1258
+ readonly name: string;
1259
+ /** Length in bytes of a KEM shared secret produced by this KEM */
1260
+ readonly Nsecret: number;
1261
+ /** Length in bytes of an encapsulated secret produced by this KEM */
1262
+ readonly Nenc: number;
1263
+ /** Length in bytes of a public key for this KEM */
1264
+ readonly Npk: number;
1265
+ /** Length in bytes of a private key for this KEM */
1266
+ readonly Nsk: number;
1267
+ /**
1268
+ * Derives a key pair deterministically from input keying material.
1269
+ *
1270
+ * @param ikm - Input keying material already validated to be at least {@link Nsk} bytes
1271
+ * @param extractable - Whether the private key should be extractable
1272
+ *
1273
+ * @returns A promise resolving to a {@link KeyPair}
1274
+ */
1275
+ DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair>;
1276
+ /**
1277
+ * Generates a random key pair.
1278
+ *
1279
+ * @param extractable - Whether the private key should be extractable
1280
+ *
1281
+ * @returns A promise resolving to a {@link KeyPair}
1282
+ */
1283
+ GenerateKeyPair(extractable: boolean): Promise<KeyPair>;
1284
+ /**
1285
+ * Serializes a public key to bytes.
1286
+ *
1287
+ * @param key - The public Key to serialize
1288
+ *
1289
+ * @returns A promise resolving to the serialized public key
1290
+ */
1291
+ SerializePublicKey(key: Key): Promise<Uint8Array>;
1292
+ /**
1293
+ * Deserializes a public key from bytes.
1294
+ *
1295
+ * @param key - The serialized public key already validated to be exactly {@link Npk} bytes
1296
+ *
1297
+ * @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
1298
+ */
1299
+ DeserializePublicKey(key: Uint8Array): Promise<Key>;
1300
+ /**
1301
+ * Serializes a private key to bytes.
1302
+ *
1303
+ * @param key - The private Key to serialize
1304
+ *
1305
+ * @returns A promise resolving to the serialized private key
1306
+ */
1307
+ SerializePrivateKey(key: Key): Promise<Uint8Array>;
1308
+ /**
1309
+ * Deserializes a private key from bytes.
1310
+ *
1311
+ * @param key - The serialized private key already validated to be exactly {@link Nsk} bytes
1312
+ * @param extractable - Whether the private key should be extractable
1313
+ *
1314
+ * @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
1315
+ */
1316
+ DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<Key>;
1317
+ /**
1318
+ * Encapsulates a shared secret to a recipient's public key.
1319
+ *
1320
+ * This is the sender-side operation that generates an ephemeral key pair, performs the KEM
1321
+ * operation, and returns both the shared secret and the encapsulated secret to send to the
1322
+ * recipient.
1323
+ *
1324
+ * @param pkR - The recipient's public key
1325
+ *
1326
+ * @returns A promise resolving to an object containing the shared secret and encapsulated secret
1327
+ */
1328
+ Encap(pkR: Key): Promise<{
1329
+ shared_secret: Uint8Array;
1330
+ enc: Uint8Array;
1331
+ }>;
1332
+ /**
1333
+ * Decapsulates a shared secret using a recipient's private key.
1334
+ *
1335
+ * This is the recipient-side operation that uses the private key to extract the shared secret
1336
+ * from the encapsulated secret.
1337
+ *
1338
+ * @param enc - The encapsulated secret of {@link Nenc} length
1339
+ * @param skR - The recipient's private key
1340
+ * @param pkR - The recipient's public key (when user input to {@link CipherSuite.SetupRecipient}
1341
+ * is a {@link KeyPair})
1342
+ *
1343
+ * @returns A promise resolving to the shared secret
1344
+ */
1345
+ Decap(enc: Uint8Array, skR: Key, pkR: Key | undefined): Promise<Uint8Array>;
1346
+ }
1347
+ /**
1348
+ * Authenticated Encryption with Associated Data (AEAD) implementation interface.
1349
+ *
1350
+ * This implementation interface defines the contract for additional AEAD implementations to be
1351
+ * usable with {@link CipherSuite}. While this module provides built-in AEAD implementations based on
1352
+ * [Web Cryptography](https://www.w3.org/TR/webcrypto-2/), this interface is exported to allow
1353
+ * custom AEAD implementations that may not rely on Web Cryptography (e.g., using native bindings,
1354
+ * alternative crypto libraries, or specialized hardware).
1355
+ *
1356
+ * Custom AEAD implementations must conform to this interface to be compatible with
1357
+ * {@link CipherSuite} and its APIs.
1358
+ *
1359
+
1360
+
1361
+
1362
+
1363
+
1364
+
1365
+
1366
+
1367
+
1368
+
1369
+
1370
+
1371
+
1372
+
1373
+
1374
+
1375
+
1376
+
1377
+
1378
+
1379
+
1380
+
1381
+
1382
+
1383
+
1384
+
1385
+
1386
+
1387
+
1388
+
1389
+
1390
+
1391
+
1392
+
1393
+
1394
+
1395
+
1396
+
1397
+
1398
+
1399
+
1400
+ * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
1401
+ */
1402
+ export interface AEAD {
1403
+ /** AEAD algorithm identifier */
1404
+ readonly id: number;
1405
+ /** Type discriminator, always 'AEAD' */
1406
+ readonly type: 'AEAD';
1407
+ /** Human-readable name of the AEAD algorithm */
1408
+ readonly name: string;
1409
+ /** Length in bytes of a key for this AEAD */
1410
+ readonly Nk: number;
1411
+ /** Length in bytes of a nonce for this AEAD */
1412
+ readonly Nn: number;
1413
+ /** Length in bytes of the authentication tag for this AEAD */
1414
+ readonly Nt: number;
1415
+ /**
1416
+ * Encrypts and authenticates plaintext with associated data.
1417
+ *
1418
+ * @param key - The encryption key of {@link Nk} bytes
1419
+ * @param nonce - The nonce of {@link Nn} bytes
1420
+ * @param aad - Additional authenticated data
1421
+ * @param pt - Plaintext to encrypt
1422
+ *
1423
+ * @returns A promise resolving to the ciphertext with authentication tag appended
1424
+ */
1425
+ Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>;
1426
+ /**
1427
+ * Decrypts and verifies ciphertext with associated data.
1428
+ *
1429
+ * @param key - The decryption key of {@link Nk} bytes
1430
+ * @param nonce - The nonce of {@link Nn} bytes
1431
+ * @param aad - Additional authenticated data
1432
+ * @param ct - Ciphertext with authentication tag appended
1433
+ *
1434
+ * @returns A promise resolving to the decrypted plaintext
1435
+ */
1436
+ Open(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, ct: Uint8Array): Promise<Uint8Array>;
1437
+ }
1438
+ /**
1439
+ * Integer to Octet String Primitive (I2OSP) as defined in RFC 8017. Converts a non-negative integer
1440
+ * into a byte string of specified length. It's exported for use in custom KEM, KDF, or AEAD
1441
+ * implementations.
1442
+ *
1443
+ * @param n - Non-negative safe integer to convert
1444
+ * @param w - Desired length of output in bytes
1445
+ *
1446
+ * @returns A Uint8Array of length w containing the big-endian representation of n
1447
+ * @group Utilities
1448
+ */
1449
+ export declare function I2OSP(n: number, w: number): Uint8Array;
1450
+ /**
1451
+ * Export-only AEAD mode.
1452
+ *
1453
+ * A special AEAD mode that disables encryption/decryption operations and only allows key export
1454
+ * functionality. Used when HPKE is employed solely for key agreement and derivation, not for
1455
+ * message encryption. Cannot be used with Seal/Open operations.
1456
+ *
1457
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1458
+ *
1459
+ * @group AEAD Algorithms
1460
+ */
1461
+ export declare const AEAD_EXPORT_ONLY: AEADFactory;
1462
+ /**
1463
+ * HKDF-SHA256 key derivation function.
1464
+ *
1465
+ * A two-stage KDF using HMAC-based Extract-and-Expand as specified in RFC 5869. Uses SHA-256 as the
1466
+ * hash function with an output length (Nh) of 32 bytes.
1467
+ *
1468
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1469
+ *
1470
+ * - HMAC with SHA-256
1471
+ *
1472
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1473
+ *
1474
+ * > [!TIP]\
1475
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1476
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1477
+ *
1478
+ * @group KDF Algorithms
1479
+ */
1480
+ export declare const KDF_HKDF_SHA256: KDFFactory;
1481
+ /**
1482
+ * HKDF-SHA384 key derivation function.
1483
+ *
1484
+ * A two-stage KDF using HMAC-based Extract-and-Expand as specified in RFC 5869. Uses SHA-384 as the
1485
+ * hash function with an output length (Nh) of 48 bytes.
1486
+ *
1487
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1488
+ *
1489
+ * - HMAC with SHA-384
1490
+ *
1491
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1492
+ *
1493
+ * > [!TIP]\
1494
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1495
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1496
+ *
1497
+ * @group KDF Algorithms
1498
+ */
1499
+ export declare const KDF_HKDF_SHA384: KDFFactory;
1500
+ /**
1501
+ * HKDF-SHA512 key derivation function.
1502
+ *
1503
+ * A two-stage KDF using HMAC-based Extract-and-Expand as specified in RFC 5869. Uses SHA-512 as the
1504
+ * hash function with an output length (Nh) of 64 bytes.
1505
+ *
1506
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1507
+ *
1508
+ * - HMAC with SHA-512
1509
+ *
1510
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1511
+ *
1512
+ * > [!TIP]\
1513
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1514
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1515
+ *
1516
+ * @group KDF Algorithms
1517
+ */
1518
+ export declare const KDF_HKDF_SHA512: KDFFactory;
1519
+ /**
1520
+ * SHAKE128 key derivation function.
1521
+ *
1522
+ * A one-stage KDF using the SHAKE128 extendable-output function (XOF) with an output length (Nh) of
1523
+ * 32 bytes.
1524
+ *
1525
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1526
+ *
1527
+ * - SHAKE128 (cSHAKE128 without any parameters) digest
1528
+ *
1529
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1530
+ *
1531
+ * > [!TIP]\
1532
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1533
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1534
+ *
1535
+ * @group KDF Algorithms
1536
+ */
1537
+ export declare const KDF_SHAKE128: KDFFactory;
1538
+ /**
1539
+ * SHAKE256 key derivation function.
1540
+ *
1541
+ * A one-stage KDF using the SHAKE256 extendable-output function (XOF) with an output length (Nh) of
1542
+ * 64 bytes.
1543
+ *
1544
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1545
+ *
1546
+ * - SHAKE256 (cSHAKE256 without any parameters) digest
1547
+ *
1548
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1549
+ *
1550
+ * > [!TIP]\
1551
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1552
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1553
+ *
1554
+ * @group KDF Algorithms
1555
+ */
1556
+ export declare const KDF_SHAKE256: KDFFactory;
1557
+ /**
1558
+ * Diffie-Hellman Key Encapsulation Mechanism using NIST P-256 curve and HKDF-SHA256.
1559
+ *
1560
+ * A Diffie-Hellman based KEM using the NIST P-256 elliptic curve (also known as secp256r1) with
1561
+ * HKDF-SHA256 for key derivation.
1562
+ *
1563
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1564
+ *
1565
+ * - ECDH with P-256 curve
1566
+ * - HMAC with SHA-256 (for HKDF)
1567
+ *
1568
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1569
+ *
1570
+ * > [!TIP]\
1571
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1572
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1573
+ *
1574
+ * @group KEM Algorithms
1575
+ */
1576
+ export declare const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory;
1577
+ /**
1578
+ * Diffie-Hellman Key Encapsulation Mechanism using NIST P-384 curve and HKDF-SHA384.
1579
+ *
1580
+ * A Diffie-Hellman based KEM using the NIST P-384 elliptic curve (also known as secp384r1) with
1581
+ * HKDF-SHA384 for key derivation.
1582
+ *
1583
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1584
+ *
1585
+ * - ECDH with P-384 curve
1586
+ * - HMAC with SHA-384 (for HKDF)
1587
+ *
1588
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1589
+ *
1590
+ * > [!TIP]\
1591
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1592
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1593
+ *
1594
+ * @group KEM Algorithms
1595
+ */
1596
+ export declare const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory;
1597
+ /**
1598
+ * Diffie-Hellman Key Encapsulation Mechanism using NIST P-521 curve and HKDF-SHA512.
1599
+ *
1600
+ * A Diffie-Hellman based KEM using the NIST P-521 elliptic curve (also known as secp521r1) with
1601
+ * HKDF-SHA512 for key derivation.
1602
+ *
1603
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1604
+ *
1605
+ * - ECDH with P-521 curve
1606
+ * - HMAC with SHA-512 (for HKDF)
1607
+ *
1608
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1609
+ *
1610
+ * > [!TIP]\
1611
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1612
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1613
+ *
1614
+ * @group KEM Algorithms
1615
+ */
1616
+ export declare const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory;
1617
+ /**
1618
+ * Diffie-Hellman Key Encapsulation Mechanism using Curve25519 and HKDF-SHA256.
1619
+ *
1620
+ * A Diffie-Hellman based KEM using the X25519 elliptic curve (Curve25519 for ECDH) with HKDF-SHA256
1621
+ * for key derivation.
1622
+ *
1623
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1624
+ *
1625
+ * - X25519 key agreement
1626
+ * - HMAC with SHA-256 (for HKDF)
1627
+ *
1628
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1629
+ *
1630
+ * > [!TIP]\
1631
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1632
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1633
+ *
1634
+ * @group KEM Algorithms
1635
+ */
1636
+ export declare const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory;
1637
+ /**
1638
+ * Diffie-Hellman Key Encapsulation Mechanism using Curve448 and HKDF-SHA512.
1639
+ *
1640
+ * A Diffie-Hellman based KEM using the X448 elliptic curve (Curve448 for ECDH) with HKDF-SHA512 for
1641
+ * key derivation.
1642
+ *
1643
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1644
+ *
1645
+ * - X448 key agreement
1646
+ * - HMAC with SHA-512 (for HKDF)
1647
+ *
1648
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1649
+ *
1650
+ * > [!TIP]\
1651
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1652
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1653
+ *
1654
+ * @group KEM Algorithms
1655
+ */
1656
+ export declare const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory;
1657
+ /**
1658
+ * Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-512).
1659
+ *
1660
+ * A post-quantum KEM based on structured lattices (FIPS 203 / CRYSTALS-Kyber).
1661
+ *
1662
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1663
+ *
1664
+ * - ML-KEM-512 key encapsulation
1665
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
1666
+ *
1667
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1668
+ *
1669
+ * > [!TIP]\
1670
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1671
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1672
+ *
1673
+ * @group KEM Algorithms
1674
+ */
1675
+ export declare const KEM_ML_KEM_512: KEMFactory;
1676
+ /**
1677
+ * Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-768).
1678
+ *
1679
+ * A post-quantum KEM based on structured lattices (FIPS 203 / CRYSTALS-Kyber).
1680
+ *
1681
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1682
+ *
1683
+ * - ML-KEM-768 key encapsulation
1684
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
1685
+ *
1686
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1687
+ *
1688
+ * > [!TIP]\
1689
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1690
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1691
+ *
1692
+ * @group KEM Algorithms
1693
+ */
1694
+ export declare const KEM_ML_KEM_768: KEMFactory;
1695
+ /**
1696
+ * Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-1024).
1697
+ *
1698
+ * A post-quantum KEM based on structured lattices (FIPS 203 / CRYSTALS-Kyber).
1699
+ *
1700
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1701
+ *
1702
+ * - ML-KEM-1024 key encapsulation
1703
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
1704
+ *
1705
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1706
+ *
1707
+ * > [!TIP]\
1708
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1709
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1710
+ *
1711
+ * @group KEM Algorithms
1712
+ */
1713
+ export declare const KEM_ML_KEM_1024: KEMFactory;
1714
+ /**
1715
+ * AES-128-GCM Authenticated Encryption with Associated Data (AEAD).
1716
+ *
1717
+ * Uses AES in Galois/Counter Mode with 128-bit keys.
1718
+ *
1719
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1720
+ *
1721
+ * - AES-GCM encryption and decryption
1722
+ *
1723
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1724
+ *
1725
+ * > [!TIP]\
1726
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1727
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1728
+ *
1729
+ * @group AEAD Algorithms
1730
+ */
1731
+ export declare const AEAD_AES_128_GCM: AEADFactory;
1732
+ /**
1733
+ * AES-256-GCM Authenticated Encryption with Associated Data (AEAD).
1734
+ *
1735
+ * Uses AES in Galois/Counter Mode with 256-bit keys.
1736
+ *
1737
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1738
+ *
1739
+ * - AES-GCM encryption and decryption
1740
+ *
1741
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1742
+ *
1743
+ * > [!TIP]\
1744
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1745
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1746
+ *
1747
+ * @group AEAD Algorithms
1748
+ */
1749
+ export declare const AEAD_AES_256_GCM: AEADFactory;
1750
+ /**
1751
+ * ChaCha20-Poly1305 Authenticated Encryption with Associated Data (AEAD).
1752
+ *
1753
+ * Uses ChaCha20 stream cipher with Poly1305 MAC.
1754
+ *
1755
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1756
+ *
1757
+ * - ChaCha20-Poly1305 encryption and decryption
1758
+ *
1759
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1760
+ *
1761
+ * > [!TIP]\
1762
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1763
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1764
+ *
1765
+ * @group AEAD Algorithms
1766
+ */
1767
+ export declare const AEAD_ChaCha20Poly1305: AEADFactory;
1768
+ /**
1769
+ * Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519 aka X-Wing).
1770
+ *
1771
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1772
+ *
1773
+ * - ML-KEM-768 key encapsulation
1774
+ * - X25519 key agreement
1775
+ * - SHA3-256 digest
1776
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient side for seed expansion
1777
+ *
1778
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1779
+ *
1780
+ * > [!TIP]\
1781
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1782
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1783
+ *
1784
+ * @group KEM Algorithms
1785
+ */
1786
+ export declare const KEM_MLKEM768_X25519: KEMFactory;
1787
+ /**
1788
+ * Hybrid KEM combining ML-KEM-768 with P-256 (MLKEM768-P256).
1789
+ *
1790
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1791
+ *
1792
+ * - ML-KEM-768 key encapsulation
1793
+ * - ECDH with P-256 curve
1794
+ * - SHA3-256 digest
1795
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient side for seed expansion
1796
+ *
1797
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1798
+ *
1799
+ * > [!TIP]\
1800
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1801
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1802
+ *
1803
+ * @group KEM Algorithms
1804
+ */
1805
+ export declare const KEM_MLKEM768_P256: KEMFactory;
1806
+ /**
1807
+ * Hybrid KEM combining ML-KEM-1024 with P-384 (MLKEM1024-P384).
1808
+ *
1809
+ * Depends on the following Web Cryptography algorithms being supported in the runtime:
1810
+ *
1811
+ * - ML-KEM-1024 key encapsulation
1812
+ * - ECDH with P-384 curve
1813
+ * - SHA3-256 digest
1814
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient side for seed expansion
1815
+ *
1816
+ * This is a factory function that must be passed to the {@link CipherSuite} constructor.
1817
+ *
1818
+ * > [!TIP]\
1819
+ * > An implementation of this algorithm not reliant on Web Cryptography is also exported by
1820
+ * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
1821
+ *
1822
+ * @group KEM Algorithms
1823
+ */
1824
+ export declare const KEM_MLKEM1024_P384: KEMFactory;