Quickstart

Getting started with @nhtio/encryption is quick and easy. Just follow the steps below and you'll be up and running in no time.

Prerequisites

• Node.js version 22 or higher.

Installation

You can install @nhtio/encryption directly from your preferred package manager

npm

npm i @nhtio/encryption

pnpm

pnpm add @nhtio/encryption

yarn

yarn add @nhtio/encryption

Initializing the Encryption Class

Create an instance of the encryption class using a secret key which is at least 32 characters long:

import { Encryption, Secret } from '@nhtio/encryption'
const encryption = new Encryption(new Secret('...'))

What is a Secret?

A Secret is a special wrapper around content which should not be exposed in logs, during JSON serialization or during string concatenation.

To understand why you need a special Secret object, you need to understand the root of the problem. Let's start with an example.

Given that you have a Token class that generates an opaque token for a user and persists its hash inside the database. The plain token (aka raw value) is shared with the user and it should only be visible once (for security reasons). Here is a dummy implementation of the same.

class Token {
  generate() {
    return {
      value: 'opaque_raw_token',
      hash: 'hash_of_raw_token_inside_db',
    }
  }
}

const token = new Token().generate()
return response.send(token)

At the same time, you want to drop a log statement inside your application that you can later use to debug the flow of the application, and this is how you log the token.

const token = new Token().generate()

logger.log('token generated %O', token)
// token generated {"value":"opaque_raw_token","hash":"hash_of_raw_token_inside_db"}

return response.send(token)

BOOM! You have weakened the security of your app. Now, anyone monitoring the logs can grab raw token values from the log and use them to perform the actions on behalf of the user.

Now, to prevent this from happening, you should work with a branded data type. Our old friend PHP has it, so we need it as well.

This is what exactly the Secret utility class does for you. Create values that prevent themselves from leaking inside logs or during JSON serialization.

import { Secret } from '@nhtio/encryption'

class Token {
  generate() {
    return {
      // THIS LINE 👇
      value: new Secret('opaque_raw_token'),
      hash: 'hash_of_raw_token_inside_db',
    }
  }
}

const token = new Token().generate()

logger.log('token generated %O', token)
// AND THIS LOG 👇
// token generated {"value":"[redacted]","hash":"hash_of_raw_token_inside_db"}

return response.send(token)

Need the original value back? You can call the release method to get the secret value back. Again, the idea is not to prevent your code from accessing the raw value. It's to stop the logging and serialization layer from reading it.

const secret = new Secret('opaque_raw_token')
const rawValue = secret.release()

rawValue === opaque_raw_token // true

Encrypting values

You may encrypt values using the Encryption.encrypt method. The method accepts the value to encrypt and an optional time duration after which to consider the value expired.

import { Encryption, Secret } from '@nhtio/encryption'
const encryption = new Encryption(new Secret('...'))
const encrypted = encryption.encrypt('hello world')

Define a time duration after which the value will be considered expired and cannot be decrypted.

import { Encryption, Secret } from '@nhtio/encryption'
const encryption = new Encryption(new Secret('...'))
const encrypted = encryption.encrypt('hello world', '2 hours')

Decrypting values

Encrypted values can be decrypted using the Encryption.decrypt method. The method accepts the encrypted value as the first argument.

import { Encryption, Secret } from '@nhtio/encryption'
const encryption = new Encryption(new Secret('...'))
encryption.decrypt(encryptedValue)

Supported data types

See the documentation for @nhtio/serialization for more information about supported types.