hibp

README

Pwned Passwords API in Go

This library implements the HaveIBeenPwned.org's Pwned Passwords v3 API in Go.

Features:

• No external dependencies to reduce the likelihood of supply-chain attacks.
• Cache support, as API responses can sometimes be huge.
• Concurrent request optimization. Sharing a single request for password hash prefix.
• Efficient memory use, no large allocations.

Example:

import (
	"github.com/supabase/hibp"
)

func main() {
	pwnedClient := hibp.PwnedClient{
		// please always set a User-Agent identifying your project
		UserAgent: "my-super-cool-project",
	}

	isPwned, err := pwnedClient.Check(context.Background(), "password1")
	if err != nil {
		if ur, ok := err.(*hibp.ErrorUnknownResponse); ok {
			// any non-200 response available in ur.Response
		}

		panic(err)
	}

	fmt.Print("Your password is ")
	if isPwned {
		fmt.Print("pwned!\n")
	} else {
		fmt.Print("safe for now!\n")
	}
}

License

Maintained by the Auth team at Supabase. Licensed under the MIT License.

Documentation

Index

• Variables
• func PwnedPasswordsURL(prefix string) string
• type ErrorUnexpectedResponse
  • func (e *ErrorUnexpectedResponse) Error() string
• type PwnedCache
• type PwnedClient
  • func (c *PwnedClient) Check(ctx context.Context, password string) (bool, error)

Variables

var DefaultUserAgent = "https://github.com/supabase/hibp"

DefaultUserAgent is the User-Agent header sent to the Pwned Passwords API if it has not been explicitly set.

Functions

func PwnedPasswordsURL

func PwnedPasswordsURL(prefix string) string

PwnedPasswordsURL returns the URL for the prefix.

Types

type ErrorUnexpectedResponse

type ErrorUnexpectedResponse struct {
	// Response that was not expected.
	Response *http.Response
}

ErrorUnexpectedResponse is an error returned if the response from the HaveIBeenPwned.org API was not expected.

func (*ErrorUnexpectedResponse) Error

func (e *ErrorUnexpectedResponse) Error() string

type PwnedCache

type PwnedCache interface {
	// Add records the provided prefix and suffixes in the cache.
	Add(ctx context.Context, prefix []byte, suffixes [][]byte) error

	// Contains checks if the provided prefix and suffix are in the cache.
	Contains(ctx context.Context, prefix, suffix []byte) (bool, error)
}

PwnedCache is the interface with which you can cache responses from the Pwned Passwords API.

type PwnedClient

type PwnedClient struct {
	// UserAgent is sent as the User-Agent header to HTTP requests.
	UserAgent string

	// Cache, when set, will be used to cache and lookup results.
	Cache PwnedCache

	// HTTP allows you to override the HTTP client used. If not set http.DefaultClient is used.
	HTTP interface {
		Do(*http.Request) (*http.Response, error)
	}
	// contains filtered or unexported fields
}

PwnedClient can be used to send requests to the Pwned Passwords API. Zero value is safe to use, though it is highly recommended you configure the UserAgent property per the HaveIBeenPwned.org API rules.

func (*PwnedClient) Check

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

Check uses the Pwned Passwords API to check if the provided password is found in a breach. If two concurrent calls are made with passwords that share the same SHA1 prefix, only a single request will be sent. You can cancel the context to cancel long-running requests.

Unexpected HTTPS responses will return ErrorUnexpectedResponse.