sgerrand / ex_humaans / 25317065796

99%

push

github

feat(webhooks): add HMAC-SHA256 signature verification helper (#92)

* feat(webhooks): add HMAC-SHA256 signature verification helper

Webhook consumers all need the same primitive: verify that an incoming
delivery was signed with the endpoint's secret before trusting any of
its content. Bundling this avoids every user having to re-derive
constant-time comparison and signature-stripping logic.

Humaans.Webhooks.verify_signature/3 takes the raw payload, the
signature header value (with or without a sha256= prefix), and the
endpoint secret. It returns :ok | {:error, :invalid_signature |
:missing_signature | :missing_secret}, comparing in constant time via
:crypto.hash_equals/2.

Also adds Humaans.webhooks/0 for symmetry with the other top-level
accessors.

* fix(webhooks): replace :crypto.hash_equals/2 with portable constant-time compare

:crypto.hash_equals/2 is unavailable in OTP 24 and before, breaking mix compile
--warnings-as-errors. Swap in a hand-rolled XOR-accumulator comparison over
equal-length binaries using Bitwise.bor/2 and bxor/2.

* fix(webhooks): match sha256= prefix case-insensitively

Headers like `SHA256=<digest>` left the prefix intact through
`strip_prefix/1`, so the byte-length check in `secure_compare/2`
rejected otherwise valid signatures. Lowercase the signature before
the prefix strip so the pattern match sees a normalised form, and
add regression tests for upper- and mixed-case prefixes.

* fix(webhooks): allow nil secret in verify_signature/3 typespec

The function clauses already accept `nil` and return
`{:error, :missing_secret}`, but the spec advertised `secret` as
`String.t()` only. Widen it to `String.t() | nil` so generated docs
and Dialyzer agree with the supported call shapes.

* docs(webhooks): cover missing_signature and missing_secret in README example

The README's verify_signature/3 example only matched :ok and
{:error, :invalid_signature}, so copy-paste users would hit
CaseClauseError when the header was absent o... (continued)

14 of 14 new or added lines in 2 files covered. (100.0%)

173 of 173 relevant lines covered (100.0%)

21.36 hits per line