bcrypt

Postconditions — what we check

• hash · invalid-args

  error
  Whendata or salt is null/undefined, or data is not a string/Buffer, or salt is not a string or number
  ThrowsError with message 'data and salt arguments required' or 'data must be a string or Buffer and salt must either be a salt string or a number of rounds'
  Required handlingCaller MUST validate inputs before calling bcrypt.hash(). Wrap calls in try-catch (synchronous throw path) or use .catch() / try-await-catch for the Promise path. Unhandled rejections will crash the process in Node.js.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• hash · hashing-error

  error
  WhenAn error occurs during the native bcrypt hashing operation (e.g., native module failure)
  ThrowsError — rejected Promise or callback first argument
  Required handlingCaller MUST wrap bcrypt.hash() in try-catch when using async/await, or provide an error-checking callback. Unhandled rejections will crash the process.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• hash · hash-invalid-callback

  error
  WhenA third argument is passed as the callback but is not a function (e.g., a string, object, or number). Returns a rejected Promise regardless of whether data and salt are valid.
  ThrowsRejected Promise with Error('cb must be a function or null to return a Promise'). This is a programmer error — the rejection fires synchronously before any hashing occurs.
  Required handlingCaller MUST either omit the callback (use async/await) or ensure cb is a function. Passing a non-function third argument is a programming error that produces a rejected promise. Wrap the call in try-catch or handle with .catch().
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• hash · success

  info
  WhenHashing completes successfully
  ReturnsPromise<string> resolving to the bcrypt hash string (60 characters)
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• compare · invalid-args

  error
  Whendata or hash is null/undefined, or data is not a string/Buffer, or hash is not a string
  ThrowsError with message 'data and hash arguments required' or 'data must be a string or Buffer and hash must be a string'
  Required handlingCaller MUST validate that both arguments are present and of the correct type. Wrap calls in try-catch or use .catch() on the returned Promise.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• compare · comparison-error

  error
  WhenAn error occurs during the native bcrypt comparison (e.g., malformed hash string)
  ThrowsError — rejected Promise or callback first argument
  Required handlingCaller MUST wrap bcrypt.compare() in try-catch when using async/await. A malformed hash string causes an error, not a false return value.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• compare · compare-invalid-callback

  error
  WhenA third argument is passed as the callback but is not a function (e.g., a string, object, or number). Returns a rejected Promise regardless of whether data and hash are valid.
  ThrowsRejected Promise with Error('cb must be a function or null to return a Promise'). This is a programmer error.
  Required handlingCaller MUST either omit the callback (use async/await) or ensure cb is a function. Wrap the call in try-catch or handle with .catch().
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• compare · mismatch

  info
  WhenThe plain-text data does not match the hash
  ReturnsPromise<false> — resolves to boolean false
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• compare · match

  info
  WhenThe plain-text data matches the hash
  ReturnsPromise<true> — resolves to boolean true
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• genSalt · invalid-rounds

  error
  Whenrounds parameter is provided but is not a number
  ThrowsError with message 'rounds must be a number'
  Required handlingCaller MUST ensure rounds is a number when provided. Wrap in try-catch or use .catch() on the returned Promise.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• genSalt · invalid-minor

  error
  Whenminor version parameter is provided but is not 'a' or 'b'
  ThrowsError with message 'minor must be either a or b'
  Required handlingOnly pass 'a' or 'b' as the minor version. The default ('b') is recommended for new code.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• genSalt · gen-salt-entropy-error

  error
  WhenNode.js crypto.randomBytes() fails to generate random bytes — typically due to system entropy exhaustion in containerized or virtualized environments (rare but real in CI/CD and Docker).
  ThrowsRejected Promise (or callback error) with the Error from crypto.randomBytes(). Error message varies by OS — commonly 'Error generating random bytes' or similar.
  Required handlingCaller MUST wrap bcrypt.genSalt() in try-catch or use .catch(). While rare in production, entropy exhaustion is a known failure mode in ephemeral containers and edge deployments. In registration flows, a failure here means the user cannot create an account — treat as a retriable error.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][3]
