Have I Been Pwned

This plugin checks candidate passwords against the Have I Been Pwned k-anonymity range API before selected password-bearing routes run. Kernia sends only the SHA-1 prefix, not the full password or hash.

Installation

uv add kernia httpx

Import path

from kernia.plugins.haveibeenpwned import have_i_been_pwned

Server configuration

auth.py

import os

from kernia import KerniaOptions
from kernia.auth import init
from kernia.plugins.haveibeenpwned import have_i_been_pwned

from .db import adapter

auth = init(KerniaOptions(
    database=adapter,
    secret=os.environ["KERNIA_SECRET"],
    base_url=os.environ["KERNIA_BASE_URL"],
    base_path="/api/auth",
    plugins=(
        have_i_been_pwned(count_threshold=0),
    ),
))

API routes

Schema impact

No schema changes. Optional cache entries can be stored in secondary_storage.

Behavior and options

Default gated paths are /sign-up/email and /reset-password.
count_threshold allows policy tuning.
Range API responses are cached for six hours when secondary storage is configured.