hpke 0.5.0 → 1.0.0

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