• genSalt · success

  info
  WhenSalt generation succeeds
  ReturnsPromise<string> resolving to the generated salt string
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• hashSync · hash-sync-invalid-args

  error
  Whendata or salt is null/undefined, or data is not a string/Buffer, or salt is not a string or number
  ThrowsError('data and salt arguments required') if either arg is null/undefined; Error('data must be a string or Buffer and salt must either be a salt string or a number of rounds') for type mismatches. Throws synchronously — not a rejected Promise.
  Required handlingCaller MUST validate inputs before calling bcrypt.hashSync(). Wrap in try-catch since this is a synchronous throw (not a rejected Promise). A missing try-catch will propagate the exception up the call stack — in Express, this crashes the request handler unless a global error boundary catches it.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• hashSync · hash-sync-event-loop-block

  warning
  WhenCalled in a web server request handler with saltRounds >= 10
  ThrowsDoes not throw — but blocks the Node.js event loop for 100ms–1s+ per call
  Required handlingDO NOT call bcrypt.hashSync() inside Express/Fastify/Next.js route handlers or any code on the request/response hot path. Use the async bcrypt.hash() instead. Blocking the event loop during password hashing causes ALL concurrent HTTP requests to queue, leading to cascading latency under load. This is a behavioral correctness issue, not just a performance concern.
  costhighin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[2]
• compareSync · compare-sync-invalid-args

  error
  Whendata or hash is null/undefined, or data is not a string/Buffer, or hash is not a string
  ThrowsError('data and hash arguments required') if either arg is null/undefined; Error('data must be a string or Buffer and hash must be a string') for type mismatches. Throws synchronously.
  Required handlingCaller MUST validate inputs before calling bcrypt.compareSync(). Wrap in try-catch. A malformed hash string (e.g., not a valid bcrypt hash) will cause this function to throw — it does NOT return false for an invalid hash format.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• compareSync · compare-sync-event-loop-block

  warning
  WhenCalled in a web server request handler
  ThrowsDoes not throw — but blocks the Node.js event loop for 100ms–1s+ per call
  Required handlingDO NOT call bcrypt.compareSync() inside Express/Fastify/Next.js route handlers. Use bcrypt.compare() (async) instead. During login endpoints under load, using compareSync serializes all auth checks — each login queues behind the previous one, causing login latency to multiply linearly with concurrent users.
  costhighin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[2]
• genSaltSync · gen-salt-sync-invalid-rounds

  error
  Whenrounds parameter is provided but is not a number (e.g., a string)
  ThrowsError('rounds must be a number'). Throws synchronously.
  Required handlingCaller MUST ensure rounds is a number when provided. Wrap in try-catch. Note: falsy values (0, null, undefined) are silently coerced to the default 10 rounds — only non-number, truthy values throw.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• genSaltSync · gen-salt-sync-invalid-minor

  error
  Whenminor parameter is provided but is not 'a' or 'b'
  ThrowsError('minor must be either "a" or "b"'). Throws synchronously.
  Required handlingOnly pass 'a' or 'b' as the minor version. Omit the parameter to use the default 'b'. Passing any other string causes an immediate synchronous throw.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• genSaltSync · gen-salt-sync-success

  info
  WhenSalt generation succeeds
  Returnsstring — a bcrypt salt in the format '$2b$<rounds>$<22-char-base64-salt>' (29 characters total). This salt string is passed directly to bcrypt.hashSync().
  Required handlingNo action required — use the returned salt string as input to hashSync() or hash().
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• getRounds · get-rounds-missing-hash

  error
  Whenhash argument is null or undefined
  ThrowsError('hash argument required'). Throws synchronously.
  Required handlingCaller MUST check that the hash argument exists before calling getRounds(). Wrap in try-catch. Common failure pattern: calling getRounds() during hash migration/audit over DB rows where some rows have null password fields.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• getRounds · get-rounds-invalid-type

  error
  Whenhash argument is not a string (e.g., a Buffer or number)
  ThrowsError('hash must be a string'). Throws synchronously.
  Required handlingCaller MUST ensure the hash is a string. Wrap in try-catch. Common failure pattern: passing a Buffer or TypeScript typed value that hasn't been .toString()'d before passing to getRounds().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• getRounds · get-rounds-success

  info
  Whenhash argument is a valid bcrypt hash string
  Returnsnumber — the integer cost factor (rounds) embedded in the hash string. Extracted from the hash format: '$2b$<cost>$...'. For most production hashes, returns 10-12.
  Required handlingNo action required. Compare the returned number against your current minimum rounds policy (e.g., if returned value < 12, trigger a rehash on next login to upgrade security).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/kelektiv/node.bcrypt.jshttps://github.com/kelektiv/node.bcrypt.js/blob/master/bcrypt.js
2. [2]github.com/kelektiv/node.bcrypt.jshttps://github.com/kelektiv/node.bcrypt.js/blob/master/README.md
3. [3]nodejs.org/api/crypto.htmlhttps://nodejs.org/api/crypto.html#cryptorandombytessize-callback