Skip to main content

Hashing

Balda provides built-in secure password hashing using PBKDF2 with SHA-256.

Overview​

  • Algorithm: PBKDF2 with SHA-256
  • Default iterations: 600,000
  • Default salt length: 16 bytes
  • Default key length: 256 bits
  • Format: salt:hash (base64-encoded)

Basic Usage​

import { Server } from 'balda';

const server = new Server();

// Hash a password
const hashedPassword = await server.hash('user-password-123');

// Verify password
const isValid = await server.compareHash(hashedPassword, 'user-password-123');
console.log(isValid); // true

Authentication Example​

import { controller, post } from 'balda';

@controller('/auth')
export class AuthController {
  @post('/register')
  async register(req: Request, res: Response) {
    const { email, password } = req.body;

    const hashedPassword = await server.hash(password);
    await saveUser(email, hashedPassword);

    res.created({ message: 'User registered' });
  }

  @post('/login')
  async login(req: Request, res: Response) {
    const { email, password } = req.body;

    const user = await findUser(email);
    const isValid = await server.compareHash(user.passwordHash, password);

    if (!isValid) {
      return res.unauthorized({ error: 'Invalid credentials' });
    }

    res.json({ token: generateToken(user) });
  }
}

Configuration​

Customize hashing parameters to balance security and performance:

const server = new Server();

server.configureHash({
  iterations: 1_000_000,  // Default: 600,000 (min: 1)
  saltLength: 32,         // Default: 16 bytes (min: 8)
  keyLength: 512          // Default: 256 bits (min: 128)
});

Options​

OptionDefaultMinDescription
iterations600,0001PBKDF2 iterations. Higher = more secure, slower
saltLength16 bytes8Random salt length. Longer = more secure
keyLength256 bits128Derived key length

Configuration Examples​

// Development (faster hashing)
if (process.env.NODE_ENV === 'development') {
  server.configureHash({ iterations: 10_000 });
}

// High security
server.configureHash({
  iterations: 1_500_000,
  saltLength: 32,
  keyLength: 512
});
caution

Configure hash settings before hashing passwords. Changing configuration makes existing hashes incompatible.

Security Best Practices​

// ✅ Always hash passwords before storing
const passwordHash = await server.hash(password);

// ✅ Use strong password requirements
const minLength = 12;
const requireUppercase = true;
const requireNumbers = true;
const requireSpecialChars = true;

// ✅ Implement rate limiting on auth endpoints
import { rateLimiter } from 'balda';
server.use('/auth/login', rateLimiter({
  windowMs: 15 * 60 * 1000,
  max: 5
}));

// ✅ Use HTTPS in production
// ✅ Log security events (failed logins, etc.)

API Reference​

server.configureHash(options): void​

Configure hash settings.

server.configureHash({
  iterations?: number,   // Default: 600,000, min: 1
  saltLength?: number,   // Default: 16 bytes, min: 8
  keyLength?: number     // Default: 256 bits, min: 128
});

Throws: Error if values are below minimum thresholds.

server.hash(data: string): Promise<string>​

Hash a string using PBKDF2 with SHA-256.

const hash = await server.hash('my-password');
// Returns: "base64-salt:base64-hash"

Throws: Error if data is empty.

server.compareHash(hash: string, data: string): Promise<boolean>​

Verify a string against a hash.

const isValid = await server.compareHash(hash, 'my-password');
// Returns: true or false