Password breach checking

theAuth integrates with the HaveIBeenPwned Pwned Passwords API to detect compromised passwords at sign-up and password change. It uses the k-anonymity model, only the first 5 characters of the SHA-1 hash are sent to the API. Your users’ actual passwords never leave your server. createHibpModule is standalone, it does not hook automatically into the username module or any other password flow. Call check() or enforce() yourself wherever you accept a new password.

Setup

lib/theauth.ts

import { createTheAuth } from '@glinr/theauth';
import { createHibpModule } from '@glinr/theauth/auth'; 

const hibp = createHibpModule({ threshold: 0 }); // reject any breach count above 0

const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  auth: { session: { secret: process.env.SESSION_SECRET! } },
  username: { password: { minLength: 8 } },
});

Call hibp.enforce() before delegating to the username module’s signUp:

Sign-up handler

async function handleSignUp(username: string, password: string) {
  await hibp.enforce(password); // throws HibpBreachedError if compromised
  return theauth.username?.signUp({ username, password });
}

check() and enforce()

The module exposes two methods with different failure modes. check() does not apply threshold, it always returns the raw breach count:

Manual usage

const hibp = createHibpModule();

// Returns the breach count as a number. 0 means clean (or the API was
// unreachable and onError is 'allow', the default).
const count = await hibp.check('user-entered-password');

if (count > 0) {
  console.warn(`Password seen ${count} times in breaches`);
}

// Throws HibpBreachedError if count exceeds the configured threshold
await hibp.enforce('user-entered-password');

check() is useful when you want to warn the user without blocking them. enforce() throws a typed HibpBreachedError (with a count property) so you can catch it and return a friendly message:

import { HibpBreachedError } from '@glinr/theauth/auth';

try {
  await hibp.enforce(password);
} catch (err) {
  if (err instanceof HibpBreachedError) {
    return { error: `This password has appeared in ${err.count} known breaches. Choose another.` };
  }
  throw err;
}

How k-anonymity works

SHA-1 hash the password               → "5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8"
Send only the first 5 chars           → GET /range/5BAA6
API returns ~500 hashes with that prefix
Check if the rest of the hash appears in the list
If yes, the password has been breached. The full hash is never sent.

The full password hash is never transmitted. The API response contains partial hashes from other users’ passwords, so the provider cannot determine which password you were checking.

Configuration

The Pwned Passwords API is free and does not require an API key. Point apiUrl at a self-hosted mirror if you run one:

lib/theauth.ts

const hibp = createHibpModule({
  threshold: 0, // reject any breach count greater than this
  apiUrl: 'https://api.pwnedpasswords.com', // default, override for a self-hosted mirror
  timeoutMs: 5000, // ms before the check is abandoned
  onError: 'allow', // 'allow' | 'block', behavior when the API is unreachable
});

If the HIBP API is unreachable and onError is 'allow' (the default), check() returns 0 and enforce() passes through, a slow network does not block your users from registering. Set onError: 'block' to fail closed instead, check() throws HibpApiError and enforce() propagates it.

Configuration reference

number

default:0

Reject passwords seen in more than this many breaches. Default 0 rejects any breach at all.

string

default:"https://api.pwnedpasswords.com"

Base URL for the Pwned Passwords range API.

number

default:5000

Milliseconds to wait for the HIBP API before giving up.

'allow' | 'block'

default:"'allow'"

Behavior when the HIBP API is unreachable or returns an error.

Two-factor auth

Add TOTP as a second layer of protection beyond password quality.

Trusted devices

Skip 2FA on devices you have marked as trusted.

Username and password

theAuth’s built-in password module that HIBP enforcement typically guards.

Compliance

Audit trail, GDPR tooling, and the other compliance-related features.

Compliance and security

Lifecycle

Identity primitives

Standards

Password breach checking

Setup

check() and enforce()

How k-anonymity works

Configuration

Configuration reference

Two-factor auth

Trusted devices

Username and password

Compliance

​Setup

​check() and enforce()

​How k-anonymity works

​Configuration

​Configuration reference

​Related

Two-factor auth

Trusted devices

Username and password

Compliance

Setup

check() and enforce()

How k-anonymity works

Configuration

Configuration reference

Related