Skip to content

INTER-2844: fix: compare webhook signatures in constant time - #315

Draft
JuroUhlar wants to merge 1 commit into
mainfrom
inter-2844-constant-time-webhook-signature
Draft

JuroUhlar wants to merge 1 commit into
mainfrom
inter-2844-constant-time-webhook-signature

Conversation

@JuroUhlar

@JuroUhlar JuroUhlar commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Context

INTER-2844 | go-sdk#123 (same fix in the Go SDK)

Why

isValidWebhookSignature compared HMAC signatures with ===, which can return as soon as a byte differs; it now compares them in constant time.

Things to note

  • The length check compares byte lengths, not string lengths. A 64-character signature with a multibyte character (like é) has a longer buffer, and timingSafeEqual would throw on it.
  • A v1 header entry without = gives an undefined signature, which now returns false early instead of throwing in Buffer.from.
  • No input changes result: the old and new code return the same boolean for valid, uppercase, whitespace, empty, truncated, and multibyte headers.

Verification

  • Unit tests pass (11 webhook tests). The constant-time test fails if the comparison is reverted to ===.
  • The v1 and multibyte tests fail if the length check uses string length or skips the undefined guard.

Change outline

 isValidHmacSignature(signature, data, secret)
+  signature undefined           -> false
+  received = Buffer(signature)
+  expected = Buffer(hmacHex(data, secret))
+  byte lengths differ           -> false
-  return signature === hmacHex(data, secret)
+  return timingSafeEqual(received, expected)

`isValidHmacSignature` now uses `crypto.timingSafeEqual`. It returns false
when the signature is missing or its byte length differs, so malformed
headers never throw.

Refs INTER-2844
@JuroUhlar
JuroUhlar requested a balanced review from Copilot November 20, 2026 18:16
@changeset-bot

changeset-bot Bot commented Nov 20, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 27a0008

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

🚀 Following releases will be created using changesets from this PR:

@fingerprint/node-sdk@7.11.1

Patch Changes

  • webhooks: isValidWebhookSignature compares signatures in constant time. (27a0008)

@github-actions

Copy link
Copy Markdown
Contributor

Coverage report

St.❔
Category Percentage Covered / Total
🟢 Statements
98.31% (+0.06% 🔼)
174/177
🟢 Branches
97.14% (+0.11% 🔼)
102/105
🟢 Functions 100% 37/37
🟢 Lines
98.28% (+0.06% 🔼)
171/174

Test suite run success

142 tests passing in 32 suites.

Report generated by 🧪jest coverage report action from 27a0008

Show full coverage report
St File % Stmts % Branch % Funcs % Lines Uncovered Line #s
🟢 All files 98.3 97.14 100 98.27
🟢  src 98.6 98.82 100 98.58
🔴   ...edApiTypes.ts 0 0 0 0
🔴   index.ts 0 0 0 0
🟢   sealedResults.ts 100 100 100 100
🟢   ...rApiClient.ts 96.15 97.22 100 96.15 364,368
🟢   types.ts 100 100 100 100
🟢   urlUtils.ts 100 100 100 100
🟢   webhook.ts 100 100 100 100
🟢  src/errors 97.05 90 100 96.96
🟢   apiErrors.ts 100 100 100 100
🟢   ...orResponse.ts 100 100 100 100
🟢   toError.ts 87.5 88.88 100 87.5 21
🟢   unsealError.ts 100 50 100 100 14

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the constant-time webhook signature-validation change.

No open issues 🎉

What changed in this PR

Updates the Node SDK’s webhook signature validation to compare HMAC signatures in constant time while preserving existing acceptance behavior.

Changes:

  • Uses crypto.timingSafeEqual with guards for undefined signatures and unequal byte lengths.
  • Adds regression tests for malformed signatures, multibyte input, multiple signatures, and constant-time comparison.
  • Adds a patch-release changeset.
File Description
tests/​unit-tests/​webhookTests.spec.ts Adds signature-validation and constant-time comparison regression tests.
src/​webhook.ts Replaces string equality with guarded constant-time comparison.
.changeset/​constant-time-webhook-signature.md Documents the webhook security fix for a patch release.

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants