SWI-11363 Add CONTRIBUTING guide + harden webhook auth and outbound fetch handling#14
Merged
Conversation
Sets community-supported expectations (no dedicated dev team, PRs/issues looked at by a Bandmate as bandwidth allows), plus issue/PR guidance, PII guardrails, and the test/typecheck checklist. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Strip brackets from IPv6-literal hostnames before the isIP() fast path so literals like https://[::1]/ are classified against the blocklist instead of silently falling through, and wrap DNS resolution failures (including the default resolver's ENOTFOUND throw) in EgressBlockedError so callers that pattern-match on the typed error get a consistent fail-closed result.
Add an onRequest hook that enforces HTTP Basic auth (via safeEqual) on every /bw/* route, gated by new required AdapterConfig fields webhookUser/webhookPassword. The REST facade keeps its own separate authOk check and is unaffected. Updates all existing tests that hit /bw/* or build an AdapterConfig to supply the new fields and, where applicable, the Authorization header, plus the local bench script.
Update stale test count in README and make SECURITY.md / egress-guard.ts honest about the range denylist not defending against DNS rebinding.
Harden webhook authentication and outbound fetch handling
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
kshahbw
changed the title
joshraub-bw
approved these changes
Jul 15, 2026
kshahbw
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two pieces of work land together here:
Contributing guide
Adds
CONTRIBUTING.mdcovering local setup, the test/typecheck workflow, and project conventions.Webhook & callback hardening
safeEqualhelper (crypto.timingSafeEqual), replacing the previous!==string comparisons./bw/*routes now require HTTP Basic auth (WEBHOOK_USER/WEBHOOK_PASSWORD), matching Bandwidth's nativeCallbackCreds. This is a distinct secret from the Twilio-compat REST credential. The translator stamps the same credentials onto the BXML callback verbs it emits, so Bandwidth presents them on continuation callbacks.http/https, and loopback/link-local/private ranges (IPv4, IPv6, IPv4-mapped) are refused. Redirects disabled; request timeout applied.127.0.0.1; setHOST=0.0.0.0to expose it.EGRESS_ALLOW_HOSTSswitches outbound fetches to a strict default-deny allowlist.SECURITY.mddocumenting the auth model, the egress guard (and its defense-in-depth boundary), and setup.WEBHOOK_USER,WEBHOOK_PASSWORD(also set matchingCallbackCredson your Bandwidth Voice application).127.0.0.1— containerized/exposed deployments must setHOST=0.0.0.0.EGRESS_ALLOW_PRIVATE=1(local dev againstlocalhost/LAN),EGRESS_ALLOW_HOSTS(strict allowlist).Testing
Full suite green: 303/303 (
npm test), typecheck clean. Adds coverage for the egress guard (range classification, IPv6-literal + IPv4-mapped, redirect/timeout), inbound auth (401 on missing/wrong creds, REST facade not unlocked by webhook creds), and callback-credential stamping.🤖 Generated with Claude Code