npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

quick-crypto

v1.0.0

Published

Easy way to encrypt and decrypt objects and values.

Downloads

5

Readme

Quick Crypto

An easy way to encrypt and decrypt objects and simple strings with TypeScript.

With this library, you can easily encrypt both complex objects and simple values.

Installation

npm install quick-crypto

Build

npm run build

Test

npm run test

Methods list:

These are the ten methods you can use from this library:

  • cipherObject()
  • decipherObject()
  • cipherObjects()
  • decipherObjects()
  • cipherValue()
  • decipherValue()
  • cipherValues()
  • decipherValues()
  • generateKeyAndIv()
  • getDefaultKeyAndIv()

Additional Notes

  • All cipher and decipher methods have the option to receive a custom key and iv. If they are not provided, the values will be encrypted with the default key of this library.

  • To generate your own key and iv, you can use the method generateKeyAndIv(), and if you need to know the default key and iv, you can use the method getDefaultKeyAndIv().

  • The best approach to use this in production would be to generate custom keys and ivs with generateKeyAndIv().

  • It is possible to create your own key and iv, save them in a database, and use them to encrypt your data.

  • In the examples below, the encrypted values are just representative and are not the same as the real ones.

Usage

Each method will be explained below.

cipherObject

  • This method is used to easily encrypt any object properties.
  • You can pass an array of strings with the names of the properties of the object that you want to encrypt.
  • If no key and/or iv is given, it will use the default key and/or iv.
  • Below is an example of how this method works.

Signature

