doc: reorganize doc and examples

README.md

@@ -1,5 +1,43 @@
 # [Cipher.js](https://github.com/therootcompany/cipher.js) for Bun, Node, and Browsers
 
+Because you don't have to be an expert to _use_ cryptography!
+
+- Keys can be 128-, 192-, or 256-bit (16, 19, or 24 bytes)
+- Plain input can be raw `Uint8Array`s or (UTF-8) `String`s
+- Encrypted output can be `Base64UrlSafe` Strings, or raw `Uint8Array`s
+
+## Table of Contents
+
+0. Example
+1. Generate a Key
+2. Initialize the Cipher (Codec)
+3. Encrypt (Cipher) Data
+4. Decrypt (Decipher) Data
+5. Convert between Bytes, Hex, Base64, and URL-Safe Base64
+6. API
+7. Implementation Details
+
+## Example
+
+Encrypt and Decrypt with AES-CBC.
+
+```js
+let Cipher = require("@root/cipher");
+
+let cipher = Cipher.create(sharedSecret);
+
+let plainBytes = [0xde, 0xad, 0xbe, 0xef];
+let encBase64UrlSafe = cipher.encrypt(plainBytes);
+
+let originalBytes = Cipher.decrypt(encBase64UrlSafe);
+```
+
+## Usage
+
+Copy-and-Paste Snippets for the Masses
+
+### 1. Generate a Key
+
 ```js
 // Generate a 128-bit, 192-bit, or 256-bit AES secret:
 let secretBytes = new Uint8Array(16); // or 24, or 32
@@ -8,72 +46,143 @@ crypto.getRandomValues(secretBytes);
 let secretHex = Cipher.utils.bytesTohex(secretBytes);
 ```
 
+### 2. Initialize the Cipher (Codec)
+
 ```js
-let Cipher = require("@root/cipher");
+let secretHex = process.env.APP_SECRET_KEY;
 
-let sharedSecret = Cipher.utils.hexToBytes(secretHex);
+let secretBytes = Cipher.utils.hexToBytes(secretHex);
 let cipher = Cipher.create(sharedSecret);
+```
+
+### 3. Encrypt (Cipher) Data
 
-let plain = "123-45-6789";
-let encBase64UrlSafe = cipher.encryptString(plain);
-console.info("Encrypted", encBase64UrlSafe);
+#### Plain Bytes => Encrypted Base64UrlSafe
 
-let original = Cipher.decryptToString(encBase64UrlSafe);
-console.info("Decrypted", original === plain, original);
+```sh
+let plainBytes = [0xde, 0xad, 0xbe, 0xef];
+let encBase64UrlSafe = cipher.encrypt(plainBytes);
+console.info("Encrypted (URL-Safe Base64)", encBase64UrlSafe);
 ```
 
-## Usage
+#### Plain String => Encrypted Base64UrlSafe
 
-```js
-let cipher = Cipher.create(keyBytes);
+```sh
+let plainText = "123-45-6789";
+let encBase64UrlSafe = cipher.encryptString(plainText);
+console.info("Encrypted (URL-Safe Base64)", encBase64UrlSafe);
+```
 
-let encString = await cipher.encrypt(payloadBytes);
-let encString = cipher.encryptString(payloadString);
+#### Plain Bytes => Encrypted Bytes
 
-let decBytes = cipher.decrypt(encString);
-let decString = cipher.decryptToString(encString);
+```sh
+let plainBytes = [0xde, 0xad, 0xbe, 0xef];
+let encBytes = cipher.encryptAsBytes(plainBytes);
+console.info("Encrypted (Bytes)", encBytes);
 ```
 
+#### Plain String => Encrypted Bytes
+
+```sh
+let plainText = "123-45-6789";
+let encBytes = cipher.encryptStringAsBytes(plainText);
+console.info("Encrypted (Bytes)", encBytes);
+```
+
+### 4. Decrypt (Decipher) Data
+
+#### Encrypted String => Plain Bytes
+
+```sh
+let bytes = cipher.decrypt(encBase64UrlSafe);
+console.info("Plain (Bytes)", bytes);
+```
+
+#### Encrypted Bytes => Plain Bytes
+
+```sh
+let bytes = cipher.decryptBytes(encBytes);
+console.info("Plain (Bytes)", bytes);
+```
+
+#### Encrypted String => Plain String
+
+```sh
+let text = cipher.decryptToString(encBase64UrlSafe);
+console.info("Plain (Text)", text);
+```
+
+#### Encrypted Bytes => Plain String
+
+```sh
+let text = cipher.decryptBytesToString(encBytes);
+console.info("Plain (Text)", text);
+```
+
+### 5. Convert between Bytes, Hex, Base64, and URL-Safe Base64
+
+Doing what `Uint8Array` should do, but doesn't.
+
+#### Bytes <=> Hex
+
 ```sh
 let hex = Cipher.utils.bytesToHex(bytes);
 let bytes = Cipher.utils.hexToBytes(hex);
