Hashing

Bun.password

Bun.password is a collection of utility functions for hashing and verifying passwords with various cryptographically secure algorithms.

const password = "super-secure-pa$$word";

const hash = await Bun.password.hash(password);
// => $argon2id$v=19$m=65536,t=2,p=1$tFq+9AVr1bfPxQdh6E8DQRhEXg/M/SqYCNu6gVdRRNs$GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4

const isMatch = await Bun.password.verify(password, hash);
// => true

The second argument to Bun.password.hash accepts a params object that lets you pick and configure the hashing algorithm.

const password = "super-secure-pa$$word";

// use argon2 (default)
const argonHash = await Bun.password.hash(password, {
  algorithm: "argon2id", // "argon2id" | "argon2i" | "argon2d"
  memoryCost: 4, // memory usage in kibibytes
  timeCost: 3, // the number of iterations
});

// use bcrypt
const bcryptHash = await Bun.password.hash(password, {
  algorithm: "bcrypt",
  cost: 4, // number between 4-31
});

The algorithm used to create the hash is stored in the hash itself. When using bcrypt, the returned hash is encoded in Modular Crypt Format for compatibility with most existing bcrypt implementations; with argon2 the result is encoded in the newer PHC format.

The verify function automatically detects the algorithm based on the input hash and use the correct verification method. It can correctly infer the algorithm from both PHC- or MCF-encoded hashes.

const password = "super-secure-pa$$word";

const hash = await Bun.password.hash(password, {
  /* config */
});

const isMatch = await Bun.password.verify(password, hash);
// => true

Synchronous versions of all functions are also available. Keep in mind that these functions are computationally expensive, so using a blocking API may degrade application performance.

const password = "super-secure-pa$$word";

const hash = Bun.password.hashSync(password, {
  /* config */
});

const isMatch = Bun.password.verifySync(password, hash);
// => true

Bun.hash

Bun.hash is a collection of utilities for non-cryptographic hashing. Non-cryptographic hashing algorithms are optimized for speed of computation over collision-resistance or security.

The standard Bun.hash functions uses Wyhash to generate a 64-bit hash from an input of arbitrary size.

Bun.hash("some data here");
// 11562320457524636935n

The input can be a string, TypedArray, DataView, ArrayBuffer, or SharedArrayBuffer.

const arr = new Uint8Array([1, 2, 3, 4]);

Bun.hash("some data here");
Bun.hash(arr);
Bun.hash(arr.buffer);
Bun.hash(new DataView(arr.buffer));

Optionally, an integer seed can be specified as the second parameter. For 64-bit hashes seeds above Number.MAX_SAFE_INTEGER should be given as BigInt to avoid loss of precision.

Bun.hash("some data here", 1234);
// 15724820720172937558n

Additional hashing algorithms are available as properties on Bun.hash. The API is the same for each, only changing the return type from number for 32-bit hashes to bigint for 64-bit hashes.

Bun.hash.wyhash("data", 1234); // equivalent to Bun.hash()
Bun.hash.crc32("data", 1234);
Bun.hash.adler32("data", 1234);
Bun.hash.cityHash32("data", 1234);
Bun.hash.cityHash64("data", 1234);
Bun.hash.murmur32v3("data", 1234);
Bun.hash.murmur32v2("data", 1234);
Bun.hash.murmur64v2("data", 1234);

Bun.CryptoHasher

Bun.CryptoHasher is a general-purpose utility class that lets you incrementally compute a hash of string or binary data using a range of cryptographic hash algorithms. The following algorithms are supported:

• "blake2b256"
• "blake2b512"
• "md4"
• "md5"
• "ripemd160"
• "sha1"
• "sha224"
• "sha256"
• "sha384"
• "sha512"
• "sha512-224"
• "sha512-256"
• "sha3-224"
• "sha3-256"
• "sha3-384"
• "sha3-512"
• "shake128"
• "shake256"

const hasher = new Bun.CryptoHasher("sha256");
hasher.update("hello world");
hasher.digest();
// Uint8Array(32) [ <byte>, <byte>, ... ]

Once initialized, data can be incrementally fed to to the hasher using .update(). This method accepts string, TypedArray, and ArrayBuffer.

const hasher = new Bun.CryptoHasher("sha256");

hasher.update("hello world");
hasher.update(new Uint8Array([1, 2, 3]));
hasher.update(new ArrayBuffer(10));

If a string is passed, an optional second parameter can be used to specify the encoding (default 'utf-8'). The following encodings are supported:

hasher.update("hello world"); // defaults to utf8
hasher.update("hello world", "hex");
hasher.update("hello world", "base64");
hasher.update("hello world", "latin1");

After the data has been feed into the hasher, a final hash can be computed using .digest(). By default, this method returns a Uint8Array containing the hash.

const hasher = new Bun.CryptoHasher("sha256");
hasher.update("hello world");

hasher.digest();
// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]

The .digest() method can optionally return the hash as a string. To do so, specify an encoding:

hasher.digest("base64");
// => "uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek="

hasher.digest("hex");
// => "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"

Alternatively, the method can write the hash into a pre-existing TypedArray instance. This may be desirable in some performance-sensitive applications.

const arr = new Uint8Array(32);

hasher.digest(arr);

console.log(arr);
// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]