Project: a private password-breach check

Asking the range route

The practice API has a range route built the same way as the real services: GET /v1/breaches/range/<prefix> answers with plain text, one line per known hash with that prefix, written as SUFFIX:COUNT, where the count is how many times that password turned up in leaks. It also pads every answer with decoy lines whose count is 0, so even the size of the response gives little away. Real services do the same when a client asks for it with an Add-Padding: true header.

import hashlib
import requests

def range_lines(prefix):
    r = requests.get(f"https://api.gradient.test/v1/breaches/range/{prefix}", timeout=10)
    r.raise_for_status()
    return r.text.splitlines()

digest = hashlib.sha1("summer2026".encode()).hexdigest().upper()
lines = range_lines(digest[:5])
print(len(lines), "lines, for example", lines[:2])
for line in lines:
    found, count = line.split(":")
    if found == digest[5:]:
        print("found: this password appeared", int(count), "times")

r.text is the response as a string, and splitlines cuts it into lines, whichever line ending the server used. The matching is one string comparison per line: no database, no machine learning, just the right protocol.

def parse_range(text):
    return {}


answer = "0018A45C4D1DEF81644B54AB7F969B88D65:3\r\n00D4F6E8FA6EECAD2A3AA415EEC418D38EC:12\r\n\r\n011053fd0102e94d6ae2f8b83d76faf94f6:1"
print(parse_range(answer))

Keep the password out of everything

The protocol protects the password on the way to the service. The rest of your code has to protect it too, because passwords often leak through logs rather than through clever attacks:

• Never log it, not in a debug line, not in an error message. Log the outcome ("password rejected: found in breaches") and nothing that identifies the password, not even the full hash.
• Never put it in a URL. URLs end up in server logs, browser history and analytics. The prefix is the only part that goes into the request, and that's by design.
• Decide what a failure means. If the service is down, do you refuse every sign-up (fail closed) or allow it and check later (fail open)? Some sign-up forms fail open and check later; this project fails closed on purpose, asking the member to try again, because a breached password let through is hard to take back. Either way, the choice is written down, not an accident of an unhandled exception.

Making the network call a parameter, a function passed in, keeps those rules testable: a test can pass a fake that records exactly what was sent, with no network at all.

In a real sign-up flow

Run the check on your server, where the password arrives anyway, so the browser doesn't need to call a third party. Run it at sign-up and at every password change, and refuse a breached password with a message that says why and suggests a long passphrase instead of listing rules. Answers for a prefix rarely change, so caching them for a day cuts both latency and calls to the service. And keep the check next to, not instead of, the other defenses: slow salted hashing in storage, rate limits on login attempts, and a second factor (a code from an app or a security key, on top of the password) for accounts that matter.

import hashlib

sent = []

def fake_fetch(prefix):
    sent.append(prefix)
    known = {hashlib.sha1(p.encode()).hexdigest().upper(): n for p, n in [("password", 3210442), ("letmein", 640117)]}
    return "\n".join(f"{h[5:]}:{n}" for h, n in known.items() if h.startswith(prefix))

def times_breached(password, fetch):
    digest = hashlib.sha1(password.encode("utf-8")).hexdigest().upper()
    for line in fetch(digest[:5]).splitlines():
        suffix, count = line.split(":")
        if suffix.upper() == digest[5:]:
            return int(count)
    return 0

print(times_breached("password", fake_fetch), times_breached("pine-gap-ridge-lantern-94", fake_fetch))
print("everything sent:", sent)
print("any password in it?", any(p in s for s in sent for p in ["password", "pine-gap-ridge-lantern-94"]))