bcrypt-ts

零依赖的 TypeScript 优化版 bcrypt。兼容 Node.js 上的 C++ bcrypt 绑定，并可在浏览器中运行。

为什么选择 bcrypt-ts 而不是 bcrypt.js

• 完全使用 TypeScript 编写
• 为 Node.js 和浏览器环境提供独立的 ESM 模块
• 压缩后的输出
• 更好的 tree-shaking

安全注意事项

除了引入盐值以抵御彩虹表攻击外，bcrypt 是一种自适应函数：随着时间推移， 迭代次数可以增加以使其变慢，因此即使计算能力不断提升，它仍能抵御暴力搜索攻击。（参见）

虽然 bcrypt-ts 与 C++ bcrypt 绑定兼容，但它由纯 JavaScript 构建，因此速度较慢（约慢 30%），实际上减少了在相同时间跨度内可处理的迭代次数。

最大输入长度为 72 字节（请注意，UTF-8 编码的字符最多占用 4 字节），生成的 哈希长度为 60 个字符。请注意，为了与 Node.js 上的 C++ 绑定保持兼容，库不会隐式检查最大输入长度，但必要时应使用 truncates(password) 进行检查。

安装

Node.js

安装该包：

npm install bcrypt-ts

CDN

jsDelivr:

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

unpkg:

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

用法

在 Node.js 中，使用内置的 crypto 模块 的 randomBytes 接口来获取安全随机数。

浏览器

在浏览器中，bcrypt.js 依赖 Web Crypto API 的 getRandomValues 接口来获取安全随机数。如果没有可用的密码学安全随机源，该包将抛出错误。

如何在这两者之间进行选择

• 如果你是在纯 Node.js 环境中使用此包，那么你可能会使用 node 捆绑包。
• 如果你使用的是 webpack 或 Vite 等打包工具，那么你可能会使用浏览器捆绑包。
• 如果你遇到因使用了错误捆绑包而导致的问题，你可以从 bcrypt-ts/node 和 bcrypt-ts/browser 导入以手动选择捆绑包。

用法 - 同步

要对密码进行哈希：

import { genSaltSync, hashSync } from "bcrypt-ts";

const salt = genSaltSync(10);
const result = hashSync("B4c0//", salt);
// Store hash in your password DB

要检查密码：

import { compareSync } from "bcrypt-ts";

// Load hash from your password DB
const hash = "xxx";

compareSync("B4c0//", hash); // true
compareSync("not_bacon", hash); // false

同时自动生成盐和哈希：

import { hashSync } from "bcrypt-ts";

const result = hashSync("bacon", 8);

用法 - 异步

要哈希一个密码：

import { genSalt, hash } from "bcrypt-ts";

const salt = await genSalt(10);
const result = await hash("B4c0//", salt);
// Store hash in your password DB

要检查密码：

import { compare } from "bcrypt-ts";

// Load hash from your password DB
const hash = "xxxxxx";

await compare("B4c0//", hash); // true
await compare("not_bacon", hash); // false

自动生成盐和哈希：

import { hash } from "bcrypt-ts";

const result = await hash("B4c0//", 10);
// Store hash in your password DB

注意： 在底层，异步 API 将操作拆分为小块。在完成一个块后，下一个块的执行被放置在 JS 事件队列 的末尾，从而高效地让出执行权给其他计算。

用法 - 命令行

Usage: bcrypt <input> [rounds|salt]

API

/**
 * Synchronously tests a string against a hash.
 *
 * @param content String to compare
 * @param hash Hash to test against
 */
export const compareSync: (content: string, hash: string) => boolean;
/**
 * Asynchronously compares the given data against the given hash.
 *
 * @param content Data to compare
 * @param hash Data to be compared to
 * @param progressCallback Callback successively called with the percentage of rounds completed
 *  (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
 */
export const compare: (
  content: string,
  hash: string,
  progressCallback?: ((percent: number) => void) | undefined,
) => Promise<boolean>;

/**
 * Synchronously generates a hash for the given string.
 *
 * @param contentString String to hash
 * @param salt Salt length to generate or salt to use, default to 10
 * @returns Resulting hash
 */
export const hashSync: (contentString: string, salt?: string | number) => string;
/**
 * Asynchronously generates a hash for the given string.
 *
 * @param contentString String to hash
 * @param salt Salt length to generate or salt to use
 * @param progressCallback Callback successively called with the percentage of rounds completed
 *  (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
 */
export const hash: (
  contentString: string,
  salt: number | string,
  progressCallback?: ((progress: number) => void) | undefined,
) => Promise<string>;

/**
 * Gets the number of rounds used to encrypt the specified hash.
 *
 * @param hash Hash to extract the used number of rounds from
 * @returns Number of rounds used
 * @throws {Error} If `hash` is not a string
 */
export const getRounds: (hash: string) => number;
/**
 * Gets the salt portion from a hash. Does not validate the hash.
 *
 * @param hash Hash to extract the salt from
 * @returns Extracted salt part
 * @throws {Error} If `hash` is not a string or otherwise invalid
 */
export const getSalt: (hash: string) => string;

/**
 * Synchronously generates a salt.
 *
 * @param rounds Number of rounds to use, defaults to 10 if omitted
 * @returns Resulting salt
 * @throws {Error} If a random fallback is required but not set
 */
export const genSaltSync: (rounds?: number) => string;
/**
 * Asynchronously generates a salt.
 *
 * @param rounds Number of rounds to use, defaults to 10 if omitted
 */
export const genSalt: (rounds?: number) => Promise<string>;

致谢

• 基于 bcrypt.js
  • 基于 Shane Girish 在 bcrypt-nodejs 中开始的工作
    • 基于 javascript-bcrypt（采用新 BSD 许可证）。