@alessiofrittoli/crypto-cipher 2.2.0 → 3.0.0-alpha.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.
Files changed (8) hide show
  1. package/README.md +286 -282
  2. package/dist/index.d.mts +36 -13
  3. package/dist/index.d.ts +36 -13
  4. package/dist/index.js +1 -1
  5. package/dist/index.mjs +1 -1
  6. package/dist/types.d.mts +4 -4
  7. package/dist/types.d.ts +4 -4
  8. package/package.json +34 -30
package/README.md CHANGED
@@ -13,7 +13,6 @@
13
13
  [downloads-badge]: https://img.shields.io/npm/dm/%40alessiofrittoli%2Fcrypto-cipher.svg
14
14
  [deps-badge]: https://img.shields.io/librariesio/release/npm/%40alessiofrittoli%2Fcrypto-cipher
15
15
  [deps-url]: https://libraries.io/npm/%40alessiofrittoli%2Fcrypto-cipher
16
-
17
16
  [sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2
18
17
  [sponsor-url]: https://github.com/sponsors/alessiofrittoli
19
18
 
@@ -31,8 +30,8 @@
31
30
  - [`Cipher.decrypt()`](#cipherdecrypt)
32
31
  - [`Cipher.streamEncrypt()`](#cipherstreamencrypt)
33
32
  - [`Cipher.streamDecrypt()`](#cipherstreamencrypt)
34
- - [`Cipher.hybridEncrypt()`](#cipherhybridencrypt)
35
- - [`Cipher.hybridDecrypt()`](#cipherhybriddecrypt)
33
+ - [`Cipher.hybridStreamEncrypt()`](#cipherhybridstreamencrypt)
34
+ - [`Cipher.hybridStreamDecrypt()`](#cipherhybridstreamdecrypt)
36
35
  - [Types](#types)
37
36
  - [Examples](#examples)
38
37
  - [In-memory data buffer encryption/decryption](#in-memory-data-buffer-encryptiondecryption)
@@ -103,11 +102,11 @@ Defines the minimum, maximum, and default lengths for salt.
103
102
  <details>
104
103
  <summary>Properties</summary>
105
104
 
106
- | Property | Value |
107
- |------------|-------|
108
- | `min` | 16 |
109
- | `max` | 64 |
110
- | `default` | 32 |
105
+ | Property | Value |
106
+ | --------- | ----- |
107
+ | `min` | 16 |
108
+ | `max` | 64 |
109
+ | `default` | 32 |
111
110
 
112
111
  </details>
113
112
 
@@ -120,11 +119,11 @@ Defines the minimum, maximum, and default lengths for initialization vectors (IV
120
119
  <details>
121
120
  <summary>Properties</summary>
122
121
 
123
- | Property | Value |
124
- |------------|-------|
125
- | `min` | 8 |
126
- | `max` | 32 |
127
- | `default` | 16 |
122
+ | Property | Value |
123
+ | --------- | ----- |
124
+ | `min` | 8 |
125
+ | `max` | 32 |
126
+ | `default` | 16 |
128
127
 
129
128
  </details>
130
129
 
@@ -137,11 +136,11 @@ Defines the minimum, maximum, and default lengths for authentication tags.
137
136
  <details>
138
137
  <summary>Properties</summary>
139
138
 
140
- | Property | Value |
141
- |------------|-------|
142
- | `min` | 4 |
143
- | `max` | 16 |
144
- | `default` | 16 |
139
+ | Property | Value |
140
+ | --------- | ----- |
141
+ | `min` | 4 |
142
+ | `max` | 16 |
143
+ | `default` | 16 |
145
144
 
146
145
  </details>
147
146
 
@@ -154,11 +153,11 @@ Defines the minimum, maximum, and default lengths for additional authenticated d
154
153
  <details>
155
154
  <summary>Properties</summary>
156
155
 
157
- | Property | Value |
158
- |------------|-------|
159
- | `min` | 16 |
160
- | `max` | 4096 |
161
- | `default` | 32 |
156
+ | Property | Value |
157
+ | --------- | ----- |
158
+ | `min` | 16 |
159
+ | `max` | 4096 |
160
+ | `default` | 32 |
162
161
 
163
162
  </details>
164
163
 
@@ -171,10 +170,10 @@ Specifies default AES algorithms for buffer and stream operations.
171
170
  <details>
172
171
  <summary>Properties</summary>
173
172
 
174
- | Operation | Algorithm | Description |
175
- |------------|--------------|-------------|
176
- | `buffer` | `aes-256-gcm` | Default algorithm used for buffer data encryption/decryption |
177
- | `stream` | `aes-256-cbc` | Default algorithm used for stream encryption/decryption |
173
+ | Operation | Algorithm | Description |
174
+ | --------- | ------------- | ------------------------------------------------------------ |
175
+ | `buffer` | `aes-256-gcm` | Default algorithm used for buffer data encryption/decryption |
176
+ | `stream` | `aes-256-cbc` | Default algorithm used for stream encryption/decryption |
178
177
 
179
178
  </details>
180
179
 
@@ -212,17 +211,17 @@ Supported AES algorithms:
212
211
  Encrypts an in-memory data buffer.
213
212
 
214
213
  ⚠️ This is not suitable for large data.
215
- Use [`Cipher.streamEncrypt()`](#cipherstreamencrypt) or [`Cipher.hybridEncrypt()`](#cipherhybridencrypt) methods for large data encryption.
214
+ Use [`Cipher.streamEncrypt()`](#cipherstreamencrypt) or [`Cipher.hybridStreamEncrypt()`](#cipherhybridStreamEncrypt) methods for large data encryption.
216
215
 
217
216
  <details>
218
217
 
219
218
  <summary>Parameters</summary>
220
219
 
221
- | Name | Type | Description |
222
- |----------|-------------------------|-----------------------------------------|
223
- | `data` | `CoerceToUint8ArrayInput` | Data to encrypt. |
224
- | `secret` | `CoerceToUint8ArrayInput` | Secret key for encryption. |
225
- | `options`| `Cph.Options` | (Optional) Additional encryption options.|
220
+ | Name | Type | Description |
221
+ | --------- | ------------------------- | ----------------------------------------- |
222
+ | `data` | `CoerceToUint8ArrayInput` | Data to encrypt. |
223
+ | `secret` | `CoerceToUint8ArrayInput` | Secret key for encryption. |
224
+ | `options` | `Cph.Options` | (Optional) Additional encryption options. |
226
225
 
227
226
  </details>
228
227
 
@@ -251,17 +250,17 @@ Type: `Buffer`
251
250
  Decrypts an in-memory data buffer.
252
251
 
253
252
  ⚠️ This is not suitable for large data.
254
- Use [`Cipher.streamDecrypt()`](#cipherstreamdecrypt) or [`Cipher.hybridDecrypt()`](#cipherhybriddecrypt) methods for large data decryption.
253
+ Use [`Cipher.streamDecrypt()`](#cipherstreamdecrypt) or [`Cipher.hybridStreamDecrypt()`](#cipherhybridStreamDecrypt) methods for large data decryption.
255
254
 
256
255
  <details>
257
256
 
258
257
  <summary>Parameters</summary>
259
258
 
260
- | Name | Type | Description |
261
- |----------|-------------------------|-----------------------------------------|
262
- | `data` | `CoerceToUint8ArrayInput` | Data to decrypt. |
263
- | `secret` | `CoerceToUint8ArrayInput` | Secret key for decryption. |
264
- | `options`| `Cph.Options` | (Optional) Decryption options (must match encryption).|
259
+ | Name | Type | Description |
260
+ | --------- | ------------------------- | ------------------------------------------------------ |
261
+ | `data` | `CoerceToUint8ArrayInput` | Data to decrypt. |
262
+ | `secret` | `CoerceToUint8ArrayInput` | Secret key for decryption. |
263
+ | `options` | `Cph.Options` | (Optional) Decryption options (must match encryption). |
265
264
 
266
265
  </details>
267
266
 
@@ -293,10 +292,10 @@ Encrypts a `Readable` stream to a `Writable` stream.
293
292
 
294
293
  <summary>Parameters</summary>
295
294
 
296
- | Name | Type | Description |
297
- |-----------|-----------------------------------|---------------------------------------|
298
- | `secret` | `CoerceToUint8ArrayInput` | Secret key for encryption. |
299
- | `options` | `Cph.Stream.Symmetric.EncryptOptions` | Stream encryption options. |
295
+ | Name | Type | Description |
296
+ | --------- | ------------------------------------- | -------------------------- |
297
+ | `secret` | `CoerceToUint8ArrayInput` | Secret key for encryption. |
298
+ | `options` | `Cph.Stream.Symmetric.EncryptOptions` | Stream encryption options. |
300
299
 
301
300
  </details>
302
301
 
@@ -309,7 +308,7 @@ Encrypts a `Readable` stream to a `Writable` stream.
309
308
  Type: `Cph.Stream.Symmetric.EncryptReturnType`
310
309
 
311
310
  - An object containing:
312
- - a new instance of `crypto.Cipher` allowing you to add listeners to the `cipher` encryption process.
311
+ - a new instance of `crypto.Cipheriv` allowing you to add listeners to the `cipher` encryption process.
313
312
  - the actual `encrypt` callback that must be called and awaited in order to start the encryption process.
314
313
 
315
314
  </details>
@@ -331,10 +330,10 @@ Decrypts a `Readable` stream to a `Writable` stream.
331
330
 
332
331
  <summary>Parameters</summary>
333
332
 
334
- | Name | Type | Description |
335
- |-----------|-----------------------------------|---------------------------------------|
336
- | `secret` | `CoerceToUint8ArrayInput` | Secret key for decryption. |
337
- | `options` | `Cph.Stream.Symmetric.DecryptOptions` | Stream decryption options. |
333
+ | Name | Type | Description |
334
+ | --------- | ------------------------------------- | -------------------------- |
335
+ | `secret` | `CoerceToUint8ArrayInput` | Secret key for decryption. |
336
+ | `options` | `Cph.Stream.Symmetric.DecryptOptions` | Stream decryption options. |
338
337
 
339
338
  </details>
340
339
 
@@ -347,7 +346,7 @@ Decrypts a `Readable` stream to a `Writable` stream.
347
346
  Type: `Promise<Cph.Stream.Symmetric.DecryptReturnType>`
348
347
 
349
348
  - A new Promise that resolves when Key IV extraction completes returning an object containing:
350
- - a new instance of `crypto.Decipher` allowing you to add listeners to the `decipher` decryption process.
349
+ - a new instance of `crypto.Decipheriv` allowing you to add listeners to the `decipher` decryption process.
351
350
  - the actual `decrypt` callback that must be called and awaited in order to start the decryption process.
352
351
 
353
352
  </details>
@@ -361,7 +360,7 @@ Type: `Promise<Cph.Stream.Symmetric.DecryptReturnType>`
361
360
 
362
361
  ---
363
362
 
364
- ##### `Cipher.hybridEncrypt()`
363
+ ##### `Cipher.hybridStreamEncrypt()`
365
364
 
366
365
  Encrypts a stream using hybrid encryption (symmetric + RSA).
367
366
 
@@ -369,11 +368,11 @@ Encrypts a stream using hybrid encryption (symmetric + RSA).
369
368
 
370
369
  <summary>Parameters</summary>
371
370
 
372
- | Name | Type | Description |
373
- |-------------|-----------------------------------|---------------------------------------|
374
- | `secret` | `CoerceToUint8ArrayInput` | Symmetric secret key. |
371
+ | Name | Type | Description |
372
+ | ----------- | --------------------------------------- | ----------------------------------------------------------- |
373
+ | `secret` | `CoerceToUint8ArrayInput` | Symmetric secret key. |
375
374
  | `publicKey` | `crypto.RsaPublicKey \| crypto.KeyLike` | RSA public key used to encrypt the generated symmetric key. |
376
- | `options` | `Cph.Stream.Hybrid.EncryptOptions` | Stream encryption options. |
375
+ | `options` | `Cph.Stream.Hybrid.EncryptOptions` | Stream encryption options. |
377
376
 
378
377
  </details>
379
378
 
@@ -394,13 +393,13 @@ Type: `Cph.Stream.Hybrid.EncryptReturnType`
394
393
  ---
395
394
 
396
395
  - See [`CoerceToUint8ArrayInput`](#coercetouint8arrayinput) for more informations about supported input data types.
397
- - See [`Cph.Stream.Hybrid.EncryptOptions`](#cphstreamhybridencryptoptions) for more informations about encryption options.
396
+ - See [`Cph.Stream.Hybrid.EncryptOptions`](#cphstreamhybridStreamEncryptoptions) for more informations about encryption options.
398
397
  - See [In-memory data stream with hybrid encryption/decryption](#in-memory-data-stream-with-hybrid-encryptiondecryption) examples.
399
398
  - See [File based data stream with hybrid encryption/decryption](#file-based-data-stream-with-hybrid-encryptiondecryption) examples.
400
399
 
401
400
  ---
402
401
 
403
- ##### `Cipher.hybridDecrypt()`
402
+ ##### `Cipher.hybridStreamDecrypt()`
404
403
 
405
404
  Decrypts a stream using hybrid decryption (symmetric + RSA).
406
405
 
@@ -408,10 +407,10 @@ Decrypts a stream using hybrid decryption (symmetric + RSA).
408
407
 
409
408
  <summary>Parameters</summary>
410
409
 
411
- | Name | Type | Description |
412
- |--------------|-----------------------------------|---------------------------------------|
410
+ | Name | Type | Description |
411
+ | ------------ | ---------------------------------------- | ---------------------------------------------------------------- |
413
412
  | `privateKey` | `crypto.RsaPrivateKey \| crypto.KeyLike` | RSA private key for used to decrpyt the encrypted symmetric key. |
414
- | `options` | `Cph.Stream.Hybrid.DecryptOptions` | Stream decryption options. |
413
+ | `options` | `Cph.Stream.Hybrid.DecryptOptions` | Stream decryption options. |
415
414
 
416
415
  </details>
417
416
 
@@ -424,14 +423,14 @@ Decrypts a stream using hybrid decryption (symmetric + RSA).
424
423
  Type: `Promise<Cph.Stream.Hybrid.DecryptReturnType>`
425
424
 
426
425
  - A new Promise that resolves when Key IV extraction completes returning an object containing:
427
- - a new instance of `crypto.Decipher` allowing you to add listeners to the `decipher` decryption process.
426
+ - a new instance of `crypto.Decipheriv` allowing you to add listeners to the `decipher` decryption process.
428
427
  - the actual `decrypt` callback that must be called and awaited in order to start the decryption process.
429
428
 
430
429
  </details>
431
430
 
432
431
  ---
433
432
 
434
- - See [`Cph.Stream.Hybrid.DecryptOptions`](#cphstreamhybriddecryptoptions) for more informations about decryption options.
433
+ - See [`Cph.Stream.Hybrid.DecryptOptions`](#cphstreamhybridStreamDecryptoptions) for more informations about decryption options.
435
434
  - See [In-memory data stream with hybrid encryption/decryption](#in-memory-data-stream-with-hybrid-encryptiondecryption) examples.
436
435
  - See [File based data stream with hybrid encryption/decryption](#file-based-data-stream-with-hybrid-encryptiondecryption) examples.
437
436
 
@@ -467,8 +466,8 @@ Common options in encryption/decryption processes.
467
466
 
468
467
  <summary>Type parameters</summary>
469
468
 
470
- | Parameter | Default | Description |
471
- |-----------|----------------|-------------|
469
+ | Parameter | Default | Description |
470
+ | --------- | ------------------ | -------------------------------------------------------------------------------------- |
472
471
  | `T` | `Cph.AesAlgorithm` | Accepted algorithm in `Cph.Options`. This is usefull to constraint specifc algorithms. |
473
472
 
474
473
  </details>
@@ -479,14 +478,14 @@ Common options in encryption/decryption processes.
479
478
 
480
479
  <summary>Properties</summary>
481
480
 
482
- | Property | Type | Default | Description |
483
- |-------------|----------|---------------|-------------|
484
- | `algorithm` | `T` | `aes-256-gcm \| aes-256-cbc` | Accepted algorithms. |
485
- | `salt` | `number` | `32` | The `salt` length in bytes. Minimum: `16`, Maximum: `64`. |
486
- | `iv` | `number` | `16` | The Initialization Vector length in bytes. Minimum: `8`, Maximum: `32`. |
487
- | `authTag` | `number` | `16` | The `authTag` length in bytes. Minimum: `4`, Maximum: `16`. |
488
- | `aad` | `CoerceToUint8ArrayInput` | - | Custom Additional Authenticated Data. `aadLength` is then automatically resolved. If not provided, a random AAD is generated with a max length of `aadLength`. |
489
- | `aadLength` | `number` | `32` | The auto generated AAD length in bytes. Minimum: `16`, Maximum: `128`. |
481
+ | Property | Type | Default | Description |
482
+ | ----------- | ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
483
+ | `algorithm` | `T` | `aes-256-gcm \| aes-256-cbc` | Accepted algorithms. |
484
+ | `salt` | `number` | `32` | The `salt` length in bytes. Minimum: `16`, Maximum: `64`. |
485
+ | `iv` | `number` | `16` | The Initialization Vector length in bytes. Minimum: `8`, Maximum: `32`. |
486
+ | `authTag` | `number` | `16` | The `authTag` length in bytes. Minimum: `4`, Maximum: `16`. |
487
+ | `aad` | `CoerceToUint8ArrayInput` | - | Custom Additional Authenticated Data. `aadLength` is then automatically resolved. If not provided, a random AAD is generated with a max length of `aadLength`. |
488
+ | `aadLength` | `number` | `32` | The auto generated AAD length in bytes. Minimum: `16`, Maximum: `128`. |
490
489
 
491
490
  </details>
492
491
 
@@ -502,10 +501,10 @@ Stream symmetric encryption options.
502
501
 
503
502
  <summary>Properties</summary>
504
503
 
505
- | Property | Type | Description |
506
- |----------|----------|-------------|
504
+ | Property | Type | Description |
505
+ | -------- | ---------- | ------------------------------------------------------------- |
507
506
  | `input` | `Readable` | The `Readable` Stream from where raw data to encrypt is read. |
508
- | `output` | `Writable` | The `Writable` Stream where encrypted data is written. |
507
+ | `output` | `Writable` | The `Writable` Stream where encrypted data is written. |
509
508
 
510
509
  </details>
511
510
 
@@ -519,9 +518,9 @@ Returnign object from `Cipher.streamEncrypt()` method.
519
518
 
520
519
  <summary>Properties</summary>
521
520
 
522
- | Property | Type | Description |
523
- |----------|----------|-------------|
524
- | `cipher` | `crypto.Cipher` | The `crypto.Cipher` instance. |
521
+ | Property | Type | Description |
522
+ | --------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
523
+ | `cipher` | `crypto.Cipheriv` | The `crypto.Cipheriv` instance. |
525
524
  | `encrypt` | `() => Promise<void>` | The actual `encrypt` callback that must be called and awaited in order to start the encryption process. |
526
525
 
527
526
  </details>
@@ -538,10 +537,10 @@ Stream symmetric decryption options.
538
537
 
539
538
  <summary>Properties</summary>
540
539
 
541
- | Property | Type | Description |
542
- |----------|----------|-------------|
540
+ | Property | Type | Description |
541
+ | -------- | ---------- | -------------------------------------------------------- |
543
542
  | `input` | `Readable` | The `Readable` Stream from where encrypted data is read. |
544
- | `output` | `Writable` | The `Writable` Stream where decrypted data is written. |
543
+ | `output` | `Writable` | The `Writable` Stream where decrypted data is written. |
545
544
 
546
545
  </details>
547
546
 
@@ -555,10 +554,10 @@ Returnign object from awaited `Cipher.streamDecrypt()` method.
555
554
 
556
555
  <summary>Properties</summary>
557
556
 
558
- | Property | Type | Description |
559
- |----------|----------|-------------|
560
- | `decipher` | `crypto.Decipher` | The `crypto.Decipher` instance. |
561
- | `decrypt` | `() => Promise<void>` | The actual `decrypt` callback that must be called and awaited in order to start the decryption process. |
557
+ | Property | Type | Description |
558
+ | ---------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
559
+ | `decipher` | `crypto.Decipheriv` | The `crypto.Decipheriv` instance. |
560
+ | `decrypt` | `() => Promise<void>` | The actual `decrypt` callback that must be called and awaited in order to start the decryption process. |
562
561
 
563
562
  </details>
564
563
 
@@ -574,7 +573,7 @@ Stream hybrid encryption options.
574
573
 
575
574
  ##### `Cph.Stream.Hybrid.EncryptReturnType`
576
575
 
577
- Returnign object from `Cipher.hybridEncrypt()` method.
576
+ Returnign object from `Cipher.hybridStreamEncrypt()` method.
578
577
 
579
578
  - Alias for [`Cph.Stream.Symmetric.EncryptReturnType`](#cphstreamsymmetricencryptreturntype)
580
579
 
@@ -590,8 +589,8 @@ Stream hybrid decryption options.
590
589
 
591
590
  <summary>Properties</summary>
592
591
 
593
- | Property | Type | Description |
594
- |----------------|----------|-------------|
592
+ | Property | Type | Description |
593
+ | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
595
594
  | `rsaKeyLength` | `number` | The RSA key length in bytes used while encrypting data. This is used to properly extract the encrypted Cipher Key and Initialization Vector from the encrypted data. |
596
595
 
597
596
  </details>
@@ -600,7 +599,7 @@ Stream hybrid decryption options.
600
599
 
601
600
  ##### `Cph.Stream.Hybrid.DecryptReturnType`
602
601
 
603
- Returnign object from awaited `Cipher.hybridDecrypt()` method.
602
+ Returnign object from awaited `Cipher.hybridStreamDecrypt()` method.
604
603
 
605
604
  - Alias for [`Cph.Stream.Symmetric.DecryptReturnType`](#cphstreamsymmetricdecryptreturntype)
606
605
 
@@ -611,8 +610,8 @@ Returnign object from awaited `Cipher.hybridDecrypt()` method.
611
610
  #### Importing the library
612
611
 
613
612
  ```ts
614
- import { Cipher } from '@alessiofrittoli/crypto-cipher'
615
- import type { Cph as CipherTypes } from '@alessiofrittoli/crypto-cipher/types'
613
+ import { Cipher } from "@alessiofrittoli/crypto-cipher";
614
+ import type { Cph as CipherTypes } from "@alessiofrittoli/crypto-cipher/types";
616
615
  ```
617
616
 
618
617
  #### In-memory data buffer encryption/decryption
@@ -621,14 +620,14 @@ The simpliest way to encrypt/decrypt in-memory data buffers.
621
620
 
622
621
  ```ts
623
622
  // encrypt
624
- const data = 'my top-secret data'
625
- const password = 'my-very-strong-password'
623
+ const data = "my top-secret data";
624
+ const password = "my-very-strong-password";
626
625
 
627
- const encrypted = Cipher.encrypt( data, password )
626
+ const encrypted = Cipher.encrypt(data, password);
628
627
 
629
628
  // decrypt
630
- const decrypted = Cipher.decrypt( encrypted, password )
631
- console.log( decrypted ) // Outputs: my top-secret data
629
+ const decrypted = Cipher.decrypt(encrypted, password);
630
+ console.log(decrypted); // Outputs: my top-secret data
632
631
  ```
633
632
 
634
633
  ---
@@ -642,45 +641,41 @@ The in-memory data stream comes pretty handy when, for example, we need to strea
642
641
  ```ts
643
642
  // /api/stream-encrypt
644
643
 
645
- import { Readable, Writable } from 'stream'
644
+ import { Readable, Writable } from "stream";
646
645
 
647
646
  const routeHandler = () => {
648
- const data = 'my top-secret data'
649
- const password = 'my-very-strong-password'
650
- const stream = new TransformStream()
651
- const writer = stream.writable.getWriter()
652
-
647
+ const data = "my top-secret data";
648
+ const password = "my-very-strong-password";
649
+ const stream = new TransformStream();
650
+ const writer = stream.writable.getWriter();
651
+
653
652
  // Create a `Readable` Stream with raw data.
654
- const input = new Readable( {
655
- read()
656
- {
657
- this.push( data )
658
- this.push( null ) // Signal end of stream
653
+ const input = new Readable({
654
+ read() {
655
+ this.push(data);
656
+ this.push(null); // Signal end of stream
659
657
  },
660
- } )
661
-
658
+ });
659
+
662
660
  // `Writable` Stream where encrypted data is written
663
- const output = new Writable( {
664
- write( chunk, encoding, callback )
665
- {
666
- writer.write( chunk )
667
- callback()
661
+ const output = new Writable({
662
+ write(chunk, encoding, callback) {
663
+ writer.write(chunk);
664
+ callback();
668
665
  },
669
- final( callback )
670
- {
671
- writer.close()
672
- callback()
673
- }
674
- } )
675
-
676
- Cipher.streamEncrypt( password, { input, output } )
677
- .encrypt()
678
-
666
+ final(callback) {
667
+ writer.close();
668
+ callback();
669
+ },
670
+ });
671
+
672
+ Cipher.streamEncrypt(password, { input, output }).encrypt();
673
+
679
674
  return (
680
675
  // encrypted stream
681
- new Response( stream.readable )
682
- )
683
- }
676
+ new Response(stream.readable)
677
+ );
678
+ };
684
679
  ```
685
680
 
686
681
  ##### Decrypting received stream
@@ -688,59 +683,51 @@ const routeHandler = () => {
688
683
  ```ts
689
684
  // /api/stream-decrypt
690
685
 
691
- import { Transform, Writable } from 'stream'
692
- import { StreamReader } from '@alessiofrittoli/stream-reader'
693
-
694
- const password = 'my-very-strong-password'
695
-
696
- const routeHandler = () => (
697
- fetch( '/api/stream-encrypt' )
698
- .then( response => {
699
-
700
- if ( ! response.body ) {
701
- return (
702
- new Respone( null, { status: 400 } )
703
- )
704
- }
705
-
706
- const stream = new TransformStream()
707
- const writer = stream.writable.getWriter()
708
- const reader = new StreamReader( response.body )
709
- const input = new Transform()
710
-
711
- reader.read()
712
-
713
-
714
- reader.on( 'read', chunk => {
715
- input.push( chunk )
716
- } )
717
- reader.on( 'close', () => {
718
- input.push( null )
719
- } )
720
-
721
- const output = new Writable( {
722
- write( chunk, encoding, callback )
723
- {
724
- writer.write( chunk )
725
- callback()
726
- },
727
- final( callback ) {
728
- writer.close()
729
- callback()
730
- },
731
- } )
732
-
733
- const { decrypt } = await Cipher.streamDecrypt( password, { input, output } )
734
-
735
- decrypt()
736
-
737
- return (
738
- // decrypted stream
739
- new Response( stream.readable )
740
- )
741
-
742
- } )
743
- )
686
+ import { Transform, Writable } from "stream";
687
+ import { StreamReader } from "@alessiofrittoli/stream-reader";
688
+
689
+ const password = "my-very-strong-password";
690
+
691
+ const routeHandler = () =>
692
+ fetch("/api/stream-encrypt").then((response) => {
693
+ if (!response.body) {
694
+ return new Respone(null, { status: 400 });
695
+ }
696
+
697
+ const stream = new TransformStream();
698
+ const writer = stream.writable.getWriter();
699
+ const reader = new StreamReader(response.body);
700
+ const input = new Transform();
701
+
702
+ reader.read();
703
+
704
+ reader.on("read", (chunk) => {
705
+ input.push(chunk);
706
+ });
707
+ reader.on("close", () => {
708
+ input.push(null);
709
+ });
710
+
711
+ const output = new Writable({
712
+ write(chunk, encoding, callback) {
713
+ writer.write(chunk);
714
+ callback();
715
+ },
716
+ final(callback) {
717
+ writer.close();
718
+ callback();
719
+ },
720
+ });
721
+
722
+ const { decrypt } = await Cipher.streamDecrypt(password, { input, output });
723
+
724
+ decrypt();
725
+
726
+ return (
727
+ // decrypted stream
728
+ new Response(stream.readable)
729
+ );
730
+ });
744
731
  ```
745
732
 
746
733
  ---
@@ -752,58 +739,64 @@ Hybrid encryption offers an higher level of security by encrypting the generated
752
739
  ##### Keypair
753
740
 
754
741
  ```ts
755
- const password = 'my-very-strong-password'
742
+ const password = "my-very-strong-password";
756
743
 
757
744
  /** RSA modulus length is required for proper key extraction during decryption process. */
758
- const rsaKeyLength = 512 // bytes
759
- const keyPair = crypto.generateKeyPairSync( 'rsa', {
760
- modulusLength : rsaKeyLength * 8, // 4096 bits
761
- publicKeyEncoding : { type: 'spki', format: 'pem' },
762
- privateKeyEncoding : { type: 'pkcs1', format: 'pem' },
763
- } )
764
-
745
+ const rsaKeyLength = 512; // bytes
746
+ const keyPair = crypto.generateKeyPairSync("rsa", {
747
+ modulusLength: rsaKeyLength * 8, // 4096 bits
748
+ publicKeyEncoding: { type: "spki", format: "pem" },
749
+ privateKeyEncoding: { type: "pkcs1", format: "pem" },
750
+ });
765
751
 
766
752
  // or you can optionally set a custom passphrase
767
- const keyPair = crypto.generateKeyPairSync( 'rsa', {
768
- modulusLength : rsaKeyLength * 8, // 4096 bits
769
- publicKeyEncoding : { type: 'spki', format: 'pem' },
770
- privateKeyEncoding : { type: 'pkcs1', format: 'pem', passphrase: password, cipher: 'aes-256-cbc' },
771
- } )
753
+ const keyPair = crypto.generateKeyPairSync("rsa", {
754
+ modulusLength: rsaKeyLength * 8, // 4096 bits
755
+ publicKeyEncoding: { type: "spki", format: "pem" },
756
+ privateKeyEncoding: {
757
+ type: "pkcs1",
758
+ format: "pem",
759
+ passphrase: password,
760
+ cipher: "aes-256-cbc",
761
+ },
762
+ });
772
763
  ```
773
764
 
774
765
  ##### Encrypt
775
766
 
776
767
  ```ts
777
- const data = 'my top-secret data'
768
+ const data = "my top-secret data";
778
769
  /** Store encrypted chunks for next example. */
779
- const encryptedChunks: Buffer[] = []
770
+ const encryptedChunks: Buffer[] = [];
780
771
 
781
772
  // Create a `Readable` Stream with raw data.
782
- const input = new Readable( {
783
- read()
784
- {
785
- this.push( data ) // Push data to encrypt
786
- this.push( null ) // Signal end of stream
773
+ const input = new Readable({
774
+ read() {
775
+ this.push(data); // Push data to encrypt
776
+ this.push(null); // Signal end of stream
787
777
  },
788
- } )
789
-
778
+ });
779
+
790
780
  // Create a `Writable` Stream where encrypted data is written
791
- const output = new Writable( {
792
- write( chunk, encoding, callback )
793
- {
781
+ const output = new Writable({
782
+ write(chunk, encoding, callback) {
794
783
  // push written chunk to `encryptedChunks` for further usage.
795
- encryptedChunks.push( chunk )
796
- callback()
797
- }
798
- } )
799
-
800
- const { encrypt } = Cipher.hybridEncrypt( password, {
801
- key : keyPair.publicKey,
802
- padding : crypto.constants.RSA_PKCS1_OAEP_PADDING,
803
- oaepHash : 'SHA-256',
804
- }, { input, output } )
805
-
806
- await encrypt()
784
+ encryptedChunks.push(chunk);
785
+ callback();
786
+ },
787
+ });
788
+
789
+ const { encrypt } = Cipher.hybridStreamEncrypt(
790
+ password,
791
+ {
792
+ key: keyPair.publicKey,
793
+ padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
794
+ oaepHash: "SHA-256",
795
+ },
796
+ { input, output }
797
+ );
798
+
799
+ await encrypt();
807
800
  ```
808
801
 
809
802
  ---
@@ -812,37 +805,36 @@ await encrypt()
812
805
 
813
806
  ```ts
814
807
  /** Store decrypted chunks. */
815
- const chunks: Buffer[] = []
808
+ const chunks: Buffer[] = [];
816
809
  // Create a `Readable` Stream with encrypted data.
817
- const input = new Readable( {
818
- read()
819
- {
820
- this.push( Buffer.concat( encryptedChunks ) ) // Push data to decrypt
821
- this.push( null ) // Signal end of stream
810
+ const input = new Readable({
811
+ read() {
812
+ this.push(Buffer.concat(encryptedChunks)); // Push data to decrypt
813
+ this.push(null); // Signal end of stream
822
814
  },
823
- } )
815
+ });
824
816
 
825
817
  // Create a `Writable` Stream where decrypted data is written
826
- const output = new Writable( {
827
- write( chunk, encoding, callback )
828
- {
829
- chunks.push( chunk )
830
- callback()
818
+ const output = new Writable({
819
+ write(chunk, encoding, callback) {
820
+ chunks.push(chunk);
821
+ callback();
831
822
  },
832
- } )
823
+ });
833
824
 
834
- const { decrypt } = await Cipher.hybridDecrypt(
825
+ const { decrypt } = await Cipher.hybridStreamDecrypt(
835
826
  {
836
- key : keyPair.privateKey,
827
+ key: keyPair.privateKey,
837
828
  passphrase: password, // optional passhrase (required if set while generating keypair).
838
- padding : crypto.constants.RSA_PKCS1_OAEP_PADDING,
839
- oaepHash : 'SHA-256',
840
- }, { input, output, rsaKeyLength }
841
- )
829
+ padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
830
+ oaepHash: "SHA-256",
831
+ },
832
+ { input, output, rsaKeyLength }
833
+ );
842
834
 
843
- await decrypt()
835
+ await decrypt();
844
836
 
845
- console.log( Buffer.concat( chunks ).toString() ) // Outputs: 'my top-secret data'
837
+ console.log(Buffer.concat(chunks).toString()); // Outputs: 'my top-secret data'
846
838
  ```
847
839
 
848
840
  ---
@@ -854,17 +846,16 @@ Nothig differs from the [In-memory data stream encryption/decryption](#in-memory
854
846
  ##### Encrypt a file
855
847
 
856
848
  ```ts
857
- import fs from 'fs'
849
+ import fs from "fs";
858
850
 
859
- const password = 'my-very-strong-password'
851
+ const password = "my-very-strong-password";
860
852
 
861
853
  // input where raw data to encrypt is read
862
- const input = fs.createReadStream( 'my-very-large-top-secret-file.pdf' )
854
+ const input = fs.createReadStream("my-very-large-top-secret-file.pdf");
863
855
  // output where encrypted data is written
864
- const output = fs.createWriteStream( 'my-very-large-top-secret-file.encrypted' )
856
+ const output = fs.createWriteStream("my-very-large-top-secret-file.encrypted");
865
857
  // encrypt
866
- await Cipher.streamEncrypt( password, { input, output } )
867
- .encrypt()
858
+ await Cipher.streamEncrypt(password, { input, output }).encrypt();
868
859
  ```
869
860
 
870
861
  ---
@@ -872,17 +863,19 @@ await Cipher.streamEncrypt( password, { input, output } )
872
863
  ##### Decrypt a file
873
864
 
874
865
  ```ts
875
- import fs from 'fs'
866
+ import fs from "fs";
876
867
 
877
- const password = 'my-very-strong-password'
868
+ const password = "my-very-strong-password";
878
869
 
879
870
  // input where encrypted data is read
880
- const input = fs.createReadStream( 'my-very-large-top-secret-file.encrypted' )
871
+ const input = fs.createReadStream("my-very-large-top-secret-file.encrypted");
881
872
  // output where decrypted data is written
882
- const output = fs.createWriteStream( 'my-very-large-top-secret-file-decrypted.pdf' )
873
+ const output = fs.createWriteStream(
874
+ "my-very-large-top-secret-file-decrypted.pdf"
875
+ );
883
876
  // decrypt
884
- const { decrypt } = await Cipher.streamDecrypt( password, { input, output } )
885
- await decrypt()
877
+ const { decrypt } = await Cipher.streamDecrypt(password, { input, output });
878
+ await decrypt();
886
879
  ```
887
880
 
888
881
  ---
@@ -894,43 +887,51 @@ Nothig differs from the [In-memory data stream with hybrid encryption/decryption
894
887
  ##### Keypair
895
888
 
896
889
  ```ts
897
- const password = 'my-very-strong-password'
890
+ const password = "my-very-strong-password";
898
891
 
899
892
  /** RSA modulus length is required for proper key extraction during decryption process. */
900
- const rsaKeyLength = 512 // bytes
901
- const keyPair = crypto.generateKeyPairSync( 'rsa', {
902
- modulusLength : rsaKeyLength * 8, // 4096 bits
903
- publicKeyEncoding : { type: 'spki', format: 'pem' },
904
- privateKeyEncoding : { type: 'pkcs1', format: 'pem' },
905
- } )
906
-
893
+ const rsaKeyLength = 512; // bytes
894
+ const keyPair = crypto.generateKeyPairSync("rsa", {
895
+ modulusLength: rsaKeyLength * 8, // 4096 bits
896
+ publicKeyEncoding: { type: "spki", format: "pem" },
897
+ privateKeyEncoding: { type: "pkcs1", format: "pem" },
898
+ });
907
899
 
908
900
  // or you can optionally set a custom passphrase
909
- const keyPair = crypto.generateKeyPairSync( 'rsa', {
910
- modulusLength : rsaKeyLength * 8, // 4096 bits
911
- publicKeyEncoding : { type: 'spki', format: 'pem' },
912
- privateKeyEncoding : { type: 'pkcs1', format: 'pem', passphrase: password, cipher: 'aes-256-cbc' },
913
- } )
901
+ const keyPair = crypto.generateKeyPairSync("rsa", {
902
+ modulusLength: rsaKeyLength * 8, // 4096 bits
903
+ publicKeyEncoding: { type: "spki", format: "pem" },
904
+ privateKeyEncoding: {
905
+ type: "pkcs1",
906
+ format: "pem",
907
+ passphrase: password,
908
+ cipher: "aes-256-cbc",
909
+ },
910
+ });
914
911
  ```
915
912
 
916
913
  ##### Encrypt a file
917
914
 
918
915
  ```ts
919
- import fs from 'fs'
916
+ import fs from "fs";
920
917
 
921
- const password = 'my-very-strong-password'
918
+ const password = "my-very-strong-password";
922
919
 
923
920
  // input where raw data to encrypt is read
924
- const input = fs.createReadStream( 'my-very-large-top-secret-file.pdf' )
921
+ const input = fs.createReadStream("my-very-large-top-secret-file.pdf");
925
922
  // output where encrypted data is written
926
- const output = fs.createWriteStream( 'my-very-large-top-secret-file.encrypted' )
923
+ const output = fs.createWriteStream("my-very-large-top-secret-file.encrypted");
927
924
  // encrypt
928
- const { encrypt } = Cipher.hybridEncrypt( password, {
929
- key : keyPair.publicKey,
930
- padding : crypto.constants.RSA_PKCS1_OAEP_PADDING,
931
- oaepHash : 'SHA-256',
932
- }, { input, output } )
933
- await encrypt()
925
+ const { encrypt } = Cipher.hybridStreamEncrypt(
926
+ password,
927
+ {
928
+ key: keyPair.publicKey,
929
+ padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
930
+ oaepHash: "SHA-256",
931
+ },
932
+ { input, output }
933
+ );
934
+ await encrypt();
934
935
  ```
935
936
 
936
937
  ---
@@ -938,23 +939,26 @@ await encrypt()
938
939
  ##### Decrypt a file
939
940
 
940
941
  ```ts
941
- import fs from 'fs'
942
+ import fs from "fs";
942
943
 
943
- const password = 'my-very-strong-password'
944
+ const password = "my-very-strong-password";
944
945
 
945
946
  // input where encrypted data is read
946
- const input = fs.createReadStream( 'my-very-large-top-secret-file.encrypted' )
947
+ const input = fs.createReadStream("my-very-large-top-secret-file.encrypted");
947
948
  // output where decrypted data is written
948
- const output = fs.createWriteStream( 'my-very-large-top-secret-file-decrypted.pdf' )
949
+ const output = fs.createWriteStream(
950
+ "my-very-large-top-secret-file-decrypted.pdf"
951
+ );
949
952
  // decrypt
950
- const { decrypt } = await Cipher.hybridDecrypt(
953
+ const { decrypt } = await Cipher.hybridStreamDecrypt(
951
954
  {
952
- key : keyPair.privateKey,
955
+ key: keyPair.privateKey,
953
956
  passphrase: password, // optional passhrase (required if set while generating keypair).
954
- padding : crypto.constants.RSA_PKCS1_OAEP_PADDING,
955
- oaepHash : 'SHA-256',
956
- }, { input, output, rsaKeyLength }
957
- )
957
+ padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
958
+ oaepHash: "SHA-256",
959
+ },
960
+ { input, output, rsaKeyLength }
961
+ );
958
962
  ```
959
963
 
960
964
  ---