Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status

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.

Why use magic

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.


Load auth0-magic before any process listener is added or remove all uncaughtException process listeners right after requiring magic.

auth0-magic currently uses libsodium.js#0.7.6 which removes all uncaughtException listeners during the module load .libsodium.js needs to do that because it is generated by EMScripten which adds listeners during build. Related issue in libsodium.js repo here


  const magic = require('auth0-magic');


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

Recommended input type

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.