npm package: @mgraphic/cipher-token
Description: Package to encrypt and decrypt data into a storable string with multiple options to generate a key
Author: Keith Marshall
Latest version: 1.1.2

<div align="center">
  <img src="https://raw.githubusercontent.com/mgraphic/cipher-token/main/cipher-token-logo.png" width="75%" />
  <br />
  <br />
  <a href="https://www.npmjs.com/package/@mgraphic/cipher-token"><img src="https://img.shields.io/npm/v/@mgraphic/cipher-token?maxAge=3600" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/@mgraphic/cipher-token"><img src="https://img.shields.io/npm/dt/@mgraphic/cipher-token?maxAge=3600" alt="npm downloads" /></a>
  <a href="https://github.com/mgraphic/cipher-token/actions/workflows/test.yml"><img src="https://github.com/mgraphic/cipher-token/actions/workflows/test.yml/badge.svg?branch=main" alt="test" /></a>
  <a href="https://github.com/mgraphic/cipher-token/actions/workflows/publish.yml"><img src="https://github.com/mgraphic/cipher-token/actions/workflows/publish.yml/badge.svg?branch=main" alt="publish" /></a>
  <br />
  <a href="https://github.com/mgraphic/cipher-token/blob/main/docs/globals.md" target="_blank">
    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
  </a>
  <a href="https://github.com/mgraphic/cipher-token/graphs/commit-activity" target="_blank">
    <img alt="Maintenance" src="https://img.shields.io/badge/Maintained%3F-yes-brightgreen.svg" />
  </a>
  <br />
  <br />

**Link to the full [API Documentation](docs/globals.md)**

</div>

<br />

> A package tool to encrypt and decrypt secrets into storable string values without requiring a vault to store them. Tokens can ciphered and deciphered by a single key that can be generated by a string, buffer, file, or auto-generated (to be stored privately), or even a combination of these.

```bash
npm install @mgraphic/cipher-token
```

## CLI Tool

```bash
npx @mgraphic/cipher-token
```

_Results In..._