cipherObject<T extends Record<string, any>>(obj: T, propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T;

Examples

Let's create an Address object to show how this method works.

import { cipherObject } from 'quick-crypto';

type Address = {
    street: string,
    number: number,
    state: string,
    city: string
};

const address: Address = {
    street: 'some street',
    number: 123,
    state: 'NY',
    city: 'New York'
};

// It will encrypt all string properties and use the default key and iv
const cryptoAddress = cipherObject<Address>(address);
console.log(cryptoAddress);
// { 
//   street: 'erblfebrfluierlwuhlrl738743bdwd',
//   number: 123,
//   state: 'jqwnkbdkwekwyeg7',
//   city: 'lenkwndekuw8'
// }

// It will encrypt only the properties passed in the array in the second parameter and use the default key and iv
const cryptoAddress2 = cipherObject<Address>(address, ['street', 'city']);
console.log(cryptoAddress2);
// { 
//   street: 'erblfebrfluierlwuhlrl738743bdwd',
//   number: 123,
//   state: 'NY',
//   city: 'lenkwndekuw8'
// }

Example (using custom key and iv)

import { cipherObject, generateKeyAndIv } from 'quick-crypto';

type Address = {
    street: string,
    number: number,
    state: string,
    city: string
};

const address: Address = {
    street: 'some street',
    number: 123,
    state: 'NY',
    city: 'New York'
};

// It will encrypt only the properties passed in the array in the second parameter using the generated key and iv
const { key, iv } = generateKeyAndIv();
const cryptoAddress = cipherObject<Address>(address, ['street', 'city'], key, iv);
console.log(cryptoAddress);
// { 
//   street: 'erblfebrfluierlwuhlrl738743bdwd',
//   number: 123,
//   state: 'NY',
//   city: 'lenkwndekuw8'
// }

// It will encrypt all string properties using the generated key and iv
const { key: key2, iv: iv2 } = generateKeyAndIv();
const cryptoAddress2 = cipherObject<Address>(address, undefined, key2, iv2);
console.log(cryptoAddress2);
// { 
//   street: 'erblfebrfluierlwuhlrl738743bdwd',
//   number: 123,
//   state: 'dkhbcdkd',
//   city: 'lenkwndekuw8'
// }

// It will encrypt all string properties using the generated key and the default iv
const { key: key3 } = generateKeyAndIv();
const cryptoAddress3 = cipherObject<Address>(address, undefined, key3);
console.log(cryptoAddress3);
// { 
//   street: 'erblfebrfluierlwuhlrl738743bdwd',
//   number: 123,
//   state: 'dkhbcdkd',
//   city: 'lenkwndekuw8'
// }

decipherObject

  • This method is used to decrypt an object.
  • The same key and iv used to encrypt the object need to be provided.
  • If the default key and/or iv were used to encrypt the object, you don't need to pass any parameters.
  • Similar to the cipherObject method, you can pass an array of strings with the names of the object properties to be decrypted.

Signature

decipherObject<T extends Record<string, any>>(obj: T, propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T;

Examples

To show how this method works, we will create a encrypted address object.

import { decipherObject } from 'quick-crypto';

type Address = {
    street: string,
    number: number,
    state: string,
    city: string
};

const encryptedAddress: Address = {
    street: 'skjdckkdkwnjkqlklqwxwxw',
    number: 123,
    state: 'qlqnknslqskqnl',
    city: 'endkwdxkwnjknwnjxwk'
};

// It will decrypt all string properties of the object using the default key and iv.
const decryptedAddress = decipherObject<Address>(encryptedAddress);
console.log(decryptedAddress);
// { 
//   street: 'some street',
//   number: 123,
//   state: 'NY',
//   city: 'New York'
// }

// It will decrypt only the properties received in the array in the second parameter using the default key and iv.
const decryptedAddress2 = decipherObject<Address>(encryptedAddress, ['street', 'city']);
console.log(decryptedAddress2);
// { 
//   street: 'some street',
//   number: 123,
//   state: 'qlqnknslqskqnl',
//   city: 'New York'
// }

Example (using custom key and iv)

import { decipherObject, generateKeyAndIv } from 'quick-crypto';

type Address = {
    street: string,
    number: number,
    state: string,
    city: string
};

const encryptedAddress: Address = {
    street: 'skjdckkdkwnjkqlklqwxwxw',
    number: 123,
    state: 'qlqnknslqskqnl',
    city: 'endkwdxkwnjknwnjxwk'
};

const { key, iv } = generateKeyAndIv();

// It will decrypt the properties using the same key and iv that were used to encrypt them.
const decryptedAddress = decipherObject<Address>(encryptedAddress, ['street', 'city'], key, iv);
console.log(decryptedAddress);
// { 
//   street: 'some street',
//   number: 123,
//   state: 'qlqnknslqskqnl',
//   city: 'New York'
// }

// It will decrypt all string properties using the same key and iv that were used to encrypt them.
const decryptedAddress2 = decipherObject<Address>(encryptedAddress, undefined, key, iv);
console.log(decryptedAddress2);
// { 
//   street: 'some street',
//   number: 123,
//   state: 'NY',
//   city: 'New York'
// }

Additional Notes

  • To use a custom key and iv to decrypt objects, it must be the same key and iv used to encrypt the object.
  • If no key and/or iv is given, the method will use the default key and iv to decrypt the object.
  • Ensure that the keys and ivs used for encryption and decryption match to avoid errors.
  • In the examples above, the encrypted values are just representative and are not the same as the real ones.

cipherObjects

  • This method is similar to the cipherObject method, but it accepts an array of objects to encrypt instead of a single object.
  • It is used to easily encrypt any array of objects.
  • You can pass an array of strings with the names of the properties you want to encrypt.
  • If no key and/or IV is provided, the default key and/or IV will be used.
  • It returns an array of objects of the same type as the input array.
  • Below is an example demonstrating how this method works.

Signature

cipherObjects<T extends Record<string, any>>(obj: T[], propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T[];

Examples

Let's create an Address object and an array of addresses to show how this method works:

import { cipherObjects } from 'quick-crypto';

type Address = {
  street: string,
  number: number,
  state: string,
  city: string
}

const addresses: Address[] = [
  {
    street: 'some street',
    number: 123,
    state: 'NY',
    city: 'New York'
  },
  {
    street: 'some other street',
    number: 987,
    state: 'CA',
    city: 'San Francisco'
  }
];

// Encrypts all string properties of all objects in the array using the default key and IV
const encryptedAddresses = cipherObjects<Address>(addresses);
console.log(encryptedAddresses);
// [
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 123,
//     state: 'jqwnkbdkwekwyeg7',
//     city: 'lenkwndekuw8'
//   },
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 987,
//     state: 'jqwnkbdkwekwyeg7',
//     city: 'lenkwndekuw8'
//   }
// ] 

// Encrypts only the 'street' and 'city' properties of all objects in the array using the default key and IV
const encryptedAddresses2 = cipherObjects<Address>(addresses, ['street', 'city']);
console.log(encryptedAddresses2);
// [
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 123,
//     state: 'NY',
//     city: 'lenkwndekuw8'
//   },
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 987,
//     state: 'CA',
//     city: 'lenkwndekuw8'
//   }
// ] 

Example (using custom key and iv)

import { cipherObjects, generateKeyAndIv } from 'quick-crypto';

type Address = {
  street: string,
  number: number,
  state: string,
  city: string
}

const addresses: Address[] = [
  {
    street: 'some street',
    number: 123,
    state: 'NY',
    city: 'New York'
  },
  {
    street: 'some other street',
    number: 987,
    state: 'CA',
    city: 'San Francisco'
  }
];

// Generate a custom key and IV
const { key, iv } = generateKeyAndIv();

// Encrypt the 'street' and 'city' properties using the custom key and IV
const encryptedAddresses = cipherObjects<Address>(addresses, ['street', 'city'], key, iv);
console.log(encryptedAddresses);
// [
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 123,
//     state: 'NY',
//     city: 'lenkwndekuw8'
//   },
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 987,
//     state: 'CA',
//     city: 'lenkwndekuw8'
//   }
// ] 

// Encrypt all string properties using the custom key and IV
const encryptedAddresses2 = cipherObjects<Address>(addresses, undefined, key, iv);
console.log(encryptedAddresses2);
// [
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 123,
//     state: 'bkjsw',
//     city: 'lenkwndekuw8'
//   },
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 987,
//     state: 'kqjwksq',
//     city: 'lenkwndekuw8'
//   }
// ] 

// Encrypt all string properties using the custom key and the default IV
const { key } = generateKeyAndIv();
const encryptedAddresses3 = cipherObjects<Address>(addresses, undefined, key);
console.log(encryptedAddresses3);
// [
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 123,
//     state: 'bkjsw',
//     city: 'lenkwndekuw8'
//   },
//   { 
//     street: 'erblfebrfluierlwuhlrl738743bdwd',
//     number: 987,
//     state: 'kqjwksq',
//     city: 'lenkwndekuw8'
//   }
// ] 

decipherObjects

  • This method is similar to the decipherObject method, but it accepts an array of encrypted objects to decrypt instead of a single object.
  • It is used to easily decrypt any array of objects.
  • You can pass an array of strings with the names of the properties you want to decrypt.
  • If no key and/or IV is provided, the default key and/or IV will be used.
  • It returns an array of objects of the same type as the input array.
  • Below is an example demonstrating how this method works.

Signature

decipherObjects<T extends Record<string, any>>(obj: T[], propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T[];

Examples

Let's create an Address object and an array of encrypted addresses to show how this method works:

import { decipherObjects } from 'quick-crypto';

type Address = {
  street: string,
  number: number,
  state: string,
  city: string
}

const encryptedAddresses: Address[] = [
  {
    street: 'eldnel2kwl2w2lsm22',
    number: 123,
    state: 'w2knsk2wjk2k',
    city: 'ls2wkjnksjn2kjwnk'
  },
  {
    street: '2kwl2wm2lwk2wl2lw',
    number: 987,
    state: 'kwml2mw2swkl2',
    city: '2lkmw2lm2ls'
  }
];

// Decrypts all string properties of all objects in the array using the default key and IV
const decryptedAddresses = decipherObjects<Address>(encryptedAddresses);
console.log(decryptedAddresses);
// [
//  {
//    street: 'some street',
//    number: 123,
//    state: 'NY',
//    city: 'New York'
//  },
//  {
//    street: 'some other street',
//    number: 987,
//    state: 'CA',
//    city: 'San Francisco'
//  }
// ] 

// Decrypts only the 'street' and 'city' properties of all objects in the array using the default key and IV
const decryptedAddresses2 = decipherObjects<Address>(encryptedAddresses, ['street', 'city']);
console.log(decryptedAddresses2);
// [
//  {
//    street: 'some street',
//    number: 123,
//    state: 'w2knsk2wjk2k',
//    city: 'New York'
//  },
//  {
//    street: 'some other street',
//    number: 987,
//    state: 'kwml2mw2swkl2',
//    city: 'San Francisco'
//  }
// ] 
  • To use a custom key and IV to decipher objects, they must be the same key and IV used to encrypt the objects.

cipherValue, decipherValue, cipherValues, and decipherValues

  • These methods are used to encrypt and decrypt strings or an array of strings.
  • You can use the default key and IV, or provide a custom key and IV, similar to the other methods in this library.

Signature

cipherValue(value: string, key?: string, iv?: string): string;
decipherValue(value: string, key?: string, iv?: string): string;
cipherValues(values: string[], key?: string, iv?: string): string[];
decipherValues(values: string[], key?: string, iv?: string): string[];

Examples (Single string with default key and IV)

import { cipherValue, decipherValue } from 'quick-crypto';

const myString = 'hello';

// Encrypt the value with default key and IV
const encrypted = cipherValue(myString);
console.log(encrypted);
// jk3k3ej3bkde3

// Decrypt the value
const decrypted = decipherValue(encrypted);
console.log(decrypted);
// hello

Examples (Single string with custom key and IV)

import { cipherValue, decipherValue, generateKeyAndIv } from 'quick-crypto';

const { key, iv } = generateKeyAndIv();
const myString = 'hello';

// Encrypt the value with custom key and IV
const encrypted = cipherValue(myString, key, iv);
console.log(encrypted);
// jk3k3ej3bkde3

// Decrypt the value
const decrypted = decipherValue(encrypted, key, iv);
console.log(decrypted);
// hello

Examples (Array of strings with default key and IV)

import { cipherValues, decipherValues } from 'quick-crypto';

const myStringArray = ['hello', 'world', 'code'];

// Encrypt each value with default key and IV
const encrypted = cipherValues(myStringArray);
console.log(encrypted);
// ['ml2nkws2l', 'k2jwk2kn2', '2ljw2nkw2']

// Decrypt the values
const decrypted = decipherValues(encrypted);
console.log(decrypted);
// ['hello', 'world', 'code']

Examples (Array of strings with custom key and IV)

import { cipherValues, decipherValues, generateKeyAndIv } from 'quick-crypto';

const { key, iv } = generateKeyAndIv();
const myStringArray = ['hello', 'world', 'code'];

// Encrypt the values with custom key and IV
const encrypted = cipherValues(myStringArray, key, iv);
console.log(encrypted);
// ['ml2nkws2l', 'k2jwk2kn2', '2ljw2nkw2']

// Decrypt the values
const decrypted = decipherValues(encrypted, key, iv);
console.log(decrypted);
// ['hello', 'world', 'code']

generateKeyAndIv

  • This method is used to generate a random key and IV to encrypt values.
  • It returns a 32-character key and a 16-character IV.

Signature

generateKeyAndIv(): { key: string, iv: string }

Example

import { generateKeyAndIv } from 'quick-crypto';

const { key, iv } = generateKeyAndIv();
console.log(key, iv);
// 456s73667d1dadbafa935dgba3ecdfkl
// t7654wedsdr0679l

getDefaultKeyAndIv

  • This method returns the default key and IV used in this library and is recommended for testing purposes.
  • It returns a 32-character key and a 16-character IV.

Signature

getDefaultKeyAndIv(): { key: string, iv: string }

Example

import { getDefaultKeyAndIv } from 'quick-crypto';

const { key, iv } = getDefaultKeyAndIv();
console.log(key, iv);
// 456s73667d1dadbafa935dgba3ecdfkl
// t7654wedsdr0679l