@molecule/api-password-bcrypt

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Password hashing provider for molecule.dev — the native bcrypt addon, with bcryptjs as the fallback when the addon cannot be loaded.

Quick Start

import { setProvider } from '@molecule/api-password'
import { provider } from '@molecule/api-password-bcrypt'

setProvider(provider) // cost reads SALT_ROUNDS (default 12, clamped 10-16)

Type

provider

Installation

npm install @molecule/api-password-bcrypt @molecule/api-password bcrypt bcryptjs

API

Types

NativeBcrypt

The subset of the native bcrypt module this provider delegates to.

Declared structurally rather than taking the module's own types so that the two implementations are interchangeable here by construction.

type NativeBcrypt = {
  /** Hashes a plain-text password at the given bcrypt cost. */
  hash(password: string, rounds: number): Promise<string>
  /** Checks a plain-text password against a stored bcrypt hash. */
  compare(password: string, passwordHash: string): Promise<boolean>
}

Functions

loadNativeBcrypt()

Resolves the native bcrypt module, or null when it cannot be loaded.

Resolved once per process and cached, so the module load happens at most once and every later call goes straight to the binding. A failure is reported on console.warn exactly once, for the same reason: hashing silently dropping from the threadpool back onto the event loop is a performance regression a consumer must be able to see.

function loadNativeBcrypt(): Promise<NativeBcrypt | null>

Returns: The native module to delegate to, or null to use bcryptjs.

Constants

provider

Password provider backed by the native bcrypt addon, falling back to bcryptjs when the addon cannot be loaded on this platform.

const provider: PasswordProvider

Core Interface

Implements @molecule/api-password interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-password'
import { provider } from '@molecule/api-password-bcrypt'

export function setupPasswordBcrypt(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-password ^1.0.1

Runtime Dependencies

• @molecule/api-password
• bcrypt
• bcryptjs

Both implementations produce and verify the same $2b$ hashes at the same cost factor, so stored hashes do not care which one wrote them and a process can switch between them freely.

Which one runs matters for Latency, not for security. bcryptjs is pure JavaScript, so a cost-12 hash holds the event loop for ~100 ms at a stretch and every other request waits behind it; the native addon runs the identical cost-12 computation on a libuv threadpool thread. Measured at cost 12 with the CPU pinned to one core: ~101 ms of event-loop stall per bcryptjs hash, and ~296 ms of accumulated delay across three concurrent signups, against ~13 ms and ~4 ms for the native addon. The cost factor is deliberately identical — lowering it would trade the protection for the speed.

bcrypt semantics a consumer must know (identical in both implementations):

• Only the first 72 BYTES of a password are read — passwords sharing the same first 72 bytes compare equal (multi-byte UTF-8 hits the cap sooner). Don't prepend long app-controlled prefixes before hashing.
• compare() returns false (never throws) for a malformed/non-bcrypt stored hash — an empty or corrupted passwordHash column is indistinguishable from a wrong password by design (no user enumeration). It DOES throw Illegal arguments when passed undefined/null — that means a wiring bug (e.g. an OAuth-only account with no password hash), not a wrong password; guard those rows before calling.
• The default cost reads SALT_ROUNDS, clamped to 10–16: cost is EXPONENTIAL and bcrypt accepts absurd values (32 = hours per hash, silently).