hibp

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 14, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package hibp is the library behind the hibp command line: the HTTP client, request shaping, and the typed data models for the HaveIBeenPwned Pwned Passwords API.

The Client uses k-anonymity: only the first 5 characters of a SHA1 hash are sent to the API, so the full password is never transmitted.

Index

Constants

View Source
const BaseURL = "https://" + Host

BaseURL is the root every request is built from.

View Source
const DefaultUserAgent = "hibp-cli/0.1.0 (github.com/tamnd/hibp-cli)"

DefaultUserAgent identifies the client to the API.

View Source
const Host = "api.pwnedpasswords.com"

Host is the API host.

Variables

This section is empty.

Functions

This section is empty.

Types

type CheckResult

type CheckResult struct {
	Password   string `json:"password"`    // masked: first 2 + "..." + last 2, or all "*"
	SHA1Prefix string `json:"sha1_prefix"` // first 5 chars sent to API
	PwnedCount int    `json:"pwned_count"` // 0 = not found
	Pwned      bool   `json:"pwned"`
}

CheckResult is the output of a password check.

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	BaseURL   string
	// Rate is the minimum gap between requests. Zero means no pacing.
	Rate    time.Duration
	Retries int
	// contains filtered or unexported fields
}

Client talks to the HIBP Pwned Passwords API.

func NewClient

func NewClient() *Client

NewClient returns a Client with sensible defaults.

func NewClientFromConfig

func NewClientFromConfig(cfg Config) *Client

NewClientFromConfig returns a Client configured from a Config.

func (*Client) Check

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

Check hashes the password, queries /range/{prefix} using k-anonymity, and returns how many times the password has appeared in known breaches.

func (*Client) Range

func (c *Client) Range(ctx context.Context, prefix string) ([]HashEntry, error)

Range queries /range/{prefix} and returns all hash suffix entries. prefix must be exactly 5 uppercase hex characters.

type Config

type Config struct {
	BaseURL   string
	UserAgent string
	Rate      time.Duration
	Timeout   time.Duration
	Retries   int
}

Config holds the client configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults for the HIBP Pwned Passwords API.

type Domain

type Domain struct{}

Domain is the hibp driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input into the canonical (type, id).

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type HashEntry

type HashEntry struct {
	Suffix string `json:"suffix"`
	Count  int    `json:"count"`
}

HashEntry is one line in a /range response.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL