# Symmetric Crypto (ES)

[**⚖️** MIT](./LICENSE.md)

🔗
[DistBoard @hugoalh](https://hugoalh.github.io/distboard/symmetric_crypto_ecmascript)
● [GitHub](https://github.com/hugoalh/symmetric-crypto-es)
● [JSR](https://jsr.io/@hugoalh/symmetric-crypto)
● [NPM](https://www.npmjs.com/package/@hugoalh/symmetric-crypto)

An ECMAScript module to provide an easier symmetric crypto.

## 🎯 Runtime Targets

Any runtime which support ECMAScript should able to use this; These runtimes are officially supported:

- **[Bun](https://bun.sh/)** >= v1.1.0
- **[Deno](https://deno.land/)** >= v2.1.0
- **[NodeJS](https://nodejs.org/)** >= v20.9.0

## 🛡️ Runtime Permissions

This does not request any runtime permission.

## #️⃣ Entrypoints

| **Name** | **Path** | **Description** |
|:--|:--|:--|
| `.` | `./mod.ts` | Default. |
| `./legacy/edition/symencdec.1` | `./legacy/symencdec/1.ts` | Migration for edition `symencdec.1`. |
| `./legacy/edition/symencdec.2` | `./legacy/symencdec/2.ts` | Migration for edition `symencdec.2`. |
| `./legacy/edition/symencdec.3` | `./legacy/symencdec/3.ts` | Migration for edition `symencdec.3`. |
| `./legacy/edition/webcrypto.1` | `./legacy/webcrypto/1.ts` | Migration for edition `webcrypto.1`. |
| `./legacy/version/{SemVer}` | N/A | Migration for (specify) version. |

> [!NOTE]
> - Different runtimes have vary support for the entrypoints, visit the runtime documentation for more information.
> - These are not part of the public APIs hence should not be used:
>   - Benchmark/Test file (e.g.: `example.bench.ts`, `example.test.ts`).
>   - Entrypoint name or path include any underscore prefix (e.g.: `_example.ts`, `foo/_example.ts`).
>   - Identifier/Namespace/Symbol include any underscore prefix (e.g.: `_example`, `Foo._example`).

## 🧩 APIs

- ```ts
  class SymmetricCryptor {
    decrypt(data: Uint8Array): Uint8Array;
    decryptStream(): SymmetricCryptorDecryptStream | SymmetricCryptorDecryptStreamAuthTag | SymmetricCryptorDecryptStreamCCM;
    encrypt(data: Uint8Array): Uint8Array;
    encryptStream(): SymmetricCryptorEncryptStream | SymmetricCryptorEncryptStreamCCM;
  }
  ```
- ```ts
  class SymmetricCryptorChain {
    constructor(cryptors: readonly SymmetricCryptor[]);
    decrypt(data: Uint8Array): Uint8Array;
    decryptStream(): TransformStream<Uint8Array, Uint8Array>;
    encrypt(data: Uint8Array): Uint8Array;
    encryptStream(): TransformStream<Uint8Array, Uint8Array>;
  }
  ```
- ```ts
  class SymmetricCryptorDecryptStream extends TransformStream<Uint8Array, Uint8Array>;
  ```
- ```ts
  class SymmetricCryptorDecryptStreamAuthTag extends TransformStream<Uint8Array, Uint8Array>;
  ```
- ```ts
  class SymmetricCryptorDecryptStreamCCM extends TransformStream<Uint8Array, Uint8Array>;
  ```
- ```ts
  class SymmetricCryptorEncryptStream extends TransformStream<Uint8Array, Uint8Array>;
  ```
- ```ts
  class SymmetricCryptorEncryptStreamCCM extends TransformStream<Uint8Array, Uint8Array>;
  ```
- ```ts
  function createSymmetricCryptor(key: BinaryLike, options?: SymmetricCryptorOptions): Promise<SymmetricCryptor>;
  ```
- ```ts
  interface SymmetricCryptorOptions {
    algorithm?: SymmetricCryptoAlgorithm;
    salt?: BinaryLike;
    scrypt?: ScryptOptions;
  }
  ```

> [!NOTE]
> - For the full or prettier documentation, can visit via:
>   - [Deno CLI `deno doc`](https://docs.deno.com/runtime/reference/cli/doc)
>   - [JSR](https://jsr.io/@hugoalh/symmetric-crypto)

## ✍️ Examples

- ```ts
  const data = "qwertyuiop";
  const cryptor = await createSymmetricCryptor("QwErTyUiOp");
  const encrypted = cryptor.encrypt(new TextEncoder().encode(data));
  const decrypted = cryptor.decrypt(encrypted);
  ```
- ```ts
  const cryptor = await createSymmetricCryptor("QwErTyUiOp");
  await using file = await Deno.open(filePath);
  const encrypted = file.readable.pipeThrough(cryptor.encryptStream());
  ```