magic is a lightweight wrapper around the crypto interface to OpenSSL and the libsodium library which provides a standard cryptography API for internal use, consistent with best current practices recommended by the product security team at Auth0. Named not for what it is intended to do, but for what it is intended to prevent.
All public functions support both callbacks and promises (and therefore async/await), allowing easy integration into any preexisting codebase. All constructions requiring secret keys will generate them as necessary if they are not supplied, and return them for future use.
Supported Node versions: >= 12
This is a fork of the original repository located here. This repository is meant to replace the other repository for archival purposes when it eventually gets deleted.
Most libraries offering a cryptography toolkit allow for a variety of configuration. Usually the reasoning behind this is to empower the developer to configure the cryptography functions as they like. At the same time however this requires developers to be knowledgable of what the different parameters are for and how they affect the security of the function output. Bad choices in parameters can lead to insecure cryptography with disastrous results.
magic is a library that supports as little configuration as possible allowing developers to use a cryptography library without needing expert knowledge. Secure configuration is embedded in the library following best current practices recommended by the Product Security team at Auth0.
npm install auth0-magic
magic offers a variety of functions for the following cases:
magic also offers a variety of utility functions:
Magic implements a core and and alt API. The core api implements the recommended algorithms for each cryptographic operation. When in doubt, please use them. The alt api implements alternative algorithms for each cryptographic operation. They should only be used over the core api when required by an external specification or interoperability concerns.
Detailed documentation on the supported API can be found in the /docs folder
It is recommended that magic is always used with node.js buffers for all (non-boolean) inputs, with the exception of passwords.
Due to the variety of tasks to which it may be put, the library attempts to be as unopinionated about encoding as it is opinionated about algorithms. There is minimal decoding functionality, which will attempt to break down any plaintext input as utf-8 and any cryptographic input (keys, ciphertexts, macs, signatures, etc.) as hex. If as a consumer of this library you decide to depend on this builtin decoder it is recommended that you extensively test it to make sure your inputs are being parsed appropriately. When in doubt, it is always safer to parse them yourself and pass in binary data.