bcrypt-ts

Optimized bcrypt in TypeScript with zero dependencies. Compatible to the C++ bcrypt binding on Node.js and also working in the browser.

Why bcrypt-ts instead of bcrypt.js

• bcrypt-ts is fully written in TypeScript
• bcrypt-ts provides dual ESM/cjs mode for both Node.js and browser environments
• Minified output
• Tree shakable

Security considerations

Besides incorporating a salt to protect against rainbow table attacks, bcrypt is an adaptive function: over time, the iteration count can be increased to make it slower, so it remains resistant to brute-force search attacks even with increasing computation power. (see)

While bcrypt-ts is compatible with the C++ bcrypt binding, it is built in pure JavaScript and thus slower (about 30%), effectively reducing the number of iterations that can be processed in an equal time span.

The maximum input length is 72 bytes (note that UTF-8 encoded characters use up to 4 bytes) and the length of generated hashes is 60 characters. Note that maximum input length is not implicitly checked by the library for compatibility with the C++ binding on Node.js, but should be checked with truncates(password) where necessary.

Install

Node.js

Install the package:

1npm install bcrypt-ts

CDN

jsDelivr:

• https://cdn.jsdelivr.net/npm/bcrypt-ts/dist/browser.mjs (ESM)
• https://cdn.jsdelivr.net/npm/bcrypt-ts/dist/browser.umd.js (UMD)

unpkg:

• https://unpkg.com/bcrypt-ts/dist/browser.mjs (ESM)
• https://unpkg.com/n/bcrypt-ts/dist/browser.umd.js (UMD)

Usage

On Node.js, the inbuilt crypto module's randomBytes interface is used to obtain secure random numbers.

Browser

In the browser, bcrypt.js relies on Web Crypto API's getRandomValues interface to obtain secure random numbers. If no cryptographically secure source of randomness is available, the package will throw an error.

How to choose between them

• If you are using this package in pure Node.js environment, then you will probably use the node bundle.
• If you are using bundler like webpack or Vite, then you will probably use the browser bundle.
• If you meet any issues where an incorrect bundle is used, you can import from bcrypt-ts/node and bcrypt-ts/browser to manually select the bundle.

Usage - Sync

To hash a password:

1import { genSaltSync, hashSync } from "bcrypt-ts";
2
3const salt = genSaltSync(10);
4const result = hashSync("B4c0//", salt);
5// Store hash in your password DB

To check a password:

1import { compareSync } from "bcrypt-ts";
2
3// Load hash from your password DB
4const hash = "xxx";
5
6compareSync("B4c0//", hash); // true
7compareSync("not_bacon", hash); // false

Auto-gen a salt and hash at the same time:

1import { hashSync } from "bcrypt-ts";
2
3const result = hashSync("bacon", 8);

Usage - Async

To hash a password:

1import { genSalt, hash } from "bcrypt-ts";
2
3const salt = await genSalt(10);
4const result = await hash("B4c0//", salt);
5// Store hash in your password DB

To check a password:

1import { compare } from "bcrypt-ts";
2
3// Load hash from your password DB
4const hash = "xxxxxx";
5
6await compare("B4c0//", hash); // true
7await compare("not_bacon", hash); // false

Auto-gen a salt and hash:

1import { hash } from "bcrypt-ts";
2
3const result = await hash("B4c0//", 10);
4// Store hash in your password DB

Note: Under the hood, asynchronous APIs split an operation into small chunks. After the completion of a chunk, the execution of the next chunk is placed on the back of the JS event queue, efficiently yielding for other computation to execute.

Usage - Command Line

Usage: bcrypt <input> [rounds|salt]

API

1/**
2 * Synchronously tests a string against a hash.
3 *
4 * @param content String to compare
5 * @param hash Hash to test against
6 */
7export const compareSync: (content: string, hash: string) => boolean;
8/**
9 * Asynchronously compares the given data against the given hash.
10 *
11 * @param content Data to compare
12 * @param hash Data to be compared to
13 * @param progressCallback Callback successively called with the percentage of rounds completed
14 *  (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
15 */
16export const compare: (
17  content: string,
18  hash: string,
19  progressCallback?: ((percent: number) => void) | undefined,
20) => Promise<boolean>;
21
22/**
23 * Synchronously generates a hash for the given string.
24 *
25 * @param contentString String to hash
26 * @param salt Salt length to generate or salt to use, default to 10
27 * @returns Resulting hash
28 */
29export const hashSync: (
30  contentString: string,
31  salt?: string | number,
32) => string;
33/**
34 * Asynchronously generates a hash for the given string.
35 *
36 * @param contentString String to hash
37 * @param salt Salt length to generate or salt to use
38 * @param progressCallback Callback successively called with the percentage of rounds completed
39 *  (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
40 */
41export const hash: (
42  contentString: string,
43  salt: number | string,
44  progressCallback?: ((progress: number) => void) | undefined,
45) => Promise<string>;
46
47/**
48 * Gets the number of rounds used to encrypt the specified hash.
49 *
50 * @param hash Hash to extract the used number of rounds from
51 * @returns Number of rounds used
52 * @throws {Error} If `hash` is not a string
53 */
54export const getRounds: (hash: string) => number;
55/**
56 * Gets the salt portion from a hash. Does not validate the hash.
57 *
58 * @param hash Hash to extract the salt from
59 * @returns Extracted salt part
60 * @throws {Error} If `hash` is not a string or otherwise invalid
61 */
62export const getSalt: (hash: string) => string;
63
64/**
65 * Synchronously generates a salt.
66 *
67 * @param rounds Number of rounds to use, defaults to 10 if omitted
68 * @returns Resulting salt
69 * @throws {Error} If a random fallback is required but not set
70 */
71export const genSaltSync: (rounds?: number) => string;
72/**
73 * Asynchronously generates a salt.
74 *
75 * @param rounds Number of rounds to use, defaults to 10 if omitted
76 */
77export const genSalt: (rounds?: number) => Promise<string>;

Credits

• Based on bcrypt.js

  • Based on work started by Shane Girish at bcrypt-nodejs
    • Based on javascript-bcrypt (New BSD-licensed).