+```
+
+#### Bytes <=> Base64
 
+```js
 let base64 = Cipher.utils.bytesToBase64(bytes);
 let bytes = Cipher.utils.base64ToBytes(base64);
+```
 
+#### Bytes <=> URL-Safe Base64
+
+```sh
 let base64urlsafe = Cipher.utils.bytesToUrlSafe(bytes);
 let bytes = Cipher.utils.urlSafeToBytes(base64urlsafe);
 ```
 
 ## API
 
 ```text
-Cipher.create(keyBytes)             => cipher instance
+Cipher.create(keyBytes)                => cipher instance
+
+cipher.encrypt(bytes)                  => Promise<Base64UrlSafe>
+cipher.encryptString(string)           => Promise<Base64UrlSafe>
+
+cipher.encryptAsBytes(bytes)           => Promise<Uint8Array>
+cipher.encryptStringAsBytes(string)    => Promise<Uint8Array>
 
-cipher.encrypt(bytes)               => Promise<encrypted>
-cipher.encryptString(string)        => Promise<encrypted>
+cipher.decrypt(encrypted)              => Promise<Uint8Array>
+cipher.decryptToString(encrypted)      => Promise<Base64UrlSafe>
 
-cipher.decrypt(encrypted)           => Promise<bytes>
-cipher.decryptToString(encrypted)   => Promise<string>
+cipher.decryptBytes(encBytes)          => Promise<Uint8Array>
+cipher.decryptBytesToString(encBytes)  => Promise<Base64UrlSafe>
 ```
 
 ```text
-Cipher.utils.bytesToHex(bytes)      => hexString
-Cipher.utils.hexToBytes(hex)        => bytes
+Cipher.utils.bytesToHex(bytes)         => hex string
+Cipher.utils.hexToBytes(hex)           => bytes
 
-Cipher.utils.bytesToBase64(bytes)   => base64
-Cipher.utils.base64ToBytes(base64)  => bytes
+Cipher.utils.bytesToBase64(bytes)      => base64
+Cipher.utils.base64ToBytes(base64)     => bytes
 
-Cipher.utils.bytesToUrlSafe(bytes)  => url-safe base64 string
-Cipher.utils.urlSafeToBytes(url64)  => bytes
+Cipher.utils.bytesToUrlSafe(bytes)     => url-safe base64 string
+Cipher.utils.urlSafeToBytes(url64)     => bytes
 ```
 
-To swap between the string and byte encrypted form
+## Implementation Details
 
-```text
-Cipher.utils.encryptedToBytes(encString)
-Cipher.utils.bytesToEncrypted(encString)
-```
+The _Initialization Vector_ (_IV_) is a _salt_ that prevents known-plaintext
+attacks - meaning that if you encrypt the same message with the same key twice,
+you get a different encrypted output.
+
+The first 16-bytes are for the _IV_. \
+The following bytes are the data. \
+If the data is somehow corrupted or truncated, but the first bytes are intact,
+the IV can be used to restore the first partial data.
 
 # LICENSE