hibp

README

hibp-go

Go client for checking breached passwords using HaveIBeenPwned's k-Anonymity API.

Features

• Standard library only (crypto/sha1, net/http, bufio).
• Implements k-Anonymity: only the first 5 hexadecimal characters of the SHA-1 hash are sent over the network. The password never leaves your application.
• Sends Add-Padding: true to prevent network packet size inspection.
• Returns breach occurrence count alongside a boolean status.
• Streams responses line-by-line with bufio.Scanner to avoid buffering large payloads in memory.

Installation

go get github.com/fumbledlol/hibp-go

Usage

Check password

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/fumbledlol/hibp-go"
)

func main() {
	pwned, count, err := hibp.Check(context.Background(), "password123")
	if err != nil {
		log.Fatal(err)
	}

	if pwned {
		fmt.Printf("Password appeared in %d breaches.\n", count)
	} else {
		fmt.Println("Password not found in breaches.")
	}
}

Validate during signup

func ValidatePassword(ctx context.Context, password string) error {
    pwned, count, err := hibp.Check(ctx, password)
    if err != nil {
        return nil
    }

    if pwned && count > 10 {
        return fmt.Errorf("password appears in %d known breaches, choose another", count)
    }

    return nil
}

Reusable client

client := hibp.New(
    hibp.WithUserAgent("auth-service/1.0"),
    hibp.WithHTTPClient(httpClient),
)

pwned, count, err := client.Check(ctx, "user-secret")

License

MIT

Documentation

Index

• Constants
• Variables
• func Check(ctx context.Context, password string) (bool, int64, error)
• func IsPwned(ctx context.Context, password string) (bool, error)
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) Check(ctx context.Context, password string) (bool, int64, error)
  • func (c *Client) IsPwned(ctx context.Context, password string) (bool, error)
• type Option
  • func WithEndpoint(endpoint string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithUserAgent(userAgent string) Option

Constants

const (
	// DefaultEndpoint is the official HaveIBeenPwned range API base URL.
	DefaultEndpoint = "https://api.pwnedpasswords.com/range/"

	// DefaultUserAgent is the default HTTP User-Agent header.
	DefaultUserAgent = "hibp-go/1.0"

	// DefaultTimeout is the default HTTP request timeout.
	DefaultTimeout = 5 * time.Second
)

Variables

var (
	// ErrEmptyPassword is returned when an empty password string is provided.
	ErrEmptyPassword = errors.New("hibp: password cannot be empty")

	// ErrUnexpectedStatus is returned when HIBP returns a non-200 HTTP status.
	ErrUnexpectedStatus = errors.New("hibp: unexpected HTTP response status")
)

var DefaultClient = New()

DefaultClient is the package-level default client.

Functions

func Check

func Check(ctx context.Context, password string) (bool, int64, error)

Check checks a password using the default client.

func IsPwned

func IsPwned(ctx context.Context, password string) (bool, error)

IsPwned checks a password using the default client.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client checks passwords against HaveIBeenPwned.

func New

func New(opts ...Option) *Client

New creates a new HIBP client.

func (*Client) Check

func (c *Client) Check(ctx context.Context, password string) (bool, int64, error)

Check evaluates whether a password exists in known data breaches, returning true and the breach count if found.

func (*Client) IsPwned

func (c *Client) IsPwned(ctx context.Context, password string) (bool, error)

IsPwned returns whether a password has been breached.

type Option

type Option func(*Client)

Option configures the HIBP Client.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint sets a custom range API endpoint.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom http.Client.

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent sets a custom User-Agent header.