NOTE

O Bun implementa as funções `createHash` e `createHmac` de [`node:crypto`](https://nodejs.org/api/crypto.html) além das APIs nativas do Bun documentadas abaixo.

---

Bun.password

Bun.password é uma coleção de funções utilitárias para hashing e verificação de senhas com vários algoritmos criptograficamente seguros.

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

O segundo argumento para Bun.password.hash aceita um objeto de parâmetros que permite escolher e configurar o algoritmo de hashing.

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

// usa argon2 (padrão)
const argonHash = await Bun.password.hash(password, {
  algorithm: "argon2id", // "argon2id" | "argon2i" | "argon2d"
  memoryCost: 4, // uso de memória em kibibytes
  timeCost: 3, // número de iterações
});

// usa bcrypt
const bcryptHash = await Bun.password.hash(password, {
  algorithm: "bcrypt",
  cost: 4, // número entre 4-31
});

O algoritmo usado para criar o hash é armazenado no próprio hash. Ao usar bcrypt, o hash retornado é codificado em Modular Crypt Format para compatibilidade com a maioria das implementações existentes de bcrypt; com argon2 o resultado é codificado no formato mais novo PHC.

A função verify detecta automaticamente o algoritmo com base no hash de entrada e usa o método de verificação correto. Ela pode inferir corretamente o algoritmo tanto de hashes codificados em PHC quanto em MCF.

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

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

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

Versões síncronas de todas as funções também estão disponíveis. Tenha em mente que estas funções são computacionalmente caras, então usar uma API bloqueante pode degradar o desempenho da aplicação.

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

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

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

Salt

Quando você usa Bun.password.hash, um salt é automaticamente gerado e incluído no hash.

bcrypt - Modular Crypt Format

No seguinte hash Modular Crypt Format (usado por bcrypt):

Entrada:

await Bun.password.hash("hello", {
  algorithm: "bcrypt",
});

Saída:

$2b$10$Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi;

O formato é composto de:

• bcrypt: $2b
• rounds: $10 - rodadas (log10 do número real de rodadas)
• salt: $Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi
• hash: $GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4

Por padrão, a biblioteca bcrypt trunca senhas maiores que 72 bytes. No Bun, se você passar para Bun.password.hash uma senha maior que 72 bytes e usar o algoritmo bcrypt, a senha será hashada via SHA-512 antes de ser passada para o bcrypt.

await Bun.password.hash("hello".repeat(100), {
  algorithm: "bcrypt",
});

Então, em vez de enviar ao bcrypt uma senha de 500 bytes silenciosamente truncada para 72 bytes, o Bun fará hash da senha usando SHA-512 e enviará a senha hashada para o bcrypt (apenas se exceder 72 bytes). Este é um comportamento padrão mais seguro.

argon2 - Formato PHC

No seguinte hash formato PHC (usado por argon2):

Entrada:

await Bun.password.hash("hello", {
  algorithm: "argon2id",
});

Saída:

$argon2id$v=19$m=65536,t=2,p=1$xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs$2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI

O formato é composto de:

• algorithm: $argon2id
• version: $v=19
• memory cost: 65536
• iterations: t=2
• parallelism: p=1
• salt: $xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs
• hash: $2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI

---

Bun.hash

Bun.hash é uma coleção de utilitários para hashing não criptográfico. Algoritmos de hashing não criptográfico são otimizados para velocidade de computação em vez de resistência a colisão ou segurança.

As funções padrão Bun.hash usam Wyhash para gerar um hash de 64 bits a partir de uma entrada de tamanho arbitrário.

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

A entrada pode ser uma string, TypedArray, DataView, ArrayBuffer ou 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));

Opcionalmente, uma seed inteira pode ser especificada como segundo parâmetro. Para hashes de 64 bits, seeds acima de Number.MAX_SAFE_INTEGER devem ser fornecidas como BigInt para evitar perda de precisão.

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

Algoritmos de hashing adicionais estão disponíveis como propriedades em Bun.hash. A API é a mesma para cada um, mudando apenas o tipo de retorno de number para hashes de 32 bits para bigint para hashes de 64 bits.

Bun.hash.wyhash("data", 1234); // equivalente a Bun.hash()
Bun.hash.crc32("data", 1234);
Bun.hash.adler32("data", 1234);
Bun.hash.cityHash32("data", 1234);
Bun.hash.cityHash64("data", 1234);
Bun.hash.xxHash32("data", 1234);
Bun.hash.xxHash64("data", 1234);
Bun.hash.xxHash3("data", 1234);
Bun.hash.murmur32v3("data", 1234);
Bun.hash.murmur32v2("data", 1234);
Bun.hash.murmur64v2("data", 1234);
Bun.hash.rapidhash("data", 1234);

---

Bun.CryptoHasher

Bun.CryptoHasher é uma classe utilitária de propósito geral que permite computar incrementalmente um hash de string ou dados binários usando uma variedade de algoritmos de hash criptográfico. Os seguintes algoritmos são suportados:

• "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>, ... ]

Uma vez inicializado, os dados podem ser alimentados incrementalmente ao hasher usando .update(). Este método aceita string, TypedArray e ArrayBuffer.

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

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

Se uma string for passada, um segundo parâmetro opcional pode ser usado para especificar a codificação (padrão 'utf-8'). As seguintes codificações são suportadas:

Categoria	Codificações
Codificações binárias	"base64" "base64url" "hex" "binary"
Codificações de caracteres	"utf8" "utf-8" "utf16le" "latin1"
Codificações legadas	"ascii" "binary" "ucs2" "ucs-2"

hasher.update("hello world"); // padrão utf8
hasher.update("hello world", "hex");
hasher.update("hello world", "base64");
hasher.update("hello world", "latin1");

Depois que os dados foram alimentados ao hasher, um hash final pode ser computado usando .digest(). Por padrão, este método retorna um Uint8Array contendo o hash.

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

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

O método .digest() pode opcionalmente retornar o hash como uma string. Para fazer isso, especifique uma codificação:

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

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

Alternativamente, o método pode escrever o hash em uma instância TypedArray pré-existente. Isso pode ser desejável em algumas aplicações sensíveis a desempenho.

const arr = new Uint8Array(32);

hasher.digest(arr);

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

HMAC em Bun.CryptoHasher

Bun.CryptoHasher pode ser usado para computar digests HMAC. Para fazer isso, passe a chave para o construtor.

const hasher = new Bun.CryptoHasher("sha256", "secret-key");
hasher.update("hello world");
console.log(hasher.digest("hex"));
// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"

Ao usar HMAC, um conjunto mais limitado de algoritmos é suportado:

• "blake2b512"
• "md5"
• "sha1"
• "sha224"
• "sha256"
• "sha384"
• "sha512-224"
• "sha512-256"
• "sha512"

Diferente do Bun.CryptoHasher não-HMAC, a instância Bun.CryptoHasher HMAC não é reiniciada após .digest() ser chamado, e tentar usar a mesma instância novamente lançará um erro.

Outros métodos como .copy() e .update() são suportados (desde que seja antes de .digest()), mas métodos como .digest() que finalizam o hasher não são.

const hasher = new Bun.CryptoHasher("sha256", "secret-key");
hasher.update("hello world");

const copy = hasher.copy();
copy.update("!");
console.log(copy.digest("hex"));
// => "3840176c3d8923f59ac402b7550404b28ab11cb0ef1fa199130a5c37864b5497"

console.log(hasher.digest("hex"));
// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"