v1.1.0: New APIs, better testing and more type safety

Welcome to go-hibp v1.1.0!

Important

This release breaks current implementations. Please read the release notes and the code documentation before you update to this version.

Note

This is supposed to be a v2 release, to comply with semver semantics. But given that some Go tools are not able to handle v2.x.x as version number and requiring us to create a separate branch or subdirectory for v2, I've decided to go with v1.1.x for this release instead. While this break semver, I think this module is not used widely enough to justify the v2 branching.

New HIBP APIs

• Latest breach API: PR #35 adds support for the latest breach API. Thanks to @freman for the PR!
• Subscription Status API: PR #39 adds support for the Subscription Status API. Thanks to @tekkamanendless for the PR!

Client changes

• Custom HTTP client: PR #36 adds support for a custom HTTP client provided by the user. This can be useful if you want to customize the HTTP client. Thanks to @AndreZiviani for the PR!
• Custom logger support: PR #37 removes the default usage of log.Printf and replaces it with a custom logger that has to satisfy the io.Writer interface. This is to avoid frequent and cluttered the logs in production environments due to rate limiting. Thanks to @tekkamanendless for the PR!
• Talking about rate limiting... PR #41 adds one second to the rate limit delay to avoid rounding issue. PR also provided by @tekkamanendless

Better testing

PR #44 overhauls the complete testing suite. Instead of running lots of test against the online HIBP API (which usually results in lots of rate limiting) we now provide a proper mock server emulating valid and invalid responses. Most tests are run against the local mock server and only one test per API is executed against the online API for integration testing. This not only makes the tests run faster, since we do not have to wait for long rate limit times, but we can also simulate scenarios that we weren't able to test before, resulting in better test coverage. We are now at ~97% of coverage compared to the ~80% beforehand.

Removal of pointer type returns (BREAKING CHANGE)

PR #44 (and #45 in fact) also changes the returns types of all APIs that would return a pointer type to return actual types instead. This reduces the chance of nil pointer dereferences. To make sure the user can still check if the API returned something or not, every type now provides a Present() method indicating if the API returned the value or not. This change will break current implementation but I think it's a good step to avoid unnesessary pointer returns.

Replacement of nil types in JSON returns (BREAKING CHANGE)

In the same run, nil types in JSON returns were also changed. In case an API returns null-able types in the response, so far we've handled this with pointer types (like *int). This is also a possible cause for nil-pointer dereferences. Therefore these types have been replaced with my niljson which provides type safe access to null-able JSON return types. This will also break current implementations and will introduce a new dependency to your go.mod.

Unified API date type (BREAKING CHANGE)

Last part of the #44 PR was to unify the APIDate type. The custom APIDate type has been made suitible for the different date types retured by the HIBP API (ISO8601, YYYY-MM-DD). It has also been simplified by putting it into a struct. It can now be handled like a normal time.Time type instead of having to make use of the .Time() method. The RenewalTime type has been removed accordingly.

Fix of HTTP 404 returns (POSSIBLY BREAKING CHANGE)

While implementing the new testing suite in #44, I noticed that some APIs return a HTTP 404 i. e. if an account is not listed in a paste (or similar). This 404 would, until now, cause the API request to return an error. This is misleading since the "NotFound" basically indicates that the account was not breached/leaked. This behaviour has been fixed for the corresponding APIs and returns nil instead of an error if a HTTP 404 is received. This will likely break implementations but is the actual correct way to handle the responses.

API key checking for APIs that require such. (POSSIBLY BREAKING CHANGE)

All APIs that require an API key to query the HIBP API are now checking if the API key has been set on the client before sending the HTTP request. If the API requires key and no key has been set, the method will fail with an error and not query the online API.

What's Changed

• Add latestbreach api by @freman in #35
• feat: Add support for user provided http client by @AndreZiviani in #36
• Use a custom logger by @tekkamanendless in #37
• Make the linter happy by @tekkamanendless in #40
• Add the subscription/status API by @tekkamanendless in #39
• Sleep 1 second longer than required by @tekkamanendless in #41
• BREAKING CHANGE: Refactor date handling with unified APIDate type by @wneessen in #43
• BREAKING CHANGE: Test overhaul and get rid of pointer returns by @wneessen in #44
• BREAKING CHANGE: Refactor Match to replace pointers with value semantics. by @wneessen in #45
• Add references to godoc by @wneessen in #46
• BREAKING CHANGE: Add error handling for missing API key by @wneessen in #47
• Update package version to 2.0.1 by @wneessen in #48

Github Workflow changes/maintenance changes

• Fix tests and Github workflow by @wneessen in #42

New Contributors

• @AndreZiviani made their first contribution in #36
• @tekkamanendless made their first contribution in #37

Big thanks again to all contributors for their PRs, reviews, issues and comments. Your support is highly appreciated!

Full Changelog: v1.0.7...v1.1.0

v1.0.7: subscribeddomains/breacheddomain API and bug fixes

This release adds access to the breacheddomain/breacheddomain API endpoints and fixes a potential out of index access.

What's Changed

• Improved test coverage by @wneessen in #30
• Fix possible out of index access by @wneessen in #32
• Add missing API calls for breacheddomain and breacheddomain by @freman in #33

New Contributors

• @freman made their first contribution in #33

Thanks

Thanks to @KenjiTakahashi for reporting the out of index access error via #34

Full Changelog: v1.0.6...v1.0.7

v1.0.6: NTLM hash support

This release introduces support for NTLM hashes in the PwnedPassAPI as announced by Troy Hunt.

To be able to generate NTLM hashes, we needed the ability to calculate MD4 hashes, as NTLM basically is calculated like this: MD4(UTF-16LE(pw)). For this we ported the official golang.org/x/crypto/md4 package, so we can still claim that the module "only depends on Go stdlib".

A new Client option has been introduced: WithPwnedNTLMHash. If the client is initalized with this option, all generic methods (ListHashesPassword and CheckPassword) will operate on NTLM hashes.

Additionally, there are now equivalent methods for checking passwords and listing hashes for NTLM: CheckNTLM and ListHashesNTLM

What's Changed

• #27: Implement NTLM hash support for PwnedPassAPI by @wneessen in #28

Full Changelog: v1.0.5...v1.0.6

v1.0.5: Better error handling

This releases overhauls the error handling of the different APIs. Aside of fixing #22, in this release we reworked the general error handling. Errors are no defined via errors.New() and therefore can be checked via errors.Is() accordingly. General code cleanup was also performed. Check the PRs for all details.

What's Changed

• Fix missing HTTP response return in PastedAccount method. by @wneessen in #23
• Fix/24 verify and overhaul the error handling of the different apis by @wneessen in #25

Thanks to @chandru89new for finding the error and raising the error issue.

Full Changelog: v1.0.4...v1.0.5

[BREAKING CHANGE] v1.0.4: Code cleanup with golangci-lint

This release introduces breaking changes

I am currently implementing code standards across all my code bases by introducing a golangci-lint workflow. This release applies this workflow to go-hibp. Unfortunately this introduces a breaking change be renaming all methods and references that previously had Api in it to API and Http to HTTP.

Please update your code accordingly.

What's Changed

• Fixes and test coverage by @wneessen in #18
• Implement a golangci-lint workflow and the accordingly GH action by @wneessen in #19
• Better test coverage by @wneessen in #20

Full Changelog: v1.0.3...v1.0.4

v1.0.3: Hashlists support

This release adds support for retrieving hash lists in the PwnedPass API (See #14). We've added 3 new ListHashes*() methods to get access to all returned hashes:

• ListHashesPrefix(): which accepts a 5-character hash as expected by the API endpoint (this is basically the previously private apiCall() method)
• ListHashesSHA1(): which retrieves the list based on a given SHA1 checksum
• ListHashesPassword(): which retrieves the list based on a give password string

We've also added length checks for *SHA1() and *Prefix() methods, so that invalid data provided to them will return an error.

Thanks binaek for feature request and the testing.

Changes worth mentioning

• #14 implements the changes around the ListHashes*() methods
• 8fe5b20 removes paddings results from the match lists

v1.0.2: Maintenance release

This is a maintenance release. Since the last release we've introduced code scanning via SonarQube and coverage testing using Codecov. This release addresses some findings and the better testing

Changes worth mentioning

• 842cc12 Fixed a code smell in WithUserAgent() identified by SonarQube
• af15c66 Added RateLimitSleep() to all tests so we can test via Github actions w/o failing
• 77e5a43 Moved all code examples from dedicated files to the Example_* functions in the test files

First stable release

This release is the first stable release that implements all provided APIs in the HIBP system

BreachedAccount, better HTTP handling and rate limiting

Merge pull request #4 from wneessen/breaches

BreachedAccount, better HTTP handling and rate limiting

New methods for the breaches API

Added BreachByName()