Difficulty: Intermediate
Type: Test
Background
packages/webhook-utils implements HMAC-SHA256 signature verification with replay protection via a tolerance window, as documented in its README (verifySignature/generateSignature, t=<timestamp>,v1=<hmac> format). The package advertises timing-attack resistance and replay protection as headline features, which means its edge-case behavior deserves thorough test coverage.
Problem
The documented behaviors — tolerance: 0 disabling timestamp checks, malformed signature headers, missing v1= or t= segments, non-numeric timestamps, and clock-skew scenarios (timestamp slightly in the future) — are the kind of edge cases most likely to be under-tested, since the README frames them as "not recommended for production" or troubleshooting notes rather than guaranteed, tested behavior.
Expected outcome
A comprehensive test file covering: valid signature acceptance, invalid HMAC rejection, expired timestamp rejection (outside tolerance), future-timestamp handling, tolerance: 0 behavior, malformed header formats (missing t=, missing v1=, extra segments, empty string), and confirmation that verification timing does not vary meaningfully between a correct-length-wrong-value signature and a valid one (timing-safety smoke test).
Suggested implementation
- Add test cases to the existing webhook-utils test suite (run via
pnpm test:webhook-utils).
- Use
generateSignature to construct valid signatures, then deliberately corrupt/truncate/rearrange them for negative test cases.
- For the timing-safety check, this can be a best-effort smoke test (e.g. asserting the library uses a constant-time comparison function internally) rather than a precise timing measurement, since timing tests are inherently flaky in CI-like environments.
Acceptance criteria
Likely affected files/directories
packages/webhook-utils/ (test directory/file alongside the source), packages/webhook-utils/README.md (only if a documented behavior turns out to be inaccurate and needs a correction note).
Difficulty: Intermediate
Type: Test
Background
packages/webhook-utilsimplements HMAC-SHA256 signature verification with replay protection via atolerancewindow, as documented in its README (verifySignature/generateSignature,t=<timestamp>,v1=<hmac>format). The package advertises timing-attack resistance and replay protection as headline features, which means its edge-case behavior deserves thorough test coverage.Problem
The documented behaviors —
tolerance: 0disabling timestamp checks, malformed signature headers, missingv1=ort=segments, non-numeric timestamps, and clock-skew scenarios (timestamp slightly in the future) — are the kind of edge cases most likely to be under-tested, since the README frames them as "not recommended for production" or troubleshooting notes rather than guaranteed, tested behavior.Expected outcome
A comprehensive test file covering: valid signature acceptance, invalid HMAC rejection, expired timestamp rejection (outside tolerance), future-timestamp handling,
tolerance: 0behavior, malformed header formats (missingt=, missingv1=, extra segments, empty string), and confirmation that verification timing does not vary meaningfully between a correct-length-wrong-value signature and a valid one (timing-safety smoke test).Suggested implementation
pnpm test:webhook-utils).generateSignatureto construct valid signatures, then deliberately corrupt/truncate/rearrange them for negative test cases.Acceptance criteria
tolerance: 0, and at least three malformed-header shapes.pnpm test:webhook-utils.verifySignature/generateSignatureare required — this is test-only unless a bug is discovered, in which case it should be filed as a separate issue.Likely affected files/directories
packages/webhook-utils/(test directory/file alongside the source),packages/webhook-utils/README.md(only if a documented behavior turns out to be inaccurate and needs a correction note).