![CLI Example](https://raw.githubusercontent.com/mgraphic/cipher-token/main/cli-example.png)

You can either use the prompt interaction to create a token, decipher a token, or generate a random string to be used for a key.

**tokenize**

```bash
npx @mgraphic/cipher-token tokenize --key=<secret key> [flags...] <plainText>
```

Arguments
|ARGUMENT|DESCRIPTION|TYPE|REQUIRED|
|-|-|-|-|
|`plainText`|Plain text to tokenize|string|yes|

Options
|FLAG|ALIAS|DESCRIPTION|TYPE|DEFAULT|REQUIRED|
|-|-|-|-|-|-|
|`--cipher-algorithm`|`-a`|Cipher Algorithm|string|`aes-256-gcm`|false|
|`--encryption-encoding`|`-e`|Encryption Encoding|string|`hex`|false|
|`--hash-algorithm`|`-y`|Hash Algorithm|string|`sha256`|false|
|`--key`||Secret Key|string||true|
|`--key-length`|`-k`|Key Length|number|32|false|
|`--salt-byte-size`|`-b`|Salt Byte Size|number|8|false|
|`--salt-encoding`|`-s`|Salt Encoding|string|`hex`|false|
|`--tag-encoding`|`-t`|Tag Encoding|string|`hex`|false|
|`--text-encoding`|`-x`|Text Encoding|string|`utf8`|false|
|`--token-encoding`|`-z`|Token Encoding|string|`base64`|false|

**untokenize**

```bash
npx @mgraphic/cipher-token untokenize --key=<secret key> [flags...] <token>
```

Arguments
|ARGUMENT|DESCRIPTION|TYPE|REQUIRED|
|-|-|-|-|
|`token`|Token string to decipher|string|yes|

Options
|FLAG|ALIAS|DESCRIPTION|TYPE|DEFAULT|REQUIRED|
|-|-|-|-|-|-|
|`--cipher-algorithm`|`-a`|Cipher Algorithm|string|`aes-256-gcm`|false|
|`--encryption-encoding`|`-e`|Encryption Encoding|string|`hex`|false|
|`--hash-algorithm`|`-y`|Hash Algorithm|string|`sha256`|false|
|`--key`||Secret Key|string||true|
|`--key-length`|`-k`|Key Length|number|32|false|
|`--salt-byte-size`|`-b`|Salt Byte Size|number|8|false|
|`--salt-encoding`|`-s`|Salt Encoding|string|`hex`|false|
|`--tag-encoding`|`-t`|Tag Encoding|string|`hex`|false|
|`--text-encoding`|`-x`|Text Encoding|string|`utf8`|false|
|`--token-encoding`|`-z`|Token Encoding|string|`base64`|false|

**generate**

```bash
npx @mgraphic/cipher-token generate [flags...]
```

Options
|FLAG|ALIAS|DESCRIPTION|TYPE|DEFAULT|REQUIRED|
|-|-|-|-|-|-|
|`--byte-size`|`-b`|Byte Size|number|32|false|

## Code Examples

### Key From String

```javascript
const { getCipherToken, getDecipherToken } = require('@mgraphic/cipher-token');

//   Encrypt:
const cipherToken = getCipherToken();
cipherToken.keyFromString('secret_string_key');
const token = cipherToken.tokenize('Secret Text encrypted by a string key');
console.log('Token:', token);

// Decrypt:
const decipherToken = getDecipherToken();
decipherToken.keyFromString('secret_string_key');
const decrypted = decipherToken.untokenize(token);
console.log('Decrypted:', decrypted);
```

### Key From File

```javascript
const { getCipherToken, getDecipherToken } = require('@mgraphic/cipher-token');

//   Encrypt:
const cipherToken = getCipherToken();
await cipherToken.keyFromFile('package.json');
const token = cipherToken.tokenize('Secret Text encrypted by a file key');
console.log('Token', ': ', token);

//   Decrypt:
const decipherToken = getDecipherToken();
await decipherToken.keyFromFile('package.json');
const decrypted = decipherToken.untokenize(token);
console.log('Decrypted', ': ', decrypted);
```

### Key From Buffer

```javascript
const { getCipherToken, getDecipherToken } = require('@mgraphic/cipher-token');

//   Encrypt:
const cipherToken = getCipherToken();
cipherToken.keyFromBuffer(Buffer.from('buffer_key'));
const token = cipherToken.tokenize('Secret Text encrypted by a buffer key');
console.log('Token', ': ', token);

//   Decrypt:
const decipherToken = getDecipherToken();
decipherToken.keyFromBuffer(Buffer.from('buffer_key'));
const decrypted = decipherToken.untokenize(token);
console.log('Decrypted', ': ', decrypted);
```

### Key From Buffer, File, and String

```javascript
const { getCipherToken, getDecipherToken } = require('@mgraphic/cipher-token');

//   Encrypt:
const cipherToken = getCipherToken();
await cipherToken.keyFrom({
  buffer: Buffer.from('buffer_key'),
  text: 'secreat-key-string',
  file: 'package.json',
});
const token = cipherToken.tokenize('Secret Text encrypted by a combo key');
console.log('Token', ': ', token);

//   Decrypt:
const decipherToken = getDecipherToken();
await decipherToken.keyFrom({
  buffer: Buffer.from('buffer_key'),
  text: 'secreat-key-string',
  file: 'package.json',
});
const decrypted = decipherToken.untokenize(token);
console.log('Decrypted', ': ', decrypted);
```

### Key From Random Generated String

```javascript
const {
  getCipherToken,
  getDecipherToken,
  generateRandomString,
} = require('@mgraphic/cipher-token');

//   Encrypt:
const key = generateRandomString();
const cipherToken = getCipherToken();
cipherToken.keyFromString(key);
const token = cipherToken.tokenize(
  'Secret Text encrypted by a random bytes key'
);
console.log('Token', ': ', token);

//   Decrypt:
const decipherToken = getDecipherToken();
decipherToken.keyFromString(key);
const decrypted = decipherToken.untokenize(token);
console.log('Decrypted', ': ', decrypted);
```

---

## Author

**Keith Marshall <keith@kmarshall.com>**

- Github: [@mgraphic](https://github.com/mgraphic)
- LinkedIn: [@marshallgraphic](https://linkedin.com/in/marshallgraphic)

## License

Copyright © 2024 [Keith Marshall <keith@kmarshall.com>](https://github.com/mgraphic).<br />
This project is [MIT](https://github.com/mgraphic/cipher-token/blob/master/LICENSE) licensed.