scrypt-js

scrypt-js is a JavaScript implementation of the scrypt password-based key derivation function (PBKDF) designed for brute-force resistance. It provides both synchronous and asynchronous computation methods with advanced features including non-blocking execution, cancellable operations, and progress callbacks for real-time feedback during key derivation.

Package Information

• Package Name: scrypt-js
• Package Type: npm
• Language: JavaScript (with TypeScript definitions)
• Installation: npm install scrypt-js

Core Imports

const scrypt = require("scrypt-js");

TypeScript/ES6:

import * as scrypt from "scrypt-js";
// or
import { scrypt as scryptAsync, syncScrypt } from "scrypt-js";

Basic Usage

const scrypt = require("scrypt-js");

// Convert password and salt to byte arrays
const password = Buffer.from("myPassword", "utf8");
const salt = Buffer.from("mySalt", "utf8");

// Set scrypt parameters
const N = 1024;  // CPU/memory cost
const r = 8;     // Block size  
const p = 1;     // Parallelization
const dkLen = 32; // Desired key length

// Asynchronous with progress callback
const progressCallback = (progress) => {
  console.log(`Progress: ${Math.round(progress * 100)}%`);
  // Return true to cancel operation
  return false;
};

scrypt.scrypt(password, salt, N, r, p, dkLen, progressCallback)
  .then(key => {
    console.log("Derived key:", Buffer.from(key).toString("hex"));
  })
  .catch(error => {
    console.error("Error:", error);
  });

// Synchronous (blocking)
const key = scrypt.syncScrypt(password, salt, N, r, p, dkLen);
console.log("Derived key:", Buffer.from(key).toString("hex"));

Capabilities

Asynchronous Key Derivation

Computes the scrypt PBKDF asynchronously using a Promise, allowing for non-blocking execution and progress monitoring.

function scrypt(
  password: ArrayLike<number>,
  salt: ArrayLike<number>, 
  N: number,
  r: number,
  p: number,
  dkLen: number,
  callback?: ProgressCallback
): Promise<Uint8Array>;

Parameters:

• password: Password as byte array (ArrayLike<number>)
• salt: Salt as byte array (ArrayLike<number>)
• N: CPU/memory cost parameter (must be power of 2)
• r: Block size parameter
• p: Parallelization parameter
• dkLen: Desired key length in bytes
• callback: Optional callback for progress updates and cancellation

Returns: Promise that resolves to Uint8Array containing the derived key

Features:

• Non-blocking execution that yields control to event loop
• Progress callback receives values from 0 to 1
• Cancellable by returning true from progress callback (Promise rejects when cancelled)
• Always calls progress callback with 0 at start and 1 at completion

Synchronous Key Derivation

Computes the scrypt PBKDF synchronously, blocking execution until completion.

function syncScrypt(
  password: ArrayLike<number>,
  salt: ArrayLike<number>,
  N: number, 
  r: number,
  p: number,
  dkLen: number
): Uint8Array;

Parameters:

• password: Password as byte array (ArrayLike<number>)
• salt: Salt as byte array (ArrayLike<number>)
• N: CPU/memory cost parameter (must be power of 2)
• r: Block size parameter
• p: Parallelization parameter
• dkLen: Desired key length in bytes

Returns: Uint8Array containing the derived key

Note: This function blocks the JavaScript event loop during computation and is not recommended for UI applications.

Types

type ProgressCallback = (progress: number) => boolean | void;

ProgressCallback function:

• progress: Number between 0 and 1 (inclusive) indicating completion percentage
• Returns: true to cancel the operation, false or undefined to continue

Parameter Guidelines

Security Parameters

The scrypt algorithm uses three tuning parameters that affect security and performance:

• N (CPU/Memory Cost): Must be a power of 2. Higher values increase memory usage and computation time. Common values: 1024, 2048, 4096, 8192, 16384.
• r (Block Size): Affects memory latency and bandwidth dependency. Typical value: 8.
• p (Parallelization): Affects multi-processing dependency. Typical values: 1-4.

Recommended Parameters

• Interactive logins: N=1024, r=8, p=1 (fast but less secure)
• File encryption: N=16384, r=8, p=1 (balanced security/performance)
• High security: N=32768 or higher, r=8, p=1 (slow but very secure)

Input Encoding

Important: Always normalize Unicode passwords using String.prototype.normalize('NFKC') before converting to bytes to ensure consistent results across platforms.

// Recommended password encoding
const password = Buffer.from("myPassword".normalize('NFKC'), "utf8");
const salt = Buffer.from("mySalt".normalize('NFKC'), "utf8");

Error Handling

// Async error handling
scrypt.scrypt(password, salt, N, r, p, dkLen)
  .then(key => {
    // Success
  })
  .catch(error => {
    // Handle errors (invalid parameters, out of memory, etc.)
  });

// Sync error handling  
try {
  const key = scrypt.syncScrypt(password, salt, N, r, p, dkLen);
} catch (error) {
  // Handle errors
}

Platform Compatibility

• Node.js: Full support via CommonJS require
• Browsers: Full support via script tag or module bundlers (IE9+)
• TypeScript: Complete type definitions included
• Module Systems: Supports CommonJS, AMD/RequireJS, and browser globals
• Unicode normalization: Requires String.prototype.normalize() support or polyfill (unorm package)

Performance Considerations

• Use asynchronous version (scrypt) for UI applications to avoid blocking
• Use synchronous version (syncScrypt) only for server-side or CLI applications
• Consider using Web Workers in browsers for CPU-intensive operations
• Memory usage scales with N parameter - monitor for large N values
• Progress callback adds slight overhead but enables cancellation and UX feedback

References

• scrypt specification (RFC 7914)
• Unicode normalization best practices